RTEMS Data Types

Contents

4. RTEMS Data Types#

4.1. Introduction#

This chapter contains a complete list of the RTEMS primitive data types in alphabetical order. This is intended to be an overview and the user is encouraged to look at the appropriate chapters in the manual for more information about the usage of the various data types.

4.2. List of Data Types#

The following is a complete list of the RTEMS primitive data types in alphabetical order:

4.2.1. BSP_output_char_function_type#

Polled character output functions shall have this type.

4.2.2. BSP_polling_getchar_function_type#

Polled character input functions shall have this type.

4.2.3. Timer_Classes#

The timer class indicates how the timer was most recently fired.

ENUMERATORS:

TIMER_DORMANT

This timer class indicates that the timer was never in use.

TIMER_INTERVAL

This timer class indicates that the timer is currently in use as an interval timer which will fire in the context of the clock tick ISR.

TIMER_INTERVAL_ON_TASK

This timer class indicates that the timer is currently in use as an interval timer which will fire in the context of the Timer Server task.

TIMER_TIME_OF_DAY

This timer class indicates that the timer is currently in use as an time of day timer which will fire in the context of the clock tick ISR.

TIMER_TIME_OF_DAY_ON_TASK

This timer class indicates that the timer is currently in use as an time of day timer which will fire in the context of the Timer Server task.

4.2.4. rtems_api_configuration_table#

This structure contains a summary of the Classic API configuration.

MEMBERS:

maximum_tasks

This member contains the maximum number of Classic API Tasks configured for this application. See CONFIGURE_MAXIMUM_TASKS.

notepads_enabled

This member is true, if the Classic API Notepads are enabled, otherwise it is false.

maximum_timers

This member contains the maximum number of Classic API Timers configured for this application. See CONFIGURE_MAXIMUM_TIMERS.

maximum_semaphores

This member contains the maximum number of Classic API Semaphores configured for this application. See CONFIGURE_MAXIMUM_SEMAPHORES.

maximum_message_queues

This member contains the maximum number of Classic API Message Queues configured for this application. See CONFIGURE_MAXIMUM_MESSAGE_QUEUES.

maximum_partitions

This member contains the maximum number of Classic API Partitions configured for this application. See CONFIGURE_MAXIMUM_PARTITIONS.

maximum_regions

This member contains the maximum number of Classic API Regions configured for this application. See CONFIGURE_MAXIMUM_REGIONS.

maximum_ports

This member contains the maximum number of Classic API Dual-Ported Memories configured for this application. See CONFIGURE_MAXIMUM_PORTS.

maximum_periods

This member contains the maximum number of Classic API Rate Monotonic Periods configured for this application. See CONFIGURE_MAXIMUM_PERIODS.

maximum_barriers

This member contains the maximum number of Classic API Barriers configured for this application. See CONFIGURE_MAXIMUM_BARRIERS.

number_of_initialization_tasks

This member contains the number of Classic API Initialization Tasks configured for this application. See CONFIGURE_RTEMS_INIT_TASKS_TABLE.

User_initialization_tasks_table

This member contains the pointer to Classic API Initialization Tasks Table of this application. See CONFIGURE_RTEMS_INIT_TASKS_TABLE.

DESCRIPTION:

Use rtems_configuration_get_rtems_api_configuration() to get the configuration table.

4.2.5. rtems_asr#

This type defines the return type of routines which are used to process asynchronous signals.

NOTES:

This type can be used to document asynchronous signal routines in the source code.

4.2.6. rtems_asr_entry#

This type defines the prototype of routines which are used to process asynchronous signals.

4.2.7. rtems_assert_context#

This structure provides the context in which an assertion failed.

MEMBERS:

file

This member provides the file name of the source code file containing the failed assertion statement.

line

This member provides the line number in the source code file containing the failed assertion statement.

function

This member provides the function name containing the failed assertion statement.

failed_expression

This member provides the expression of the failed assertion statement.

4.2.8. rtems_attribute#

This type represents Classic API attributes.

NOTES:

Attributes are primarily used when creating objects.

4.2.9. rtems_device_driver#

This type shall be used in device driver entry declarations and definitions.

NOTES:

Device driver entries return an rtems_status_code status code. This type definition helps to document device driver entries in the source code.

4.2.10. rtems_device_driver_entry#

Device driver entries shall have this type.

4.2.11. rtems_device_major_number#

This integer type represents the major number of devices.

NOTES:

The major number of a device is determined by rtems_io_register_driver() and the application configuration (see CONFIGURE_MAXIMUM_DRIVERS) .

4.2.12. rtems_device_minor_number#

This integer type represents the minor number of devices.

NOTES:

The minor number of devices is managed by the device driver.

4.2.13. rtems_driver_address_table#

This structure contains the device driver entries.

MEMBERS:

initialization_entry

This member is the device driver initialization entry. This entry is called by rtems_io_initialize().

open_entry

This member is the device driver open entry. This entry is called by rtems_io_open().

close_entry

This member is the device driver close entry. This entry is called by rtems_io_close().

read_entry

This member is the device driver read entry. This entry is called by rtems_io_read().

write_entry

This member is the device driver write entry. This entry is called by rtems_io_write().

control_entry

This member is the device driver control entry. This entry is called by rtems_io_control().

DESCRIPTION:

This structure is used to register a device driver via rtems_io_register_driver().

4.2.14. rtems_event_set#

This integer type represents a bit field which can hold exactly 32 individual events.

4.2.15. rtems_exception_frame#

This structure represents an architecture-dependent exception frame.

4.2.16. rtems_extensions_table#

The extensions table contains a set of extensions which may be registered in the system through the CONFIGURE_INITIAL_EXTENSIONS application configuration option or the rtems_extension_create() directive.

4.2.17. rtems_fatal_code#

This integer type represents system termination codes.

DESCRIPTION:

This integer type is large enough to store a 32-bit integer or a pointer.

NOTES:

The interpretation of a system termination code depends on the system termination source, see rtems_fatal_source.

4.2.18. rtems_fatal_extension#

Fatal extensions are invoked when the system should terminate.

PARAMETERS:

source

This parameter is the system termination source. The source indicates the component which caused the system termination request, see rtems_fatal_source. The system termination code may provide additional information related to the system termination request.

always_set_to_false

This parameter is a value equal to false.

code

This parameter is the system termination code. This value must be interpreted with respect to the source.

NOTES:

The fatal extensions are invoked in extension forward order and with maskable interrupts disabled.

The fatal extension should be extremely careful with respect to the RTEMS directives it calls. Depending on the system termination source, the system may be in an undefined and corrupt state.

It is recommended to register fatal extensions through initial extension sets, see CONFIGURE_INITIAL_EXTENSIONS.

4.2.19. rtems_fatal_source#

This enumeration represents system termination sources.

NOTES:

The system termination code may provide additional information depending on the system termination source, see rtems_fatal_code.

4.2.20. rtems_id#

This type represents RTEMS object identifiers.

4.2.21. rtems_initialization_tasks_table#

This structure defines the properties of the Classic API user initialization task.

MEMBERS:

name

This member defines the task name.

stack_size

This member defines the task stack size in bytes.

initial_priority

This member defines the initial task priority.

attribute_set

This member defines the attribute set of the task.

entry_point

This member defines the entry point of the task.

mode_set

This member defines the initial modes of the task.

argument

This member defines the entry point argument of the task.

4.2.22. rtems_interrupt_attributes#

This structure provides the attributes of an interrupt vector.

MEMBERS:

is_maskable

This member is true, if the interrupt vector is maskable by rtems_interrupt_local_disable(), otherwise it is false. Interrupt vectors which are not maskable by rtems_interrupt_local_disable() should be used with care since they cannot use most operating system services.

can_enable

This member is true, if the interrupt vector can be enabled by rtems_interrupt_vector_enable(), otherwise it is false. When an interrupt vector can be enabled, this means that the enabled state can always be changed from disabled to enabled. For an interrupt vector which can be enabled it follows that it may be enabled.

maybe_enable

This member is true, if the interrupt vector may be enabled by rtems_interrupt_vector_enable(), otherwise it is false. When an interrupt vector may be enabled, this means that the enabled state may be changed from disabled to enabled. The requested enabled state change should be checked by rtems_interrupt_vector_is_enabled(). Some interrupt vectors may be optionally available and cannot be enabled on a particular target.

can_disable

This member is true, if the interrupt vector can be disabled by rtems_interrupt_vector_disable(), otherwise it is false. When an interrupt vector can be disabled, this means that the enabled state can be changed from enabled to disabled. For an interrupt vector which can be disabled it follows that it may be disabled.

maybe_disable

This member is true, if the interrupt vector may be disabled by rtems_interrupt_vector_disable(), otherwise it is false. When an interrupt vector may be disabled, this means that the enabled state may be changed from enabled to disabled. The requested enabled state change should be checked by rtems_interrupt_vector_is_enabled(). Some interrupt vectors may be always enabled and cannot be disabled on a particular target.

can_raise

This member is true, if the interrupt vector can be raised by rtems_interrupt_raise(), otherwise it is false.

can_raise_on

This member is true, if the interrupt vector can be raised on a processor by rtems_interrupt_raise_on(), otherwise it is false.

can_clear

This member is true, if the interrupt vector can be cleared by rtems_interrupt_clear(), otherwise it is false.

cleared_by_acknowledge

This member is true, if the pending status of the interrupt associated with the interrupt vector is cleared by an interrupt acknowledge from the processor, otherwise it is false.

can_get_affinity

This member is true, if the affinity set of the interrupt vector can be obtained by rtems_interrupt_get_affinity(), otherwise it is false.

can_set_affinity

This member is true, if the affinity set of the interrupt vector can be set by rtems_interrupt_set_affinity(), otherwise it is false.

can_be_triggered_by_message

This member is true, if the interrupt associated with the interrupt vector can be triggered by a message. Interrupts may be also triggered by signals, rtems_interrupt_raise(), or rtems_interrupt_raise_on(). Examples for message triggered interrupts are the PCIe MSI/MSI-X and the ARM GICv3 Locality-specific Peripheral Interrupts (LPI).

trigger_signal

This member describes the trigger signal of the interrupt associated with the interrupt vector. Interrupts are normally triggered by signals which indicate an interrupt request from a peripheral. Interrupts may be also triggered by messages, rtems_interrupt_raise(), or rtems_interrupt_raise_on().

can_get_priority

This member is true, if the priority of the interrupt vector can be obtained by rtems_interrupt_get_priority(), otherwise it is false.

can_set_priority

This member is true, if the priority of the interrupt vector can be set by rtems_interrupt_set_priority(), otherwise it is false.

maximum_priority

This member represents the maximum priority value of the interrupt vector. By convention, the minimum priority value is zero. Lower priority values shall be associated with a higher importance. The higher the priority value, the less important is the service of the associated interrupt vector. Where nested interrupts are supported, interrupts with a lower priority value may preempt other interrupts having a higher priority value.

DESCRIPTION:

The rtems_interrupt_get_attributes() directive may be used to obtain the attributes of an interrupt vector.

4.2.23. rtems_interrupt_entry#

This structure represents an interrupt entry.

MEMBERS:

Members of the type shall not be accessed directly by the application.

NOTES:

This structure shall be treated as an opaque data type from the API point of view. Members shall not be accessed directly. An entry may be initialized by RTEMS_INTERRUPT_ENTRY_INITIALIZER() or rtems_interrupt_entry_initialize(). It may be installed for an interrupt vector with rtems_interrupt_entry_install() and removed from an interrupt vector by rtems_interrupt_entry_remove().

4.2.24. rtems_interrupt_handler#

Interrupt handler routines shall have this type.

4.2.25. rtems_interrupt_level#

This integer type represents interrupt levels.

4.2.26. rtems_interrupt_lock#

This structure represents an ISR lock.

NOTES:

Lock objects are only needed in some RTEMS build configurations, for example where the SMP support is enabled. The RTEMS_INTERRUPT_LOCK_NEEDS_OBJECT constant can be used to determine whether a lock object is needed or not. This may help to reduce the memory demands of an application. All lock operations do not use the lock object parameter if lock objects are not needed.

 1#include <rtems.h>
 2
 3#if RTEMS_INTERRUPT_LOCK_NEEDS_OBJECT
 4rtems_interrupt_lock lock = RTEMS_INTERRUPT_LOCK_INITIALIZER( "name" );
 5#endif
 6
 7struct s {
 8#if RTEMS_INTERRUPT_LOCK_NEEDS_OBJECT
 9  rtems_interrupt_lock lock;
10#endif
11  int foobar;
12};

4.2.27. rtems_interrupt_lock_context#

This structure provides an ISR lock context for acquire and release pairs.

4.2.28. rtems_interrupt_per_handler_routine#

Visitor routines invoked by rtems_interrupt_handler_iterate() shall have this type.

4.2.29. rtems_interrupt_server_action#

This structure represents an interrupt server action.

MEMBERS:

Members of the type shall not be accessed directly by the application.

NOTES:

This structure shall be treated as an opaque data type from the API point of view. Members shall not be accessed directly.

4.2.30. rtems_interrupt_server_config#

This structure defines an interrupt server configuration.

MEMBERS:

Members of the type shall not be accessed directly by the application.

NOTES:

See also rtems_interrupt_server_create().

4.2.31. rtems_interrupt_server_control#

This structure represents an interrupt server.

MEMBERS:

Members of the type shall not be accessed directly by the application.

NOTES:

This structure shall be treated as an opaque data type from the API point of view. Members shall not be accessed directly. The structure is initialized by rtems_interrupt_server_create() and maintained by the interrupt server support.

4.2.32. rtems_interrupt_server_entry#

This structure represents an interrupt server entry.

MEMBERS:

Members of the type shall not be accessed directly by the application.

NOTES:

This structure shall be treated as an opaque data type from the API point of view. Members shall not be accessed directly. An entry is initialized by rtems_interrupt_server_entry_initialize() and destroyed by rtems_interrupt_server_entry_destroy(). Interrupt server actions can be prepended to the entry by rtems_interrupt_server_action_prepend(). The entry is submitted to be serviced by rtems_interrupt_server_entry_submit().

4.2.33. rtems_interrupt_server_request#

This structure represents an interrupt server request.

MEMBERS:

Members of the type shall not be accessed directly by the application.

NOTES:

This structure shall be treated as an opaque data type from the API point of view. Members shall not be accessed directly. A request is initialized by rtems_interrupt_server_request_initialize() and destroyed by rtems_interrupt_server_request_destroy(). The interrupt vector of the request can be set by rtems_interrupt_server_request_set_vector(). The request is submitted to be serviced by rtems_interrupt_server_request_submit().

4.2.34. rtems_interrupt_signal_variant#

This enumeration provides interrupt trigger signal variants.

ENUMERATORS:

RTEMS_INTERRUPT_UNSPECIFIED_SIGNAL

This interrupt signal variant indicates that the interrupt trigger signal is unspecified.

RTEMS_INTERRUPT_NO_SIGNAL

This interrupt signal variant indicates that the interrupt cannot be triggered by a signal.

RTEMS_INTERRUPT_SIGNAL_LEVEL_LOW

This interrupt signal variant indicates that the interrupt is triggered by a low level signal.

RTEMS_INTERRUPT_SIGNAL_LEVEL_HIGH

This interrupt signal variant indicates that the interrupt is triggered by a high level signal.

RTEMS_INTERRUPT_SIGNAL_EDGE_FALLING

This interrupt signal variant indicates that the interrupt is triggered by a falling edge signal.

RTEMS_INTERRUPT_SIGNAL_EDGE_RAISING

This interrupt signal variant indicates that the interrupt is triggered by a raising edge signal.

4.2.35. rtems_interval#

This type represents clock tick intervals.

4.2.36. rtems_isr#

This type defines the return type of interrupt service routines.

DESCRIPTION:

This type can be used to document interrupt service routines in the source code.

4.2.37. rtems_isr_entry#

Interrupt service routines installed by rtems_interrupt_catch() shall have this type.

4.2.38. rtems_message_queue_config#

This structure defines the configuration of a message queue constructed by rtems_message_queue_construct().

MEMBERS:

name

This member defines the name of the message queue.

maximum_pending_messages

This member defines the maximum number of pending messages supported by the message queue.

maximum_message_size

This member defines the maximum message size supported by the message queue.

storage_area

This member shall point to the message buffer storage area begin. The message buffer storage area for the message queue shall be an array of the type defined by RTEMS_MESSAGE_QUEUE_BUFFER() with a maximum message size equal to the maximum message size of this configuration.

storage_size

This member defines size of the message buffer storage area in bytes.

storage_free

This member defines the optional handler to free the message buffer storage area. It is called when the message queue is deleted. It is called from task context under protection of the object allocator lock. It is allowed to call free() in this handler. If handler is NULL, then no action will be performed.

attributes

This member defines the attributes of the message queue.

4.2.39. rtems_mode#

This type represents a Classic API task mode set.

4.2.40. rtems_mp_packet_classes#

This enumeration defines the MPCI packet classes.

4.2.41. rtems_mpci_entry#

MPCI handler routines shall have this return type.

4.2.42. rtems_mpci_get_packet_entry#

MPCI get packet routines shall have this type.

4.2.43. rtems_mpci_initialization_entry#

MPCI initialization routines shall have this type.

4.2.44. rtems_mpci_receive_packet_entry#

MPCI receive packet routines shall have this type.

4.2.45. rtems_mpci_return_packet_entry#

MPCI return packet routines shall have this type.

4.2.46. rtems_mpci_send_packet_entry#

MPCI send packet routines shall have this type.

4.2.47. rtems_mpci_table#

This type represents the user-provided MPCI control.

4.2.48. rtems_multiprocessing_table#

This type represents the user-provided MPCI configuration.

4.2.49. rtems_name#

This type represents Classic API object names.

DESCRIPTION:

It is an unsigned 32-bit integer which can be treated as a numeric value or initialized using rtems_build_name() to encode four ASCII characters. A value of zero may have a special meaning in some directives.

4.2.50. rtems_object_api_class_information#

This structure is used to return information to the application about the objects configured for a specific API/Class combination.

MEMBERS:

minimum_id

This member contains the minimum valid object identifier for this class.

maximum_id

This member contains the maximum valid object identifier for this class.

maximum

This member contains the maximum number of active objects configured for this class.

auto_extend

This member is true, if this class is configured for automatic object extension, otherwise it is false.

unallocated

This member contains the number of currently inactive objects of this class.

4.2.51. rtems_option#

This type represents a Classic API directive option set.

4.2.52. rtems_packet_prefix#

This type represents the prefix found at the beginning of each MPCI packet sent between nodes.

4.2.53. rtems_rate_monotonic_period_states#

This enumeration defines the states in which a period may be.

ENUMERATORS:

RATE_MONOTONIC_INACTIVE

This status indicates the period is off the watchdog chain, and has never been initialized.

RATE_MONOTONIC_ACTIVE

This status indicates the period is on the watchdog chain, and running. The owner may be executing or blocked waiting on another object.

RATE_MONOTONIC_EXPIRED

This status indicates the period is off the watchdog chain, and has expired. The owner may still execute and has taken too much time to complete this iteration of the period.

4.2.54. rtems_rate_monotonic_period_statistics#

This structure provides the statistics of a period.

MEMBERS:

count

This member contains the number of periods executed.

missed_count

This member contains the number of periods missed.

min_cpu_time

This member contains the least amount of processor time used in a period.

max_cpu_time

This member contains the highest amount of processor time used in a period.

total_cpu_time

This member contains the total amount of processor time used in a period.

min_wall_time

This member contains the least amount of CLOCK_MONOTONIC time used in a period.

max_wall_time

This member contains the highest amount of CLOCK_MONOTONIC time used in a period.

total_wall_time

This member contains the total amount of CLOCK_MONOTONIC time used in a period.

4.2.55. rtems_rate_monotonic_period_status#

This structure provides the detailed status of a period.

MEMBERS:

owner

This member contains the identifier of the owner task of the period.

state

This member contains the state of the period.

since_last_period

This member contains the time elapsed since the last successful invocation rtems_rate_monotonic_period() using CLOCK_MONOTONIC. If the period is expired or has not been initiated, then this value has no meaning.

executed_since_last_period

This member contains the processor time consumed by the owner task since the last successful invocation rtems_rate_monotonic_period(). If the period is expired or has not been initiated, then this value has no meaning.

postponed_jobs_count

This member contains the count of jobs which are not released yet.

4.2.56. rtems_regulator_attributes#

This structure defines the configuration of a regulator created by rtems_regulator_create().

MEMBERS:

deliverer

This member contains a pointer to an application function invoked by the Delivery thread to output a message to the destination.

deliverer_context

This member contains a pointer to an application defined context which is passed to delivery function.

maximum_message_size

This member contains the maximum size message to process.

maximum_messages

This member contains the maximum number of messages to be able to buffer.

output_thread_priority

This member contains the priority of output thread.

output_thread_stack_size

This member contains the Stack size of output thread.

output_thread_period

This member contains the period (in ticks) of output thread.

maximum_to_dequeue_per_period

This member contains the maximum number of messages the output thread should dequeue and deliver per period.

NOTES:

This type is passed as an argument to rtems_regulator_create().

4.2.57. rtems_regulator_deliverer#

This type represents the function signature used to specify a delivery function for the RTEMS Regulator.

NOTES:

This type is used in the rtems_regulator_attributes structure which is passed as an argument to rtems_regulator_create().

4.2.58. rtems_regulator_statistics#

This structure defines the statistics maintained by each Regulator instance.

MEMBERS:

obtained

This member contains the number of successfully obtained buffers.

released

This member contains the number of successfully released buffers.

delivered

This member contains the number of successfully delivered buffers.

period_statistics

This member contains the Rate Monotonic Period statistics for the Delivery Thread. It is an instance of the rtems_rate_monotonic_period_statistics structure.

NOTES:

This type is passed as an argument to rtems_regulator_get_statistics().

4.2.59. rtems_signal_set#

This integer type represents a bit field which can hold exactly 32 individual signals.

4.2.60. rtems_stack_allocate_hook#

A thread stack allocator allocate handler shall have this type.

4.2.61. rtems_stack_allocate_init_hook#

A task stack allocator initialization handler shall have this type.

4.2.62. rtems_stack_free_hook#

A task stack allocator free handler shall have this type.

4.2.63. rtems_status_code#

This enumeration provides status codes for directives of the Classic API.

ENUMERATORS:

RTEMS_SUCCESSFUL

This status code indicates successful completion of a requested operation.

RTEMS_TASK_EXITTED

This status code indicates that a thread exitted.

RTEMS_MP_NOT_CONFIGURED

This status code indicates that multiprocessing was not configured.

RTEMS_INVALID_NAME

This status code indicates that an object name was invalid.

RTEMS_INVALID_ID

This status code indicates that an object identifier was invalid.

RTEMS_TOO_MANY

This status code indicates you have attempted to create too many instances of a particular object class.

RTEMS_TIMEOUT

This status code indicates that a blocking directive timed out.

RTEMS_OBJECT_WAS_DELETED

This status code indicates the object was deleted while the thread was blocked waiting.

RTEMS_INVALID_SIZE

This status code indicates that a specified size was invalid.

RTEMS_INVALID_ADDRESS

This status code indicates that a specified address was invalid.

RTEMS_INVALID_NUMBER

This status code indicates that a specified number was invalid.

RTEMS_NOT_DEFINED

This status code indicates that the item has not been initialized.

RTEMS_RESOURCE_IN_USE

This status code indicates that the object still had resources in use.

RTEMS_UNSATISFIED

This status code indicates that the request was not satisfied.

RTEMS_INCORRECT_STATE

This status code indicates that an object was in wrong state for the requested operation.

RTEMS_ALREADY_SUSPENDED

This status code indicates that the thread was already suspended.

RTEMS_ILLEGAL_ON_SELF

This status code indicates that the operation was illegal on the calling thread.

RTEMS_ILLEGAL_ON_REMOTE_OBJECT

This status code indicates that the operation was illegal on a remote object.

RTEMS_CALLED_FROM_ISR

This status code indicates that the operation should not be called from this execution environment.

RTEMS_INVALID_PRIORITY

This status code indicates that an invalid thread priority was provided.

RTEMS_INVALID_CLOCK

This status code indicates that a specified date or time was invalid.

RTEMS_INVALID_NODE

This status code indicates that a specified node identifier was invalid.

RTEMS_NOT_CONFIGURED

This status code indicates that the directive was not configured.

RTEMS_NOT_OWNER_OF_RESOURCE

This status code indicates that the caller was not the owner of the resource.

RTEMS_NOT_IMPLEMENTED

This status code indicates the directive or requested portion of the directive is not implemented. This is a hint that you have stumbled across an opportunity to submit code to the RTEMS Project.

RTEMS_INTERNAL_ERROR

This status code indicates that an internal RTEMS inconsistency was detected.

RTEMS_NO_MEMORY

This status code indicates that the directive attempted to allocate memory but was unable to do so.

RTEMS_IO_ERROR

This status code indicates a device driver IO error.

RTEMS_INTERRUPTED

This status code is used internally by the implementation to indicate a blocking device driver call has been interrupted and should be reflected to the caller as interrupted.

RTEMS_PROXY_BLOCKING

This status code is used internally by the implementation when performing operations on behalf of remote tasks. This is referred to as proxying operations and this status indicates that the operation could not be completed immediately and the proxy is blocking.

4.2.64. rtems_task#

This type defines the return type of task entry points.

DESCRIPTION:

This type can be used to document task entry points in the source code.

4.2.65. rtems_task_argument#

This integer type represents task argument values.

NOTES:

The type is an architecture-specific unsigned integer type which is large enough to represent pointer values and 32-bit unsigned integers.

4.2.66. rtems_task_begin_extension#

Task begin extensions are invoked when a task begins execution.

PARAMETERS:

executing

This parameter is the TCB of the executing thread.

NOTES:

The task begin extensions are invoked in extension forward order.

Task begin extensions are invoked with thread dispatching enabled. This allows the use of dynamic memory allocation, creation of POSIX keys, and use of C++ thread-local storage. Blocking synchronization primitives are allowed also.

The task begin extensions are invoked before the global construction.

The task begin extensions may be called as a result of a task restart through rtems_task_restart().

4.2.67. rtems_task_config#

This structure defines the configuration of a task constructed by rtems_task_construct().

MEMBERS:

name

This member defines the name of the task.

initial_priority

This member defines the initial priority of the task.

storage_area

This member shall point to the task storage area begin. The task storage area will contain the task stack, the thread-local storage, and the floating-point context on architectures with a separate floating-point context.

The task storage area begin address and size should be aligned by RTEMS_TASK_STORAGE_ALIGNMENT. To avoid memory waste, use RTEMS_ALIGNED() and RTEMS_TASK_STORAGE_ALIGNMENT to enforce the recommended alignment of a statically allocated task storage area.

storage_size

This member defines size of the task storage area in bytes. Use the RTEMS_TASK_STORAGE_SIZE() macro to determine the recommended task storage area size.

maximum_thread_local_storage_size

This member defines the maximum thread-local storage size supported by the task storage area. Use RTEMS_ALIGN_UP() and RTEMS_TASK_STORAGE_ALIGNMENT to adjust the size to meet the minimum alignment requirement of a thread-local storage area used to construct a task.

If the value is less than the actual thread-local storage size, then the task construction by rtems_task_construct() fails.

If the is less than the task storage area size, then the task construction by rtems_task_construct() fails.

The actual thread-local storage size is determined when the application executable is linked. The rtems-exeinfo command line tool included in the RTEMS Tools can be used to obtain the thread-local storage size and alignment of an application executable.

The application may configure the maximum thread-local storage size for all threads explicitly through the CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE configuration option.

storage_free

This member defines the optional handler to free the task storage area. It is called on exactly two mutually exclusive occasions. Firstly, when the task construction aborts due to a failed task create extension, or secondly, when the task is deleted. It is called from task context under protection of the object allocator lock. It is allowed to call free() in this handler. If handler is NULL, then no action will be performed.

initial_modes

This member defines the initial modes of the task.

attributes

This member defines the attributes of the task.

4.2.68. rtems_task_create_extension#

Task create extensions are invoked when a task is created.

PARAMETERS:

executing

This parameter is the TCB of the executing thread. When the idle thread is created, the executing thread is equal to NULL.

created

This parameter is the TCB of the created thread.

RETURN VALUES:

Returns true, if the task create extension was successful, otherwise false.

NOTES:

The task create extensions are invoked in extension forward order.

The task create extensions are invoked after a new task has been completely initialized, but before it is started.

While normal tasks are created, the executing thread is the owner of the object allocator mutex. The object allocator mutex allows nesting, so the normal memory allocation routines can be used allocate memory for the created thread.

If the task create extension returns false, then the task create operation stops immediately and the entire task create operation will fail. In this case, all task delete extensions are invoked, see rtems_task_delete_extension.

4.2.69. rtems_task_delete_extension#

Task delete extensions are invoked when a task is deleted.

PARAMETERS:

executing

This parameter is the TCB of the executing thread. If the idle thread is created and one of the initial task create extension fails, then the executing thread is equal to NULL.

created

This parameter is the TCB of the deleted thread. The executing and deleted arguments are never equal.

NOTES:

The task delete extensions are invoked in extension reverse order.

The task delete extensions are invoked by task create directives before an attempt to allocate a TCB is made.

If a task create extension failed, then a task delete extension may be invoked without a previous invocation of the corresponding task create extension of the extension set.

4.2.70. rtems_task_entry#

This type defines the task entry point of an RTEMS task.

4.2.71. rtems_task_exitted_extension#

Task exitted extensions are invoked when a task entry returns.

PARAMETERS:

executing

This parameter is the TCB of the executing thread.

NOTES:

The task exitted extensions are invoked in extension forward order.

4.2.72. rtems_task_priority#

This integer type represents task priorities of the Classic API.

4.2.73. rtems_task_restart_extension#

Task restart extensions are invoked when a task restarts.

PARAMETERS:

executing

This parameter is the TCB of the executing thread.

restarted

This parameter is the TCB of the executing thread. Yes, the executing thread.

NOTES:

The task restart extensions are invoked in extension forward order.

The task restart extensions are invoked in the context of the restarted thread right before the execution context is reloaded. The thread stack reflects the previous execution context.

Thread restart and delete requests issued by restart extensions lead to recursion.

4.2.74. rtems_task_start_extension#

Task start extensions are invoked when a task was made ready for the first time.

PARAMETERS:

executing

This parameter is the TCB of the executing thread.

started

This parameter is the TCB of the started thread.

NOTES:

The task start extensions are invoked in extension forward order.

In SMP configurations, the thread may already run on another processor before the task start extensions are actually invoked. Task switch and task begin extensions may run before or in parallel with the thread start extension in SMP configurations, see rtems_task_switch_extension and rtems_task_begin_extension.

4.2.75. rtems_task_switch_extension#

Task switch extensions are invoked when a thread switch from an executing thread to a heir thread takes place.

PARAMETERS:

executing

This parameter is the TCB of the executing thread. In SMP configurations, this is the previously executing thread also known as the ancestor thread.

heir

This parameter is the TCB of the heir thread. In SMP configurations, this is the executing thread.

NOTES:

The task switch extensions are invoked in extension forward order.

The invocation conditions of the task switch extensions depend on whether RTEMS was built with SMP support enabled or disabled. A user must pay attention to the differences to correctly implement a task switch extension.

Where the system was built with SMP support disabled, the task switch extensions are invoked before the context switch from the currently executing thread to the heir thread. The executing is a pointer to the TCB of the currently executing thread. The heir is a pointer to the TCB of the heir thread. The context switch initiated through the multitasking start is not covered by the task switch extensions.

Where the system was built with SMP support enabled, the task switch extensions are invoked after the context switch to the heir thread. The executing is a pointer to the TCB of the previously executing thread. Despite the name, this is not the currently executing thread. The heir is a pointer to the TCB of the newly executing thread. This is the currently executing thread. The context switches initiated through the multitasking start are covered by the task switch extensions. The reason for the differences to uniprocessor configurations is that the context switch may update the heir thread of the processor. The task switch extensions are invoked with maskable interrupts disabled and with ownership of a processor-specific SMP lock. Task switch extensions may run in parallel on multiple processors. It is recommended to use thread-local or processor-specific data structures for task switch extensions. A global SMP lock should be avoided for performance reasons, see rtems_interrupt_lock_initialize().

4.2.76. rtems_task_terminate_extension#

Task terminate extensions are invoked when a task terminates.

PARAMETERS:

executing

This parameter is the TCB of the executing thread. This is the terminating thread.

NOTES:

The task terminate extensions are invoked in extension reverse order.

The task terminate extensions are invoked in the context of the terminating thread right before the thread dispatch to the heir thread should take place. The thread stack reflects the previous execution context. The POSIX cleanup and key destructors execute in this context.

Thread restart and delete requests issued by terminate extensions lead to recursion.

4.2.77. rtems_task_visitor#

Visitor routines invoked by rtems_task_iterate() shall have this type.

4.2.78. rtems_tcb#

This structure represents the TCB.

4.2.79. rtems_time_of_day#

This type represents Classic API calendar times.

MEMBERS:

year

This member contains the year A.D.

month

This member contains the month of the year with values from 1 to 12.

day

This member contains the day of the month with values from 1 to 31.

hour

This member contains the hour of the day with values from 0 to 23.

minute

This member contains the minute of the hour with values from 0 to 59.

second

This member contains the second of the minute with values from 0 to 59.

ticks

This member contains the clock tick of the second with values from 0 to rtems_clock_get_ticks_per_second() minus one.

4.2.80. rtems_timer_information#

The structure contains information about a timer.

MEMBERS:

the_class

The timer class member indicates how the timer was most recently fired.

initial

This member indicates the initial requested interval.

start_time

This member indicates the time the timer was initially scheduled. The time is in clock ticks since the clock driver initialization or the last clock tick counter overflow.

stop_time

This member indicates the time the timer was scheduled to fire. The time is in clock ticks since the clock driver initialization or the last clock tick counter overflow.

4.2.81. rtems_timer_service_routine#

This type defines the return type of routines which can be fired by directives of the Timer Manager.

DESCRIPTION:

This type can be used to document timer service routines in the source code.

4.2.82. rtems_timer_service_routine_entry#

This type defines the prototype of routines which can be fired by directives of the Timer Manager.

4.2.83. rtems_vector_number#

This integer type represents interrupt vector numbers.

Contents