\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{controlFxns}{7}
\manSection{NAME}
{\tt \manName{controlFxns}}
-- description of the RCI task control functions.
\manSection{USAGE}
This man page describes how RCI control task functions 
(as set up by {\tt rciControlFxns()}) are called by the task monitor.
The functions associated with an RCI control task are called by the monitor 
with the following arguments:
\cverbatim

startup(td, arg)
   RCI_DESC *td;
   int arg;

control(td, arg)
   RCI_DESC *td;
   int arg;

release(td, arg, code)
   RCI_DESC *td; 
   int arg, code; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt td} --}
Pointer to task descriptor of the current RCI task.
\manItem{{\tt arg} --}
User specified argument.
\manItem{{\tt code} --}
Code indicating the nature of the release condition.
\manSection{DESCRIPTION}
This man page gives a detailed description of the way in which the
RCI task control functions interface to the
rest of the system. 

The control functions are called during an RCI control session.
The sequence in which they are called during the control session
is described in the following piece of pseudo code:

\cverbatim
        controlSession:

                startup(td, arg);
 
                while (task not released)
                 { if (task ready)
                    { control(td, arg);
                    }
                 }
        release:
                release(td, arg, code); @endcverbatim

Superimposed on the above code is the following error behaviour:
if the monitor detects an error, such as a timeout or an abort
by another task, then it does a
``{\tt goto release}'' as soon as no control functions are running. The
release function determines the nature of the release condition (i.e.,
a normal release request or some sort of error) by examining its second
argument {\tt code} (described below).

Each control function is called with the task descriptor {\tt td} 
and a user specified function value as arguments.
Much of the information used by that function is obtained by making
appropriate references to that task descriptor. This includes the parameters
and scratch variables in the task control block ({\tt RCI_TCB}, q.v.), and
the structure describing the I/O device (see {\tt IOdevice(3)}).
In addition, if robots are attached to the task,
robot descriptors can be be obtained with the macro 
{\tt TASKROBOT(td, num)}, where {\TT num} is the index of the
attached robot within the task (returned from the call 
{\tt rciAttachRobot()}).
Given the task descriptor {\tt td},
the following constructions may be used
to obtain the various structures:

\cverbatim
   RCI_TCB *tcb;        /* task control block */
   IO_DEVICE *dev;      /* IO device */
   RCI_RBT *rbt;        /* a robot structure */
   HOW *how;            /* a HOW structure */
   JLS *jls;            /* a joint level structure */
   KYN *kyn;            /* a robot dependent kyn structure */
   void *var;           /* a robot dependent var structure */

   /* for any task ... */

   tcb = TASKTCB(td);
   dev = TASKDEV(td);

   /* and for one with an attached robot ... */

   rbt = TASKROBOT(td, num);
   how = rbt->how;
   jls = rbt->jls;
   kyn = rbt->kyn;
   var = rbt->var; @endcverbatim

The {\tt startup} function is used to initialize attached devices, set up data
structures, and obtain pointers to shared memory (created by the
planning task) using the 
{\tt getSharedMemory()} or {\tt getGlobalMemory()} calls. Pointers to shared
regions, once obtained, can be stored for quick access in the
{\tt sharedMem} and {\tt globalMem} fields of the task control block.
Private memory, allocated out of memory local to the control task,
can be stored in the {\tt privateMem} field. These fields are cleared
at the end of the control session.

The {\tt control} function is the ``bread and butter''
control function. It is called once per control cycle, and does
I/O and calls the interface functions for any attached robots.

Fields in the task control block that are of immediate interest to
the control function include the {\tt cycleCount}, and the flag
{\tt newRate}, which is set whenever the control cycle rate is changed
with the {\tt rciRate()} primitive. The new interval and offset
can then be obtained from the {\tt interval} and
{\tt offset} fields. {\tt newRate} is cleared at the end of the control cycle
during which it was set.

The {\tt release} function is responsible for ``closing up shop'' when the
task is released. Reasons for tasks being released include error conditions
or a normal release request caused by a call to {\tt rciRelease()} in the
planning task. The release function can determine the nature of the release
condition by examining an integer code which is passed to it as a 
second argument. The possible values of {\tt code}, defined
in {\tt <rciMonitor.h>}, are:

\manItem{{\tt RELEASE_REQ} --}
Normal release; {\tt rciRelease()} called from planning task.
\manItem{{\tt EXTERNAL_ABORT} --}
Abort issued by another task.
\manItem{{\tt RUN_TIMEOUT} --}     
Control task took too long to execute (the check for this condition is not
currently implemented).
\manItem{{\tt BLK_TIMEOUT} --}     
Control task had to wait too long to wake up.
\manItem{{\tt LAG_TIMEOUT} --}     
Task far too far behind schedule.
\manItem{{\tt STARTUP_FXN_ERR} --}     
Abort was issued inside the task's startup function.
\manItem{{\tt CONTROL_FXN_ERR} --}     
Abort was issued inside the task's control function, or during a function
called with {\tt rciExecute()}.

\manSection{DIAGNOSTICS}

Errors that occur at the control level generally result in an abort
condition being raised through a call to {\tt rciAbort()}. The abort condition
can be raised either by the monitor or by the control functions themselves.

Abort codes that are generated by the monitor are:

\manItem{{\tt ERunTimeout} --}
Task took too long to execute.
\manItem{{\tt EBlkTimeout} --}
Task had to wait too long to run.
\manItem{{\tt ELagTimeout} --}
Task fell too far behind schedule.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt HOW(3)}, {\tt CHG(3)}, {\tt JLS(3)}, {\tt RCI_TCB(3)}, {\tt
IOdevice(7)}, {\tt rciAbort(3)}, {\tt rciControlFxns(3)},
{\tt rciAttachRobot(3)}, {\tt TASKROBOT(3)}, {\tt rbtComfxns(7)}.
\manEnd
\end
