diff options
Diffstat (limited to 'c-user/configuring_a_system.rst')
| -rw-r--r-- | c-user/configuring_a_system.rst | 5345 |
1 files changed, 5345 insertions, 0 deletions
diff --git a/c-user/configuring_a_system.rst b/c-user/configuring_a_system.rst new file mode 100644 index 0000000..e993877 --- /dev/null +++ b/c-user/configuring_a_system.rst @@ -0,0 +1,5345 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +.. _Configuring a System: + +Configuring a System +#################### + +.. index:: configuring a system + +Introduction +============ + +RTEMS must be configured for an application. This configuration encompasses a +variety of information including the length of each clock tick, the maximum +number of each information RTEMS object that can be created, the application +initialization tasks, the task scheduling algorithm to be used, and the device +drivers in the application. + +Although this information is contained in data structures that are used by +RTEMS at system initialization time, the data structures themselves should only +rarely to be generated by hand. RTEMS provides a set of macros system which +provides a simple standard mechanism to automate the generation of these +structures. + +.. index:: confdefs.h +.. index:: confdefs.h +.. index:: <rtems/confdefs.h> +.. index:: <rtems/confdefs.h> + +The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic +generation of system configuration. It is based on the idea of setting macros +which define configuration parameters of interest to the application and +defaulting or calculating all others. This variety of macros can automatically +produce all of the configuration data required for an RTEMS application. + +.. sidebar: Trivia: + + The term ``confdefs`` is shorthand for a *Configuration Defaults*. + +As a general rule, application developers only specify values for the +configuration parameters of interest to them. They define what resources or +features they require. In most cases, when a parameter is not specified, it +defaults to zero (0) instances, a standards compliant value, or disabled as +appropriate. For example, by default there will be 256 task priority levels but +this can be lowered by the application. This number of priority levels is +required to be compliant with the RTEID/ORKID standards upon which the Classic +API is based. There are similar cases where the default is selected to be +compliant with with the POSIX standard. + +For each configuration parameter in the configuration tables, the macro +corresponding to that field is discussed. The RTEMS Maintainers expect that all +systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and +that using this mechanism will avoid internal RTEMS configuration changes +impacting applications. + +.. COMMENT: === Philosophy === + +Default Value Selection Philosophy +================================== + +The user should be aware that the defaults are intentionally set as low as +possible. By default, no application resources are configured. The +``<rtems/confdefs.h>`` file ensures that at least one application task or +thread is configured and that at least one of the initialization task/thread +tables is configured. + +.. COMMENT: === Sizing the RTEMS Workspace === + +.. _Sizing the RTEMS Workspace: + +Sizing the RTEMS Workspace +========================== + +The RTEMS Workspace is a user-specified block of memory reserved for use by +RTEMS. The application should NOT modify this memory. This area consists +primarily of the RTEMS data structures whose exact size depends upon the values +specified in the Configuration Table. In addition, task stacks and floating +point context areas are dynamically allocated from the RTEMS Workspace. + +The ``<rtems/confdefs.h>`` mechanism calculates the size of the RTEMS Workspace +automatically. It assumes that all tasks are floating point and that all will +be allocated the minimum stack space. This calculation includes the amount of +memory that will be allocated for internal use by RTEMS. The automatic +calculation may underestimate the workspace size truly needed by the +application, in which case one can use the ``CONFIGURE_MEMORY_OVERHEAD`` macro +to add a value to the estimate. See :ref:`Specify Memory Overhead` for more +details. + +The memory area for the RTEMS Workspace is determined by the BSP. In case the +RTEMS Workspace is too large for the available memory, then a fatal run-time +error occurs and the system terminates. + +The file ``<rtems/confdefs.h>`` will calculate the value of the +``work_space_size`` parameter of the Configuration Table. There are many +parameters the application developer can specify to help ``<rtems/confdefs.h>`` +in its calculations. Correctly specifying the application requirements via +parameters such as ``CONFIGURE_EXTRA_TASK_STACKS`` and +``CONFIGURE_MAXIMUM_TASKS`` is critical for production software. + +For each class of objects, the allocation can operate in one of two ways. The +default way has an ceiling on the maximum number of object instances which can +concurrently exist in the system. Memory for all instances of that object class +is reserved at system initialization. The second way allocates memory for an +initial number of objects and increases the current allocation by a fixed +increment when required. Both ways allocate space from inside the RTEMS +Workspace. + +See :ref:`Unlimited Objects` for more details about the second way, which +allows for dynamic allocation of objects and therefore does not provide +determinism. This mode is useful mostly for when the number of objects cannot +be determined ahead of time or when porting software for which you do not know +the object requirements. + +The space needed for stacks and for RTEMS objects will vary from one version of +RTEMS and from one target processor to another. Therefore it is safest to use +``<rtems/confdefs.h>`` and specify your application's requirements in terms of +the numbers of objects and multiples of ``RTEMS_MINIMUM_STACK_SIZE``, as far as +is possible. The automatic estimates of space required will in general change +when: + +- a configuration parameter is changed, + +- task or interrupt stack sizes change, + +- the floating point attribute of a task changes, + +- task floating point attribute is altered, + +- RTEMS is upgraded, or + +- the target processor is changed. + +Failure to provide enough space in the RTEMS Workspace may result in fatal +run-time errors terminating the system. + +.. COMMENT: === Potential Issues === + +Potential Issues with RTEMS Workspace Size Estimation +===================================================== + +The ``<rtems/confdefs.h>`` file estimates the amount of memory required for the +RTEMS Workspace. This estimate is only as accurate as the information given to +``<rtems/confdefs.h>`` and may be either too high or too low for a variety of +reasons. Some of the reasons that ``<rtems/confdefs.h>`` may reserve too much +memory for RTEMS are: + +- All tasks/threads are assumed to be floating point. + +Conversely, there are many more reasons that the resource estimate could be too +low: + +- Task/thread stacks greater than minimum size must be accounted for explicitly + by developer. + +- Memory for messages is not included. + +- Device driver requirements are not included. + +- Network stack requirements are not included. + +- Requirements for add-on libraries are not included. + +In general, ``<rtems/confdefs.h>`` is very accurate when given enough +information. However, it is quite easy to use a library and forget to account +for its resources. + +.. COMMENT: === Format to be followed for making changes in this file === + +Format to be followed for making changes in this file +===================================================== + +*MACRO NAME:*: + Should be alphanumeric. Can have '_' (underscore). + +*DATA TYPE:* + Please refer to all existing formats. + +*RANGE:* + The range depends on the Data Type of the macro. + + - If the data type is of type task priority, then its value should be an + integer in the range of 1 to 255. + + - If the data type is an integer, then it can have numbers, characters (in + case the value is defined using another macro) and arithmetic operations + (+, -, \*, /). + + - If the data type is a function pointer the first character should be an + alphabet or an underscore. The rest of the string can be alphanumeric. + + - If the data type is RTEMS Attributes or RTEMS Mode then the string should + be alphanumeric. + + - If the data type is RTEMS NAME then the value should be an integer>=0 or + RTEMS_BUILD_NAME( 'U', 'I', '1', ' ' ) + +*DEFAULT VALUE:* + The default value should be in the following formats- Please note that the + '.' (full stop) is necessary. + + - In case the value is not defined then: This is not defined by default. + + - If we know the default value then: The default value is XXX. + + - If the default value is BSP Specific then: This option is BSP specific. + +*DESCRIPTION:* + The description of the macro. (No specific format) + +*NOTES:* + Any further notes. (No specific format) + +.. COMMENT: === Configuration Example === + +Configuration Example +===================== + +In the following example, the configuration information for a system with a +single message queue, four (4) tasks, and a timeslice of fifty (50) +milliseconds is as follows: + +.. code-block:: c + + #include <bsp.h> + #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER + #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER + #define CONFIGURE_MICROSECONDS_PER_TICK 1000 /* 1 millisecond */ + #define CONFIGURE_TICKS_PER_TIMESLICE 50 /* 50 milliseconds */ + #define CONFIGURE_RTEMS_INIT_TASKS_TABLE + #define CONFIGURE_MAXIMUM_TASKS 4 + #define CONFIGURE_MAXIMUM_MESSAGE_QUEUES 1 + #define CONFIGURE_MESSAGE_BUFFER_MEMORY \ + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(20, sizeof(struct USER_MESSAGE)) + #define CONFIGURE_INIT + #include <rtems/confdefs.h> + +In this example, only a few configuration parameters are specified. The impact +of these are as follows: + +- The example specified ``CONFIGURE_RTEMS_INIT_TASK_TABLE`` but did not specify + any additional parameters. This results in a configuration of an application + which will begin execution of a single initialization task named ``Init`` + which is non-preemptible and at priority one (1). + +- By specifying ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, this application + is configured to have a clock tick device driver. Without a clock tick device + driver, RTEMS has no way to know that time is passing and will be unable to + support delays and wall time. Further configuration details about time are + provided. Per ``CONFIGURE_MICROSECONDS_PER_TICK`` and + ``CONFIGURE_TICKS_PER_TIMESLICE``, the user specified they wanted a clock + tick to occur each millisecond, and that the length of a timeslice would be + fifty (50) milliseconds. + +- By specifying ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, the application + will include a console device driver. Although the console device driver may + support a combination of multiple serial ports and display and keyboard + combinations, it is only required to provide a single device named + ``/dev/console``. This device will be used for Standard Input, Output and + Error I/O Streams. Thus when ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` + is specified, implicitly three (3) file descriptors are reserved for the + Standard I/O Streams and those file descriptors are associated with + ``/dev/console`` during initialization. All console devices are expected to + support the POSIX*termios* interface. + +- The example above specifies via ``CONFIGURE_MAXIMUM_TASKS`` that the + application requires a maximum of four (4) simultaneously existing Classic + API tasks. Similarly, by specifying ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``, + there may be a maximum of only one (1) concurrently existent Classic API + message queues. + +- The most surprising configuration parameter in this example is the use of + ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. Message buffer memory is allocated from + the RTEMS Workspace and must be accounted for. In this example, the single + message queue will have up to twenty (20) messages of type ``struct + USER_MESSAGE``. + +- The ``CONFIGURE_INIT`` constant must be defined in order to make + ``<rtems/confdefs.h>`` instantiate the configuration data structures. This + can only be defined in one source file per application that includes + ``<rtems/confdefs.h>`` or the symbol table will be instantiated multiple + times and linking errors produced. + +This example illustrates that parameters have default values. Among other +things, the application implicitly used the following defaults: + +- All unspecified types of communications and synchronization objects in the + Classic and POSIX Threads API have maximums of zero (0). + +- The filesystem will be the default filesystem which is the In-Memory File + System (IMFS). + +- The application will have the default number of priority levels. + +- The minimum task stack size will be that recommended by RTEMS for the target + architecture. + +.. COMMENT: === Unlimited Objects === + +.. _Unlimited Objects: + +Unlimited Objects +----------------- + +In real-time embedded systems the RAM is normally a limited, critical resource +and dynamic allocation is avoided as much as possible to ensure predictable, +deterministic execution times. For such cases, see :ref:`Sizing the RTEMS +Workspace` for an overview of how to tune the size of the workspace. +Frequently when users are porting software to RTEMS the precise resource +requirements of the software is unknown. In these situations users do not need +to control the size of the workspace very tightly because they just want to get +the new software to run; later they can tune the workspace size as needed. + +The following API-independent object classes can be configured in unlimited +mode: + +- POSIX Keys + +- POSIX Key Value Pairs + +The following object classes in the Classic API can be configured in unlimited +mode: + +- Tasks + +- Timers + +- Semaphores + +- Message Queues + +- Periods + +- Barriers + +- Partitions + +- Regions + +- Ports + +Additionally, the following object classes from the POSIX API can be configured +in unlimited mode: + +- Threads + +- Mutexes + +- Condition Variables + +- Timers + +- Message Queues + +- Message Queue Descriptors + +- Semaphores + +- Barriers + +- Read/Write Locks + +- Spinlocks + +The following object classes can *not* be configured in unlimited mode: + +- Drivers + +- File Descriptors + +- User Extensions + +- POSIX Queued Signals + +Due to the memory requirements of unlimited objects it is strongly recommended +to use them only in combination with the unified work areas. See :ref:`Separate +or Unified Work Areas` for more information on unified work areas. + +The following example demonstrates how the two simple configuration defines for +unlimited objects and unified works areas can replace many seperate +configuration defines for supported object classes: + +.. code-block:: c + + #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER + #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER + #define CONFIGURE_UNIFIED_WORK_AREAS + #define CONFIGURE_UNLIMITED_OBJECTS + #define CONFIGURE_RTEMS_INIT_TASKS_TABLE + #define CONFIGURE_INIT + #include <rtems/confdefs.h> + +Users are cautioned that using unlimited objects is not recommended for +production software unless the dynamic growth is absolutely required. It is +generally considered a safer embedded systems programming practice to know the +system limits rather than experience an out of memory error at an arbitrary and +largely unpredictable time in the field. + +.. COMMENT: === Per Object Class Unlimited Object Instances === + +.. _Per Object Class Unlimited Object Instances: + +Per Object Class Unlimited Object Instances +------------------------------------------- +.. index:: rtems_resource_unlimited + +When the number of objects is not known ahead of time, RTEMS provides an +auto-extending mode that can be enabled individually for each object type by +using the macro ``rtems_resource_unlimited``. This takes a value as a +parameter, and is used to set the object maximum number field in an API +Configuration table. The value is an allocation unit size. When RTEMS is +required to grow the object table it is grown by this size. The kernel will +return the object memory back to the RTEMS Workspace when an object is +destroyed. The kernel will only return an allocated block of objects to the +RTEMS Workspace if at least half the allocation size of free objects remain +allocated. RTEMS always keeps one allocation block of objects allocated. Here +is an example of using ``rtems_resource_unlimited``: + +.. code-block:: c + + #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5) + +.. index:: rtems_resource_is_unlimited +.. index:: rtems_resource_maximum_per_allocation + +Object maximum specifications can be evaluated with the +``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation`` +macros. + +.. COMMENT: === Unlimited Object Instances === + +.. _Unlimited Object Instances: + +Unlimited Object Instances +-------------------------- + +To ease the burden of developers who are porting new software RTEMS also +provides the capability to make all object classes listed above operate in +unlimited mode in a simple manner. The application developer is only +responsible for enabling unlimited objects and specifying the allocation size. + +.. COMMENT: === CONFIGURE_UNLIMITED_OBJECTS === + +.. _Enable Unlimited Object Instances: + +Enable Unlimited Object Instances +--------------------------------- +.. index:: CONFIGURE_UNLIMITED_OBJECTS + +*CONSTANT:* + ``CONFIGURE_UNLIMITED_OBJECTS`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_UNLIMITED_OBJECTS`` enables ``rtems_resource_unlimited`` mode for +Classic API and POSIX API objects that do not already have a specific maximum +limit defined. + +**NOTES:** + +When using unlimited objects, it is common practice to also specify +``CONFIGURE_UNIFIED_WORK_AREAS`` so the system operates with a single pool of +memory for both RTEMS and application memory allocations. + +.. COMMENT: === CONFIGURE_UNLIMITED_ALLOCATION_SIZE === + +.. _Specify Unlimited Objects Allocation Size: + +Specify Unlimited Objects Allocation Size +----------------------------------------- + +*CONSTANT:* + ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* If not defined and ``CONFIGURE_UNLIMITED_OBJECTS`` is defined, + the default value is eight (8). + +**DESCRIPTION:** + +``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` provides an allocation size to use for +``rtems_resource_unlimited`` when using ``CONFIGURE_UNLIMITED_OBJECTS``. + +**NOTES:** + +By allowing users to declare all resources as being unlimited the user can +avoid identifying and limiting the resources +used. ``CONFIGURE_UNLIMITED_OBJECTS`` does not support varying the allocation +sizes for different objects; users who want that much control can define the +``rtems_resource_unlimited`` macros themselves. + +.. code-block:: c + + #define CONFIGURE_UNLIMITED_OBJECTS + #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5 + +.. COMMENT: === Classic API Configuration === + +Classic API Configuration +========================= + +This section defines the Classic API related system configuration parameters +supported by ``<rtems/confdefs.h>``. + +.. COMMENT: === CONFIGURE_MAXIMUM_TASKS === + +.. _Specify Maximum Classic API Tasks: + +Specify Maximum Classic API Tasks +--------------------------------- +.. index:: CONFIGURE_MAXIMUM_TASKS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_TASKS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API Tasks that can +be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +The calculations for the required memory in the RTEMS Workspace for tasks +assume that each task has a minimum stack size and has floating point support +enabled. The configuration parameter ``CONFIGURE_EXTRA_TASK_STACKS`` is used +to specify task stack requirements *ABOVE* the minimum size required. See +:ref:`Reserve Task/Thread Stack Memory Above Minimum` for more information +about ``CONFIGURE_EXTRA_TASK_STACKS``. + +The maximum number of POSIX threads is specified by +``CONFIGURE_MAXIMUM_POSIX_THREADS``. + +.. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_POSIX_THREADS. + +A future enhancement to ``<rtems/confdefs.h>`` could be to eliminate the +assumption that all tasks have floating point enabled. This would require the +addition of a new configuration parameter to specify the number of tasks which +enable floating point support. + +.. COMMENT: === CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS === + +.. _Specify Maximum Classic API Timers: + +Specify Maximum Classic API Timers +---------------------------------- +.. index:: CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS + +*CONSTANT:* + ``CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default, and Classic API Notepads are not supported. + +**DESCRIPTION:** + ``CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS`` should be defined if the + user wants to have support for Classic API Notepads in their application. + +**NOTES:** + Disabling Classic API Notepads saves the allocation of sixteen (16) + thirty-two bit integers. This saves sixty-four bytes per task/thread + plus the allocation overhead. Notepads are rarely used in applications + and this can save significant memory in a low RAM system. Classic API + Notepads are deprecated, and this option has been removed from + post 4.11 versions of RTEMS. + +.. COMMENT: === CONFIGURE_MAXIMUM_TIMERS === + +.. _Specify Maximum Classic API Timers: + +Specify Maximum Classic API Timers +---------------------------------- +.. index:: CONFIGURE_MAXIMUM_TIMERS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_TIMERS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_TIMERS`` is the maximum number of Classic API Timers that +can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_SEMAPHORES === + +.. _Specify Maximum Classic API Semaphores: + +Specify Maximum Classic API Semaphores +-------------------------------------- +.. index:: CONFIGURE_MAXIMUM_SEMAPHORES + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_SEMAPHORES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_SEMAPHORES`` is the maximum number of Classic API +Semaphores that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_MRSP_SEMAPHORES === + +.. _Specify Maximum Classic API Semaphores usable with MrsP: + +Specify Maximum Classic API Semaphores usable with MrsP +------------------------------------------------------- +.. index:: CONFIGURE_MAXIMUM_MRSP_SEMAPHORES + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` is the maximum number of Classic API +Semaphores using the Multiprocessor Resource Sharing Protocol (MrsP) that can +be concurrently active. + +**NOTES:** + +This configuration option is only used on SMP configurations. On uni-processor +configurations the Priority Ceiling Protocol is used for MrsP semaphores and +thus no extra memory is necessary. + +.. COMMENT: === CONFIGURE_MAXIMUM_MESSAGE_QUEUES === + +.. _Specify Maximum Classic API Message Queues: + +Specify Maximum Classic API Message Queues +------------------------------------------ +.. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` is the maximum number of Classic API +Message Queues that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_BARRIERS === + +.. _Specify Maximum Classic API Barriers: + +Specify Maximum Classic API Barriers +------------------------------------ +.. index:: CONFIGURE_MAXIMUM_BARRIERS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_BARRIERS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_BARRIERS`` is the maximum number of Classic API Barriers +that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_PERIODS === + +.. _Specify Maximum Classic API Periods: + +Specify Maximum Classic API Periods +----------------------------------- +.. index:: CONFIGURE_MAXIMUM_PERIODS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_PERIODS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_PERIODS`` is the maximum number of Classic API Periods that +can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_PARTITIONS === + +.. _Specify Maximum Classic API Partitions: + +Specify Maximum Classic API Partitions +-------------------------------------- +.. index:: CONFIGURE_MAXIMUM_PARTITIONS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_PARTITIONS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_PARTITIONS`` is the maximum number of Classic API +Partitions that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_REGIONS === + +.. _Specify Maximum Classic API Regions: + +Specify Maximum Classic API Regions +----------------------------------- +.. index:: CONFIGURE_MAXIMUM_REGIONS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_REGIONS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_REGIONS`` is the maximum number of Classic API Regions that +can be concurrently active. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_MAXIMUM_PORTS === + +.. _Specify Maximum Classic API Ports: + +Specify Maximum Classic API Ports +--------------------------------- +.. index:: CONFIGURE_MAXIMUM_PORTS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_PORTS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_PORTS`` is the maximum number of Classic API Ports that can +be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_USER_EXTENSIONS === + +.. _Specify Maximum Classic API User Extensions: + +Specify Maximum Classic API User Extensions +------------------------------------------- +.. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` is the maximum number of Classic API User +Extensions that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === Classic API Initialization Task Configuration === + +Classic API Initialization Tasks Table Configuration +==================================================== + +The ``<rtems/confdefs.h>`` configuration system can automatically generate an +Initialization Tasks Table named ``Initialization_tasks`` with a single entry. +The following parameters control the generation of that table. + +.. COMMENT: === CONFIGURE_RTEMS_INIT_TASKS_TABLE === + +.. _Instantiate Classic API Initialization Task Table: + +Instantiate Classic API Initialization Task Table +------------------------------------------------- +.. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE + +*CONSTANT:* + ``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` is defined if the user wishes to use a +Classic RTEMS API Initialization Task Table. The table built by +``<rtems/confdefs.h>`` specifies the parameters for a single task. This is +sufficient for applications which initialization the system from a single task. + +By default, this field is not defined as the user MUST select their own API for +initialization tasks. + +**NOTES:** + +The application may choose to use the initialization tasks or threads table +from another API. + +A compile time error will be generated if the user does not configure any +initialization tasks or threads. + +.. COMMENT: === CONFIGURE_INIT_TASK_ENTRY_POINT === + +.. _Specifying Classic API Initialization Task Entry Point: + +Specifying Classic API Initialization Task Entry Point +------------------------------------------------------ +.. index:: CONFIGURE_INIT_TASK_ENTRY_POINT + +*CONSTANT:* + ``CONFIGURE_INIT_TASK_ENTRY_POINT`` + +*DATA TYPE:* + Task entry function pointer (``rtems_task_entry``). + +*RANGE:* + Valid task entry function pointer. + +*DEFAULT VALUE:* + The default value is ``Init``. + +**DESCRIPTION:** + +``CONFIGURE_INIT_TASK_ENTRY_POINT`` is the entry point (a.k.a. function name) +of the single initialization task defined by the Classic API Initialization +Tasks Table. + +**NOTES:** + +The user must implement the function ``Init`` or the function name provided in +this configuration parameter. + +.. COMMENT: === CONFIGURE_INIT_TASK_NAME === + +.. _Specifying Classic API Initialization Task Name: + +Specifying Classic API Initialization Task Name +----------------------------------------------- +.. index:: CONFIGURE_INIT_TASK_NAME + +*CONSTANT:* + ``CONFIGURE_INIT_TASK_NAME`` + +*DATA TYPE:* + RTEMS Name (``rtems_name``). + +*RANGE:* + Any value. + +*DEFAULT VALUE:* + The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. + +**DESCRIPTION:** + +``CONFIGURE_INIT_TASK_NAME`` is the name of the single initialization task +defined by the Classic API Initialization Tasks Table. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_INIT_TASK_STACK_SIZE === + +.. _Specifying Classic API Initialization Task Stack Size: + +Specifying Classic API Initialization Task Stack Size +----------------------------------------------------- +.. index:: CONFIGURE_INIT_TASK_STACK_SIZE + +*CONSTANT:* + ``CONFIGURE_INIT_TASK_STACK_SIZE`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is RTEMS_MINIMUM_STACK_SIZE. + +**DESCRIPTION:** + +``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single +initialization task defined by the Classic API Initialization Tasks Table. + +**NOTES:** + +If the stack size specified is greater than the configured minimum, it must be +accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve +Task/Thread Stack Memory Above Minimum` for more information about +``CONFIGURE_EXTRA_TASK_STACKS``. + +.. COMMENT: === CONFIGURE_INIT_TASK_PRIORITY === + +.. _Specifying Classic API Initialization Task Priority: + +Specifying Classic API Initialization Task Priority +--------------------------------------------------- +.. index:: CONFIGURE_INIT_TASK_PRIORITY + +*CONSTANT:* + ``CONFIGURE_INIT_TASK_PRIORITY`` + +*DATA TYPE:* + RTEMS Task Priority (``rtems_task_priority``). + +*RANGE:* + One (1) to CONFIGURE_MAXIMUM_PRIORITY. + +*DEFAULT VALUE:* + The default value is 1, which is the highest priority in the + Classic API. + +**DESCRIPTION:** + +``CONFIGURE_INIT_TASK_PRIORITY`` is the initial priority of the single +initialization task defined by the Classic API Initialization Tasks Table. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_INIT_TASK_ATTRIBUTES === + +.. _Specifying Classic API Initialization Task Attributes: + +Specifying Classic API Initialization Task Attributes +----------------------------------------------------- +.. index:: CONFIGURE_INIT_TASK_ATTRIBUTES + +*CONSTANT:* + ``CONFIGURE_INIT_TASK_ATTRIBUTES`` + +*DATA TYPE:* + RTEMS Attributes (``rtems_attribute``). + +*RANGE:* + Valid task attribute sets. + +*DEFAULT VALUE:* + The default value is ``RTEMS_DEFAULT_ATTRIBUTES``. + +**DESCRIPTION:** + +``CONFIGURE_INIT_TASK_ATTRIBUTES`` is the task attributes of the single +initialization task defined by the Classic API Initialization Tasks Table. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_INIT_TASK_INITIAL_MODES === + +.. _Specifying Classic API Initialization Task Modes: + +Specifying Classic API Initialization Task Modes +------------------------------------------------ +.. index:: CONFIGURE_INIT_TASK_INITIAL_MODES + +*CONSTANT:* + ``CONFIGURE_INIT_TASK_INITIAL_MODES`` + +*DATA TYPE:* + RTEMS Mode (``rtems_mode``). + +*RANGE:* + Valid task mode sets. + +*DEFAULT VALUE:* + The default value is ``RTEMS_NO_PREEMPT``. + +**DESCRIPTION:** + +``CONFIGURE_INIT_TASK_INITIAL_MODES`` is the initial execution mode of the +single initialization task defined by the Classic API Initialization Tasks +Table. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_INIT_TASK_ARGUMENTS === + +.. _Specifying Classic API Initialization Task Arguments: + +Specifying Classic API Initialization Task Arguments +---------------------------------------------------- +.. index:: CONFIGURE_INIT_TASK_ARGUMENTS + +*CONSTANT:* + ``CONFIGURE_INIT_TASK_ARGUMENTS`` + +*DATA TYPE:* + RTEMS Task Argument (``rtems_task_argument``). + +*RANGE:* + Complete range of the type. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_INIT_TASK_ARGUMENTS`` is the task argument of the single +initialization task defined by the Classic API Initialization Tasks Table. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_HAS_OWN_INIT_TASK_TABLE === + +.. _Not Using Generated Initialization Tasks Table: + +Not Using Generated Initialization Tasks Table +---------------------------------------------- +.. index:: CONFIGURE_HAS_OWN_INIT_TASK_TABLE + +*CONSTANT:* + ``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` is defined if the user wishes to define +their own Classic API Initialization Tasks Table. This table should be named +``Initialization_tasks``. + +**NOTES:** + +This is a seldom used configuration parameter. The most likely use case is when +an application desires to have more than one initialization task. + +.. COMMENT: === POSIX API Configuration === + +POSIX API Configuration +======================= + +The parameters in this section are used to configure resources for the RTEMS +POSIX API. They are only relevant if the POSIX API is enabled at configure +time using the ``--enable-posix`` option. + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_THREADS === + +.. _Specify Maximum POSIX API Threads: + +Specify Maximum POSIX API Threads +--------------------------------- +.. index:: CONFIGURE_MAXIMUM_POSIX_THREADS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_THREADS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API +Threads that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +This calculations for the required memory in the RTEMS Workspace for threads +assume that each thread has a minimum stack size and has floating point support +enabled. The configuration parameter ``CONFIGURE_EXTRA_TASK_STACKS`` is used +to specify thread stack requirements *ABOVE* the minimum size required. See +:ref:`Reserve Task/Thread Stack Memory Above Minimum` for more information +about ``CONFIGURE_EXTRA_TASK_STACKS``. + +The maximum number of Classic API Tasks is specified by +``CONFIGURE_MAXIMUM_TASKS``. + +All POSIX threads have floating point enabled. + +.. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_TASKS. + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MUTEXES === + +.. _Specify Maximum POSIX API Mutexes: + +Specify Maximum POSIX API Mutexes +--------------------------------- +.. index:: CONFIGURE_MAXIMUM_POSIX_MUTEXES + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_MUTEXES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_MUTEXES`` is the maximum number of POSIX API Mutexes +that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES === + +.. _Specify Maximum POSIX API Condition Variables: + +Specify Maximum POSIX API Condition Variables +--------------------------------------------- +.. index:: CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES`` is the maximum number of POSIX +API Condition Variables that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_KEYS === + +.. _Specify Maximum POSIX API Keys: + +Specify Maximum POSIX API Keys +------------------------------ +.. index:: CONFIGURE_MAXIMUM_POSIX_KEYS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_KEYS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX API Keys that +can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: XXX - Key pairs + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_TIMERS === + +.. _Specify Maximum POSIX API Timers: + +Specify Maximum POSIX API Timers +-------------------------------- +.. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_TIMERS`` is the maximum number of POSIX API Timers +that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS === + +.. _Specify Maximum POSIX API Queued Signals: + +Specify Maximum POSIX API Queued Signals +---------------------------------------- +.. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` is the maximum number of POSIX API +Queued Signals that can be concurrently active. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES === + +.. _Specify Maximum POSIX API Message Queues: + +Specify Maximum POSIX API Message Queues +---------------------------------------- +.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` is the maximum number of POSIX API +Message Queues that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: XXX - memory for buffers note + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS === + +.. _Specify Maximum POSIX API Message Queue Descriptors: + +Specify Maximum POSIX API Message Queue Descriptors +--------------------------------------------------- +.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + greater than or equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGES_QUEUES`` + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` is the maximum number of +POSIX API Message Queue Descriptors that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS`` should be greater than or +equal to ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES``. + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_SEMAPHORES === + +.. _Specify Maximum POSIX API Semaphores: + +Specify Maximum POSIX API Semaphores +------------------------------------ +.. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` is the maximum number of POSIX API +Semaphores that can be concurrently active. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_BARRIERS === + +.. _Specify Maximum POSIX API Barriers: + +Specify Maximum POSIX API Barriers +---------------------------------- +.. index:: CONFIGURE_MAXIMUM_POSIX_BARRIERS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_BARRIERS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_BARRIERS`` is the maximum number of POSIX API +Barriers that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_SPINLOCKS === + +.. _Specify Maximum POSIX API Spinlocks: + +Specify Maximum POSIX API Spinlocks +----------------------------------- +.. index:: CONFIGURE_MAXIMUM_POSIX_SPINLOCKS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_SPINLOCKS`` is the maximum number of POSIX API +Spinlocks that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === CONFIGURE_MAXIMUM_POSIX_RWLOCKS === + +.. _Specify Maximum POSIX API Read/Write Locks: + +Specify Maximum POSIX API Read/Write Locks +------------------------------------------ +.. index:: CONFIGURE_MAXIMUM_POSIX_RWLOCKS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_POSIX_RWLOCKS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_POSIX_RWLOCKS`` is the maximum number of POSIX API +Read/Write Locks that can be concurrently active. + +**NOTES:** + +This object class can be configured in unlimited allocation mode. + +.. COMMENT: === POSIX Initialization Threads Table Configuration === + +POSIX Initialization Threads Table Configuration +================================================ + +The ``<rtems/confdefs.h>`` configuration system can automatically generate a +POSIX Initialization Threads Table named ``POSIX_Initialization_threads`` with +a single entry. The following parameters control the generation of that table. + +.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_TABLE === + +.. _Instantiate POSIX API Initialization Thread Table: + +Instantiate POSIX API Initialization Thread Table +------------------------------------------------- +.. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE + +*CONSTANT:* + .. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This field is not defined by default, as the user MUST select their own API + for initialization tasks. + +**DESCRIPTION:** + +``CONFIGURE_POSIX_INIT_THREAD_TABLE`` is defined if the user wishes to use a +POSIX API Initialization Threads Table. The table built by +``<rtems/confdefs.h>`` specifies the parameters for a single thread. This is +sufficient for applications which initialization the system from a single task. + +By default, this field is not defined as the user MUST select their own API for +initialization tasks. + +**NOTES:** + +The application may choose to use the initialization tasks or threads table +from another API. + +A compile time error will be generated if the user does not configure any +initialization tasks or threads. + +.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT === + +.. _Specifying POSIX API Initialization Thread Entry Point: + +Specifying POSIX API Initialization Thread Entry Point +------------------------------------------------------ +.. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT + +*CONSTANT:* + ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` + +*DATA TYPE:* + POSIX thread function pointer (``void *(*entry_point)(void *)``). + +*RANGE:* + Undefined or a valid POSIX thread function pointer. + +*DEFAULT VALUE:* + The default value is ``POSIX_Init``. + +**DESCRIPTION:** + +``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` is the entry point (a.k.a. function +name) of the single initialization thread defined by the POSIX API +Initialization Threads Table. + +**NOTES:** + +The user must implement the function ``POSIX_Init`` or the function name +provided in this configuration parameter. + +.. COMMENT: === CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE === + +.. _Specifying POSIX API Initialization Thread Stack Size: + +Specifying POSIX API Initialization Thread Stack Size +----------------------------------------------------- +.. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE + +*CONSTANT:* + ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 2 \* RTEMS_MINIMUM_STACK_SIZE. + +**DESCRIPTION:** + +``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the single +initialization thread defined by the POSIX API Initialization Threads Table. + +**NOTES:** + +If the stack size specified is greater than the configured minimum, it must be +accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve +Task/Thread Stack Memory Above Minimum` for more information about +``CONFIGURE_EXTRA_TASK_STACKS``. + +.. COMMENT: === CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE === + +.. _Not Using Generated POSIX Initialization Threads Table: + +Not Using Generated POSIX Initialization Threads Table +------------------------------------------------------ +.. index:: CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE + +*CONSTANT:* + ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` is defined if the user wishes to +define their own POSIX API Initialization Threads Table. This table should be +named ``POSIX_Initialization_threads``. + +**NOTES:** + +This is a seldom used configuration parameter. The most likely use case is when +an application desires to have more than one initialization task. + +.. COMMENT: === Basic System Information === + +Basic System Information +======================== + +This section defines the general system configuration parameters supported by +``<rtems/confdefs.h>``. + +.. COMMENT: === CONFIGURE_UNIFIED_WORK_AREAS === + +.. _Separate or Unified Work Areas: + +Separate or Unified Work Areas +------------------------------ +.. index:: CONFIGURE_UNIFIED_WORK_AREAS +.. index:: unified work areas +.. index:: separate work areas +.. index:: RTEMS Workspace +.. index:: C Program Heap + +*CONSTANT:* + ``CONFIGURE_UNIFIED_WORK_AREAS`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default, which specifies that the C Program Heap and + the RTEMS Workspace will be separate. + +**DESCRIPTION:** + +When defined, the C Program Heap and the RTEMS Workspace will be one pool of +memory. + +When not defined, there will be separate memory pools for the RTEMS Workspace +and C Program Heap. + +**NOTES:** + +Having separate pools does have some advantages in the event a task blows a +stack or writes outside its memory area. However, in low memory systems the +overhead of the two pools plus the potential for unused memory in either pool +is very undesirable. + +In high memory environments, this is desirable when you want to use the RTEMS +"unlimited" objects option. You will be able to create objects until you run +out of all available memory rather then just until you run out of RTEMS +Workspace. + +.. COMMENT: === CONFIGURE_MICROSECONDS_PER_TICK === + +.. _Length of Each Clock Tick: + +Length of Each Clock Tick +------------------------- +.. index:: CONFIGURE_MICROSECONDS_PER_TICK +.. index:: tick quantum + +*CONSTANT:* + ``CONFIGURE_MICROSECONDS_PER_TICK`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + This is not defined by default. When not defined, the clock tick quantum is + configured to be 10,000 microseconds which is ten (10) milliseconds. + +**DESCRIPTION:** + +This constant is used to specify the length of time between clock ticks. + +When the clock tick quantum value is too low, the system will spend so much +time processing clock ticks that it does not have processing time available to +perform application work. In this case, the system will become unresponsive. + +The lowest practical time quantum varies widely based upon the speed of the +target hardware and the architectural overhead associated with interrupts. In +general terms, you do not want to configure it lower than is needed for the +application. + +The clock tick quantum should be selected such that it all blocking and delay +times in the application are evenly divisible by it. Otherwise, rounding errors +will be introduced which may negatively impact the application. + +**NOTES:** + +This configuration parameter has no impact if the Clock Tick Device driver is +not configured. + +There may be BSP specific limits on the resolution or maximum value of a clock +tick quantum. + +.. COMMENT: === CONFIGURE_TICKS_PER_TIMESLICE === + +.. _Specifying Timeslicing Quantum: + +Specifying Timeslicing Quantum +------------------------------ +.. index:: CONFIGURE_TICKS_PER_TIMESLICE +.. index:: ticks per timeslice + +*CONSTANT:* + ``CONFIGURE_TICKS_PER_TIMESLICE`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is 50. + +**DESCRIPTION:** + +This configuration parameter specifies the length of the timeslice quantum in +ticks for each task. + +**NOTES:** + +This configuration parameter has no impact if the Clock Tick Device driver is +not configured. + +.. COMMENT: === CONFIGURE_MAXIMUM_PRIORITY === + +.. _Specifying the Number of Thread Priority Levels: + +Specifying the Number of Thread Priority Levels +----------------------------------------------- +.. index:: CONFIGURE_MAXIMUM_PRIORITY +.. index:: maximum priority +.. index:: number of priority levels + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_PRIORITY`` + +*DATA TYPE:* + Unsigned integer (``uint8_t``). + +*RANGE:* + Valid values for this configuration parameter must be one (1) less than + than a power of two (2) between 4 and 256 inclusively. In other words, + valid values are 3, 7, 31, 63, 127, and 255. + +*DEFAULT VALUE:* + The default value is 255, because RTEMS must support 256 priority levels to + be compliant with various standards. These priorities range from zero (0) + to 255. + +**DESCRIPTION:** + +This configuration parameter specified the maximum numeric priority of any task +in the system and one less that the number of priority levels in the system. + +Reducing the number of priorities in the system reduces the amount of memory +allocated from the RTEMS Workspace. + +**NOTES:** + +The numerically greatest priority is the logically lowest priority in the +system and will thus be used by the IDLE task. + +Priority zero (0) is reserved for internal use by RTEMS and is not available to +applications. + +With some schedulers, reducing the number of priorities can reduce the amount +of memory used by the scheduler. For example, the Deterministic Priority +Scheduler (DPS) used by default uses three pointers of storage per priority +level. Reducing the number of priorities from 256 levels to sixteen (16) can +reduce memory usage by about three (3) kilobytes. + +.. COMMENT: === CONFIGURE_MINIMUM_TASK_STACK_SIZE === + +.. _Specifying the Minimum Task Size: + +Specifying the Minimum Task Size +-------------------------------- +.. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE +.. index:: minimum task stack size + +*CONSTANT:* + ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + This is not defined by default, which sets the executive to the recommended + minimum stack size for this processor. + +**DESCRIPTION:** + +The configuration parameter is set to the number of bytes the application wants +the minimum stack size to be for every task or thread in the system. + +Adjusting this parameter should be done with caution. Examining the actual +usage using the Stack Checker Usage Reporting facility is recommended. + +**NOTES:** + +This parameter can be used to lower the minimum from that recommended. This can +be used in low memory systems to reduce memory consumption for stacks. However, +this must be done with caution as it could increase the possibility of a blown +task stack. + +This parameter can be used to increase the minimum from that recommended. This +can be used in higher memory systems to reduce the risk of stack overflow +without performing analysis on actual consumption. + +.. COMMENT: === CONFIGURE_INTERRUPT_STACK_SIZE === + +.. _Configuring the Size of the Interrupt Stack: + +Configuring the Size of the Interrupt Stack +------------------------------------------- +.. index:: CONFIGURE_INTERRUPT_STACK_SIZE +.. index:: interrupt stack size + +*CONSTANT:* + ``CONFIGURE_INTERRUPT_STACK_SIZE`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is CONFIGURE_MINIMUM_TASK_STACK_SIZE, which is the + minimum interrupt stack size. + +**DESCRIPTION:** + +``CONFIGURE_INTERRUPT_STACK_SIZE`` is set to the size of the interrupt stack. +The interrupt stack size is often set by the BSP but since this memory may be +allocated from the RTEMS Workspace, it must be accounted for. + +**NOTES:** + +In some BSPs, changing this constant does NOT change the size of the interrupt +stack, only the amount of memory reserved for it. + +Patches which result in this constant only being used in memory calculations +when the interrupt stack is intended to be allocated from the RTEMS Workspace +would be welcomed by the RTEMS Project. + +.. COMMENT: === CONFIGURE_EXTRA_TASK_STACKS === + +.. _Reserve Task/Thread Stack Memory Above Minimum: + +Reserve Task/Thread Stack Memory Above Minimum +---------------------------------------------- +.. index:: CONFIGURE_EXTRA_TASK_STACKS +.. index:: memory for task tasks + +*CONSTANT:* + ``CONFIGURE_EXTRA_TASK_STACKS`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Undefined or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +This configuration parameter is set to the number of bytes the applications +wishes to add to the task stack requirements calculated by +``<rtems/confdefs.h>``. + +**NOTES:** + +This parameter is very important. If the application creates tasks with stacks +larger then the minimum, then that memory is NOT accounted for by +``<rtems/confdefs.h>``. + +.. COMMENT: === CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY === + +.. _Automatically Zeroing the RTEMS Workspace and C Program Heap: + +Automatically Zeroing the RTEMS Workspace and C Program Heap +------------------------------------------------------------ +.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY +.. index:: clear C Program Heap +.. index:: clear RTEMS Workspace +.. index:: zero C Program Heap +.. index:: zero RTEMS Workspace + +*CONSTANT:* + ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default, unless overridden by the BSP. The default + is *NOT* to zero out the RTEMS Workspace or C Program Heap. + +**DESCRIPTION:** + +This macro indicates whether RTEMS should zero the RTEMS Workspace and C +Program Heap as part of its initialization. If defined, the memory regions are +zeroed. Otherwise, they are not. + +**NOTES:** + +Zeroing memory can add significantly to system boot time. It is not necessary +for RTEMS but is often assumed by support libraries. + +.. COMMENT: === CONFIGURE_STACK_CHECKER_ENABLED === + +.. _Enable The Task Stack Usage Checker: + +Enable The Task Stack Usage Checker +----------------------------------- +.. index:: CONFIGURE_STACK_CHECKER_ENABLED + +*CONSTANT:* + ``CONFIGURE_STACK_CHECKER_ENABLED`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default, and thus stack checking is disabled. + +**DESCRIPTION:** + +This configuration parameter is defined when the application wishes to enable +run-time stack bounds checking. + +**NOTES:** + +In 4.9 and older, this configuration parameter was named ``STACK_CHECKER_ON``. + +This increases the time required to create tasks as well as adding overhead to +each context switch. + +.. COMMENT: === CONFIGURE_INITIAL_EXTENSIONS === + +.. _Specify Application Specific User Extensions: + +Specify Application Specific User Extensions +-------------------------------------------- +.. index:: CONFIGURE_INITIAL_EXTENSIONS + +*CONSTANT:* + ``CONFIGURE_INITIAL_EXTENSIONS`` + +*DATA TYPE:* + List of user extension initializers (``rtems_extensions_table``). + +*RANGE:* + Undefined or a list of one or more user extensions. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +If ``CONFIGURE_INITIAL_EXTENSIONS`` is defined by the application, then this +application specific set of initial extensions will be placed in the initial +extension table. + +**NOTES:** + +None. + +.. COMMENT: === Custom Stack Allocator === + +Configuring Custom Task Stack Allocation +======================================== + +RTEMS allows the application or BSP to define its own allocation and +deallocation methods for task stacks. This can be used to place task stacks in +special areas of memory or to utilize a Memory Management Unit so that stack +overflows are detected in hardware. + +.. COMMENT: === CONFIGURE_TASK_STACK_ALLOCATOR_INIT === + +.. _Custom Task Stack Allocator Initialization: + +Custom Task Stack Allocator Initialization +------------------------------------------ +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT + +*CONSTANT:* + ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +*DATA TYPE:* + Function pointer. + +*RANGE:* + Undefined, NULL or valid function pointer. + +*DEFAULT VALUE:* + The default value is NULL, which indicates that task stacks will be + allocated from the RTEMS Workspace. + +**DESCRIPTION:** + +``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` configures the initialization method +for an application or BSP specific task stack allocation implementation. + +**NOTES:** + +A correctly configured system must configure the following to be consistent: + +- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +- ``CONFIGURE_TASK_STACK_ALLOCATOR`` + +- ``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. COMMENT: === CONFIGURE_TASK_STACK_ALLOCATOR === + +.. _Custom Task Stack Allocator: + +Custom Task Stack Allocator +--------------------------- +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR + +.. index:: task stack allocator + +*CONSTANT:* + ``CONFIGURE_TASK_STACK_ALLOCATOR`` + +*DATA TYPE:* + Function pointer. + +*RANGE:* + Undefined or valid function pointer. + +*DEFAULT VALUE:* + The default value is ``_Workspace_Allocate``, which indicates that task + stacks will be allocated from the RTEMS Workspace. + +**DESCRIPTION:** + +``CONFIGURE_TASK_STACK_ALLOCATOR`` may point to a user provided routine to +allocate task stacks. + +**NOTES:** + +A correctly configured system must configure the following to be consistent: + +- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +- ``CONFIGURE_TASK_STACK_ALLOCATOR`` + +- ``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. COMMENT: === CONFIGURE_TASK_STACK_DEALLOCATOR === + +.. _Custom Task Stack Deallocator: + +Custom Task Stack Deallocator +----------------------------- +.. index:: CONFIGURE_TASK_STACK_DEALLOCATOR +.. index:: task stack deallocator + +*CONSTANT:* + ``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +*DATA TYPE:* + Function pointer. + +*RANGE:* + Undefined or valid function pointer. + +*DEFAULT VALUE:* + The default value is ``_Workspace_Free``, which indicates that task stacks + will be allocated from the RTEMS Workspace. + +**DESCRIPTION:** + +``CONFIGURE_TASK_STACK_DEALLOCATOR`` may point to a user provided routine to +free task stacks. + +**NOTES:** + +A correctly configured system must configure the following to be consistent: + +- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +- ``CONFIGURE_TASK_STACK_ALLOCATOR`` + +- ``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. COMMENT: === Classic API Message Buffers === + +Configuring Memory for Classic API Message Buffers +================================================== + +This section describes the configuration parameters related to specifying the +amount of memory reserved for Classic API Message Buffers. + +.. COMMENT: === CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE === + +.. _Calculate Memory for a Single Classic Message API Message Queue: + +Calculate Memory for a Single Classic Message API Message Queue +--------------------------------------------------------------- +.. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE +.. index:: memory for a single message queue's buffers + +*CONSTANT:* + ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is None. + +**DESCRIPTION:** + +This is a helper macro which is used to assist in computing the total amount of +memory required for message buffers. Each message queue will have its own +configuration with maximum message size and maximum number of pending messages. + +The interface for this macro is as follows: + +.. code-block:: c + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per) + +Where ``max_messages`` is the maximum number of pending messages and +``size_per`` is the size in bytes of the user message. + +**NOTES:** + +This macro is only used in support of ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. + +.. COMMENT: === CONFIGURE_MESSAGE_BUFFER_MEMORY === + +.. _Reserve Memory for All Classic Message API Message Queues: + +Reserve Memory for All Classic Message API Message Queues +--------------------------------------------------------- +.. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY +.. index:: configure message queue buffer memory + +*CONSTANT:* + ``CONFIGURE_MESSAGE_BUFFER_MEMORY`` + +*DATA TYPE:* + integer summation macro + +*RANGE:* + undefined (zero) or calculation resulting in a positive integer + +*DEFAULT VALUE:* + This is not defined by default, and zero (0) memory is reserved. + +**DESCRIPTION:** + +This macro is set to the number of bytes the application requires to be +reserved for pending Classic API Message Queue buffers. + +**NOTES:** + +The following illustrates how the help macro +``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE`` can be used to assist in calculating +the message buffer memory required. In this example, there are two message +queues used in this application. The first message queue has maximum of 24 +pending messages with the message structure defined by the type +``one_message_type``. The other message queue has maximum of 500 pending +messages with the message structure defined by the type ``other_message_type``. + +.. code-block:: c + + #define CONFIGURE_MESSAGE_BUFFER_MEMORY \ + (CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 24, sizeof(one_message_type) \ + ) + \ + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 500, sizeof(other_message_type) \ + ) + +.. COMMENT: === Seldom Used Configuration Parameters === + +Seldom Used Configuration Parameters +==================================== + +This section describes configuration parameters supported by +``<rtems/confdefs.h>`` which are seldom used by applications. These parameters +tend to be oriented to debugging system configurations and providing +work-arounds when the memory estimated by ``<rtems/confdefs.h>`` is incorrect. + +.. COMMENT: === CONFIGURE_MEMORY_OVERHEAD === + +.. _Specify Memory Overhead: + +Specify Memory Overhead +----------------------- +.. index:: CONFIGURE_MEMORY_OVERHEAD + +*CONSTANT:* + ``CONFIGURE_MEMORY_OVERHEAD`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +Thie parameter is set to the number of kilobytes the application wishes to add +to the requirements calculated by ``<rtems/confdefs.h>``. + +**NOTES:** + +This configuration parameter should only be used when it is suspected that a +bug in ``<rtems/confdefs.h>`` has resulted in an underestimation. Typically +the memory allocation will be too low when an application does not account for +all message queue buffers or task stacks. + +.. COMMENT: === CONFIGURE_HAS_OWN_CONFIGURATION_TABLE === + +.. _Do Not Generate Configuration Information: + +Do Not Generate Configuration Information +----------------------------------------- +.. index:: CONFIGURE_HAS_OWN_CONFIGURATION_TABLE + +*CONSTANT:* + ``CONFIGURE_HAS_OWN_CONFIGURATION_TABLE`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +This configuration parameter should only be defined if the application is +providing their own complete set of configuration tables. + +**NOTES:** + +None. + +.. COMMENT: === C Library Support Configuration === + +C Library Support Configuration +=============================== + +This section defines the file system and IO library related configuration +parameters supported by ``<rtems/confdefs.h>``. + +.. COMMENT: === CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS === + +.. _Specify Maximum Number of File Descriptors: + +Specify Maximum Number of File Descriptors +------------------------------------------ +.. index:: CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS +.. index:: maximum file descriptors + +*CONSTANT:* + ``CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + If ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined, then the + default value is 3, otherwise the default value is 0. Three file + descriptors allows RTEMS to support standard input, output, and error I/O + streams on ``/dev/console``. + +**DESCRIPTION:** + +This configuration parameter is set to the maximum number of file like objects +that can be concurrently open. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_TERMIOS_DISABLED === + +.. _Disable POSIX Termios Support: + +Disable POSIX Termios Support +----------------------------- +.. index:: CONFIGURE_TERMIOS_DISABLED + +*CONSTANT:* + ``CONFIGURE_TERMIOS_DISABLED`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default, and resources are reserved for the termios + functionality. + +**DESCRIPTION:** + +This configuration parameter is defined if the software implementing POSIX +termios functionality is not going to be used by this application. + +**NOTES:** + +The termios support library should not be included in an application executable +unless it is directly referenced by the application or a device driver. + +.. COMMENT: === CONFIGURE_NUMBER_OF_TERMIOS_PORTS === + +.. _Specify Maximum Termios Ports: + +Specify Maximum Termios Ports +----------------------------- +.. index:: CONFIGURE_NUMBER_OF_TERMIOS_PORTS + +*CONSTANT:* + ``CONFIGURE_NUMBER_OF_TERMIOS_PORTS`` + +*DATA TYPE:* + Unsigned integer. + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 1, so a console port can be used. + +**DESCRIPTION:** + +This configuration parameter is set to the number of ports using the termios +functionality. Each concurrently active termios port requires resources. + +**NOTES:** + +If the application will be using serial ports including, but not limited to, +the Console Device (e.g. ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``), then +it is highly likely that this configuration parameter should NOT be is defined. + +.. COMMENT: === File System Configuration Parameters === + +File System Configuration Parameters +==================================== + +This section defines File System related configuration parameters. + +.. COMMENT: === CONFIGURE_HAS_OWN_MOUNT_TABLE === + +.. _Providing Application Specific Mount Table: + +Providing Application Specific Mount Table +------------------------------------------ +.. index:: CONFIGURE_HAS_OWN_MOUNT_TABLE + +*CONSTANT:* + ``CONFIGURE_HAS_OWN_MOUNT_TABLE`` + +*DATA TYPE:* + Undefined or an array of type ``rtems_filesystem_mount_table_t``. + +*RANGE:* + Undefined or an array of type ``rtems_filesystem_mount_table_t``. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +This configuration parameter is defined when the application provides their own +filesystem mount table. The mount table is an array of +``rtems_filesystem_mount_table_t`` entries pointed to by the global variable +``rtems_filesystem_mount_table``. The number of entries in this table is in an +integer variable named ``rtems_filesystem_mount_table_t``. + +.. COMMENT: XXX - is the variable name for the count right? + +**NOTES:** + +None. + +.. COMMENT: XXX - Please provide an example + +.. COMMENT: === CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM === + +.. _Configure devFS as Root File System: + +Configure devFS as Root File System +----------------------------------- +.. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM + +*CONSTANT:* + ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. If no other root file system configuration + parameters are specified, the IMFS will be used as the root file system. + +**DESCRIPTION:** + +This configuration parameter is defined if the application wishes to use the +device-only filesytem as the root file system. + +**NOTES:** + +The device-only filesystem supports only device nodes and is smaller in +executable code size than the full IMFS and miniIMFS. + +The devFS is comparable in functionality to the pseudo-filesystem name space +provided before RTEMS release 4.5.0. + +.. COMMENT: === CONFIGURE_MAXIMUM_DEVICES === + +.. _Specifying Maximum Devices for devFS: + +Specifying Maximum Devices for devFS +------------------------------------ +.. index:: CONFIGURE_MAXIMUM_DEVICES + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_DEVICES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + If ``BSP_MAXIMUM_DEVICES`` is defined, then the default value is + ``BSP_MAXIMUM_DEVICES``, otherwise the default value is 4. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_DEVICES`` is defined to the number of individual devices +that may be registered in the device file system (devFS). + +**NOTES:** + +This option is specific to the device file system (devFS) and should not be +confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter only +impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when +``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. + +.. COMMENT: === CONFIGURE_APPLICATION_DISABLE_FILESYSTEM === + +.. _Disable File System Support: + +Disable File System Support +--------------------------- +.. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM + +*CONSTANT:* + ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. If no other root file system configuration + parameters are specified, the IMFS will be used as the root file system. + +**DESCRIPTION:** + +This configuration parameter is defined if the application dose not intend to +use any kind of filesystem support. This include the device infrastructure +necessary to support ``printf()``. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM === + +.. _Use a Root IMFS with a Minimalistic Feature Set: + +Use a Root IMFS with a Minimalistic Feature Set +----------------------------------------------- +.. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM + +*CONSTANT:* + ``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the following configuration +options will be defined as well + +- ``CONFIGURE_IMFS_DISABLE_CHMOD``, + +- ``CONFIGURE_IMFS_DISABLE_CHOWN``, + +- ``CONFIGURE_IMFS_DISABLE_UTIME``, + +- ``CONFIGURE_IMFS_DISABLE_LINK``, + +- ``CONFIGURE_IMFS_DISABLE_SYMLINK``, + +- ``CONFIGURE_IMFS_DISABLE_READLINK``, + +- ``CONFIGURE_IMFS_DISABLE_RENAME``, and + +- ``CONFIGURE_IMFS_DISABLE_UNMOUNT``. + +.. COMMENT: === CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK === + +.. _Specify Block Size for IMFS: + +Specify Block Size for IMFS +--------------------------- +.. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK + +*CONSTANT:* + ``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Valid values for this configuration parameter are a power of two (2) + between 16 and 512 inclusive. In other words, valid values are 16, 32, 64, + 128, 256,and 512. + +*DEFAULT VALUE:* + The default IMFS block size is 128 bytes. + +**DESCRIPTION:** + +This configuration parameter specifies the block size for in-memory files +managed by the IMFS. The configured block size has two impacts. The first is +the average amount of unused memory in the last block of each file. For +example, when the block size is 512, on average one-half of the last block of +each file will remain unused and the memory is wasted. In contrast, when the +block size is 16, the average unused memory per file is only 8 bytes. However, +it requires more allocations for the same size file and thus more overhead per +block for the dynamic memory management. + +Second, the block size has an impact on the maximum size file that can be +stored in the IMFS. With smaller block size, the maximum file size is +correspondingly smaller. The following shows the maximum file size possible +based on the configured block size: + +- when the block size is 16 bytes, the maximum file size is 1,328 bytes. + +- when the block size is 32 bytes, the maximum file size is 18,656 bytes. + +- when the block size is 64 bytes, the maximum file size is 279,488 bytes. + +- when the block size is 128 bytes, the maximum file size is 4,329,344 bytes. + +- when the block size is 256 bytes, the maximum file size is 68,173,568 bytes. + +- when the block size is 512 bytes, the maximum file size is 1,082,195,456 + bytes. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_CHOWN === + +.. _Disable Change Owner Support of Root IMFS: + +Disable Change Owner Support of Root IMFS +----------------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_CHOWN + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_CHOWN`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to change the +owner is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_CHMOD === + +.. _Disable Change Mode Support of Root IMFS: + +Disable Change Mode Support of Root IMFS +---------------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_CHMOD + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_CHMOD`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to change the +mode is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_UTIME === + +.. _Disable Change Times Support of Root IMFS: + +Disable Change Times Support of Root IMFS +----------------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_UTIME + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_UTIME`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to change times +is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_LINK === + +.. _Disable Create Hard Link Support of Root IMFS: + +Disable Create Hard Link Support of Root IMFS +--------------------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_LINK + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_LINK`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to create hard +links is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_SYMLINK === + +.. _Disable Create Symbolic Link Support of Root IMFS: + +Disable Create Symbolic Link Support of Root IMFS +------------------------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_SYMLINK + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_SYMLINK`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to create +symbolic links is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_READLINK === + +.. _Disable Read Symbolic Link Support of Root IMFS: + +Disable Read Symbolic Link Support of Root IMFS +----------------------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_READLINK + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_READLINK`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to read symbolic +links is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_RENAME === + +.. _Disable Rename Support of Root IMFS: + +Disable Rename Support of Root IMFS +----------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_RENAME + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_RENAME`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to rename nodes +is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_READDIR === + +.. _Disable Directory Read Support of Root IMFS: + +Disable Directory Read Support of Root IMFS +------------------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_READDIR + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_READDIR`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to read a +directory is disabled in the root IMFS. It is still possible to open nodes in +a directory. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_MOUNT === + +.. _Disable Mount Support of Root IMFS: + +Disable Mount Support of Root IMFS +---------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_MOUNT + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_MOUNT`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to mount other +file systems is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_UNMOUNT === + +.. _Disable Unmount Support of Root IMFS: + +Disable Unmount Support of Root IMFS +------------------------------------ +.. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_UNMOUNT`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to unmount file +systems is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_MKNOD === + +.. _Disable Make Nodes Support of Root IMFS: + +Disable Make Nodes Support of Root IMFS +--------------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_MKNOD + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_MKNOD`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to make +directories, devices, regular files and FIFOs is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_MKNOD_FILE === + +.. _Disable Make Files Support of Root IMFS: + +Disable Make Files Support of Root IMFS +--------------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_MKNOD_FILE`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to make regular +files is disabled in the root IMFS. + +.. COMMENT: === CONFIGURE_IMFS_DISABLE_RMNOD === + +.. _Disable Remove Nodes Support of Root IMFS: + +Disable Remove Nodes Support of Root IMFS +----------------------------------------- +.. index:: CONFIGURE_IMFS_DISABLE_RMNOD + +*CONSTANT:* + ``CONFIGURE_IMFS_DISABLE_RMNOD`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +In case this configuration option is defined, then the support to remove nodes +is disabled in the root IMFS. + +.. COMMENT: === Block Device Cache Configuration === + +Block Device Cache Configuration +================================ + +This section defines Block Device Cache (bdbuf) related configuration +parameters. + +.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_LIBBLOCK === + +.. _Enable Block Device Cache: + +Enable Block Device Cache +------------------------- +.. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK + +*CONSTANT:* + ``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +Provides a Block Device Cache configuration. + +**NOTES:** + +Each option of the Block Device Cache configuration can be explicitly set by +the user with the configuration options below. The Block Device Cache is used +for example by the RFS and DOSFS file systems. + +.. COMMENT: === CONFIGURE_BDBUF_CACHE_MEMORY_SIZE === + +.. _Size of the Cache Memory: + +Size of the Cache Memory +------------------------ +.. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE + +*CONSTANT:* + ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is 32768 bytes. + +**DESCRIPTION:** + +Size of the cache memory in bytes. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_BDBUF_BUFFER_MIN_SIZE === + +.. _Minimum Size of a Buffer: + +Minimum Size of a Buffer +------------------------ +.. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE + +*CONSTANT:* + ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is 512 bytes. + +**DESCRIPTION:** + +Defines the minimum size of a buffer in bytes. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_BDBUF_BUFFER_MAX_SIZE === + +.. _Maximum Size of a Buffer: + +Maximum Size of a Buffer +------------------------ +.. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE + +*CONSTANT:* + ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + It must be positive and an integral multiple of the buffer minimum size. + +*DEFAULT VALUE:* + The default value is 4096 bytes. + +**DESCRIPTION:** + +Defines the maximum size of a buffer in bytes. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_SWAPOUT_SWAP_PERIOD === + +.. _Swapout Task Swap Period: + +Swapout Task Swap Period +------------------------ +.. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD + +*CONSTANT:* + ``CONFIGURE_SWAPOUT_SWAP_PERIOD`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is 250 milliseconds. + +**DESCRIPTION:** + +Defines the swapout task swap period in milliseconds. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_SWAPOUT_BLOCK_HOLD === + +.. _Swapout Task Maximum Block Hold Time: + +Swapout Task Maximum Block Hold Time +------------------------------------ +.. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD + +*CONSTANT:* + ``CONFIGURE_SWAPOUT_BLOCK_HOLD`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is 1000 milliseconds. + +**DESCRIPTION:** + +Defines the swapout task maximum block hold time in milliseconds. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_SWAPOUT_TASK_PRIORITY === + +.. _Swapout Task Priority: + +Swapout Task Priority +--------------------- +.. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY + +*CONSTANT:* + ``CONFIGURE_SWAPOUT_TASK_PRIORITY`` + +*DATA TYPE:* + Task priority (``rtems_task_priority``). + +*RANGE:* + Valid task priority. + +*DEFAULT VALUE:* + The default value is 15. + +**DESCRIPTION:** + +Defines the swapout task priority. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS === + +.. _Maximum Blocks per Read-Ahead Request: + +Maximum Blocks per Read-Ahead Request +------------------------------------- +.. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS + +*CONSTANT:* + ``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +Defines the maximum blocks per read-ahead request. + +**NOTES:** + +A value of 0 disables the read-ahead task (default). The read-ahead task will +issue speculative read transfers if a sequential access pattern is detected. +This can improve the performance on some systems. + +.. COMMENT: === CONFIGURE_BDBUF_MAX_WRITE_BLOCKS === + +.. _Maximum Blocks per Write Request: + +Maximum Blocks per Write Request +-------------------------------- +.. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS + +*CONSTANT:* + ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is 16. + +**DESCRIPTION:** + +Defines the maximum blocks per write request. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_BDBUF_TASK_STACK_SIZE === + +.. _Task Stack Size of the Block Device Cache Tasks: + +Task Stack Size of the Block Device Cache Tasks +----------------------------------------------- +.. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE + +*CONSTANT:* + ``CONFIGURE_BDBUF_TASK_STACK_SIZE`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is RTEMS_MINIMUM_STACK_SIZE. + +**DESCRIPTION:** + +Defines the task stack size of the Block Device Cache tasks in bytes. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY === + +.. _Read-Ahead Task Priority: + +Read-Ahead Task Priority +------------------------ +.. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY + +*CONSTANT:* + ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` + +*DATA TYPE:* + Task priority (``rtems_task_priority``). + +*RANGE:* + Valid task priority. + +*DEFAULT VALUE:* + The default value is 15. + +**DESCRIPTION:** + +Defines the read-ahead task priority. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_SWAPOUT_WORKER_TASKS === + +.. _Swapout Worker Task Count: + +Swapout Worker Task Count +------------------------- +.. index:: CONFIGURE_SWAPOUT_WORKER_TASKS + +*CONSTANT:* + ``CONFIGURE_SWAPOUT_WORKER_TASKS`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +Defines the swapout worker task count. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY === + +.. _Swapout Worker Task Priority: + +Swapout Worker Task Priority +---------------------------- +.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY + +*CONSTANT:* + ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` + +*DATA TYPE:* + Task priority (``rtems_task_priority``). + +*RANGE:* + Valid task priority. + +*DEFAULT VALUE:* + The default value is 15. + +**DESCRIPTION:** + +Defines the swapout worker task priority. + +**NOTES:** + +None. + +.. COMMENT: === BSP Specific Settings === + +BSP Specific Settings +===================== + +This section describes BSP specific configuration settings used by +``<rtems/confdefs.h>``. The BSP specific configuration settings are defined in +``<bsp.h>``. + +.. COMMENT: === Disable BSP Settings === + +.. _Disable BSP Configuration Settings: + +Disable BSP Configuration Settings +---------------------------------- +.. index:: CONFIGURE_DISABLE_BSP_SETTINGS + +*CONSTANT:* + ``CONFIGURE_DISABLE_BSP_SETTINGS`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +All BSP specific configuration settings can be disabled by the application with +the ``CONFIGURE_DISABLE_BSP_SETTINGS`` option. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK === + +.. _Specify BSP Supports sbrk(): + +Specify BSP Supports sbrk() +--------------------------- +.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK + +*CONSTANT:* + ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This option is BSP specific. + +**DESCRIPTION:** + +This configuration parameter is defined by a BSP to indicate that it does not +allocate all available memory to the C Program Heap used by the Malloc Family +of routines. + +If defined, when ``malloc()`` is unable to allocate memory, it will call the +BSP supplied ``sbrk()`` to obtain more memory. + +**NOTES:** + +This parameter should not be defined by the application. Only the BSP knows how +it allocates memory to the C Program Heap. + +.. COMMENT: === BSP_IDLE_TASK_BODY === + +.. _Specify BSP Specific Idle Task: + +Specify BSP Specific Idle Task +------------------------------ +.. index:: BSP_IDLE_TASK_BODY + +*CONSTANT:* + ``BSP_IDLE_TASK_BODY`` + +*DATA TYPE:* + Function pointer. + +*RANGE:* + Undefined or valid function pointer. + +*DEFAULT VALUE:* + This option is BSP specific. + +**DESCRIPTION:** + +If ``BSP_IDLE_TASK_BODY`` is defined by the BSP and +``CONFIGURE_IDLE_TASK_BODY`` is not defined by the application, then this BSP +specific idle task body will be used. + +**NOTES:** + +As it has knowledge of the specific CPU model, system controller logic, and +peripheral buses, a BSP specific IDLE task may be capable of turning components +off to save power during extended periods of no task activity + +.. COMMENT: === BSP_IDLE_TASK_STACK_SIZE === + +.. _Specify BSP Suggested Value for IDLE Task Stack Size: + +Specify BSP Suggested Value for IDLE Task Stack Size +---------------------------------------------------- +.. index:: BSP_IDLE_TASK_STACK_SIZE + +*CONSTANT:* + ``BSP_IDLE_TASK_STACK_SIZE`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Undefined or positive. + +*DEFAULT VALUE:* + This option is BSP specific. + +**DESCRIPTION:** + +If ``BSP_IDLE_TASK_STACK_SIZE`` is defined by the BSP and +``CONFIGURE_IDLE_TASK_STACK_SIZE`` is not defined by the application, then this +BSP suggested idle task stack size will be used. + +**NOTES:** + +The order of precedence for configuring the IDLE task stack size is: + +- RTEMS default minimum stack size. + +- If defined, then ``CONFIGURE_MINIMUM_TASK_STACK_SIZE``. + +- If defined, then the BSP specific ``BSP_IDLE_TASK_SIZE``. + +- If defined, then the application specified ``CONFIGURE_IDLE_TASK_SIZE``. + +.. COMMENT: XXX - add cross references to other related values. + +.. COMMENT: === BSP_INITIAL_EXTENSION === + +.. _Specify BSP Specific User Extensions: + +Specify BSP Specific User Extensions +------------------------------------ +.. index:: BSP_INITIAL_EXTENSION + +*CONSTANT:* + ``BSP_INITIAL_EXTENSION`` + +*DATA TYPE:* + List of user extension initializers (``rtems_extensions_table``). + +*RANGE:* + Undefined or a list of user extension initializers. + +*DEFAULT VALUE:* + This option is BSP specific. + +**DESCRIPTION:** + +If ``BSP_INITIAL_EXTENSION`` is defined by the BSP, then this BSP specific +initial extension will be placed as the last entry in the initial extension +table. + +**NOTES:** + +None. + +.. COMMENT: === BSP_INTERRUPT_STACK_SIZE === + +.. _Specifying BSP Specific Interrupt Stack Size: + +Specifying BSP Specific Interrupt Stack Size +-------------------------------------------- +.. index:: BSP_INTERRUPT_STACK_SIZE + +*CONSTANT:* + ``BSP_INTERRUPT_STACK_SIZE`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Undefined or positive. + +*DEFAULT VALUE:* + This option is BSP specific. + +**DESCRIPTION:** + +If ``BSP_INTERRUPT_STACK_SIZE`` is defined by the BSP and +``CONFIGURE_INTERRUPT_STACK_SIZE`` is not defined by the application, then this +BSP specific interrupt stack size will be used. + +**NOTES:** + +None. + +.. COMMENT: === BSP_MAXIMUM_DEVICES === + +.. _Specifying BSP Specific Maximum Devices: + +Specifying BSP Specific Maximum Devices +--------------------------------------- +.. index:: BSP_MAXIMUM_DEVICES + +*CONSTANT:* + ``BSP_MAXIMUM_DEVICES`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Undefined or positive. + +*DEFAULT VALUE:* + This option is BSP specific. + +**DESCRIPTION:** + +If ``BSP_MAXIMUM_DEVICES`` is defined by the BSP and +``CONFIGURE_MAXIMUM_DEVICES`` is not defined by the application, then this BSP +specific maximum device count will be used. + +**NOTES:** + +This option is specific to the device file system (devFS) and should not be +confused with the ``CONFIGURE_MAXIMUM_DRIVERS`` option. This parameter only +impacts the devFS and thus is only used by ``<rtems/confdefs.h>`` when +``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. + +.. COMMENT: === BSP_ZERO_WORKSPACE_AUTOMATICALLY === + +.. _BSP Recommends RTEMS Workspace be Cleared: + +BSP Recommends RTEMS Workspace be Cleared +----------------------------------------- +.. index:: BSP_ZERO_WORKSPACE_AUTOMATICALLY + +*CONSTANT:* + ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This option is BSP specific. + +**DESCRIPTION:** + +If ``BSP_ZERO_WORKSPACE_AUTOMATICALLY`` is defined by the BSP and +``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` is not defined by the application, +then the workspace will be zeroed automatically. + +**NOTES:** + +Zeroing memory can add significantly to system boot time. It is not necessary +for RTEMS but is often assumed by support libraries. + +.. COMMENT: === CONFIGURE_BSP_PREREQUISITE_DRIVERS === + +.. _Specify BSP Prerequisite Drivers: + +Specify BSP Prerequisite Drivers +-------------------------------- +.. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS + +*CONSTANT:* + ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` + +*DATA TYPE:* + List of device driver initializers (``rtems_driver_address_table``). + +*RANGE:* + Undefined or array of device drivers. + +*DEFAULT VALUE:* + This option is BSP specific. + +**DESCRIPTION:** + +``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is defined if the BSP has device drivers +it needs to include in the Device Driver Table. This should be defined to the +set of device driver entries that will be placed in the table at the *FRONT* of +the Device Driver Table and initialized before any other drivers *INCLUDING* +any application prerequisite drivers. + +**NOTES:** + +``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is typically used by BSPs to configure +common infrastructure such as bus controllers or probe for devices. + +.. COMMENT: === Idle Task Configuration === + +Idle Task Configuration +======================= + +This section defines the IDLE task related configuration parameters supported +by ``<rtems/confdefs.h>``. + +.. COMMENT: === CONFIGURE_IDLE_TASK_BODY === + +.. _Specify Application Specific Idle Task Body: + +Specify Application Specific Idle Task Body +------------------------------------------- +.. index:: CONFIGURE_IDLE_TASK_BODY + +*CONSTANT:* + ``CONFIGURE_IDLE_TASK_BODY`` + +*DATA TYPE:* + Function pointer. + +*RANGE:* + Undefined or valid function pointer. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_IDLE_TASK_BODY`` is set to the function name corresponding to the +application specific IDLE thread body. If not specified, the BSP or RTEMS +default IDLE thread body will be used. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_IDLE_TASK_STACK_SIZE === + +.. _Specify Idle Task Stack Size: + +Specify Idle Task Stack Size +---------------------------- +.. index:: CONFIGURE_IDLE_TASK_STACK_SIZE + +*CONSTANT:* + ``CONFIGURE_IDLE_TASK_STACK_SIZE`` + +*DATA TYPE:* + Unsigned integer (``size_t``). + +*RANGE:* + Undefined or positive. + +*DEFAULT VALUE:* + The default value is RTEMS_MINIMUM_STACK_SIZE. + +**DESCRIPTION:** + +``CONFIGURE_IDLE_TASK_STACK_SIZE`` is set to the +desired stack size for the IDLE task. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION === + +.. _Specify Idle Task Performs Application Initialization: + +Specify Idle Task Performs Application Initialization +----------------------------------------------------- +.. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION + +*CONSTANT:* + ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default, the user is assumed + to provide one or more initialization tasks. + +**DESCRIPTION:** + +``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` is set to indicate that the +user has configured *NO* user initialization tasks or threads and that the user +provided IDLE task will perform application initialization and then transform +itself into an IDLE task. + +**NOTES:** + +If you use this option be careful, the user IDLE task *CANNOT* block at all +during the initialization sequence. Further, once application initialization +is complete, it must make itself preemptible and enter an IDLE body loop. + +The IDLE task must run at the lowest priority of all tasks in the system. + +.. COMMENT: === Scheduler Algorithm Configuration === + +Scheduler Algorithm Configuration +================================= + +This section defines the configuration parameters related to selecting a +scheduling algorithm for an application. For the schedulers built into RTEMS, +the configuration is straightforward. All that is required is to define the +configuration macro which specifies which scheduler you want for in your +application. The currently available schedulers are: + +The pluggable scheduler interface also enables the user to provide their own +scheduling algorithm. If you choose to do this, you must define multiple +configuration macros. + +.. COMMENT: === CONFIGURE_SCHEDULER_PRIORITY === + +.. _Use Deterministic Priority Scheduler: + +Use Deterministic Priority Scheduler +------------------------------------ +.. index:: CONFIGURE_SCHEDULER_PRIORITY + +*CONSTANT:* + ``CONFIGURE_SCHEDULER_PRIORITY`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is defined by default. This is the default scheduler and specifying + this configuration parameter is redundant. + +**DESCRIPTION:** + +The Deterministic Priority Scheduler is the default scheduler in RTEMS for +uni-processor applications and is designed for predictable performance under +the highest loads. It can block or unblock a thread in a constant amount of +time. This scheduler requires a variable amount of memory based upon the +number of priorities configured in the system. + +**NOTES:** + +This scheduler may be explicitly selected by defining +``CONFIGURE_SCHEDULER_PRIORITY`` although this is equivalent to the default +behavior. + +.. COMMENT: === CONFIGURE_SCHEDULER_SIMPLE === + +.. _Use Simple Priority Scheduler: + +Use Simple Priority Scheduler +----------------------------- +.. index:: CONFIGURE_SCHEDULER_SIMPLE + +*CONSTANT:* + ``CONFIGURE_SCHEDULER_SIMPLE`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +When defined, the Simple Priority Scheduler is used at the thread scheduling +algorithm. This is an alternative scheduler in RTEMS. It is designed to +provide the same task scheduling behaviour as the Deterministic Priority +Scheduler while being simpler in implementation and uses less memory for data +management. It maintains a single sorted list of all ready threads. Thus +blocking or unblocking a thread is not a constant time operation with this +scheduler. + +This scheduler may be explicitly selected by defining +``CONFIGURE_SCHEDULER_SIMPLE``. + +**NOTES:** + +This scheduler is appropriate for use in small systems where RAM is limited. + +.. COMMENT: === CONFIGURE_SCHEDULER_EDF === + +.. _Use Earliest Deadline First Scheduler: + +Use Earliest Deadline First Scheduler +------------------------------------- +.. index:: CONFIGURE_SCHEDULER_EDF + +*CONSTANT:* + ``CONFIGURE_SCHEDULER_EDF`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +The Earliest Deadline First Scheduler (EDF) is an alternative scheduler in +RTEMS for uni-processor applications. The EDF schedules tasks with dynamic +priorities equal to deadlines. The deadlines are declared using only Rate +Monotonic manager which handles periodic behavior. Period is always equal to +deadline. If a task does not have any deadline declared or the deadline is +cancelled, the task is considered a background task which is scheduled in case +no deadline-driven tasks are ready to run. Moreover, multiple background tasks +are scheduled according their priority assigned upon initialization. All ready +tasks reside in a single ready queue. + +This scheduler may be explicitly selected by defining +``CONFIGURE_SCHEDULER_EDF``. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_SCHEDULER_CBS === + +.. _Use Constant Bandwidth Server Scheduler: + +Use Constant Bandwidth Server Scheduler +--------------------------------------- +.. index:: CONFIGURE_SCHEDULER_CBS + +*CONSTANT:* + ``CONFIGURE_SCHEDULER_CBS`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +The Constant Bandwidth Server Scheduler (CBS) is an alternative scheduler in +RTEMS for uni-processor applications. The CBS is a budget aware extension of +EDF scheduler. The goal of this scheduler is to ensure temporal isolation of +tasks. The CBS is equipped with a set of additional rules and provides with an +extensive API. + +This scheduler may be explicitly selected by defining +``CONFIGURE_SCHEDULER_CBS``. + +.. COMMENT: XXX - add cross reference to API chapter + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_SCHEDULER_PRIORITY_SMP === + +.. _Use Deterministic Priority SMP Scheduler: + +Use Deterministic Priority SMP Scheduler +---------------------------------------- +.. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP + +*CONSTANT:* + ``CONFIGURE_SCHEDULER_PRIORITY_SMP`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +The Deterministic Priority SMP Scheduler is derived from the Deterministic +Priority Scheduler but is capable of scheduling threads across multiple +processors. + +In a configuration with SMP enabled at configure time, it may be explicitly +selected by defining ``CONFIGURE_SCHEDULER_PRIORITY_SMP``. + +**NOTES:** + +This scheduler is only available when RTEMS is configured with SMP +support enabled. + +This scheduler is currently the default in SMP configurations and is only +selected when ``CONFIGURE_SMP_APPLICATION`` is defined. + +.. COMMENT: === CONFIGURE_SCHEDULER_SIMPLE_SMP === + +.. _Use Simple SMP Priority Scheduler: + +Use Simple SMP Priority Scheduler +--------------------------------- +.. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP + +*CONSTANT:* + ``CONFIGURE_SCHEDULER_SIMPLE_SMP`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +The Simple SMP Priority Scheduler is derived from the Simple Priority Scheduler +but is capable of scheduling threads across multiple processors. It is +designed to provide the same task scheduling behaviour as the Deterministic +Priority Scheduler while distributing threads across multiple processors. +Being based upon the Simple Priority Scheduler, it also maintains a single +sorted list of all ready threads. Thus blocking or unblocking a thread is not +a constant time operation with this scheduler. + +In addition, when allocating threads to processors, the algorithm is not +constant time. This algorithm was not designed with efficiency as a primary +design goal. Its primary design goal was to provide an SMP-aware scheduling +algorithm that is simple to understand. + +In a configuration with SMP enabled at configure time, it may be explicitly +selected by defining ``CONFIGURE_SCHEDULER_SIMPLE_SMP``. + +**NOTES:** + +This scheduler is only available when RTEMS is configured with SMP support +enabled. + +.. COMMENT: === Configuring a Scheduler Name === + +.. _Configuring a Scheduler Name: + +Configuring a Scheduler Name +---------------------------- +.. index:: CONFIGURE_SCHEDULER_NAME + +*CONSTANT:* + ``CONFIGURE_SCHEDULER_NAME`` + +*DATA TYPE:* + RTEMS Name (``rtems_name``). + +*RANGE:* + Any value. + +*DEFAULT VALUE:* + The default name is + - ``"UCBS"`` for the Uni-Processor CBS scheduler, + - ``"UEDF"`` for the Uni-Processor EDF scheduler, + - ``"UPD "`` for the Uni-Processor Deterministic Priority scheduler, + - ``"UPS "`` for the Uni-Processor Simple Priority scheduler, + - ``"MPA "`` for the Multi-Processor Priority Affinity scheduler, and + - ``"MPD "`` for the Multi-Processor Deterministic Priority scheduler, and + - ``"MPS "`` for the Multi-Processor Simple Priority scheduler. + +**DESCRIPTION:** + +Schedulers can be identified via ``rtems_scheduler_ident``. The name of the +scheduler is determined by the configuration. + +**NOTES:** + +None. + +.. COMMENT: === Configuring a User Scheduler === + +.. _Configuring a User Provided Scheduler: + +Configuring a User Provided Scheduler +------------------------------------- +.. index:: CONFIGURE_SCHEDULER_USER + +*CONSTANT:* + ``CONFIGURE_SCHEDULER_USER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +RTEMS allows the application to provide its own task/thread scheduling +algorithm. In order to do this, one must define ``CONFIGURE_SCHEDULER_USER`` to +indicate the application provides its own scheduling algorithm. If +``CONFIGURE_SCHEDULER_USER`` is defined then the following additional macros +must be defined: + +- ``CONFIGURE_SCHEDULER_CONTEXT`` must be defined to a static definition of the + scheduler context of the user scheduler. + +- ``CONFIGURE_SCHEDULER_CONTROLS`` must be defined to a scheduler control + initializer for the user scheduler. + +- ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` must be defined to the type of the + per-thread information of the user scheduler. + +**NOTES:** + +At this time, the mechanics and requirements for writing a new scheduler are +evolving and not fully documented. It is recommended that you look at the +existing Deterministic Priority Scheduler in +``cpukit/score/src/schedulerpriority*.c`` for guidance. For guidance on the +configuration macros, please examine ``cpukit/sapi/include/confdefs.h`` for how +these are defined for the Deterministic Priority Scheduler. + +.. COMMENT: === Configuring Clustered Schedulers === + +.. _Configuring Clustered Schedulers: + +Configuring Clustered Schedulers +-------------------------------- + +Clustered scheduling helps to control the worst-case latencies in a +multi-processor system. The goal is to reduce the amount of shared state in +the system and thus prevention of lock contention. Modern multi-processor +systems tend to have several layers of data and instruction caches. With +clustered scheduling it is possible to honour the cache topology of a system +and thus avoid expensive cache synchronization traffic. + +We have clustered scheduling in case the set of processors of a system is +partitioned into non-empty pairwise-disjoint subsets. These subsets are called +clusters. Clusters with a cardinality of one are partitions. Each cluster is +owned by exactly one scheduler instance. In order to use clustered scheduling +the application designer has to answer two questions. + +#. How is the set of processors partitioned into clusters? + +#. Which scheduler is used for which cluster? + +**CONFIGURATION:** + +The schedulers in an SMP system are statically configured on RTEMS. Firstly +the application must select which scheduling algorithms are available with the +following defines + +- ``CONFIGURE_SCHEDULER_PRIORITY_SMP``, + +- ``CONFIGURE_SCHEDULER_SIMPLE_SMP``, and + +- ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP``. + +This is necessary to calculate the per-thread overhead introduced by the +schedulers. After these definitions the configuration file must ``#include +<rtems/scheduler.h>`` to have access to scheduler specific configuration +macros. Each scheduler needs a context to store state information at run-time. +To provide a context for each scheduler is the next step. Use the following +macros to create scheduler contexts + +- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(name, prio_count)``, + +- ``RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(name)``, and + +- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_AFFINITY_SMP(name, prio_count)``. + +The ``name`` parameter is used as part of a designator for a global variable, +so the usual C/C++ designator rules apply. Additional parameters are scheduler +specific. The schedulers are registered in the system via the scheduler table. +To create the scheduler table define ``CONFIGURE_SCHEDULER_CONTROLS`` to a list +of the following scheduler control initializers + +- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP(name, obj_name)``, + +- ``RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(name, obj_name)``, and + +- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_AFFINITY_SMP(name, obj_name)``. + +The ``name`` parameter must correspond to the parameter defining the scheduler +context. The ``obj_name`` determines the scheduler object name and can be used +in ``rtems_scheduler_ident()`` to get the scheduler object identifier. + +The last step is to define which processor uses which scheduler. For this +purpose a scheduler assignment table must be defined. The entry count of this +table must be equal to the configured maximum processors +(``CONFIGURE_SMP_MAXIMUM_PROCESSORS``). A processor assignment to a scheduler +can be optional or mandatory. The boot processor must have a scheduler +assigned. In case the system needs more mandatory processors than available +then a fatal run-time error will occur. To specify the scheduler assignments +define ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` to a list of +``RTEMS_SCHEDULER_ASSIGN(index, attr)`` and +``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` macros. The ``index`` parameter must +be a valid index into the scheduler table. The ``attr`` parameter defines the +scheduler assignment attributes. By default a scheduler assignment to a +processor is optional. For the scheduler assignment attribute use one of the +mutually exclusive variants + +- ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``, + +- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and + +- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``. + +**ERRORS:** + +In case one of the scheduler indices in``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` +is invalid a link-time error will occur with an undefined reference to +``RTEMS_SCHEDULER_INVALID_INDEX``. + +Some fatal errors may occur in case of scheduler configuration inconsistencies +or a lack of processors on the system. The fatal source is +``RTEMS_FATAL_SOURCE_SMP``. None of the errors is internal. + +- ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot processor + must have a scheduler assigned. + +- ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a mandatory + processor beyond the range of physically or virtually available processors. + The processor demand must be reduced for this system. + +- ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a mandatory + processor failed during system initialization. The system may not have this + processor at all or it could be a problem with a boot loader for example. + Check the ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` definition. + +- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not allowed + to start multitasking on a processor with no scheduler assigned. + +**EXAMPLE:** + +The following example shows a scheduler configuration for a hypothetical +product using two chip variants. One variant has four processors which is used +for the normal product line and another provides eight processors for the +high-performance product line. The first processor performs hard-real time +control of actuators and sensors. The second processor is not used by RTEMS at +all and runs a Linux instance to provide a graphical user interface. The +additional processors are used for a worker thread pool to perform data +processing operations. + +The processors managed by RTEMS use two Deterministic Priority scheduler +instances capable of dealing with 256 priority levels. The scheduler with +index zero has the name ``"IO "``. The scheduler with index one has the name +``"WORK"``. The scheduler assignments of the first, third and fourth processor +are mandatory, so the system must have at least four processors, otherwise a +fatal run-time error will occur during system startup. The processor +assignments for the fifth up to the eighth processor are optional so that the +same application can be used for the normal and high-performance product lines. +The second processor has no scheduler assigned and runs Linux. A hypervisor +will ensure that the two systems cannot interfere in an undesirable way. + +.. code-block:: c + + #define CONFIGURE_SMP_MAXIMUM_PROCESSORS 8 + #define CONFIGURE_MAXIMUM_PRIORITY 255 + /* Make the scheduler algorithm available */ + #define CONFIGURE_SCHEDULER_PRIORITY_SMP + #include <rtems/scheduler.h> + /* Create contexts for the two scheduler instances */ + RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1); + RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1); + /* Define the scheduler table */ + #define CONFIGURE_SCHEDULER_CONTROLS \\ + RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \ + io, \ + rtems_build_name('I', 'O', ' ', ' ') \ + ), \ + RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \ + work, \ + rtems_build_name('W', 'O', 'R', 'K') \ + ) + /* Define the processor to scheduler assignments */ + #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \ + RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ + RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \ + RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL) + +.. COMMENT: === SMP Specific Configuration Parameters === + +SMP Specific Configuration Parameters +===================================== + +When RTEMS is configured to support SMP target systems, there are other +configuration parameters which apply. + +.. COMMENT: XXX - add -enable-smp + +.. COMMENT: === CONFIGURE_SMP_APPLICATION === + +.. _Enable SMP Support for Applications: + +Enable SMP Support for Applications +----------------------------------- +.. index:: CONFIGURE_SMP_APPLICATION + +*CONSTANT:* + ``CONFIGURE_SMP_APPLICATION`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_SMP_APPLICATION`` must be defined to enable SMP support for the +application. + +**NOTES:** + +This define may go away in the future in case all RTEMS components are SMP +ready. This configuration define is ignored on uni-processor configurations. + +.. COMMENT: === CONFIGURE_SMP_MAXIMUM_PROCESSORS === + +.. _Specify Maximum Processors in SMP System: + +Specify Maximum Processors in SMP System +---------------------------------------- +.. index:: CONFIGURE_SMP_MAXIMUM_PROCESSORS + +*CONSTANT:* + ``CONFIGURE_SMP_MAXIMUM_PROCESSORS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + The default value is 1, (if CONFIGURE_SMP_APPLICATION is defined). + +**DESCRIPTION:** + +``CONFIGURE_SMP_MAXIMUM_PROCESSORS`` must be set to the number of processors in +the SMP configuration. + +**NOTES:** + +If there are more processors available than configured, the rest will be +ignored. This configuration define is ignored on uni-processor configurations. + +.. COMMENT: === Device Driver Table === + +Device Driver Table +=================== + +This section defines the configuration parameters related to the automatic +generation of a Device Driver Table. As ``<rtems/confdefs.h>`` only is aware +of a small set of standard device drivers, the generated Device Driver Table is +suitable for simple applications with no custom device drivers. + +Note that network device drivers are not configured in the Device Driver Table. + +.. COMMENT: === CONFIGURE_MAXIMUM_DRIVERS === + +.. _Specifying the Maximum Number of Device Drivers: + +Specifying the Maximum Number of Device Drivers +----------------------------------------------- +.. index:: CONFIGURE_MAXIMUM_DRIVERS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_DRIVERS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + This is computed by default, and is set to the number of device drivers + configured using the ``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` + configuration parameters. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_DRIVERS`` is defined as the number of device drivers per +node. + +**NOTES:** + +If the application will dynamically install device drivers, then this +configuration parameter must be larger than the number of statically configured +device drivers. Drivers configured using the +``CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER`` configuration parameters are +statically installed. + +.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER === + +.. _Enable Console Device Driver: + +Enable Console Device Driver +---------------------------- +.. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER + +*CONSTANT:* + ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` is defined if the application +wishes to include the Console Device Driver. + +**NOTES:** + +This device driver is responsible for providing standard input and output using +*/dev/console*. + +BSPs should be constructed in a manner that allows ``printk()`` to work +properly without the need for the console driver to be configured. + +.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER === + +.. _Enable Clock Driver: + +Enable Clock Driver +------------------- +.. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER + +*CONSTANT:* + ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` is defined if the application +wishes to include the Clock Device Driver. + +**NOTES:** + +This device driver is responsible for providing a regular interrupt which +invokes the ``rtems_clock_tick`` directive. + +If neither the Clock Driver not Benchmark Timer is enabled and the +configuration parameter ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is +not defined, then a compile time error will occur. + +.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER === + +.. _Enable the Benchmark Timer Driver: + +Enable the Benchmark Timer Driver +--------------------------------- +.. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER + +*CONSTANT:* + ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` is defined if the +application wishes to include the Timer Driver. This device driver is +used to benchmark execution times by the RTEMS Timing Test Suites. + +**NOTES:** + +If neither the Clock Driver not Benchmark Timer is enabled and the +configuration parameter ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is +not defined, then a compile time error will occur. + +.. COMMENT: === CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER === + +.. _Specify Clock and Benchmark Timer Drivers Are Not Needed: + +Specify Clock and Benchmark Timer Drivers Are Not Needed +-------------------------------------------------------- +.. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER + +*CONSTANT:* + ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is defined when the +application does *NOT* want the Clock Device Driver and is *NOT* using the +Timer Driver. The inclusion or exclusion of the Clock Driver must be explicit +in user applications. + +**NOTES:** + +This configuration parameter is intended to prevent the common user error of +using the Hello World example as the baseline for an application and leaving +out a clock tick source. + +.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER === + +.. _Enable Real-Time Clock Driver: + +Enable Real-Time Clock Driver +----------------------------- +.. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER + +*CONSTANT:* + ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` is defined if the application wishes +to include the Real-Time Clock Driver. + +**NOTES:** + +Most BSPs do not include support for a real-time clock. This is because many +boards do not include the required hardware. + +If this is defined and the BSP does not have this device driver, then the user +will get a link time error for an undefined symbol. + +.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER === + +.. _Enable the Watchdog Device Driver: + +Enable the Watchdog Device Driver +--------------------------------- +.. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER + +*CONSTANT:* + ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` is defined if the application +wishes to include the Watchdog Driver. + +**NOTES:** + +Most BSPs do not include support for a watchdog device driver. This is because +many boards do not include the required hardware. + +If this is defined and the BSP does not have this device driver, then the user +will get a link time error for an undefined symbol. + +.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER === + +.. _Enable the Graphics Frame Buffer Device Driver: + +Enable the Graphics Frame Buffer Device Driver +---------------------------------------------- +.. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER + +*CONSTANT:* + ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` is defined if the +application wishes to include the BSP's Frame Buffer Device Driver. + +**NOTES:** + +Most BSPs do not include support for a Frame Buffer Device Driver. This is +because many boards do not include the required hardware. + +If this is defined and the BSP does not have this device driver, then the user +will get a link time error for an undefined symbol. + +.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER === + +.. _Enable Stub Device Driver: + +Enable Stub Device Driver +------------------------- +.. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER + +*CONSTANT:* + ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` is defined if the application +wishes to include the Stub Device Driver. + +**NOTES:** + +This device driver simply provides entry points that return successful and is +primarily a test fixture. It is supported by all BSPs. + +.. COMMENT: === CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS === + +.. _Specify Application Prerequisite Device Drivers: + +Specify Application Prerequisite Device Drivers +----------------------------------------------- +.. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS + +*CONSTANT:* + ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` + +*DATA TYPE:* + device driver entry structures + +*RANGE:* + Undefined or set of device driver entry structures + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` is defined if the application +has device drivers it needs to include in the Device Driver Table. This should +be defined to the set of device driver entries that will be placed in the table +at the *FRONT* of the Device Driver Table and initialized before any other +drivers *EXCEPT* any BSP prerequisite drivers. + +**NOTES:** + +In some cases, it is used by System On Chip BSPs to support peripheral buses +beyond those normally found on the System On Chip. For example, this is used by +one RTEMS system which has implemented a SPARC/ERC32 based board with +VMEBus. The VMEBus Controller initialization is performed by a device driver +configured via this configuration parameter. + +.. COMMENT: XXX Add example + +.. COMMENT: === CONFIGURE_APPLICATION_EXTRA_DRIVERS === + +.. _Specify Extra Application Device Drivers: + +Specify Extra Application Device Drivers +---------------------------------------- +.. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS + +*CONSTANT:* + ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` + +*DATA TYPE:* + device driver entry structures + +*RANGE:* + Undefined or set of device driver entry structures + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` is defined if the application has +device drivers it needs to include in the Device Driver Table. This should be +defined to the set of device driver entries that will be placed in the table at +the *END* of the Device Driver Table. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER === + +.. _Enable /dev/null Device Driver: + +Enable /dev/null Device Driver +------------------------------ +.. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER +.. index:: /dev/null + +*CONSTANT:* + ``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +This configuration variable is specified to enable ``/dev/null`` device driver. + +**NOTES:** + +This device driver is supported by all BSPs. + +.. COMMENT: === CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER === + +.. _Enable /dev/zero Device Driver: + +Enable /dev/zero Device Driver +------------------------------ +.. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER +.. index:: /dev/zero + +*CONSTANT:* + ``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +This configuration variable is specified to enable ``/dev/zero`` device driver. + +**NOTES:** + +This device driver is supported by all BSPs. + +.. COMMENT: === CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE === + +.. _Specifying Application Defined Device Driver Table: + +Specifying Application Defined Device Driver Table +-------------------------------------------------- +.. index:: CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE + +*CONSTANT:* + ``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default, indicating the ``<rtems/confdefs.h>`` is + providing the device driver table. + +**DESCRIPTION:** + +``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE`` is defined if the application wishes +to provide their own Device Driver Table. + +The table must be an array of ``rtems_driver_address_table`` entries named`` +_IO_Driver_address_table``. The application must also provide a const variable +``_IO_Number_of_drivers`` of type ``size_t`` indicating the number of entries +in the ``_IO_Driver_address_table``. + +**NOTES:** + +It is expected that there the application would only rarely need to do this. + +.. COMMENT: === Multiprocessing Configuration === + +Multiprocessing Configuration +============================= + +This section defines the multiprocessing related system configuration +parameters supported by ``<rtems/confdefs.h>``. They are only used if the +Multiprocessing Support (distinct from the SMP support) is enabled at configure +time using the ``--enable-multiprocessing`` option. + +Additionally, this class of Configuration Constants are only applicable if +``CONFIGURE_MP_APPLICATION`` is defined. + +.. COMMENT: === CONFIGURE_MP_APPLICATION === + +.. _Specify Application Will Use Multiprocessing: + +Specify Application Will Use Multiprocessing +-------------------------------------------- +.. index:: CONFIGURE_MP_APPLICATION + +*CONSTANT:* + ``CONFIGURE_MP_APPLICATION`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +This configuration parameter must be defined to indicate that the application +intends to be part of a multiprocessing configuration. Additional configuration +parameters are assumed to be provided. + +**NOTES:** + +This has no impact unless RTEMS was configured and built using the +``--enable-multiprocessing`` option. + +.. COMMENT: === CONFIGURE_MP_NODE_NUMBER === + +.. _Configure Node Number in Multiprocessor Configuration: + +Configure Node Number in Multiprocessor Configuration +----------------------------------------------------- +.. index:: CONFIGURE_MP_NODE_NUMBER + +*CONSTANT:* + ``CONFIGURE_MP_NODE_NUMBER`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is ``NODE_NUMBER``, which is assumed to be set by the + compilation environment. + +**DESCRIPTION:** + +``CONFIGURE_MP_NODE_NUMBER`` is the node number of this node in a +multiprocessor system. + +**NOTES:** + +In the RTEMS Multiprocessing Test Suite, the node number is derived from the +Makefile variable ``NODE_NUMBER``. The same code is compiled with the +``NODE_NUMBER`` set to different values. The test programs behave differently +based upon their node number. + +.. COMMENT: === CONFIGURE_MP_MAXIMUM_NODES === + +.. _Configure Maximum Node in Multiprocessor Configuration: + +Configure Maximum Node in Multiprocessor Configuration +------------------------------------------------------ +.. index:: CONFIGURE_MP_MAXIMUM_NODES + +*CONSTANT:* + ``CONFIGURE_MP_MAXIMUM_NODES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is 2. + +**DESCRIPTION:** + +``CONFIGURE_MP_MAXIMUM_NODES`` is the maximum number of nodes in a +multiprocessor system. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS === + +.. _Configure Maximum Global Objects in Multiprocessor Configuration: + +Configure Maximum Global Objects in Multiprocessor Configuration +---------------------------------------------------------------- +.. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS + +*CONSTANT:* + ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Positive. + +*DEFAULT VALUE:* + The default value is 32. + +**DESCRIPTION:** + +``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` is the maximum number of concurrently +active global objects in a multiprocessor system. + +**NOTES:** + +This value corresponds to the total number of objects which can be created with +the ``RTEMS_GLOBAL`` attribute. + +.. COMMENT: === CONFIGURE_MP_MAXIMUM_PROXIES === + +.. _Configure Maximum Proxies in Multiprocessor Configuration: + +Configure Maximum Proxies in Multiprocessor Configuration +--------------------------------------------------------- +.. index:: CONFIGURE_MP_MAXIMUM_PROXIES + +*CONSTANT:* + ``CONFIGURE_MP_MAXIMUM_PROXIES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Undefined or positive. + +*DEFAULT VALUE:* + The default value is 32. + +**DESCRIPTION:** + +``CONFIGURE_MP_MAXIMUM_PROXIES`` is the maximum number of concurrently +active thread/task proxies on this node in a multiprocessor system. + +**NOTES:** + +Since a proxy is used to represent a remote task/thread which is blocking on +this node. This configuration parameter reflects the maximum number of remote +tasks/threads which can be blocked on objects on this node. + +.. COMMENT: XXX - add xref to proxy discussion in MP chapter + +.. COMMENT: === CONFIGURE_MP_MPCI_TABLE_POINTER === + +.. _Configure MPCI in Multiprocessor Configuration: + +Configure MPCI in Multiprocessor Configuration +---------------------------------------------- +.. index:: CONFIGURE_MP_MPCI_TABLE_POINTER + +*CONSTANT:* + ``CONFIGURE_MP_MPCI_TABLE_POINTER`` + +*DATA TYPE:* + pointer to ``rtems_mpci_table`` + +*RANGE:* + undefined or valid pointer + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_MP_MPCI_TABLE_POINTER`` is the pointer to the MPCI Configuration +Table. The default value of this field is``&MPCI_table``. + +**NOTES:** + +RTEMS provides a Shared Memory MPCI Device Driver which can be used on any +Multiprocessor System assuming the BSP provides the proper set of supporting +methods. + +.. COMMENT: === CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE === + +.. _Do Not Generate Multiprocessor Configuration Table: + +Do Not Generate Multiprocessor Configuration Table +-------------------------------------------------- +.. index:: CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE + +*CONSTANT:* + ``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE`` is defined if the application +wishes to provide their own Multiprocessing Configuration Table. The generated +table is named ``Multiprocessing_configuration``. + +**NOTES:** + +This is a configuration parameter which is very unlikely to be used by an +application. If you find yourself wanting to use it in an application, please +reconsider and discuss this on the RTEMS Users mailing list. + +.. COMMENT: === Ada Tasks === + +Ada Tasks +========= + +This section defines the system configuration parameters supported by +``<rtems/confdefs.h>`` related to configuring RTEMS to support a task using Ada +tasking with GNAT/RTEMS. + +These configuration parameters are only available when RTEMS is built with the +``--enable-ada`` configure option and the application specifies +``CONFIGURE_GNAT_RTEMS``. + +Additionally RTEMS includes an Ada language binding to the Classic API which +has a test suite. This test suite is enabled only when``--enable-tests`` and +``--enable-expada`` are specified on the configure command. + +.. COMMENT: === CONFIGURE_GNAT_RTEMS === + +.. _Specify Application Includes Ada Code: + +Specify Application Includes Ada Code +------------------------------------- +.. index:: CONFIGURE_GNAT_RTEMS + +*CONSTANT:* + ``CONFIGURE_GNAT_RTEMS`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_GNAT_RTEMS`` is defined to inform RTEMS that the GNAT Ada run-time +is to be used by the application. + +**NOTES:** + +This configuration parameter is critical as it makes``<rtems/confdefs.h>`` +configure the resources (POSIX API Threads, Mutexes, Condition Variables, and +Keys) used implicitly by the GNAT run-time. + +.. COMMENT: === CONFIGURE_MAXIMUM_ADA_TASKS === + +.. _Specify the Maximum Number of Ada Tasks.: + +Specify the Maximum Number of Ada Tasks. +---------------------------------------- +.. index:: CONFIGURE_MAXIMUM_ADA_TASKS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_ADA_TASKS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Undefined or positive. + +*DEFAULT VALUE:* + If ``CONFIGURE_GNAT_RTEMS`` is defined, then the default value is 20, + otherwise the default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_ADA_TASKS`` is the number of Ada tasks that can be +concurrently active in the system. + +**NOTES:** + +None. + +.. COMMENT: === CONFIGURE_MAXIMUM_FAKE_ADA_TASKS === + +.. _Specify the Maximum Fake Ada Tasks: + +Specify the Maximum Fake Ada Tasks +---------------------------------- +.. index:: CONFIGURE_MAXIMUM_FAKE_ADA_TASKS + +*CONSTANT:* + .. index:: ``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 0. + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_FAKE_ADA_TASKS`` is the number of *fake* Ada tasks that can +be concurrently active in the system. A *fake* Ada task is a non-Ada task that +makes calls back into Ada code and thus implicitly uses the Ada run-time. + +**NOTES:** + +None. + +.. COMMENT: === PCI Library === + +PCI Library +=========== + +This section defines the system configuration parameters supported by +``rtems/confdefs.h`` related to configuring the PCI Library for RTEMS. + +The PCI Library startup behaviour can be configured in four different ways +depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined: + +.. index:: PCI_LIB_AUTO + +``PCI_LIB_AUTO`` + Used to enable the PCI auto configuration software. PCI will be automatically + probed, PCI buses enumerated, all devices and bridges will be initialized + using Plug & Play software routines. The PCI device tree will be populated + based on the PCI devices found in the system, PCI devices will be configured + by allocating address region resources automatically in PCI space according + to the BSP or host bridge driver set up. + +.. index:: PCI_LIB_READ + +``PCI_LIB_READ`` + Used to enable the PCI read configuration software. The current PCI + configuration is read to create the RAM representation (the PCI device tree) + of the PCI devices present. PCI devices are assumed to already have been + initialized and PCI buses enumerated, it is therefore required that a BIOS or + a boot loader has set up configuration space prior to booting into RTEMS. + +.. index:: PCI_LIB_STATIC + +``PCI_LIB_STATIC`` + Used to enable the PCI static configuration software. The user provides a PCI + tree with information how all PCI devices are to be configured at compile + time by linking in a custom ``struct pci_bus pci_hb`` tree. The static PCI + library will not probe PCI for devices, instead it will assume that all + devices defined by the user are present, it will enumerate the PCI buses and + configure all PCI devices in static configuration accordingly. Since probe + and allocation software is not needed the startup is faster, has smaller + footprint and does not require dynamic memory allocation. + +.. index:: PCI_LIB_PERIPHERAL + +``PCI_LIB_PERIPHERAL`` + Used to enable the PCI peripheral configuration. It is similar to + ``PCI_LIB_STATIC``, but it will never write the configuration to the PCI + devices since PCI peripherals are not allowed to access PCI configuration + space. + +Note that selecting ``PCI_LIB_STATIC`` or ``PCI_LIB_PERIPHERAL`` but not +defining ``pci_hb`` will reuslt in link errors. Note also that in these modes +Plug & Play is not performed. + +.. COMMENT: === Go Tasks === + +Go Tasks +======== + +.. COMMENT: === CONFIGURE_ENABLE_GO === + +.. _Specify Application Includes Go Code: + +Specify Application Includes Go Code +------------------------------------ +.. index:: CONFIGURE_ENABLE_GO + +*CONSTANT:* + ``CONFIGURE_ENABLE_GO`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default. + +**DESCRIPTION:** + +``CONFIGURE_ENABLE_GO`` is defined to inform RTEMS that the Go run-time is to +be used by the application. + +**NOTES:** + +The Go language support is experimental + +.. COMMENT: === CONFIGURE_MAXIMUM_GOROUTINES === + +.. _Specify the maximum number of Go routines: + +Specify the maximum number of Go routines +----------------------------------------- +.. index:: CONFIGURE_MAXIMUM_GOROUTINES + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_GOROUTINES`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 400 + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_GOROUTINES`` is defined to specify the maximum number of Go +routines. + +**NOTES:** + +The Go language support is experimental + +.. COMMENT: === CONFIGURE_MAXIMUM_GO_CHANNELS === + +.. _Specify the maximum number of Go Channels: + +Specify the maximum number of Go Channels +----------------------------------------- +.. index:: CONFIGURE_MAXIMUM_GO_CHANNELS + +*CONSTANT:* + ``CONFIGURE_MAXIMUM_GO_CHANNELS`` + +*DATA TYPE:* + Unsigned integer (``uint32_t``). + +*RANGE:* + Zero or positive. + +*DEFAULT VALUE:* + The default value is 500 + +**DESCRIPTION:** + +``CONFIGURE_MAXIMUM_GO_CHANNELS`` is defined to specify the maximum number of +Go channels. + +**NOTES:** + +The Go language support is experimental + +.. COMMENT: === Configuration Data Structures === + +Configuration Data Structures +============================= + +It is recommended that applications be configured using ``<rtems/confdefs.h>`` +as it is simpler and insulates applications from changes in the underlying data +structures. However, it is sometimes important to understand the data +structures that are automatically filled in by the configuration parameters. +This section describes the primary configuration data structures. + +If the user wishes to see the details of a particular data structure, they are +are advised to look at the source code. After all, that is one of the +advantages of RTEMS. |