This directory contains the files which constitute the RCI system.
RCI (Real time control interface) is a package that allows the creation
of real time control tasks connected to a UNIX process.

Files which contain an `SGI' in the prefix are specific to SGI
system implementations. Files which contain a `vxw' in the prefix
are specific to VxWorks implementations.

A rough description of the files in this directory follows:

Files which contain a '.vxw' at the end denote implementations
specific to vxWorks systems.

abort.h
	Definition of information message used by rciAbort().

accessMem.c
	Control level routines to access memory objects defined by
	routines in allocMem.c

allocMem.c
	Routines to allocate named (or unnamed) chunks of global memory
	that can be shared between RCI tasks.

amtest
	Test program for the memory object package (built from
	allocMem.c with -DTEST)

amtest1CPU.cts
	Script to run on amtest for a single CPU implementation.

amtest2CPU.cts
	Script to run on amtest for a double CPU implementation.

arbMonitor.c
	UNIX level code which interfaces with RCI device drivers and
	provides the functions which allow an RCI control task to be
	run on the arbiter CPU.

atomicOps.c
atomicOps.vxw.c
atomicOps.SGI.c
	Routines to do test-and-set and block copying atomically, using
	the mutual exclusion algorthims provioded in mutex.c.

attachRobot.c
	The routines rciAttachRobot() and rciDetachRobot(), which allocate
	the data structures and interface drivers used in attaching a 
	robot to an RCI control task.

auxBoot.c
	Routines used to boot the minikernel on the auxiliary CPUs.
	These are CPUs configured into the same backplane as the UNIX
	(arbiter) CPU. The present implementation assumes that the system
	is comprised of microVAX CPUs on a common Q-bus. The minikernel
	that is loaded into the auxiliary CPUs resides in the directory
	$RCCL/auxkernel.
	
auxMonitor.c
	Code executed on the auxiliary processors after they are downloaded.

auxShare.c
	Declarations of shared variables used in communicating between the
	RCI planning task primitives and the control task monitors.

auxkernStubs.c
	For systems that don't have the auxiliary CPU kernel defined (and so
	don't need to use its interface functions), this file defines the
 	appropriate stub routines.

begin.c
	Defines one text object (_RCIT_begin) and one data object
	(_RCId_begin) that are to delimit the beginning of the text and data
	segments used by the RCI control level.

buddyalloc.c
	A memory allocator which works using the buddy system. The allocator
	consists of the routines buddyAlloc() and buddyFree(), as well
	as buddyAllocInit(), which takes a user specified memory area
	and granularity specifications and turns it into a pool to be
	used by the other allocation primitives.

buddyalloc.h
	Definition of the ``pool'' descriptor used by the buddy allocation
	routines.

clockFxns.c 
clockFxns.vxw.c
clockFxns.SGI.c
	Interface routines to the RCI system clock.

cpuAlloc.c
	Routines to allocate and deallocate CPUs.

crashMessage.c
	The routine crashMessage(), which prints of diagnostic crash
	information which is returned through the UNIX kernel whenever
	a program crash occurs in one of the control tasks, executing
	either on the arbiter or one one of the auxiliary CPUs. This

crashinfo.h
	Includes the appropriate file to define the CRASHINFO structure
	for a particular TARGET system. CRASHINFO structures are used to
	return exception information when the control task dies at the
	kernel level. Consequently, they are only really needed on Sun4
	and uVAX systems where the control task is in fact run in kernel
	mode.

create.h
	Defines the data structures used to communicate task creation
	information between the RCI planning level primitives and the
	task monitors.

descriptor.c
	Routines used to obtain descriptors and names for RCI tasks
	or attached robots.

download.c
	Code which downloads program code into an auxiliary CPU once
	it has been booted.

end.c
	Defines one text object (_RCIT_end) and one data object
	(_RCId_end) that are to delimit the beginning of the text and data
	segments used by the RCI control level.

firstAlloc.h
firstAlloc.c
	A first-fit memory allocator package, hijacked from BSD 4.1

getMemory.c
	Routines to obtain pointers to shared memory sections, either
	by name or by reference to the address seen by the planning task.

hashRef.c 
hashSetup.c
hashTable.h
	A set of routines to implement the hash table used by the RCI
	memory allocation functions. Hash table creation and maintenance
	is done by routines in hashSetup.c; this is done strictly at the
	planning level. Access to the hash table is done by routines defined
	in hashRef.c; these can be called from either the control or
	planning level.

hostExec.c
hostExec.vxw.c
hostExec.SGI.c
	Routines to execute single functions in kernel mode, either "raw",
	or within the context of an RCI control task.

hostFxns.c
hostFxns.vxw.c
hostFxns.SGI.c
	Main interface routines between RCI and the system support code
	on the arbiter CPU.

inline.sed
	A sed script for generating inline code for splx(), splhigh(),
	and bcopy(). This make programs run faster.

interruptRef.c
	Routines to utilize and interrupt device for an RCI task. An interrupt
	device must be specified for an RCI task which is running on the
	arbiter CPU using either the ON_FUNCTION or ON_TRIGGER disciplines.
	The interrupt is a polling interrupt which causes the task
	monitor to execute and poll to see if the task is runable. Polling
	interrupts are not needed on the auxiliary CPUs because they can
	always poll in a loop.

interruptDev.h
	Definition of data structure used by the polling interrupt and
	signal referencing routines.

levelCheck.c
	A routine to check whether we are executing at the control
	level or the planning level.

link.h
	Macros for maintaining double circular linked lists.

loadRobot.c
	Routines used by rciAttachRobot() and rciDetachRobot() to
	manage the robot specific data structures across the RCI CPUs.

loadRobot.h
	Data structures used to communicate robot setup information
	between the RCI planning level primitives and the control task
	monitors.

loadtask.c
	Various routines used by rciCreate() in creating, or importing,
	control tasks on either the arbiter or auxiliary CPUs.

locateMemory.c
	Routines to find addresses for various RCI shared memory 
	structures.

lockMemory.c
	Wrapper routines for whatever memory locking primitives  
	are available on the system.

lockRobot.c
	Routines to create a lock file for a robot in the directory
	$RCCL/lock, to ensure that different RCI tasks (within or
	without the same program) do not try to attach the same robot.

maskInterrupts.h
	Macros to block and unblock soft interrupts at the control
	level. Used mainly to implement mutual exclusion within the
	same CPU.

mask.sun4.S
	SUN 4 assembly routines to do things like raise and lower processor
	priority, set jump and long jump, etc.

memory.c
	A test program that allocates HUGE amounts of memory to test the
	RCI paging code.

message.c
	The RCI message passing primitives.

messageDefs.h
	Data structures used by the message passing primitives.

monitor.c
	The execution code for the RCO control task monitors. There
	is one monitor per CPU, and it is responsible for calling the
	functions that comprise a control task when they become
	runable.

monitorCom.c
	Routines to execute specific commands sent to a control monitor
	from the planning level.

monitorCom.h
	Information data structures associated with the different control
	monitor commands.

monitorDefs.h
	Internal data structures used by the monitor code.

monitorSubs.c
	Support routines for the RCI control task monitors.

mutex.c
	Routines to implement mutual exclusion among multiple CPUs,
	without having an inter-CPU test-and-set facility. These routines
	right now assume that the number of CPUs is set at a maximum of 4,
	which reflects the max. no. of microVAX CPUs that can be configurerd
	into a Q-bus system.

mxtest
mxtest.c
mxtest.h
mxtestCtrl.c
	Program to test the mutual exclusion primitives.
	
noticeBuf.c
	Access routines to the notice buffer, used by the message passing
	utility.

parameterDefs.c
	Routines to access and set RCI parameters.

parameterFile.c
	Routine to read in default RCI parameters from the various
	.rciparams files.

parameters.h
	Data structure used in maintaining RCI parameters.

primitives.c
	Most of the basic RCI task control primitives, such as rciRate(),
	rciScheduling(), and rciTimeout().

procs
procs.c
	Program to start lots of processes and drive up the system load,
	to test the robustness of RCI.

rateTest
rateTest.c
rateTest.h
rateTestCtrl.c
	Program to estimate the rate at which the RCI clock is running.

rbtcom
rbtcom.c
rbtcom.h
rbtcomCtrl.c
	Program to test the raw communication with a particular robot.
	The communication can be set to various rates, and can be run using
	CLOCK, TRIGGER, or FUNCTION scheduling.

rbtcomFail.cts
	Test script for use with rbtcom to test various failure modes in the
	communication interface.

rbttest
rbttest.c
rbttest.h
rbttestCtrl.c
	Program to test the robot control interface with different robots.

rciAbort.c
	Code to implement the abort function rciAbort(). 

rciAutoAbort.h
	Defines a return macro for routines which honor the EXIT_ON_ERROR
	option.

rciCheck.c
rciCheck.h
rciCheckCtrl.c
	Automatic test program to verify that the most basic RCI system
	support is working.

rciConfig.c
	Configuration file.

rciCreate.c
	Defines the routine rciCreate(), which creates an RCI control task on
	either an arbiter or auxiliary CPU.
	
rciGlobalMem.c
	Routines to set up RCI shared memory sections.

rciSetOptions.c
	Routines to set various RCI control options.

rcitest
rcitest.c
rcitest.h
rcitestCtrl.c
	Interactive program to test the various RCI primitives.

rcitest1CPU.cts
	Test script for rcitest, meant for single CPU systems.

rcitest2CPU.cts
	Test script for rcitest, meant for double CPU systems.

remoteMemory.c
	Routines used by the sharedMemory.c, loadtask.c, and loadRobot.c
	which allocate blocks of memory on the various CPUs and also
	perform the necessary manipulations to allow them to be shared
	across CPUs.

robotDefs.c
	Routines to access information describing the default interface
	device and polling interrupt for each robot.

robotDefs.h 
	Definition of data structure used by robotDefs.c.

robotFile.c
	Routine which reads the file $RCCL/conf/robots to obtain robot
	information used by robotDefs.c.

sgiCtrlTask.c
sgiCtrlTask.h
	The routine which runs the real-time control task on SGI systems. 
	Such a routine is not needed on Sun4 and uVAX systems because the
	real-time control task there is actually the kernel.

sgiGtest.c
sgiProc.c
sgiPtest.c
sgiXtest.c
	Programs for testing system support stuff on SGI systems

sharedMemory.h
sharedMemory.c
	Planning level routines which support the creation of shared memory
	sections between the RCI tasks.

sigHandlers.c
	UNIX signal handlers for SIGHUP, which is delivered to the planning
	task whenever rciAbort() is called, and SIGXCPU, which is delivered to
	the planning task whenever a crash occurs at the control level.

signalRef.c
	Routines to keep track of UNIX signals which are being used to 
	run an RCI control task.

simSupport.c
	Routines designed to make is easy to attach and run a robot
	with an RCI task in simulator mode.

sparcStubs.c
	Stubs for low level support routines that don't exist on the
	SPARC CPU.

spl_s.sun4.S
	SUN4 assembly routines to set and and unset processor priorities.
	Not really used here.

supportFxns.c
supportFxns.vxw.c
supportFx.SGI.c
	Auxiliary RCI routines to things like printing or sending
	UNIX signals from within a control task. The name is truncated
	for the SGI version because the *@#! archiver still can't grok
	long file names.

syncs
	A program that keeps running the system disk sync command. This
	should be run in the background if you are doing tricky things that
	might cause a system crash.

sysclock.c
	Program to control the external hardware that implements
	the RCI system clock.

test.c
testCtrl.c
	Modules for a generic test program. Put anything in these
	two modules, and 'make' will build a program from it named "test".

vxwCrash.c
	vxwWorks system support for handling crashes in the control task.

vxwCtrlTask.c
vxwCtrlTask.h
	code to implement the process that executes the RCI control level on
	vxWorks.

vxwIntrTask.c
	Routines associated with the vxwWorks control level task that must
	be run at interrupt level.

vxw_crash.h
	Definition of the crash info structure for vxWorks systems.

wctest.c
wctest.h
wctestCtrl.c
	Program to test the RCI system wall clock, for those systems which
	have it implemented.

RCI testing software is not really meant for users at this point, but you are
welcome to futz around with it. The following files are part of the RCI
test software package. In addition to the files described here, there
are numerous test programs with the name XXtest that can be built, where
'XX' is some descriptive two letter prefix. They are generally built
by compiling the modules they are intended to test with the option
-DTEST into an object file named '.to'.

rbttest
rbttest.c
	The basic robot support testing program. It is an interactive
	interface to the basic RCI robot interface primitives.

rbttest.h
	Definitions used by rbttest.

rbttest.real.c
	Task level routines used by rbttest.

rbtcom.c
rbtcomCtrl.c
	A simple program to test TRIGGER mode communication with a robot

rcitest
rcitest.c
	The basic RCI testing program. It is an interactive interface to
	the basic RCI primitives; scripts are avialable (the .cts files)
	to test some of the basic RCI functionality.

rcitest.h
	Definitions used by rcitest.

rcitest.real.c
	Control task functions used by rcitest.

rcitest1CPU.cts
	C-tree matcher script to test RCI on the ARBITER CPU only
rcitest2CPU.cts
	C-tree matcher script to test RCI on ARBITER CPU and CPU 1.

mxtest.c
mxtest.h
mxtestCtrl.c
	Program to test the mutual exclusion mechanism.


