[Emc-commit] rtapi/src/rtapi rtapi.h,1.22,1.23

[<jmk...@us...>]

Update of /cvsroot/emc/rtapi/src/rtapi
In directory sc8-pr-cvs1:/tmp/cvs-serv4529/src/rtapi

Modified Files:
	rtapi.h 
Log Message:
reformat rtapi.h, new definition for clock_set_period()

Index: rtapi.h
===================================================================
RCS file: /cvsroot/emc/rtapi/src/rtapi/rtapi.h,v
retrieving revision 1.22
retrieving revision 1.23
diff -C2 -d -r1.22 -r1.23
*** rtapi.h	16 Aug 2003 20:29:39 -0000	1.22
--- rtapi.h	16 Aug 2003 22:13:28 -0000	1.23
***************
*** 2,44 ****
  #define RTAPI_H
  
! /** RTAPI is a library providing a uniform API for several real time  *
! * operating systems.  As of ver 2.0, RTLinux and RTAI are supported.  */
  
! /** This file, 'rtapi.h', defines the API as seen by realtime tasks.  *
! * The non-realtime version of the API is defined in 'ulapi.h'.  The   *
! * realtime interface is implemented in files named 'xxx_rtapi.c',     *
! * where xxx is the RTOS.  Likewise, the non-realtime interface is     *
! * implemented in files named 'xxx_ulapi.c'                            */
  
! /** Copyright (C) 2003 John Kasunich                                  *
! *                      <jmkasunich AT users DOT sourceforge DOT net>  *
! *   Copyright (C) 2003 Paul Corner                                    *
! *                      <paul_c AT users DOT sourceforge DOT net>      *
! * This library is based on version 1.0, which was released into       *
! * the public domain by its author, Fred Proctor.  Thanks Fred!        */
  
! /* This library is free software; you can redistribute it and/or      *
! * modify it under the terms of version 2.1 of the GNU Lesser General  *
! * Public License as published by the Free Software Foundation.        *
! * This library is distributed in the hope that it will be useful, but *
! * WITHOUT ANY WARRANTY; without even the implied warranty of          *
! * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU   *
! * Lesser General Public License for more details.                     *
! *                                                                     *
! * You should have received a copy of the GNU Lesser General Public    *
! * License along with this library; if not, write to the Free Software *
! * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111 USA */
  
! /** THE AUTHORS OF THIS LIBRARY ACCEPT ABSOLUTELY NO LIABILITY FOR    *
! * ANY HARM OR LOSS RESULTING FROM ITS USE.  IT IS _EXTREMELY_ UNWISE  *
! * TO RELY ON SOFTWARE ALONE FOR SAFETY.  Any machinery capable of     *
! * harming persons must have provisions for completely removing power  *
! * from all motors, etc, before persons enter any danger area.  All    *
! * machinery must be designed to comply with local and national safety *
! * codes, and the authors of this software can not, and do not, take   *
! * any responsibility for such compliance.                             */
  
! /** This code was written as part of the EMC HAL project.  For more   *
! * information, go to www.linuxcnc.org.                                */
  
  /** These status codes are returned by many RTAPI functions. */
--- 2,48 ----
  #define RTAPI_H
  
! /** RTAPI is a library providing a uniform API for several real time
!     operating systems.  As of ver 2.0, RTLinux and RTAI are supported.
! */
  
! /** This file, 'rtapi.h', defines the API as seen by realtime tasks.
!     The non-realtime version of the API is defined in 'ulapi.h'.  The
!     realtime interface is implemented in files named 'xxx_rtapi.c',
!     where xxx is the RTOS.  Likewise, the non-realtime interface is
!     implemented in files named 'xxx_ulapi.c'
! */
  
! /** Copyright (C) 2003 John Kasunich
!                        <jmkasunich AT users DOT sourceforge DOT net>
!     Copyright (C) 2003 Paul Corner
!                        <paul_c AT users DOT sourceforge DOT net>
!     This library is based on version 1.0, which was released into
!     the public domain by its author, Fred Proctor.  Thanks Fred!
! */
  
! /** This library is free software; you can redistribute it and/or
!     modify it under the terms of version 2.1 of the GNU Lesser General
!     Public License as published by the Free Software Foundation.
!     This library is distributed in the hope that it will be useful,
!     but WITHOUT ANY WARRANTY; without even the implied warranty of
!     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
!     GNU Lesser General Public License for more details.
  
!     You should have received a copy of the GNU Lesser General Public
!     License along with this library; if not, write to the Free Software
!     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111 USA
  
!     THE AUTHORS OF THIS LIBRARY ACCEPT ABSOLUTELY NO LIABILITY FOR
!     ANY HARM OR LOSS RESULTING FROM ITS USE.  IT IS _EXTREMELY_ UNWISE
!     TO RELY ON SOFTWARE ALONE FOR SAFETY.  Any machinery capable of
!     harming persons must have provisions for completely removing power
!     from all motors, etc, before persons enter any danger area.  All
!     machinery must be designed to comply with local and national safety
!     codes, and the authors of this software can not, and do not, take
!     any responsibility for such compliance.
! 
!     This code was written as part of the EMC HAL project.  For more
!     information, go to www.linuxcnc.org.
! */
  
  /** These status codes are returned by many RTAPI functions. */
***************
*** 56,151 ****
  #define RTAPI_LATE      -10	/* task could not start when requested */
  
- /* NOTE:  RTAPI assumes that ints are at least 32 bits long */
- /* FIXME - need to review the API, and change everything that needs
- to be 32 bits to long int.  */
- 
  /***********************************************************************
  *                   GENERAL PURPOSE FUNCTIONS                          *
  ************************************************************************/
  
! /** 'rtapi_init() sets up the RTAPI.  It must be called by any module  *
! * that intends to use the API, before any other RTAPI calls. Returns a *
! * status code, as defined above.  Increments a usage count.            */
! 
  extern int rtapi_init(void);
  
  
! /** 'rtapi_exit()' shuts down and cleans up the RTAPI.  It must be     *
! * called prior to exit by any module that called rtapi_init.  Returns  *
! * a status code.  Decrements the usage count maintined by rtapi_init.  */
! 
  extern int rtapi_exit(void);
  
  
! /** 'rtapi_print()' prints a printf style message.  Depending on the   *
! * RTOS, the message may be printed to stdout, or to the kernel message *
! * log, etc.  The calling syntax and format string is similar to printf *
! * except that floating point and longlongs may not be supported.  For  *
! * some RTOS's, a 256 byte buffer is used, so the format line and       *
! * arguments should not produce a line more than 255 bytes long.  Does  *
! * not block, but  can take a fairly long time, depending on the format *
! * string and OS.                                                       */
! 
  extern void rtapi_print(const char *fmt, ...);
  
  
! /** 'rtapi_print_msg()' prints debug messages.  Works like rtapi_print *
! * but only prints if 'level' is less than 'rtapi_msg_level'.           *
! * 'rtapi_msg_level' is a global.  The default is 7, but it may be      *
! * changed.  The rtapi uses the same levels for its own messages.       *
! * The defines below are used for rtapi messages, and recommended for   *
! * user messages as well.                                               */
! 
  extern int rtapi_msg_level;
- 
  #define RTAPI_MSG_ERR  3
  #define RTAPI_MSG_WARN 4
  #define RTAPI_MSG_INFO 6
  #define RTAPI_MSG_DBG  7
- 
  extern void rtapi_print_msg(int level, const char *fmt, ...);
  
  
  /***********************************************************************
! *                     CLOCK RELATED FUNCTIONS                          *
  ************************************************************************/
  
! /** The clock period is the basic time interval for realtime tasks     *
! * All task periods, whether specified when starting the task, or       *
! * changed later, will be rounded to an integer multiple of the         *
! * period set by 'rtapi_clock_set_period()'.  Note that there may be    *
! * only one hardware clock in the system, and this call may stop and    *
! * resets it.  So this function only needs to be called once, even if   *
! * there are multiple realtime tasks in multiple modules.  Calling this *
! * function after realtime tasks have been started may disrupt the      *
! * tasks.  If the call fails, it returns a negative status code.  On    *
! * success, it either returns 0, or (if the RTOS supports it), the      *
! * actual period, which may not be exactly what was requested. The      *
! * upper and lower limits for the timer period are RTOS dependent, so   *
! * be sure to check for errors.                                         */
  
! extern int rtapi_clock_set_period(unsigned long int nsecs);
  
  
! /** rtapi_get_time returns the current time in nanoseconds.  Depending *
! * on the RTOS, this may be time since boot, or time since the clock    *
! * period was set, or some other time.  Its absolute value means        *
! * nothing, but it is monotonically increasing (at least for the first  *
! * 200 years or so), and can be used to schedule future events, or to   *
! * time the duration of some activity.  Returns a 2^63 value.  The      *
! * resolution of the returned value may be as good as one nano-second,  *
! * or as poor as several microseconds.                                  */
  
  extern long long int rtapi_get_time(void);
  
- /** rtapi_sleep() is a simple delay.  It is intended only for short    *
- * delays, since it simply loops, wasting CPU cycles.  'nsec' is the    *
- * desired delay, in nano-seconds.  'rtapi_sleep_max() returns the max  *
- * delay permitted (usually approximately 1/4 of the timer period).     *
- * Any call to 'rtapi_sleep()' requesting a delay longer than the max   *
- * will delay for the max time only.  'rtapi_sleep_max()' should be     *
- * called befure using 'rtapi_sleep()' to make sure the required delays *
- * can be achieved.                                                     */
  
  extern void rtapi_sleep(unsigned long int nsec);
  extern unsigned long int rtapi_sleep_max(void);
--- 60,169 ----
  #define RTAPI_LATE      -10	/* task could not start when requested */
  
  /***********************************************************************
  *                   GENERAL PURPOSE FUNCTIONS                          *
  ************************************************************************/
  
! /** 'rtapi_init() sets up the RTAPI.  It must be called by any module
!     that intends to use the API, before any other RTAPI calls. Returns
!     a status code, as defined above.  Increments a usage count.
! */
  extern int rtapi_init(void);
  
  
! /** 'rtapi_exit()' shuts down and cleans up the RTAPI.  It must be
!     called prior to exit by any module that called rtapi_init.
!     Returns a status code.  Decrements the usage count maintained
!     by rtapi_init.
! */
  extern int rtapi_exit(void);
  
  
! /** 'rtapi_print()' prints a printf style message.  Depending on the
!     RTOS, the message may be printed to stdout, or to the kernel
!     message log, etc.  The calling syntax and format string is similar
!     to printf except that floating point and longlongs may not be
!     supported.  For some RTOS's, a 256 byte buffer is used, so the
!     format line and arguments should not produce a line more than
!     255 bytes long.  Does not block, but  can take a fairly long
!     time, depending on the format string and OS.
! */
  extern void rtapi_print(const char *fmt, ...);
  
  
! /** 'rtapi_print_msg()' prints debug messages.  Works like rtapi_print
!     but only prints if 'level' is less than 'rtapi_msg_level'.
!     'rtapi_msg_level' is a global.  The default is 7, but it may be
!     changed.  The defines below are used for RTAPI messages, and are
!     recommended for user messages as well.
! */
  extern int rtapi_msg_level;
  #define RTAPI_MSG_ERR  3
  #define RTAPI_MSG_WARN 4
  #define RTAPI_MSG_INFO 6
  #define RTAPI_MSG_DBG  7
  extern void rtapi_print_msg(int level, const char *fmt, ...);
  
  
  /***********************************************************************
! *                      TIME RELATED FUNCTIONS                          *
  ************************************************************************/
  
! /* OLD VERSION */
  
! /** The clock period is the basic time interval for realtime tasks
!     All task periods, whether specified when starting the task, or
!     changed later, will be rounded to an integer multiple of the
!     period set by 'rtapi_clock_set_period()'.  Note that there may be
!     only one hardware clock in the system, and this call may stop and
!     reset it.  So this function only needs to be called once, even if
!     there are multiple realtime tasks in multiple modules.  Calling this
!     function after realtime tasks have been started may disrupt the
!     tasks.  If the call fails, it returns a negative status code.  On
!     success, it either returns 0, or (if the RTOS supports it), the
!     actual period, which may not be exactly what was requested. The
!     upper and lower limits for the timer period are RTOS dependent, so
!     be sure to check for errors. */
  
+ /* NEW VERSION */
  
! /** 'rtapi_clock_set_period() sets the basic time interval for realtime
!     tasks.  All periodic tasks will run at an integer multiple of this
!     period.  The first call to 'rtapi_clock_set_period() with 'nsecs'
!     greater than zero will start the clock, using 'nsecs' as the clock
!     period in nano-seconds.  Due to hardware and RTOS limitations, the
!     actual period may not be exactly what was requested.  On success,
!     the function will return the actual clock period if it is available,
!     otherwise it returns the requested period.  If the requested period
!     is outside the limits imposed by the hardware or RTOS, it returns
!     RTAPI_INVAL and does not start the clock.  Once the clock is started,
!     subsequent calls with non-zero 'nsecs' return RTAPI_INVAL and have
!     no effect.  Calling 'rtapi_clock_set_period() with 'nsecs' set to
!     zero queries the clock, returning the current clock period, or zero
!     if the clock has not yet been started.
! */
! extern long int rtapi_clock_set_period(long int nsecs);
  
+ 
+ /** rtapi_get_time returns the current time in nanoseconds.  Depending
+     on the RTOS, this may be time since boot, or time since the clock
+     period was set, or some other time.  Its absolute value means
+     nothing, but it is monotonically increasing and can be used to
+     schedule future events, or to time the duration of some activity.
+     Returns a 2^63 value.  The resolution of the returned value may
+     be as good as one nano-second, or as poor as several microseconds.
+ */
  extern long long int rtapi_get_time(void);
  
  
+ /** rtapi_sleep() is a simple delay.  It is intended only for short
+     delays, since it simply loops, wasting CPU cycles.  'nsec' is the
+     desired delay, in nano-seconds.  'rtapi_sleep_max() returns the
+     max delay permitted (usually approximately 1/4 of the clock period).
+     Any call to 'rtapi_sleep()' requesting a delay longer than the max
+     will delay for the max time only.  'rtapi_sleep_max()' should be
+     called befure using 'rtapi_sleep()' to make sure the required delays
+     can be achieved.  The actual resolution of the delay may be as good
+     as one nano-second, or as bad as a several microseconds.
+ */
  extern void rtapi_sleep(unsigned long int nsec);
  extern unsigned long int rtapi_sleep_max(void);
***************
*** 156,178 ****
  ************************************************************************/
  
! /* NOTE: The RTAPI is designed to be a _simple_ API.  As such, it uses *
! * a very simple strategy to deal with SMP systems.  It ignores them!   *
! * All tasks are scheduled on the first CPU.  That doesn't mean that    *
! * additional CPUs are wasted, they will be used for non-realtime code. */
  
! /** The 'rtapi_prio_xxxx()' functions provide a portable way to set    *
! * task priority.  The mapping of actual priority to priority number    *
! * depends on the RTOS.  Priorities range from 'rtapi_prio_lowest()'    *
! * to 'rtapi_prio_highest()', inclusive. To use this API, use one of    *
! * two methods:                                                         *
! *                                                                      *
! * 1) Set your lowest priority task to 'rtapi_prio_lowest()', and for   *
! * each task of the next lowest priority, set their priorities to       *
! * 'rtapi_prio_next_higher(previous)'.                                  *
! *                                                                      *
! * 2) Set your highest priority task to 'rtapi_prio_highest()', and for *
! * each task of the next highest priority, set their priorities to      *
! * 'rtapi_prio_next_lower(previous)'.                                   */
  
  extern int rtapi_prio_highest(void);
  extern int rtapi_prio_lowest(void);
--- 174,197 ----
  ************************************************************************/
  
! /** NOTE: The RTAPI is designed to be a _simple_ API.  As such, it uses
!     a very simple strategy to deal with SMP systems.  It ignores them!
!     All tasks are scheduled on the first CPU.  That doesn't mean that
!     additional CPUs are wasted, they will be used for non-realtime code.
! */
  
! /** The 'rtapi_prio_xxxx()' functions provide a portable way to set
!     task priority.  The mapping of actual priority to priority number
!     depends on the RTOS.  Priorities range from 'rtapi_prio_lowest()'
!     to 'rtapi_prio_highest()', inclusive. To use this API, use one of
!     two methods:
  
+     1) Set your lowest priority task to 'rtapi_prio_lowest()', and for
+        each task of the next lowest priority, set their priorities to
+        'rtapi_prio_next_higher(previous)'.
+ 
+     2) Set your highest priority task to 'rtapi_prio_highest()', and
+        for each task of the next highest priority, set their priorities
+        to 'rtapi_prio_next_lower(previous)'.
+ */
  extern int rtapi_prio_highest(void);
  extern int rtapi_prio_lowest(void);
***************
*** 181,207 ****
  
  
! /** 'rtapi_task_new()' creates but does not start a realtime task.     *
! * The task is created in the "paused" state.  To start the task, call  *
! * either rtapi_task_start() for periodic tasks, or rtapi_task_resume() *
! * for free-running tasks.                                              *
! * On success, returns a positive integer task ID.  This ID is used     *
! * for all subsequent calls that need to act on the task.  On failure,  *
! * returns a negative error code as listed above.                       *
! * 'taskcode' is the name of a function taking one int and returning    *
! * void, which contains the task code.  'arg' will be passed to         *
! * 'taskcode' as an abitrary int value when the task is started.        *
! * 'prio' is the  priority, as determined by one of the priority        *
! * functions above.  'stacksize' is the amount of stack to be reserved  *
! * for the task - be generous, hardware interrupts may use the same     *
! * stack.  'uses_fp' is a flag that tells the OS whether the task uses  *
! * floating point so it can save the FPU registers on a task switch.    *
! * Failing to save registers when needed causes the dreaded "NAN bug",  *
! * so most tasks should set 'uses_fp' to RTAPI_USES_FP.  If a task      *
! * definitely does not use floating point, setting 'uses_fp' to         *
! * RTAPI_NO_FP saves a few microseconds per task switch.                */
! 
  #define RTAPI_NO_FP   0
  #define RTAPI_USES_FP 1
- 
  extern int rtapi_task_new(void (*taskcode) (int),
  			  int arg, int prio,
--- 200,225 ----
  
  
! /** 'rtapi_task_new()' creates but does not start a realtime task.
!     The task is created in the "paused" state.  To start it, call
!     either rtapi_task_start() for periodic tasks, or rtapi_task_resume()
!     for free-running tasks.
!     On success, returns a positive integer task ID.  This ID is used
!     for all subsequent calls that need to act on the task.  On failure,
!     returns a negative error code as listed above.  'taskcode' is the
!     name of a function taking one int and returning void, which contains
!     the task code.  'arg' will be passed to 'taskcode' as an abitrary
!     int value when the task is started.
!     'prio' is the  priority, as determined by one of the priority
!     functions above.  'stacksize' is the amount of stack to be used
!     for the task - be generous, hardware interrupts may use the same
!     stack.  'uses_fp' is a flag that tells the OS whether the task uses
!     floating point so it can save the FPU registers on a task switch.
!     Failing to save registers when needed causes the dreaded "NAN bug",
!     so most tasks should set 'uses_fp' to RTAPI_USES_FP.  If a task
!     definitely does not use floating point, setting 'uses_fp' to
!     RTAPI_NO_FP saves a few microseconds per task switch.
! */
  #define RTAPI_NO_FP   0
  #define RTAPI_USES_FP 1
  extern int rtapi_task_new(void (*taskcode) (int),
  			  int arg, int prio,
***************
*** 210,241 ****
  
  
! /** 'rtapi_task_delete()' is deletes a task.  'task_id' is a task ID   *
! * from a previous call to rtapi_task_new().                            *
! * It frees memory associated with 'task', and does any other cleanup   *
! * needed.  If the task has been started, you should pause it before    *
! * deleting it.  Returns a status code.  Call from within init or       *
! * cleanup code, or from another task.  A task cannot delete itself!    */
! 
  extern int rtapi_task_delete(int task_id);
  
  
! /** 'rtapi_task_start()' starts a task in periodic mode.  'task_id' is *
! * a task ID from a call to rtapi_task_new().  The task must be in      *
! * the "paused" state, or it will return RTAPI_INVAL.                   *
! * 'period_nsec' is the task period in nanoseconds, which will be       *
! * rounded to the nearest multiple of the global clock period.  A task  *
! * period less than the clock period (including zero) will be set equal *
! * to the clock period.                                                 *
! * If 'when' is RTAPI_NOW, the task will start immediately.  Otherwise, *
! * 'when' is assumed to be the desired start time, using the same time- *
! * base as rtapi_get_time().  The task will be scheduled to start at    *
! * the desired time.  If the desired time has already passed, the task  *
! * will start immediately, and function will return RTAPI_LATE.  If     *
! * 'when' is not RTAPI_NOW, and the RTOS doesn't support starting tasks *
! * at a specific time, it will return RTAPI_UNSUP and the task will not *
! *  be started.                                                         */
! 
! #define RTAPI_NOW     0
! 
  extern int rtapi_task_start(int task_id,
  			    unsigned long int period_nsec,
--- 228,258 ----
  
  
! /** 'rtapi_task_delete()' deletes a task.  'task_id' is a task ID
!     from a previous call to rtapi_task_new().  It frees memory
!     associated with 'task', and does any other cleanup needed.  If
!     the task has been started, you should pause it before deleting
!     it.  Returns a status code.  Call from within init or cleanup
!     code, or from another task.  A task cannot delete itself!
! */
  extern int rtapi_task_delete(int task_id);
  
  
! /** 'rtapi_task_start()' starts a task in periodic mode.  'task_id' is
!     a task ID from a call to rtapi_task_new().  The task must be in
!     the "paused" state, or it will return RTAPI_INVAL.
!     'period_nsec' is the task period in nanoseconds, which will be
!     rounded to the nearest multiple of the global clock period.  A
!     task period less than the clock period (including zero) will be
!     set equal to the clock period.
!     If 'when' is RTAPI_NOW, the task will start immediately.  Otherwise,
!     'when' is assumed to be the desired start time, using the same time-
!     base as rtapi_get_time().  The task will be scheduled to start at
!     the desired time.  If the desired time has already passed, the task
!     will start immediately, and function will return RTAPI_LATE.  If
!     'when' is not RTAPI_NOW, and the RTOS doesn't support starting tasks
!     at a specific time, it will return RTAPI_UNSUP and the task will not
!     be started.
! */
! #define RTAPI_NOW 0
  extern int rtapi_task_start(int task_id,
  			    unsigned long int period_nsec,
***************
*** 243,308 ****
  
  
! /** 'rtapi_wait()' suspends execution of the current task until the    *
! * next period.  The task must be periodic, if not, the result is       *
! * undefined.  The function will return RTAPI_SUCCESS at the beginning  *
! * of the next period.  Call only from within a task.                   */
! 
! extern int rtapi_wait(void);
  
  
! /** 'rtapi_task_resume() starts a task in free-running mode. 'task_id' *
! * is a task ID from a call to rtapi_task_new().  The task must be in   *
! * the "paused" state, or it will return RTAPI_INVAL.                   *
! * A free running task runs continuously until either 1) It is prempted *
! * by a higher priority task.  It will resume as soon as the higher     *
! * priority task releases the CPU. Or 2) It calls a blocking function,  *
! * like rtapi_sem_take().  It will resume when the function unblocks.   *
! * Or 3) it is returned to the "paused" state by rtapi_task_pause().    */
! 
  extern int rtapi_task_resume(int task_id);
  
  
! /** 'rtapi_task_pause() causes 'task_id' to stop execution and change  *
! * to the "paused" state.  'task_id' can be free-running or periodic.   *
! * Note that rtapi_task_pause() may called from any task, or from init  *
! * or cleanup code, not just from the task that is to be paused.        *
! * The task will resume execution when either rtapi_task_resume() or    *
! * rtapi_task_start() is called.                                        */
! 
  extern int rtapi_task_pause(int task_id);
  
  
! /** 'rtapi_task_self()' returns the task ID of the current task.       *
! * May return a negative error code if called from outside a task.      */
! 
  extern int rtapi_task_self(void);
  
  
- 
  /***********************************************************************
  *                  SHARED MEMORY RELATED FUNCTIONS                     *
  ************************************************************************/
  
! /** 'rtapi_shmem_new()' allocates a block of shared memory.  'key'     *
! * identifies the memory block, and must be non-zero.  All modules      *
! * wishing to access the same memory must use the same key.             *
! * The block will be at least 'size' bytes, and may be rounded up.      *
! * Allocating many small blocks may be very wasteful.  On success, it   *
! * returns a positive integer ID, which is used for all subsequent      *
! * calls dealing with the block.  On failure it returns a negative      *
! * error code.  To get a pointer to the shared memory, pass the ID to   *
! * 'rtapi_shmem_getptr()'.                                              */
! 
  extern int rtapi_shmem_new(int key, unsigned long int size );
  
  
! /** 'rtapi_shmem_delete()' frees the shared memory block associated    *
! * with 'shmem_id'.  Returns a status code.                             */
! 
  extern int rtapi_shmem_delete(int shmem_id);
  
! /** 'rtapi_shmem_getptr()' sets '*ptr' to point to shared memory block *
! * associated with 'shmem_id'.  Returns a status code.                  */
! 
  extern int rtapi_shmem_getptr(int shmem_id, void **ptr);
  
--- 260,325 ----
  
  
! /** 'rtapi_wait()' suspends execution of the current task until the
!     next period.  The task must be periodic, if not, the result is
!     undefined.  The function will return at the beginning of the
!     next period.  Call only from within a task.
! */
! extern void rtapi_wait(void);
  
  
! /** 'rtapi_task_resume() starts a task in free-running mode. 'task_id'
!     is a task ID from a call to rtapi_task_new().  The task must be in
!     the "paused" state, or it will return RTAPI_INVAL.
!     A free running task runs continuously until either:
!     1) It is prempted by a higher priority task.  It will resume as
!        soon as the higher priority task releases the CPU.
!     2) It calls a blocking function, like rtapi_sem_take().  It will
!        resume when the function unblocks.
!     3) it is returned to the "paused" state by rtapi_task_pause().
! */
  extern int rtapi_task_resume(int task_id);
  
  
! /** 'rtapi_task_pause() causes 'task_id' to stop execution and change
!     to the "paused" state.  'task_id' can be free-running or periodic.
!     Note that rtapi_task_pause() may called from any task, or from init
!     or cleanup code, not just from the task that is to be paused.
!     The task will resume execution when either rtapi_task_resume() or
!     rtapi_task_start() is called.
! */
  extern int rtapi_task_pause(int task_id);
  
  
! /** 'rtapi_task_self()' returns the task ID of the current task.
!     May return a negative error code if called from outside a task.
! */
  extern int rtapi_task_self(void);
  
  
  /***********************************************************************
  *                  SHARED MEMORY RELATED FUNCTIONS                     *
  ************************************************************************/
  
! /** 'rtapi_shmem_new()' allocates a block of shared memory.  'key'
!     identifies the memory block, and must be non-zero.  All modules
!     wishing to access the same memory must use the same key.
!     The block will be at least 'size' bytes, and may be rounded up.
!     Allocating many small blocks may be very wasteful.  On success,
!     it returns a positive integer ID, which is used for all subsequent
!     calls dealing with the block.  On failure it returns a negative
!     error code.  To get a pointer to the shared memory, pass the ID
!     to 'rtapi_shmem_getptr()'.
! */
  extern int rtapi_shmem_new(int key, unsigned long int size );
  
  
! /** 'rtapi_shmem_delete()' frees the shared memory block associated
!     with 'shmem_id'.  Returns a status code.
! */
  extern int rtapi_shmem_delete(int shmem_id);
  
! /** 'rtapi_shmem_getptr()' sets '*ptr' to point to shared memory block
!     associated with 'shmem_id'.  Returns a status code.
! */
  extern int rtapi_shmem_getptr(int shmem_id, void **ptr);
  
***************
*** 312,353 ****
  ************************************************************************/
  
! /** 'rtapi_sem_new()' creates a realtime semaphore.  'key' identifies  *
! * identifies the semaphore, and must be non-zero.  All modules wishing *
! * to use the same semaphore must specify the same key.  On success, it *
! * returns a positive integer ID, which is used for all subsequent      *
! * calls dealing with the semaphore.  On failure it returns a negative  *
! * error code.                                                          */
! 
  extern int rtapi_sem_new(int key);
  
  
! /** 'rtapi_sem_delete()' is the counterpart to 'rtapi_sem_new()'.  It  *
! * discards the semaphore associated with 'sem_id'.  Any tasks blocked  *
! * on 'sem' will resume execution.  Returns a status code.              */
! 
  extern int rtapi_sem_delete(int sem_id);
  
  
! /** 'rtapi_sem_give()' unlocks a semaphore.  If a higher priority task *
! * is blocked on the semaphore, the calling task will block and the     *
! * higher priority task will begin to run.  Returns a status code.      */
! 
  extern int rtapi_sem_give(int sem_id);
  
  
! /** 'rtapi_sem_take()' locks a semaphore.  Returns RTAPI_SUCCESS or    *
! * RTAPI_BADH.  If the semaphore is unlocked it returns RTAPI_SUCCESS   *
! * immediately.  If the semaphore is locked, the calling task blocks    *
! * until the semaphore is unlocked, then it returns RTAPI_SUCCESS.      */
! 
  extern int rtapi_sem_take(int sem_id);
  
  
! /** 'rtapi_sem_try()' does a non-blocking attempt to lock a semaphore. *
! * Returns RTAPI_SUCCESS, RTAPI_BADH, or RTAPI_BUSY.  If the semaphore  *
! * is unlocked, it returns RTAPI_SUCCESS.  If the semaphore is locked   *
! * it does not block, instead it returns RTAPI_BUSY, and the caller can *
! * decide how to deal with the situation.                               */
! 
  extern int rtapi_sem_try(int sem_id);
  
--- 329,370 ----
  ************************************************************************/
  
! /** 'rtapi_sem_new()' creates a realtime semaphore.  'key' identifies
!     identifies the semaphore, and must be non-zero.  All modules wishing
!     to use the same semaphore must specify the same key.  On success, it
!     returns a positive integer ID, which is used for all subsequent
!     calls dealing with the semaphore.  On failure it returns a negative
!     error code.
! */
  extern int rtapi_sem_new(int key);
  
  
! /** 'rtapi_sem_delete()' is the counterpart to 'rtapi_sem_new()'.  It
!     discards the semaphore associated with 'sem_id'.  Any tasks blocked
!     on 'sem' will resume execution.  Returns a status code.
! */
  extern int rtapi_sem_delete(int sem_id);
  
  
! /** 'rtapi_sem_give()' unlocks a semaphore.  If a higher priority task
!     is blocked on the semaphore, the calling task will block and the
!     higher priority task will begin to run.  Returns a status code.
! */
  extern int rtapi_sem_give(int sem_id);
  
  
! /** 'rtapi_sem_take()' locks a semaphore.  Returns RTAPI_SUCCESS or
!     RTAPI_BADH.  If the semaphore is unlocked it returns RTAPI_SUCCESS
!     immediately.  If the semaphore is locked, the calling task blocks
!     until the semaphore is unlocked, then it returns RTAPI_SUCCESS.
! */
  extern int rtapi_sem_take(int sem_id);
  
  
! /** 'rtapi_sem_try()' does a non-blocking attempt to lock a semaphore.
!     Returns RTAPI_SUCCESS, RTAPI_BADH, or RTAPI_BUSY.  If the semaphore
!     is unlocked, it returns RTAPI_SUCCESS.  If the semaphore is locked
!     it does not block, instead it returns RTAPI_BUSY, and the caller
!     can decide how to deal with the situation.
! */
  extern int rtapi_sem_try(int sem_id);
  
***************
*** 357,407 ****
  ************************************************************************/
  
! /** 'rtapi_fifo_new()' creates a realtime fifo. 'key' identifies the   *
! * fifo, all modules wishing to access the same fifo must use the same  *
! * key.  'size' is the depth of the fifo.  'mode' is either 'R' or 'W', *
! * to request either read or write access to the fifo.  On success, it  *
! * returns a positive integer ID, which is used for subsequent calls    *
! * dealing with the fifo.  On failure, returns a negative error code.   */
! 
! /* NOTE - RTAI fifos require (stacksize >= fifosze + 256) to avoid   *
! * oops messages on removal. (Does this apply to rtlinux as well ?) */
  
  extern int rtapi_fifo_new(int key, unsigned long int size, char mode);
  
  
! /** 'rtapi_fifo_delete()' is the counterpart to 'rtapi_fifo_new()'.    *
! * It closes the fifo associated with 'fifo_ID'.  'mode' is the mode    *
! * that was specified when the fifo was created.  Returns status code.  */
! 
  extern int rtapi_fifo_delete(int fifo_id, char mode);
  
  
! /** FIFO notes. These comments apply to both read and write functions. *
! * A fifo is a character device, an int is typically four bytes long... *
! * If less than four bytes are sent to the fifo, expect corrupt data    *
! * out of the other end !                                               *
! * The RTAI programming manual clearly states that the programmer is    *
! * responsible for the data format and integrity.                       */
! 
! /* Additional NOTE:  IMHO you should be able to write any amount of    *
! * data to a fifo, from 1 byte up to (and even beyond) the size of the  *
! * fifo.  At a future date, the somewhat peculiar RTAI fifos will be    *
! * replaced with something that works better.   John Kasunich           */
  
! /** 'rtapi_fifo_read()' reads data from 'fifo_id'.  'buf' is a buffer  *
! * for the data, and 'size' is the maximum number of bytes to read.     *
! * Returns the number of bytes actually read, or RTAPI_BADH.  Does not  *
! * block.  If 'size' bytes are not available, it will read whatever is  *
! * available, and return that count (which could be zero).              */
  
  extern int rtapi_fifo_read(int fifo_id, char *buf, unsigned long int size);
  
  
! /** 'rtapi_fifo_write()' writes data to 'fifo_id'. Up to 'size' bytes  *
! * are taken from the buffer at 'buf'.  Returns the number of bytes     *
! * actually written, or RTAPI_BADH.  Does not block.  If 'size' bytes   *
! * of space are not available in the fifo, it will write as many bytes  *
! * as it can and return that count (which may be zero).                 */
! 
  extern int rtapi_fifo_write(int fifo_id, char *buf, unsigned long int size);
  
--- 374,426 ----
  ************************************************************************/
  
! /** 'rtapi_fifo_new()' creates a realtime fifo. 'key' identifies the
!     fifo, all modules wishing to access the same fifo must use the same
!     key.  'size' is the depth of the fifo.  'mode' is either 'R' or 'W',
!     to request either read or write access to the fifo.  On success, it
!     returns a positive integer ID, which is used for subsequent calls
!     dealing with the fifo.  On failure, returns a negative error code.
! */
  
+ /* NOTE - RTAI fifos require (stacksize >= fifosze + 256) to avoid
+    oops messages on removal. (Does this apply to rtlinux as well ?)
+ */
  extern int rtapi_fifo_new(int key, unsigned long int size, char mode);
  
  
! /** 'rtapi_fifo_delete()' is the counterpart to 'rtapi_fifo_new()'.
!     It closes the fifo associated with 'fifo_ID'.  'mode' is the mode
!     that was specified when the fifo was created.  Returns status code.
! */
  extern int rtapi_fifo_delete(int fifo_id, char mode);
  
  
! /** FIFO notes. These comments apply to both read and write functions.
!     A fifo is a character device, an int is typically four bytes long...
!     If less than four bytes are sent to the fifo, expect corrupt data
!     out of the other end !
!     The RTAI programming manual clearly states that the programmer is
!     responsible for the data format and integrity.
  
!     Additional NOTE:  IMHO you should be able to write any amount of
!     data to a fifo, from 1 byte up to (and even beyond) the size of
!     the fifo.  At a future date, the somewhat peculiar RTAI fifos
!     will be replaced with something that works better.   John Kasunich
! */
  
+ /** 'rtapi_fifo_read()' reads data from 'fifo_id'.  'buf' is a buffer
+     for the data, and 'size' is the maximum number of bytes to read.
+     Returns the number of bytes actually read, or RTAPI_BADH.  Does not
+     block.  If 'size' bytes are not available, it will read whatever is
+     available, and return that count (which could be zero).
+ */
  extern int rtapi_fifo_read(int fifo_id, char *buf, unsigned long int size);
  
  
! /** 'rtapi_fifo_write()' writes data to 'fifo_id'. Up to 'size' bytes
!     are taken from the buffer at 'buf'.  Returns the number of bytes
!     actually written, or RTAPI_BADH.  Does not block.  If 'size' bytes
!     of space are not available in the fifo, it will write as many bytes
!     as it can and return that count (which may be zero).
! */
  extern int rtapi_fifo_write(int fifo_id, char *buf, unsigned long int size);
  
***************
*** 411,437 ****
  ************************************************************************/
  
! /** 'rtapi_assign_interrupt_handler()' is used to set up a handler for *
! * a hardware interrupt.  'irq' is the interrupt number, and 'handler'  *
! * is a pointer to a function taking no arguements and returning void.  *
! * 'handler will be called when the interrupt occurs.  Returns a status *
! * code.  Note:  The simulated RTOS does not support interrupts.        */
! 
  extern int rtapi_assign_interrupt_handler(unsigned int irq,
  					  void (*handler) (void));
  
  
! /** 'rtapi_free_interrupt_handler()' removes an interrupt handler that *
! * was previously installed by rtapi_assign_interrupt_handler(). 'irq'  *
! * is the interrupt number.  Removing a realtime module without freeing *
! * any handlers it has installed will almost certainly crash the box.   *
! * Returns RTAPI_SUCCESS or RTAPI_INVAL.                                */
! 
  extern int rtapi_free_interrupt_handler(unsigned int irq);
  
  
! /** 'rtapi_enable_interrupt()' and 'rtapi_disable_interrupt()' are     *
! * are used to enable and disable interrupts, presumably ones that have *
! * handlers assigned to them.  Returns a status code.                   */
! 
  extern int rtapi_enable_interrupt(unsigned int irq);
  extern int rtapi_disable_interrupt(unsigned int irq);
--- 430,456 ----
  ************************************************************************/
  
! /** 'rtapi_assign_interrupt_handler()' is used to set up a handler for
!     a hardware interrupt.  'irq' is the interrupt number, and 'handler'
!     is a pointer to a function taking no arguements and returning void.
!     'handler will be called when the interrupt occurs.  Returns a status
!     code.  Note:  The simulated RTOS does not support interrupts.
! */
  extern int rtapi_assign_interrupt_handler(unsigned int irq,
  					  void (*handler) (void));
  
  
! /** 'rtapi_free_interrupt_handler()' removes an interrupt handler that
!     was previously installed by rtapi_assign_interrupt_handler(). 'irq'
!     is the interrupt number.  Removing a realtime module without freeing
!     any handlers it has installed will almost certainly crash the box.
!     Returns RTAPI_SUCCESS or RTAPI_INVAL.
! */
  extern int rtapi_free_interrupt_handler(unsigned int irq);
  
  
! /** 'rtapi_enable_interrupt()' and 'rtapi_disable_interrupt()' are
!     are used to enable and disable interrupts, presumably ones that
!     have handlers assigned to them.  Returns a status code.
! */
  extern int rtapi_enable_interrupt(unsigned int irq);
  extern int rtapi_disable_interrupt(unsigned int irq);
***************
*** 442,456 ****
  ************************************************************************/
  
! /** 'rtapi_outb() writes 'byte' to 'port'.                             *
! * Note: This function does nothing on the simulated RTOS.              *
! * Note: Many platforms provide an inline outb() that is faster         */
! 
  extern void rtapi_outb(unsigned char byte, unsigned int port);
  
  
! /** 'rtapi_inb() gets a byte from 'port'.  Returns the byte.           *
! * Note: This function always returns zero on the simulated RTOS.       *
! * Note: Many platforms provide an inline inb() that is faster          */
! 
  extern unsigned char rtapi_inb(unsigned int port);
  
--- 461,475 ----
  ************************************************************************/
  
! /** 'rtapi_outb() writes 'byte' to 'port'.
!     Note: This function does nothing on the simulated RTOS.
!     Note: Many platforms provide an inline outb() that is faster.
! */
  extern void rtapi_outb(unsigned char byte, unsigned int port);
  
  
! /** 'rtapi_inb() gets a byte from 'port'.  Returns the byte.
!     Note: This function always returns zero on the simulated RTOS.
!     Note: Many platforms provide an inline inb() that is faster.
! */
  extern unsigned char rtapi_inb(unsigned int port);