Overview
========

The pSOS+ emulation module on top of Xenomai currently mimicks the
following services:

as_catch, as_send, as_return

ev_receive, ev_send

pt_create, pt_delete, pt_getbuf, pt_ident, pt_retbuf

q_broadcast, q_create, q_delete, q_ident, q_receive, q_send, q_urgent
q_vcreate, q_vdelete, q_vident, q_vreceive, q_vsend, q_vurgent, q_vbroadcast

rn_create, rn_delete, rn_getseg, rn_ident, rn_retseg

sm_create, sm_delete, sm_ident, sm_p, sm_v

t_create, t_delete, t_getreg, t_ident, t_mode, t_restart,
t_resume, t_setpri, t_setreg, t_start, t_suspend,

tm_cancel, tm_evafter, tm_evevery, tm_evwhen, tm_get,
tm_set, tm_tick, tm_wkafter, tm_wkwhen

i_return, k_fatal

Known variations from pSOS+
===========================

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

* t_create() returns ERR_NOTCB upon memory allocation failure
when trying to get a task control block from Xenomai's heap. There is
no control block limit for tasks.

* as_return() is currently a macro-definition expanded as
"return", so it must be called in the ASR's outer frame. The
ERR_NOTINASR status is unused.

* i_return() is a macro-definition expanded as "return", so it must be
called in the ISR's outer frame.

* sm_create() returns ERR_NOSCB upon dynamic allocation error from
Xenomai's heap. There is no control block limit for semaphores.

* q_create() returns ERR_NOQCB upon dynamic allocation error from
Xenomai's heap. There is no control block limit for queues.

* The use of private buffers is forced for variable-size message
queues when the message size exceeds sizeof(u_long[4]), otherwise, the
free buffers may be available from a local cache or obtained from a
globally shared buffer cache, whether the Q_PRIBUF flag is set for
q(v)create() or not. As a special exception, message buffers are
obtained from Xenomai's heap on a per-message basis if the queue has
no size limit and the maximum message length exceeds sizeof(u_long[4]).

* The minimum size of a partition block passed to pt_create() is
equal to the native size of a pointer, thus it's an
architecture-dependent value. Any lower value begets the ERR_BUFSIZE
error status when given.

* tm_evafter() may return ERR_NOSEG since dynamic memory is allocated
for an internal timer from Xenomai's heap.

* rn_retseg() does not check for the ERR_SEGFREE condition.

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

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

- "rn0_size_arg", size of region #0 (in bytes). Defaults to 32k.
- "tick_hz_arg", clock tick period. Defaults to 100 Hz.
- "time_slice_arg", time slice period. Defaults to 10 clock ticks.

Limitations
===========

- Not all the pSOS+ objects have a graphical dashboard associated yet
when running on top of the MVM. As of now, only tasks and queues have.
- The values displayed in the existing dashboards cannot be changed
using the Apply function in this release.
