|
From: <jmk...@us...> - 2003-07-11 02:52:46
|
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);
|