diff options
Diffstat (limited to 'c/src/lib/librtems++/README')
| -rw-r--r-- | c/src/lib/librtems++/README | 266 |
1 files changed, 0 insertions, 266 deletions
diff --git a/c/src/lib/librtems++/README b/c/src/lib/librtems++/README deleted file mode 100644 index 65b0eb980e..0000000000 --- a/c/src/lib/librtems++/README +++ /dev/null @@ -1,266 +0,0 @@ -# -# $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. - |