
Overview
========

The VRTX (R) emulation module on top of Xenomai currently mimicks
the following services:

Known variations from VRTX
==========================

* Generally speaking, control blocks are always obtained from Xenomai's
heap instead of VRTX workspace. However, VRTX workspace is still
initialized and made available to the application code (See "Module
parameters").

* There is only a single stack per task instead of distinct
supervisor/user mode stacks. The sum of the 'user' and 'sys'
parameters is used in sc_tecreate() to determine the total task size.
If this sum is lower than 1024 (bytes), ER_MEM is returned.

* The maximum number of task identifiers is currently a static
parameter defaulting to 512 (i.e. 1 - 511) which can be changed at
compile-time in api/defs.h. sc_tcreate()/sc_tecreate() calls may
return ER_TCB when tid is passed as -1 and no unique identifier
between 256 and (VRTX_MAX_TID - 1) is available.

* The maximum number of partition identifiers is currently a static
parameter defaulting to 32 (i.e. 0 - 31) which can be changed at
compile-time in api/defs.h. sc_pcreate() call may return ER_IIP
when pid is passed as -1 and no unique partition identifier is
available.

* Instead of being obtained from the system workspace, the memory
needed for partition management is taken from the storage area
provided by the application code. This means that a part of the
available storage given to sc_pcreate() and sc_pextent() is consumed
by the partition bookkeeping code and won't be available to the
application as allocatable memory. Each extent consumes about 28 bytes
for internal purposes, and 36 bytes are used at the begining of each
partition. Please refer to api/pt.h to get the exact size of the
extent and partition control blocks. Since a first extent is
automatically created for the new partition using its initial memory,
sc_pcreate() will need 28 + 36 = 64 bytes for its internal bookkeeping
information.

* VRTX object control blocks (except for tasks) are obtained from an
id. generator that can deliver up to VRTX_MAX_CB unique
identifiers. Object creation routines (except sc_t[e]create()) may
return ER_NOCB whenever no unique identifier is available or the
system memory is exhausted.

* sc_tcreate() creates a stack of the default stack size which
can be set through the module variable "task_stacksize_arg" (see
below). This size cannot be lower than 1k. Initial mode for task is
preemptable, time sliced, with floating-point support, interrupt
enabled, ready to run.

* Attempting to suspend a task while the scheduler is locked always
begets a fatal error.

* sc_tinquiry() behaves the VRTX32 way, i.e. calling this service on
behalf of an ISR with a null task identifier allows to check if the
system is idle.

* sc_screate() creates 32bit (instead of 16bit) counting semaphores.

* sc_getc()/sc_waitc()/sc_acceptc() calls are not implemented in the
emulator.

Module parameters
=================

The following parameters can be passed at startup to the VRTX
API emulation module:

- "workspace_size_arg", size of VRTX workspace (in bytes).
  Defaults to 32k.
- "tick_hz_arg", clock tick period. Defaults to 100 Hz.
- "task_stacksize_arg", size of each VRTX task stack. Defaults to 4k.
