1 files changed, 266 insertions, 0 deletions
diff --git a/c/src/lib/librtems++/README b/c/src/lib/librtems++/README
new file mode 100644
index 0000000000..65b0eb980e
--- /dev/null
+++ b/c/src/lib/librtems++/README
@@ -0,0 +1,266 @@
+#
+#  $Id$
+#
+
+RTEMS C++ Library
+=================
+
+The RTEMS C++ Library or librtems++ is a wrapper for the RTEMS API.
+The classes provide as close a match to the RTEMS C API, for
+performance, to share the existing C documentation as much as
+possible, and to allow easy tracking of any changes to the RTEMS C
+API.
+
+The C++ interface only uses RTEMS API calls.  No external references
+or internal interfaces are used.  This allows the classes to be used
+in separately compiled modules or applications which link to the RTEMS
+trap interface.
+
+(This is the goal, which has not quite been reached. The TOD macro for
+micro-seconds to ticks is used, and this uses an internal global RTEMS
+variable)
+
+The C++ interface does not deal with RTEMS initialisation or the
+device driver interface.  The current view is these parts of a system
+are best handled in the current manner.  This means BSP for
+initialisation and the C API for drivers.
+
+RTEMS C++ Classes
+=================
+
+The classes map to the managers of RTEMS.
+
+The methods have default values selected which try to fit most cases
+or follow the documented RTEMS default values.  Moving from left to
+right the parameters become less used, allowing the defaults to be
+selected. An example is the scope parameter for most classes.  This
+can be local or global.  I assume that most RTEMS objects are local,
+therefore it has been made the last parameter.
+
+Inline methods have been used for methods which are commonly used in
+applications.  This tries to add the minimum of overhead.  For
+example, the methods to send or receive events are inline, while all
+methods for control of a task are not.
+
+The RTEMS types, enumerations, and defines are used.  If a new type,
+enumeration or define is made it will map directly to the RTEMS
+equivalent.  For example the enumeration Scope is defined for various
+classes which can be local or global. The elements of the enumeration
+are forced to the same value as the RTEMS values.  An enumeration is
+used in this case to allow the compiler to type check a little
+better. It saves having to check only RTEMS_LOCAL or RTEMS_GLOBAL is
+passed as a parameter (I am not convinced this is really needed as the
+goal was to not define anything and to only use what RTEMS provided).
+
+Where possible the various parts of an option bit set, or mode can be
+controlled separately or controlled as a group.  An example is the
+task mode.  The RTEMS C API allows a set of modes to be modified at
+once.  The TaskMode class allows this to occur, while also providing
+methods to control a single mode item.
+
+The name of an object is always passed as a string.  The classes turn
+the string into a rtems_name variable.  The string does not have to be
+nul character terminated.
+
+The RTEMS C API uses 'delete' to remove or kill an RTEMS object.  This
+is a reserved word in C++, so the word 'destroy' is used instead.
+
+Calling the classes from interrupts follows the rules of RTEMS.  An
+exception introduced by the class library is the last status code.
+There is only one last status code for each instance of the library's
+classes and it is not protected.  This needs to be watched for.  Maybe
+a better solution needs to be found, such as interrupt calls do not set
+the last status code.
+
+RTEMS objects created by the C++ library can be operated on by C code
+just as any other RTEMS object. If limitations exist they should be
+documented in under the class.
+
+RTEMS Object Ownership
+======================
+
+The concept of ownership of an object is not defined as part of the
+RTEMS C API.  A piece of code executing as part a task can create a
+message queue.  Another piece of code running as part of a different
+task can destroy the message queue.  Correct behavior between the code
+that creates the message queue and the code which destroy's the
+message queue must be provided by the programmer.
+
+The librtems++ supports the concept of ownership of an RTEMS object.
+Only the C++ object that creates the RTEMS object can destroy it.  A
+C++ object can connect to an existing RTEMS object and control it,
+how-ever it can not destroy it.
+
+Copy constructors and assignment operators are provided to in-force
+this rule.
+
+Ownership only applies to classes that create RTEMS objects.  These
+classes contain a flag which signals ownership of the id.
+
+Timeouts
+========
+
+The timeout value is specified in micro-seconds.  The classes turn the
+micro-second timeout value into ticks required by the RTEMS C API.
+
+This causes a problem for timeout values which are less than one tick.
+This case is tested for and the timeout value is set to one tick.  All
+other cases round down to the nearest tick.
+
+Status Codes
+============
+
+All classes which form the C++ API are derived from the StatusCode
+class.  This class provides a common method for handling the status
+code returned by RTEMS.
+
+The last returned status code is held in the StatusCode object.  It
+can be queried directly, or as a boolean.  You can also obtain an
+error string for the status code.
+
+The setting of a status code is restricted to derived classes.
+
+The last status code attribute of the class is only ever set to an
+RTEMS defined status code.
+
+Event Class
+===========
+
+The event class allows users to send and receive events to and from
+tasks.
+
+Events objects are by default connected the RTEMS_SELF task.  A send
+or receive will operate on the task currently executing.
+
+An Event object can be connected to a task using the connect method.
+The name is the name of the task.  Connection can also be achieved by
+using the copy constructor or assignment operator.
+
+Events can be sent to a task by specifying an RTEMS task id, or by
+passing a reference to a Task object.
+
+Interrupt Class
+===============
+
+The interrupt class allows a protected virtual method of a derived
+class to be an interrupt handler.
+
+You derive from this class and provide the handler method.  The next
+interrupt after the vector is caught will cause the handler method to
+be entered.
+
+You can chain the interrupt by calling the chain method.  If the old
+handler is not an instance of this class the chain is passed as "void
+(*)(void)".  If it is an instance of this class, the handler method is
+directly called. (Chaining has not been tested)
+
+This class implements a table of pointers to the last instance to
+catch the interrupt.  A static method of the class catches the
+interrupt and re-directs the interrupt to the instance in the table.
+The re-direct adds a additional virtual function call and return to
+the overhead of the interrupt.  For a i386 type processor this is
+about 12 instructions including the function call entry.
+
+Message Queue Class
+===================
+
+The MessageQueue class allows message queue's to be created, or
+connected too.  Only the creator can destroy a message queue.
+
+The class implements, sending, urgent sending, broadcast, flushing,
+and receiving.
+
+Semaphore Class
+===============
+
+The Semaphore class allows semaphores to be created, or connected
+too.  Only the creator can destroy a semaphore.
+
+All types of semaphores can be created.
+
+(Not tested in the test code)
+
+Task Class
+==========
+
+The Task class allows tasks to be created, or connected too.  Only the
+creator can destroy a task.
+
+If creating a task, derive from the Task class and provide the body
+method.  The body method is the entry point for a task.  When
+connecting to an existing task, no body method is required to be
+provided.  It is how-ever required if you create a task.  This is not
+enforced by the compiler, how-ever the default body will be entered,
+and it contains no code.  The RTEMS default behaviour for a task that
+returns occurs.
+
+The mode of a task is controlled using the TaskMode class.
+
+The Task class allows you to start, restart, suspend, and resume a
+task.  You can control the priority, and access the note-pad
+registers.  The task can also be slept using the wake_after and
+wake_when methods.
+
+Currently the task argument is used to pass the 'this' pointer to the
+libraries default task body. The actual argument is held in the class
+instance and passed to the virtual body method. This means of passing
+the 'this' pointer through RTEMS to the default task body requires the
+actual task object to perform a restart call. This is not really the
+best solution to the problem. Another solution is to remove a notpad
+register, say 31 from the task and use it. This would mean any Task
+object could stop and restart a task how-ever a notpad register is
+lost. Any other ideas are welcome.
+
+Task Mode Class
+===============
+
+The TaskMode class allows you to query or change the mode of a task.
+The object only operates on the currently executing task.
+
+The standard flags defined in RTEMS are used.
+
+Methods are provided to operate on a group of modes which are required
+to be changed in a single operation.  The mode and mask is specified
+by ORing the required flags as documented in the RTEMS manual.
+
+Methods are provided for accessing and controlling a specific mode.
+The returned value will only contain the requested mode's flags, and
+only the that mode will be changed when setting a mode.
+
+Timer Class
+===========
+
+The Timer class allows timers to be created.  You cannot connect to an
+existing timer.
+
+You derive from the Timer class and provide the trigger method.  This
+method is called when the timer triggers or times out.
+
+You can request a single shot timer using the fire_after or fire_when
+methods, or a periodic timer by calling the repeat_file_at method.
+
+You cannot copy timer objects.
+
+Contact
+=======
+Send any question to me Chris Johns at cjohns@plessey.com.au, or the RTEMS
+mailing list.
+
+To Do
+=====
+
+1) Develop a complete test suite (under way, cjohns@plessey.com.au).
+
+2) Complete wrapping the remaining RTEMS C API.
+
+3) Provide light weight cout/cerr/clog classes based on printf for
+embedded systems.
+
+4) Provide a memory serial class which maps the <</>> operators onto
+raw memory in network byte order independent of CPU byte order.
+
+5) Fix the Task class so any Task object can restart a task.
+
+6) Provide some frame work classes which allow actor type objects that
+start in an ordered manner.
+