[Emc-commit] rtapi/src/rtapi rtai_rtapi.c,1.1.1.1,1.2 rtapi.h,1.1.1.1,1.2

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

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

Modified Files:
	rtai_rtapi.c rtapi.h 
Log Message:
added documentation to rtapi.h

Index: rtai_rtapi.c
===================================================================
RCS file: /cvsroot/emc/rtapi/src/rtapi/rtai_rtapi.c,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** rtai_rtapi.c	8 Jul 2003 15:54:38 -0000	1.1.1.1
--- rtai_rtapi.c	11 Jul 2003 02:52:43 -0000	1.2
***************
*** 73,76 ****
--- 73,77 ----
    rt_set_periodic_mode();
    start_rt_timer(nano2count((RTIME) nsecs));
+   return 0;
  }

Index: rtapi.h
===================================================================
RCS file: /cvsroot/emc/rtapi/src/rtapi/rtapi.h,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** rtapi.h	8 Jul 2003 15:54:38 -0000	1.1.1.1
--- rtapi.h	11 Jul 2003 02:52:43 -0000	1.2
***************
*** 2,19 ****
  #define RTAPI_H

! /*
!   priorities range from rtapi_prio_lowest() to rtapi_prio_highest(),
!   inclusive. To use this API, use one of two methods:
! 
!   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).
! 
!   Or,
! 
!   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);
--- 2,20 ----
  #define RTAPI_H

! /* The mapping of actual priority to priority number depends on the    */
! /* RTOS.  The 'rtapi_prio_xxxx()' functions provide a portable way to  */
! /* determind priority.  Priorities range from 'rtapi_prio_lowest()'    */
! /* to 'rtapi_prio_highest()', inclusive. To use this API, use one of   */
! /* two methods:                                                        */
! /*                                                                     */
! /* 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)'.                                 */
! /*                                                                     */
! /* Or,                                                                 */
! /*                                                                     */
! /* 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);
***************
*** 22,40 ****
--- 23,190 ----
  extern int rtapi_prio_next_lower(int prio);

+ 
+ /* 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 is only  */
+ /* one hardware clock in the PC, and this call stops and resets it.    */
+ /* So this function only needs to be called once, even if there are    */
+ /* multiple realtime tasks in multiple kernel modules.  Calling this   */
+ /* function after realtime tasks have been started may disrupt the     */
+ /* tasks.  Returns 0 on success, an RTOS specific error code on fail.  */
+ 
  extern int rtapi_clock_set_period(unsigned long int nsecs);

+ /* 'rtapi_task_new()' is the first step in creating a task.  Returns   */
+ /* a pointer to internal rtapi and rtos data that describes the task.  */
+ /* All other calls that relate to the task use this pointer as a task  */
+ /* handle.  Normally called from module init code, may block.  Returns */
+ /* a non-zero task handle on success, zero on failure.                 */
+ 
+ /* FIXME - I want to replace the current declaration with:
+ 
+ typedef struct rtapi_task *rtapi_task_handle;
+ 
+ rtapi_task_handle rtapi_task_new(void);
+ 
+ The typedef permits typechecking on the task handle, while still
+ hiding the internal contents of the structure.  All functions that
+ currently take or return a void pointer to a task would instead
+ take or return a rtapi_task_handle.  The actual code generated is
+ the same, but this form allows compile time type checking.
+ 
+ I will implement the change if/when we reach a concensus that it
+ is a good thing.  John M Kasunich - 7/10/03 */
+ 
  extern void *rtapi_task_new(void);
+ 
+ 
+ /* 'rtapi_task_delete()' is the counterpart to 'rtapi_task_new()'.  It */
+ /* frees memory associated with 'task', and does any other cleanup     */
+ /* needed.  If the task has been started, you must stop it before      */
+ /* deleting it, or bad things might happen.  Returns zero on success,  */
+ /* an RTOS dependent error code on failure.  Call from within module   */
+ /* cleanup code or any _other_ task - a task should not attempt to     */
+ /* delete itself!                                                      */
+ 
+ /* FIXME change to:
+ int rtapi_task_delete( rtapi_task_handle task );
+ */
+ 
  extern int rtapi_task_delete(void *task);

+ 
+ /* 'rtapi_task_start()' does the majority of the work needed to create */
+ /* and run a realtime task.  'task' is a task handle from a call to    */
+ /* rtapi_task_new().  'taskcode' is the name of a function containing  */
+ /* the task code.  '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 use the    */
+ /* same stack.  'period_nsec' is the task period in nanoseconds, which */
+ /* will be rounded to the nearest multiple of the global clock period. */
+ /* If non-zero, 'uses_fp' tells the OS that 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 1.  If a task definitely does not use */
+ /* floating point, setting 'uses_fp' to zero saves a few microseconds  */
+ /* on each task switch.  Returns zero on success, an RTOS dependent    */
+ /* error code on failure.  call from module init code (preferred) or   */
+ /* within a realtime task.  May block.                                 */
+ 
+ /* FIXME - Fred, you have code in the implementations of this function
+ that takes special action when 'period_nsec' is zero.  What did you have
+ in mind with that?  Non-periodic tasks that simply run until they either
+ return, pause, wait, or block?
+ */
+ 
+ /* FIXME - change to:
+ extern int rtapi_task_start(rtapi_task_handle task,
+ 				void (*taskcode)( int ),
+ 				int arg,
+ 				int prio,
+ 				unsigned long int stacksize,
+ 				unsigned long int period_nsec,
+ 				unsigned char uses_fp);
+ 
+ This declares 'taskcode' as a 'pointer to function taking one int and
+ returning void', which lets the compiler make sure it is really a
+ valid function.  Adding 'arg' lets the task init code pass a parameter
+ to the realtime task code, which can be cast to a pointer to any kind
+ of data structure that might be needed.  Can be useful for letting the
+ task code know where shared memory is located.
+ */
+ 
  extern int rtapi_task_start(void *task, void *taskcode, int prio,
  			    unsigned long int stacksize,
  			    unsigned long int period_nsec,
  			    unsigned char uses_fp);
+ 
+ /* 'rtapi_task_stop()' is the counterpart to 'rtapi_task_start()'.  It */
+ /* permanently stops 'task', and prepares it to be deleted.  Returns   */
+ /* zero on success, and an RTOS dependent error code on failure.  Call */
+ /* from within module cleanup code or any _other_ task - a task should */
+ /* not attempt to stop itself!                                         */
+ 
+ /* FIXME - change to:
+ extern int rtapi_task_stop(rtapi_task_handle task );
+ */
+ 
  extern int rtapi_task_stop(void *task);
+ 
+ 
+ /* 'rtapi_task_pause() causes 'task' to temporarily stop execution.    */
+ /* It will resume when 'rtapi_task_resume()' is called with the same   */
+ /* task handle.  Returns zero on success, an RTOS dependent error code */
+ /* on failure.  A task can pause itself, but obviously cannot resume   */
+ /* itself.  Note:  depending on the RTOS, multiple 'pauses' may or may */
+ /* not be canceled by a single 'resume'.  To be safe, don't pause a    */
+ /* task more than once.                                                */
+ 
+ /* FIXME - we could modify the wrapper function to keep track of pauses
+ and resumes, and consistently provide one behavior or the other, instead
+ of leaving it RTOS dependent.
+ */
+ 
+ /* FIXME - change to:
+ extern int rtapi_task_pause(rtapi_task_handle task);
+ extern int rtapi_task_resume(rtapi_task_handle task);
+ */
+ 
  extern int rtapi_task_pause(void *task);
  extern int rtapi_task_resume(void *task);
+ 
+ /* 'rtapi_task_set_period()' and 'rtapi_self_set_period()' are used to */
+ /* change the period of a task.   The new period is 'period_nsec',     */
+ /* rounded to the nearest integer multiple of the global period as set */
+ /* by 'rtapi_clock_set_period()'.  Returns zero on success, an RTOS    */
+ /* dependent error code on failure.                                    */
+ 
+ /* FIXME - consider deleting the 'self' version of this function, and
+ instead provide a function that returns the handle of the current task,
+ like this:
+ rtapi_task_handle rtapi_self(void);
+ 
+ That's a more generic way to allow a task to call any rtapi function
+ on itself.
+ */
+ 
+ /* FIXME - replace with:
+ 
+ extern int rtapi_task_set_period(rtapi_task_handle task,
+ 				unsigned long int period_nsec);
+ */
+ 
  extern int rtapi_task_set_period(void *task, unsigned long int period_nsec);
  extern int rtapi_self_set_period(unsigned long int period_nsec);
+ 
+ /* 'rtapi_wait()' suspends execution of the current task until the     */
+ /* next period.  At the beginning of the next period, execution will   */
+ /* resume immediately after the call to 'rtapi_wait()', instead of at  */
+ /* beginning of the 'taskcode' function.  Returns zero on success, and */
+ /* an RTOS dependent errorcode on failure.  Call only from a task.     */
+ 
  extern int rtapi_wait(void);
+ 
+ /* FIXME - need to continue documentating the rest of the API */

  extern int rtapi_alloc_shmem(int key, unsigned int size, int *id, void **ptr);