RTEMS Classic API definitions and modules. More...

Modules
	ASR Support

	Attributes

	BSP Command Line Helpers

	Barriers

	CPU Usage

	Cache
	The Cache Manager provides functions to perform maintenance operations for data and instruction caches.

	Chains
	Chain API.

	Classic API Options

	Clocks

	Configuration

	Conversion Helpers

	Dual Ported Memory

	Events
	The event manager provides a high performance method of intertask communication and synchronization.

	Fatal
	The Fatal Manager provides functions for fatal system states and or irrecoverable errors.

	Free-Running Counter and Busy Wait Delay
	Free-running counter and busy wait delay functions.

	Input/Output

	Interrupts

	Local Packages
	Local packages.

	Message Queues

	Modes

	Multiprocessing

	Object Class Information

	Partitions

	Rate Monotonic Scheduler

	Red-Black Tree Heap
	Red-Black Tree Heap API.

	Red-Black Trees
	A Red-Black Tree container.

	Regions

	Semaphores

	Signals

	Stack Checker Mechanism

	Status Codes

	Tasks

	Timecounter Support

	Timers

	Timespec
	Timespec API.

	Types
	Types used by Classic API.

	User Extensions
	The User Extensions Manager allows the application developer to augment the executive by allowing them to supply extension routines which are invoked at critical system events.

	Version
	The Version API provides functions to return the version or parts of the version of RTEMS you are using.

	Workspace

Files
file	rtems.h

file	getcopyrightnotice.c
	rtems_get_copyright_notice() Implementation

Macros
#define	RTEMS_HAS_HARDWARE_FP CPU_HARDWARE_FP
	Indicates whether this processor variant has hardware floating point support.

#define	RTEMS_SEARCH_ALL_NODES OBJECTS_SEARCH_ALL_NODES
	Indicates that a search is across all nodes.

#define	RTEMS_SEARCH_OTHER_NODES OBJECTS_SEARCH_OTHER_NODES
	Indicates that a search is across all nodes except the one the call is made from.

#define	RTEMS_SEARCH_LOCAL_NODE OBJECTS_SEARCH_LOCAL_NODE
	Indicates that the search is to be restricted to the local node.

#define	RTEMS_WHO_AM_I OBJECTS_WHO_AM_I
	Indicates that the caller wants to obtain the name of the currently executing thread. More...

#define	RTEMS_OBJECT_ID_INITIAL_INDEX OBJECTS_ID_INITIAL_INDEX
	Lowest valid index value for the index portion of an object identifier.

#define	RTEMS_OBJECT_ID_FINAL_INDEX OBJECTS_ID_FINAL_INDEX
	Maximum valid index value for the index portion of an object identifier.

#define	RTEMS_OBJECT_ID_INITIAL(_api, _class, _node) OBJECTS_ID_INITIAL(_api, _class, _node)
	Returns the identifier of the object with the lowest valid index value. More...

#define	RTEMS_OBJECT_ID_FINAL OBJECTS_ID_FINAL
	Maximum valid object identifier.

#define	RTEMS_MINIMUM_STACK_SIZE STACK_MINIMUM_SIZE
	Minimum stack size which every thread must exceed. More...

#define	RTEMS_CONFIGURED_MINIMUM_STACK_SIZE 0
	Specifies that the task should be created with the configured minimum stack size. More...

#define	RTEMS_NO_TIMEOUT ((rtems_interval) WATCHDOG_NO_TIMEOUT)
	Constant for indefinite wait. More...

#define	RTEMS_MINIMUM_PACKET_SIZE MP_PACKET_MINIMUM_PACKET_SIZE
	An MPCI must support packets of at least this size.

#define	RTEMS_MINIMUN_HETERO_CONVERSION MP_PACKET_MINIMUN_HETERO_CONVERSION
	Defines the count of `uint32_t` numbers in a packet which must be converted to native format in a heterogeneous system. More...

Functions
const char *	rtems_get_copyright_notice (void)
	Returns the pointer to the RTEMS copyright notice.

const char *	rtems_get_version_string (void)
	Returns the pointer to the RTEMS version string.

Detailed Description

RTEMS Classic API definitions and modules.

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

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

An object name is an unsigned 32-bit entity associated with the object by the user. The data type rtems_name is used to store object names.

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:

rtems_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.

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.

Object Identifiers

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 32-bit format which is used for most of the supported architectures and supports multiprocessor configurations. There is also a simpler 16-bit format which is appropriate for smaller target architectures and does not support multiprocessor configurations.

32-Bit Object Identifier Format

The 32-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.

Bits	31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	09	08	07	06	05	04	03	02	01	00
Contents	Class					API			Node								Object 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 16-bits form an identifier within a particular object type. This identifier, called the object index, ranges in value from one to the maximum number of objects configured for this object type.

16-Bit Object Identifier Format

The 16-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.

Bits	15	14	13	12	11	10	09	08	07	06	05	04	03	02	01	00
Contents	Class					API			Object Index

The 16-bit format is designed to be as similar as possible to the 32-bit format. The differences are limited to the elimination of the node field and reduction of the index field from 16-bits to 8-bits. Thus the 16-bit format only supports up to 255 object instances per API/Class combination and single processor systems. As this format is typically utilized by 16-bit processors with limited address space, this is more than enough object instances.

Object Identifer 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:

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

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, and
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:

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

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.

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 Clock Manager Time and Date Data Structures.

Todo:: Link to Clock Manager Time and Date Data Structures

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

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:

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.

Macro Definition Documentation

◆ RTEMS_CONFIGURED_MINIMUM_STACK_SIZE

#define RTEMS_CONFIGURED_MINIMUM_STACK_SIZE 0

Specifies that the task should be created with the configured minimum stack size.

Using this constant when specifying the task stack size indicates that this task is to be created with a stack size of the minimum stack size that was configured by the application. If not explicitly configured by the application, the default configured minimum stack size is the processor dependent value RTEMS_MINIMUM_STACK_SIZE. Since this uses the configured minimum stack size value, you may get a stack size that is smaller or larger than the recommended minimum. This can be used to provide large stacks for all tasks on complex applications or small stacks on applications that are trying to conserve memory.

◆ RTEMS_MINIMUM_STACK_SIZE

#define RTEMS_MINIMUM_STACK_SIZE STACK_MINIMUM_SIZE

Minimum stack size which every thread must exceed.

It is the minimum stack size recommended for use on this processor. This value is selected by the RTEMS developers conservatively to minimize the risk of blown stacks for most user applications. Using this constant when specifying the task stack size, indicates that the stack size will be at least RTEMS_MINIMUM_STACK_SIZE bytes in size. If the user configured minimum stack size is larger than the recommended minimum, then it will be used.

◆ RTEMS_MINIMUN_HETERO_CONVERSION

#define RTEMS_MINIMUN_HETERO_CONVERSION MP_PACKET_MINIMUN_HETERO_CONVERSION

Defines the count of uint32_t numbers in a packet which must be converted to native format in a heterogeneous system.

In packets longer than this value, some of the extra data may be a user message buffer which is not automatically endian swapped.

◆ RTEMS_NO_TIMEOUT

#define RTEMS_NO_TIMEOUT ((rtems_interval) WATCHDOG_NO_TIMEOUT)

Constant for indefinite wait.

This is actually an illegal interval value.

◆ RTEMS_OBJECT_ID_INITIAL

#define RTEMS_OBJECT_ID_INITIAL	(	_api,
		_class,
		_node
	)	OBJECTS_ID_INITIAL(_api, _class, _node)

Returns the identifier of the object with the lowest valid index value.

The object is specified by the API _api, the object class _class and the node _node where the object resides.

◆ RTEMS_WHO_AM_I

#define RTEMS_WHO_AM_I OBJECTS_WHO_AM_I

Indicates that the caller wants to obtain the name of the currently executing thread.

This constant is only meaningful when obtaining the name of a task.

Modules

Files

Macros

Functions