#!/bin/sh cat >jobCreate.3 <<'------ EOF ------' .TH jobCreate 3 "" "TCP Manual" .ad b .SH NAME jobCreate - create a new job structure .SH SYNOPSIS .CS .nf JOB_ID jobCreate (name, pri, func, arg1, arg2, arg3, arg4) char *name; /* job title/name */ short pri; /* job priority (highest = 0) */ FUNCPTR func; /* ptr to procedure */ ULONG arg1,arg2; /* procedure arguments*/ ULONG arg3,arg4; .fi .CE .SH DESCRIPTION A job is a procedure that is run by a jobDaemon task. It is analagous to a lightweight task. Inactive jobs don't consume task resources. Jobs are processed by the jobDaemon tasks, of which there will be several. Those tasks continually scan the job queues and execute any jobs that they find. A job is a singularity. It is not considered re-entrant (although good programming practice is to always try for re-entrancy). If a job needs to be re-scheduled while it is currently executing, then the scheduling is deferred until processing is complete, and then it is placed onto the tail of it's priority list. .SH RETURNS Returns NULL upon failure. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobCreate.3 cat >jobDaemon.3 <<'------ EOF ------' .TH jobDaemon 3 "" "TCP Manual" .ad b .SH NAME jobDaemon - The main loop for job processor tasks .SH SYNOPSIS .CS .nf VOID jobDaemon () .fi .CE .SH DESCRIPTION This is the main line code for each of the job processor tasks. Each processor runs continuously scanning the job priority lists for a job. When a job is located, the processor executes the job and scans for another job. If there are no jobs at all then the processor task sleeps on the job semaphore until a new job is added to the lists. .SH PROBLEMS We are doing taskPrioritySet to change priority levels often. I don't know how much of a performance penalty this is costing. It might be that this is very costly, it may require the kernel to reshuffle all the tasks and all the lists and a lot more. If you can, try the time slicing option and compare the performance. .SH NOTES FppReset() is called between jobs to reduce the overhead of fpp context save/restore for jobs that don't use floating point math. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobDaemon.3 cat >jobDelay.3 <<'------ EOF ------' .TH jobDelay 3 "" "TCP Manual" .ad b .SH NAME jobDelay - schedule a job after a delay .SH SYNOPSIS .CS .nf STATUS jobDelay (pJob, ticks) JOB_ID pJob; /* job pointer */ TICKS ticks; /* delay interval */ .fi .CE .SH DESCRIPTION The specified job is queued for execution after the specified clock delay has elapsed. .SH RETURNS Returns ERROR if the job system is not initialized., or if the input job pointer is invalid. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobDelay.3 cat >jobDelayTill.3 <<'------ EOF ------' .TH jobDelayTill 3 "" "TCP Manual" .ad b .SH NAME jobDelayTill - queue a job at a specified time .SH SYNOPSIS .CS .nf STATUS jobDelayTill (pJob, time) JOB_ID pJob; /* job pointer */ TICKS time; /* clock tick for queueing */ .fi .CE .SH DESCRIPTION The specified job is queued for execution at a specified clock time. .SH RETURNS Returns ERROR if the job system is not initialized., or if the input job pointer is invalid. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobDelayTill.3 cat >jobExecute.3 <<'------ EOF ------' .TH jobExecute 3 "" "TCP Manual" .ad b .SH NAME jobExecute - execute a job .SH SYNOPSIS .CS .nf VOID jobExecute (pJob) JOB *pJob; .fi .CE .SH DESCRIPTION Execute a job, removing it from any job queues and then disposing of the job after completion of the user's routine. The re-entrancy control mechanism is very simple minded and should be replaced. There is a subtle difference between 'jobQue' and 'jobexecute'. If you use 'jobQue' while a job is already being executed, then it will be re-queued after completion. 'jobExecute' will not cause a job to be re-queued if jobExecute is called while the job is already in execution. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobExecute.3 cat >jobFree.3 <<'------ EOF ------' .TH jobFree 3 "" "TCP Manual" .ad b .SH NAME jobFree - Cancel and release a job structure .SH SYNOPSIS .CS .nf STATUS jobFree (pJob) JOB_ID pJob; /* job no longer needed */ .fi .CE .SH DESCRIPTION This routine returns a no longer needed job structure back to the memory manager system. .SH RETURNS Returns ERROR upon invalid input, OK for all other conditions. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobFree.3 cat >jobLib.2 <<'------ EOF ------' .TH jobLib 2 "" "TCP Manual" .ad b .SH NAME jobLib.c - Library module for job objects .SH SYNOPSIS .nf jobSysInit - Create and initialize the jobLib system jobDaemon - The main loop for job processor tasks jobExecute - execute a job jobCreate - create a new job structure jobFree - Cancel and release a job structure jobQue - Queue a job on a jobList jobDelay - schedule a job after a delay jobDelayTill - queue a job at a specified time jobSemGet - que job upon semaphore jobListCreate - create a jobList structure, returns pointer jobListFree - destroy a jobList structure jobListProcess - queue the jobs on a job list jobListAdd - add a job onto a jobList jobListDelete - delete a job from a jobList jobListInit - initialize (clear) a jobList jobListCount - return number of jobs on a jobList jobListLock - lock a jobList (exclusive access) jobListUnlock - release exclusive control of a jobList jobListFirst - return a pointer to first job on a jobList jobListLast - return pointer to last job on a jobList jobListNext - return pointer to next job jobListPrev - return pointer to previous job on list jobListGet - get and remove the first job from a jobList jobListAddAfter - add a job into a jobList at a specified position STATUS jobSysInit (levels, procs, size, pri, slice) VOID jobDaemon () VOID jobExecute (pJob) JOB_ID jobCreate (name, pri, func, arg1, arg2, arg3, arg4) STATUS jobFree (pJob) STATUS jobQue (pJob) STATUS jobDelay (pJob, ticks) STATUS jobDelayTill (pJob, time) STATUS jobSemGet (pJob, pSem) JOB_LIST *jobListCreate () VOID jobListFree (pList) VOID jobListProcess (pList) STATUS jobListAdd (pList, pJob) STATUS jobListDelete (pList, pJob) VOID jobListInit (pList) int jobListCount (pList) VOID jobListLock (pList) VOID jobListUnlock (pList) JOB_ID jobListFirst (pList) JOB_ID jobListLast (pList) JOB_ID jobListNext (pJob) JOB_ID jobListPrev (pJob) JOB_ID jobListGet (pList) VOID jobListAddAfter (pList, oldJob, newJob) .fi .SH DESCRIPTION The jobLib system is a group of non-dedicated tasks that continuously scan a prioritized list looking for jobs to be executed. A job is a function pointer with up to 4 arguments. Ideally a job should be a short function that does not do an excessive amount of task idling. Jobs can be scheduled by the system clock or a semaphore. A job is a single entity and has only 4 states: inactive, pending, queued, and in-progress. The jobQue routine places a job in the queued condition. If jobQue is called many times while the job is already queued the job will only be executed once. Note that if a job is already in-progress when jobQue is executed, the job will immediately be placed back in the queued condition when execution is completed. (It goes back to the end of its priority waiting list). A pending job is one that is awaiting a system clock time, or waiting for a semaphore to be given. When the event occurs the job is placed into the job que for immediate execution. Job priority levels are relative to a base level priority set during the jobSysInit routine. Job priority level 0 is the highest job priority. It is expected that the number of job priority levels will be small (less than 8). Each priority level has a separate list of pending jobs. The separate lists approach eliminates sorting of jobs by priority. Each separate list acts as a FIFO. The jobSysInit call should only be made once. It establishes the number of processors tasks and the priority lists used by this system. The jobSysInit argument 'slice' will, if non-zero, cause all job processors to run at a single priority level. The jobs will be fetched out of the job queues in priority order, but the processor tasks all run at a single priority level, with round-robin scheduling in effect. If this option is desired, specify slice to be the number of clock ticks per interval. You may want to try running your application both ways and comparing the performance. (Applicable only to the VRTX kernel). ------ EOF ------ ls -l jobLib.2 cat >jobListAdd.3 <<'------ EOF ------' .TH jobListAdd 3 "" "TCP Manual" .ad b .SH NAME jobListAdd - add a job onto a jobList .SH SYNOPSIS .CS .nf STATUS jobListAdd (pList, pJob) JOB_LIST *pList; JOB_ID pJob; .fi .CE .SH DESCRIPTION The specified job is added to the specified jobList. .SH SEE ALSO jobLib(2), lstAdd(2) ------ EOF ------ ls -l jobListAdd.3 cat >jobListAddAfter.3 <<'------ EOF ------' .TH jobListAddAfter 3 "" "TCP Manual" .ad b .SH NAME jobListAddAfter - add a job into a jobList at a specified position .SH SYNOPSIS .CS .nf VOID jobListAddAfter (pList, oldJob, newJob) JOB_LIST *pList; /* list to be updated */ JOB_ID oldJob; /* job already on list */ JOB_ID newJob; /* job to be added, after oldJob */ .fi .CE .SH DESCRIPTION The new job is added to the jobList just following the old job. If old job is NULL, the new job is inserted at the front of the jobList. .SH SEE ALSO jobLib(2), lstInsert(2) ------ EOF ------ ls -l jobListAddAfter.3 cat >jobListCount.3 <<'------ EOF ------' .TH jobListCount 3 "" "TCP Manual" .ad b .SH NAME jobListCount - return number of jobs on a jobList .SH SYNOPSIS .CS .nf int jobListCount (pList) JOB_LIST *pList; .fi .CE .SH DESCRIPTION The number of jobs on a specified jobList is returned as the value of this function. .SH SEE ALSO jobLib(2), lstCount(2) ------ EOF ------ ls -l jobListCount.3 cat >jobListCreate.3 <<'------ EOF ------' .TH jobListCreate 3 "" "TCP Manual" .ad b .SH NAME jobListCreate - create a jobList structure, returns pointer .SH SYNOPSIS .CS .nf JOB_LIST *jobListCreate () .fi .CE .SH DESCRIPTION A new jobList structure is created and initialized. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobListCreate.3 cat >jobListDelete.3 <<'------ EOF ------' .TH jobListDelete 3 "" "TCP Manual" .ad b .SH NAME jobListDelete - delete a job from a jobList .SH SYNOPSIS .CS .nf STATUS jobListDelete (pList, pJob) JOB_LIST *pList; JOB_ID pJob; .fi .CE .SH DESCRIPTION The specified job is removed from the specified jobList. .SH SEE ALSO jobLib(2), lstDelete(2) ------ EOF ------ ls -l jobListDelete.3 cat >jobListFirst.3 <<'------ EOF ------' .TH jobListFirst 3 "" "TCP Manual" .ad b .SH NAME jobListFirst - return a pointer to first job on a jobList .SH SYNOPSIS .CS .nf JOB_ID jobListFirst (pList) JOB_LIST *pList; .fi .CE .SH DESCRIPTION The job pointed to by the return value remains on the specified jobList. .SH SEE ALSO jobLib(2), lstFirst(2) ------ EOF ------ ls -l jobListFirst.3 cat >jobListFree.3 <<'------ EOF ------' .TH jobListFree 3 "" "TCP Manual" .ad b .SH NAME jobListFree - destroy a jobList structure .SH SYNOPSIS .CS .nf VOID jobListFree (pList) JOB_LIST *pList; .fi .CE .SH DESCRIPTION The jobList should be empty before calling this routine. Any jobs on the list will not be free'd and will not be recovered. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobListFree.3 cat >jobListGet.3 <<'------ EOF ------' .TH jobListGet 3 "" "TCP Manual" .ad b .SH NAME jobListGet - get and remove the first job from a jobList .SH SYNOPSIS .CS .nf JOB_ID jobListGet (pList) JOB_LIST *pList; .fi .CE .SH DESCRIPTION A pointer to the first job of a jobList is returned. The job is removed (unlinked) from the list. .SH SEE ALSO jobLib(2), lstGet(2) ------ EOF ------ ls -l jobListGet.3 cat >jobListInit.3 <<'------ EOF ------' .TH jobListInit 3 "" "TCP Manual" .ad b .SH NAME jobListInit - initialize (clear) a jobList .SH SYNOPSIS .CS .nf VOID jobListInit (pList) JOB_LIST *pList; .fi .CE .SH DESCRIPTION The specified jobList is initialized. .SH SEE ALSO jobLib(2), lstInit(2) ------ EOF ------ ls -l jobListInit.3 cat >jobListLast.3 <<'------ EOF ------' .TH jobListLast 3 "" "TCP Manual" .ad b .SH NAME jobListLast - return pointer to last job on a jobList .SH SYNOPSIS .CS .nf JOB_ID jobListLast (pList) JOB_LIST *pList; .fi .CE .SH DESCRIPTION A pointer to the last job on a jobList is returned. The job remains on the list. .SH SEE ALSO jobLib(2), lstLast(2) ------ EOF ------ ls -l jobListLast.3 cat >jobListLock.3 <<'------ EOF ------' .TH jobListLock 3 "" "TCP Manual" .ad b .SH NAME jobListLock - lock a jobList (exclusive access) .SH SYNOPSIS .CS .nf VOID jobListLock (pList) JOB_LIST *pList; .fi .CE .SH DESCRIPTION The specified job is locked to prevent access by other tasks/jobs. .SH SEE ALSO jobLib(2), semTake(2) ------ EOF ------ ls -l jobListLock.3 cat >jobListNext.3 <<'------ EOF ------' .TH jobListNext 3 "" "TCP Manual" .ad b .SH NAME jobListNext - return pointer to next job .SH SYNOPSIS .CS .nf JOB_ID jobListNext (pJob) JOB_ID pJob; .fi .CE .SH DESCRIPTION Given a pointer to a job (from a jobList). This routine returns a pointer to the next job on the list. A null pointer is returned if it is the last job on the list. .SH SEE ALSO jobLib(2), lstNext(2) ------ EOF ------ ls -l jobListNext.3 cat >jobListPrev.3 <<'------ EOF ------' .TH jobListPrev 3 "" "TCP Manual" .ad b .SH NAME jobListPrev - return pointer to previous job on list .SH SYNOPSIS .CS .nf JOB_ID jobListPrev (pJob) JOB_ID pJob; .fi .CE .SH DESCRIPTION Given a pointer to a job (from a jobList). This routine returns a pointer to the previous job on the list. A null pointer is returned if it is the first job on the list. .SH SEE ALSO jobLib(2), lstPrev(2) ------ EOF ------ ls -l jobListPrev.3 cat >jobListProcess.3 <<'------ EOF ------' .TH jobListProcess 3 "" "TCP Manual" .ad b .SH NAME jobListProcess - queue the jobs on a job list .SH SYNOPSIS .CS .nf VOID jobListProcess (pList) JOB_LIST *pList; .fi .CE .SH DESCRIPTION A jobList is scanned. All jobs on the list are queued for execution. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobListProcess.3 cat >jobListUnlock.3 <<'------ EOF ------' .TH jobListUnlock 3 "" "TCP Manual" .ad b .SH NAME jobListUnlock - release exclusive control of a jobList .SH SYNOPSIS .CS .nf VOID jobListUnlock (pList) JOB_LIST *pList; .fi .CE .SH DESCRIPTION Releases exclusive control of the specified jobList. .SH SEE ALSO jobLib(2), semGive(2) ------ EOF ------ ls -l jobListUnlock.3 cat >jobQue.3 <<'------ EOF ------' .TH jobQue 3 "" "TCP Manual" .ad b .SH NAME jobQue - Queue a job on a jobList .SH SYNOPSIS .CS .nf STATUS jobQue (pJob) JOB_ID pJob; /* job pointer */ .fi .CE .SH DESCRIPTION This routine activates a job by placing it on one of the prioritized lists of pending jobs. If the job is already in a pending condition then nothing at all is done. If the job is currently in execution by one of the jobDaemon processor tasks, then a flag is set that will cause the jobDaemon to queue the job immediately upon completion. .SH RETURNS Returns ERROR if the job system is not initialized., or if the input job pointer is invalid. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobQue.3 cat >jobSemGet.3 <<'------ EOF ------' .TH jobSemGet 3 "" "TCP Manual" .ad b .SH NAME jobSemGet - que job upon semaphore .SH SYNOPSIS .CS .nf STATUS jobSemGet (pJob, pSem) JOB_ID pJob; /* job pointer */ SEM_ID pSem; /* semaphore pointer */ .fi .CE .SH DESCRIPTION The specified job is queued for execution when the specified semaphore is available. This is not a true semaphore operation since the semaphore is monitored only during the system clock tick handling routine. There is no task pending on the semaphore, just constant monitoring of the semaphore contents. If the semaphore is in heavy use by different tasks, and not just job's, then it is best not to use this routine. Create a job that does a direct 'semTake' on the semaphore instead. In that, way the job processor task is directly pending on the semaphore. Be very careful when using this routine. Note also that while the scheduler will 'take' the semaphore when it is available, there is no automatic 'give' operation when the job is finished. If this is a resource semaphore then the job routine should terminate with a 'semGive' function. .SH RETURNS Returns ERROR if the job system is not initialized., or if the input job pointer is invalid. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobSemGet.3 cat >jobSysInit.3 <<'------ EOF ------' .TH jobSysInit 3 "" "TCP Manual" .ad b .SH NAME jobSysInit - Create and initialize the jobLib system .SH SYNOPSIS .CS .nf STATUS jobSysInit (levels, procs, size, pri, slice) int levels; /* number of priority levels */ int procs; /* number of processor tasks */ int size; /* stack size for processors */ int pri; /* VxWorks priority for level '0' */ int slice; /* time slicing option, clock ticks */ .fi .CE .SH DESCRIPTION The job system must be initialized before any jobs can be queued. Most job system parameters are set as arguments to this routine. There are limits to the number of priority levels and the number of processor tasks that can be created (see the source code). The time slicing option determines if the processor (daemon) tasks use taskPrioritySet() to change their priority levels before beginning job execution. If a positive slice value is given then time slicing is initiated and all daemon tasks actually run at a single priority level. The job queues remain prioritized and jobs are still fetched from the queues in priority order. .SH ERRORS An error value is returned if any failures are detected during the process, if any arguments exceed the maximum limits, or if the system has already been initialized. .SH SEE ALSO jobLib(2) ------ EOF ------ ls -l jobSysInit.3