rciScheduling(3)

NAME
rciScheduling -- set scheduling discipline for RCI task.

USAGE
#include <rci.h>

rciScheduling (td, disp, dev)
  RCI_DESC *td;
  int disp;
  int dev;

ARGUMENTS

td --
    Pointer to task descriptor.

disp --
    Scheduling discipline.

dev --
    Used only for tasks running on the arbiter CPU. If the scheduling discipline is ON_FUNCTION or ON_TRIGGER, then this is the file descriptor for the UNIX device which provides the polling interrupt. If the scheduling discipline is ON_SIGNAL, then this is the signal number. Ignored in other cases.

RESTRICTIONS
This routine must be called from the planning level.

DESCRIPTION
This primitive sets the scheduling discipline associated with an RCI control task. There are presently four disciplines, which describe how the task will be scheduled after it has been started by a call to rciStart():

ON_CLOCK --
    Causes the task to be executed periodically at the sample interval/offset specified by rciRate().

ON_FUNCTION --
    Causes the task to be executed whenever a specified wakeup function returns true. This wakeup function must be specified from the control level by the task's startup function, using the call rciWakeupOn() (q.v.). If no function is specified, then the task will never be woken up.

ON_TRIGGER --
    This is similar to ON_FUNCTION in that a wakeup function must be specified, in the startup routine, which will be used as the basis for executing the task. The ON_TRIGGER discipline extends this by making it possible to set up a trigger function which executes at the sample interval/offset specified by rciRate() and which can be used to signal some external process which will (shortly thereafter) wake up the task itself by setting a condition detected by the wakeup function. The ON_TRIGGER discipline hence provides control task timing which is indirectly bound to the system clock; this allows a programmer to exploit parallelism between an external process and the RCI tasks. The trigger itself must be set up by the control functions before each cycle (i.e., during the startup function and every cycle therafter). This is done using the primitive rciSetTrigger() (q.v.).

ON_SIGNAL --
    This discipline is somewhat different from the others in that it causes the task to execute every time a particular UNIX signal is delivered. The task is actually executed by a handler bound to that signal, from within the context of the planning task's UNIX process. This discipline is mainly used for simulation purposes. Tasks using this discipline must be resident on the arbiter CPU. The task startup function must also specify a wakeup function that "notices" the signal, using rciWakeupOn().

    NOTE: There are support functions available for using the the ON_SIGNAL to do task simulation. See simSupport().

The dev argument is used only in the following cases:

1.

    The control task is resident on the arbiter CPU, and either the ON_FUNCTION or ON_TRIGGER disciplines have been specified. In this case, dev should be the file descriptor of a valid RCI device whose interrupt will be used in conjunction with the specified task wakeup function to execute the task. The reason this is necessary is that the arbiter cannot always use the wakeup functions to poll for task execution, since it is busy running UNIX. An RCI device is a UNIX device (driver) which implements a few special RCI ioctls() which give the driver the ability to run an RCI task.

2.  The ON_SIGNAL discipline is specified. In this case, dev is the number of the UNIX signal to which the task is connected. This signal must not be used for other purposes by the program, since RCI will attach its own signal handler to it. The signal number must be a valid UNIX signal number, and may not be SIGHUP or SIGXCPU since these are reserved by RCI.

DIAGNOSTICS
The function returns -1 in the event of failure. Error information is reported on the errorStack (q.v.). Returned error codes are accessible with getErrorCode(). Possible error codes include:

ETaskActive --
    The RCI task is presently active.

ENotDefined --
    Invalid scheduling discipline specified.

ENotAvail --
    Attempt to set up ON_SIGNAL discipline for a task not running on the arbiter CPU.

EBadDev --
    Illegal device specified (bad signal number or device is not a valid RCI device).

EMemory --
    Process is out of memory.

EInternal --
    Internal error condition.

The routine will abort the program if called from the control level.

SEE ALSO
rciRate(3), rciStart(3), rciWakeupOn(3), simSupport(3).