summaryrefslogtreecommitdiffstats
path: root/c_user/key_concepts.rst
diff options
context:
space:
mode:
Diffstat (limited to 'c_user/key_concepts.rst')
-rw-r--r--c_user/key_concepts.rst338
1 files changed, 338 insertions, 0 deletions
diff --git a/c_user/key_concepts.rst b/c_user/key_concepts.rst
new file mode 100644
index 0000000..c5ee56f
--- /dev/null
+++ b/c_user/key_concepts.rst
@@ -0,0 +1,338 @@
+Key Concepts
+############
+
+Introduction
+============
+
+The facilities provided by RTEMS are built upon a
+foundation of very powerful concepts. These concepts must be
+understood before the application developer can efficiently
+utilize RTEMS. The purpose of this chapter is to familiarize
+one with these concepts.
+
+Objects
+=======
+
+.. index:: objects
+
+RTEMS provides directives which can be used to
+dynamically create, delete, and manipulate a set of predefined
+object types. These types include tasks, message queues,
+semaphores, memory regions, memory partitions, timers, ports,
+and rate monotonic periods. The object-oriented nature of RTEMS
+encourages the creation of modular applications built upon
+re-usable "building block" routines.
+
+All objects are created on the local node as required
+by the application and have an RTEMS assigned ID. All objects
+have a user-assigned name. Although a relationship exists
+between an object’s name and its RTEMS assigned ID, the name and
+ID are not identical. Object names are completely arbitrary and
+selected by the user as a meaningful "tag" which may commonly
+reflect the object’s use in the application. Conversely, object
+IDs are designed to facilitate efficient object manipulation by
+the executive.
+
+Object Names
+------------
+.. index:: object name
+.. index:: rtems_object_name
+
+An object name is an unsigned thirty-two bit entity
+associated with the object by the user. The data type``rtems_name`` is used to store object names... index:: rtems_build_name
+
+Although not required by RTEMS, object names are often
+composed of four ASCII characters which help identify that object.
+For example, a task which causes a light to blink might be
+called "LITE". The ``rtems_build_name`` routine
+is provided to build an object name from four ASCII characters.
+The following example illustrates this:
+.. code:: c
+
+ rtems_object_name my_name;
+ my_name = rtems_build_name( 'L', 'I', 'T', 'E' );
+
+However, it is not required that the application use ASCII
+characters to build object names. For example, if an
+application requires one-hundred tasks, it would be difficult to
+assign meaningful ASCII names to each task. A more convenient
+approach would be to name them the binary values one through
+one-hundred, respectively... index:: rtems_object_get_name
+
+RTEMS provides a helper routine, ``rtems_object_get_name``,
+which can be used to obtain the name of any RTEMS object using just
+its ID. This routine attempts to convert the name into a printable string.
+
+The following example illustrates the use of this method to print
+an object name:
+.. code:: c
+
+ #include <rtems.h>
+ #include <rtems/bspIo.h>
+ void print_name(rtems_id id)
+ {
+ char buffer[10]; /* name assumed to be 10 characters or less \*/
+ char \*result;
+ result = rtems_object_get_name( id, sizeof(buffer), buffer );
+ printk( "ID=0x%08x name=%s\\n", id, ((result) ? result : "no name") );
+ }
+
+Object IDs
+----------
+
+.. index:: object ID
+.. index:: object ID composition
+.. index:: rtems_id
+
+An object ID is a unique unsigned integer value which uniquely identifies
+an object instance. Object IDs are passed as arguments to many directives
+in RTEMS and RTEMS translates the ID to an internal object pointer. The
+efficient manipulation of object IDs is critical to the performance
+of RTEMS services. Because of this, there are two object Id formats
+defined. Each target architecture specifies which format it will use.
+There is a thirty-two bit format which is used for most of the supported
+architectures and supports multiprocessor configurations. There is also
+a simpler sixteen bit format which is appropriate for smaller target
+architectures and does not support multiprocessor configurations.
+
+Thirty-Two Object ID Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The thirty-two bit format for an object ID is composed of four parts: API,
+object class, node, and index. The data type ``rtems_id``
+is used to store object IDs.
+
+.. code:: c
+
+ 31 27 26 24 23 16 15 0
+ +---------+-------+--------------+-------------------------------+
+ | | | | |
+ | Class | API | Node | Index |
+ | | | | |
+ +---------+-------+--------------+-------------------------------+
+
+The most significant five bits are the object class. The next
+three bits indicate the API to which the object class belongs.
+The next eight bits (16-23) are the number of the node on which
+this object was created. The node number is always one (1) in a single
+processor system. The least significant sixteen bits form an
+identifier within a particular object type. This identifier,
+called the object index, ranges in value from 1 to the maximum
+number of objects configured for this object type.
+
+Sixteen Bit Object ID Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The sixteen bit format for an object ID is composed of three parts: API,
+object class, and index. The data type ``rtems_id``
+is used to store object IDs.
+
+.. code:: c
+
+ 15 11 10 8 7 0
+ +---------+-------+--------------+
+ | | | |
+ | Class | API | Index |
+ | | | |
+ +---------+-------+--------------+
+
+The sixteen-bit format is designed to be as similar as possible to the
+thrity-two bit format. The differences are limited to the eliminatation
+of the node field and reduction of the index field from sixteen-bits
+to 8-bits. Thus the sixteen bit format only supports up to 255 object
+instances per API/Class combination and single processor systems.
+As this format is typically utilized by sixteen-bit processors with
+limited address space, this is more than enough object instances.
+
+Object ID Description
+---------------------
+
+The components of an object ID make it possible
+to quickly locate any object in even the most complicated
+multiprocessor system. Object ID’s are associated with an
+object by RTEMS when the object is created and the corresponding
+ID is returned by the appropriate object create directive. The
+object ID is required as input to all directives involving
+objects, except those which create an object or obtain the ID of
+an object.
+
+The object identification directives can be used to
+dynamically obtain a particular object’s ID given its name.
+This mapping is accomplished by searching the name table
+associated with this object type. If the name is non-unique,
+then the ID associated with the first occurrence of the name
+will be returned to the application. Since object IDs are
+returned when the object is created, the object identification
+directives are not necessary in a properly designed single
+processor application.
+
+In addition, services are provided to portably examine the
+subcomponents of an RTEMS ID. These services are
+described in detail later in this manual but are prototyped
+as follows:.. index:: obtaining class from object ID
+.. index:: obtaining node from object ID
+.. index:: obtaining index from object ID
+.. index:: get class from object ID
+.. index:: get node from object ID
+.. index:: get index from object ID
+.. index:: rtems_object_id_get_api
+.. index:: rtems_object_id_get_class
+.. index:: rtems_object_id_get_node
+.. index:: rtems_object_id_get_index
+
+.. code:: c
+
+ uint32_t rtems_object_id_get_api( rtems_id );
+ uint32_t rtems_object_id_get_class( rtems_id );
+ uint32_t rtems_object_id_get_node( rtems_id );
+ uint32_t rtems_object_id_get_index( rtems_id );
+
+An object control block is a data structure defined
+by RTEMS which contains the information necessary to manage a
+particular object type. For efficiency reasons, the format of
+each object type’s control block is different. However, many of
+the fields are similar in function. The number of each type of
+control block is application dependent and determined by the
+values specified in the user’s Configuration Table. An object
+control block is allocated at object create time and freed when
+the object is deleted. With the exception of user extension
+routines, object control blocks are not directly manipulated by
+user applications.
+
+Communication and Synchronization
+=================================
+.. index:: communication and synchronization
+
+In real-time multitasking applications, the ability
+for cooperating execution threads to communicate and synchronize
+with each other is imperative. A real-time executive should
+provide an application with the following capabilities:
+
+- Data transfer between cooperating tasks
+
+- Data transfer between tasks and ISRs
+
+- Synchronization of cooperating tasks
+
+- Synchronization of tasks and ISRs
+
+Most RTEMS managers can be used to provide some form
+of communication and/or synchronization. However, managers
+dedicated specifically to communication and synchronization
+provide well established mechanisms which directly map to the
+application’s varying needs. This level of flexibility allows
+the application designer to match the features of a particular
+manager with the complexity of communication and synchronization
+required. The following managers were specifically designed for
+communication and synchronization:
+
+- Semaphore
+
+- Message Queue
+
+- Event
+
+- Signal
+
+The semaphore manager supports mutual exclusion
+involving the synchronization of access to one or more shared
+user resources. Binary semaphores may utilize the optional
+priority inheritance algorithm to avoid the problem of priority
+inversion. The message manager supports both communication and
+synchronization, while the event manager primarily provides a
+high performance synchronization mechanism. The signal manager
+supports only asynchronous communication and is typically used
+for exception handling.
+
+Time
+====
+.. index:: time
+
+The development of responsive real-time applications
+requires an understanding of how RTEMS maintains and supports
+time-related operations. The basic unit of time in RTEMS is
+known as a tick. The frequency of clock ticks is completely
+application dependent and determines the granularity and
+accuracy of all interval and calendar time operations... index:: rtems_interval
+
+By tracking time in units of ticks, RTEMS is capable
+of supporting interval timing functions such as task delays,
+timeouts, timeslicing, the delayed execution of timer service
+routines, and the rate monotonic scheduling of tasks. An
+interval is defined as a number of ticks relative to the current
+time. For example, when a task delays for an interval of ten
+ticks, it is implied that the task will not execute until ten
+clock ticks have occurred.
+All intervals are specified using data type``rtems_interval``.
+
+A characteristic of interval timing is that the
+actual interval period may be a fraction of a tick less than the
+interval requested. This occurs because the time at which the
+delay timer is set up occurs at some time between two clock
+ticks. Therefore, the first countdown tick occurs in less than
+the complete time interval for a tick. This can be a problem if
+the clock granularity is large.
+
+The rate monotonic scheduling algorithm is a hard
+real-time scheduling methodology. This methodology provides
+rules which allows one to guarantee that a set of independent
+periodic tasks will always meet their deadlines – even under
+transient overload conditions. The rate monotonic manager
+provides directives built upon the Clock Manager’s interval
+timer support routines.
+
+Interval timing is not sufficient for the many
+applications which require that time be kept in wall time or
+true calendar form. Consequently, RTEMS maintains the current
+date and time. This allows selected time operations to be
+scheduled at an actual calendar date and time. For example, a
+task could request to delay until midnight on New Year’s Eve
+before lowering the ball at Times Square.
+The data type ``rtems_time_of_day`` is used to specify
+calendar time in RTEMS services.
+See `Time and Date Data Structures`_
+
+... index:: rtems_time_of_day
+
+Obviously, the directives which use intervals or wall
+time cannot operate without some external mechanism which
+provides a periodic clock tick. This clock tick is typically
+provided by a real time clock or counter/timer device.
+
+Memory Management
+=================
+.. index:: memory management
+
+RTEMS memory management facilities can be grouped
+into two classes: dynamic memory allocation and address
+translation. Dynamic memory allocation is required by
+applications whose memory requirements vary through the
+application’s course of execution. Address translation is
+needed by applications which share memory with another CPU or an
+intelligent Input/Output processor. The following RTEMS
+managers provide facilities to manage memory:
+
+- Region
+
+- Partition
+
+- Dual Ported Memory
+
+RTEMS memory management features allow an application
+to create simple memory pools of fixed size buffers and/or more
+complex memory pools of variable size segments. The partition
+manager provides directives to manage and maintain pools of
+fixed size entities such as resource control blocks.
+Alternatively, the region manager provides a more general
+purpose memory allocation scheme that supports variable size
+blocks of memory which are dynamically obtained and freed by the
+application. The dual-ported memory manager provides executive
+support for address translation between internal and external
+dual-ported RAM address space.
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+