From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/key_concepts.rst | 338 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 338 insertions(+) create mode 100644 c_user/key_concepts.rst (limited to 'c_user/key_concepts.rst') 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 + #include + 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. + -- cgit v1.2.3