From 48a7fa31f918a6fc88719b3c9393a9ba2829f42a Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 15 Nov 2016 10:37:59 -0600 Subject: Remove texinfo format documentation. Replaced by Sphinx formatted documentation. closes #2812. --- doc/user/concepts.t | 405 ---------------------------------------------------- 1 file changed, 405 deletions(-) delete mode 100644 doc/user/concepts.t (limited to 'doc/user/concepts.t') diff --git a/doc/user/concepts.t b/doc/user/concepts.t deleted file mode 100644 index 183d3225ae..0000000000 --- a/doc/user/concepts.t +++ /dev/null @@ -1,405 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2007. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@c -@c The following figure was replaced with an ASCII equivalent. -@c Figure 2-1 Object ID Composition -@c - -@chapter Key Concepts - -@section 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. - -@section Objects - -@cindex 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. - -@subsection Object Names - -@cindex object name -@findex rtems_name - -An object name is an unsigned thirty-two bit entity -associated with the object by the user. The data type -@code{@value{DIRPREFIX}name} is used to store object names. - -@findex 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 @code{@value{DIRPREFIX}build_name} routine -is provided to build an object name from four ASCII characters. -The following example illustrates this: - -@ifset is-C -@example -rtems_name my_name; - -my_name = rtems_build_name( 'L', 'I', 'T', 'E' ); -@end example -@end ifset - -@ifset is-Ada -@example -My_Name : RTEMS.Name; - -My_Name = RTEMS.Build_Name( 'L', 'I', 'T', 'E' ); -@end example -@end ifset - -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. - -@ifset is-C -@findex rtems_object_get_name - -RTEMS provides a helper routine, @code{@value{DIRPREFIX}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: - -@example -#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") ); -@} -@end example -@end ifset - - -@subsection Object IDs - -@cindex object ID -@cindex object ID composition -@findex rtems_id - -@need 3000 - -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. - -@subsubsection 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 @code{@value{DIRPREFIX}id} -is used to store object IDs. - - -@float Figure,fig:Object-Id-32 -@caption{Thirty-Two Bit Object Id} - -@ifset use-ascii -@example -@group - 31 27 26 24 23 16 15 0 - +---------+-------+--------------+-------------------------------+ - | | | | | - | Class | API | Node | Index | - | | | | | - +---------+-------+--------------+-------------------------------+ -@end group -@end example -@end ifset - -@ifset use-tex -@sp1 -@center{@image{ObjectId-32Bits,,2in,Thirty-Two Bit Object Id}} -@end ifset - -@ifset use-html -@html -

Thirty-Two Bit Object Id

-@end html -@end ifset -@end float - -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. - -@subsubsection 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 @code{@value{DIRPREFIX}id} -is used to store object IDs. - -@float Figure,fig:Object-Id-16 -@caption{Sixteen Bit Object Id} - - -@ifset use-ascii -@example -@group - 15 11 10 8 7 0 - +---------+-------+--------------+ - | | | | - | Class | API | Index | - | | | | - +---------+-------+--------------+ -@end group -@end example -@end ifset - -@ifset use-tex -@sp1 -@center{@image{ObjectId-16Bits,,2in,Sixteen Bit Object Id}} -@end ifset - -@ifset use-html -@html -

16 Bit Object Id

-@end html -@end ifset -@end float - -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. - -@subsection 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: - -@cindex obtaining class from object ID -@cindex obtaining node from object ID -@cindex obtaining index from object ID -@cindex get class from object ID -@cindex get node from object ID -@cindex get index from object ID -@findex rtems_object_id_get_api -@findex rtems_object_id_get_class -@findex rtems_object_id_get_node -@findex rtems_object_id_get_index - -@example -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 ); -@end example - -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. - -@section Communication and Synchronization - -@cindex 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: - -@itemize @bullet -@item Data transfer between cooperating tasks -@item Data transfer between tasks and ISRs -@item Synchronization of cooperating tasks -@item Synchronization of tasks and ISRs -@end itemize - -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: - -@itemize @bullet -@item Semaphore -@item Message Queue -@item Event -@item Signal -@end itemize - -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. - -@section Time - -@cindex 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. - -@findex 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 -@code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}time_of_day} is used to specify -calendar time in RTEMS services. -@xref{Clock Manager Time and Date Data Structures, , Time and Date Data Structures}. -@findex 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. - -@section Memory Management - -@cindex 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: - -@itemize @bullet -@item Region - -@item Partition - -@item Dual Ported Memory -@end itemize - -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. -- cgit v1.2.3