From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/configuring_a_system.rst | 5016 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 5016 insertions(+) create mode 100644 c_user/configuring_a_system.rst (limited to 'c_user/configuring_a_system.rst') diff --git a/c_user/configuring_a_system.rst b/c_user/configuring_a_system.rst new file mode 100644 index 0000000..b4d4066 --- /dev/null +++ b/c_user/configuring_a_system.rst @@ -0,0 +1,5016 @@ +Configuring a System +#################### + +.. COMMENT: === Introduction === + +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:: +.. index:: + +The RTEMS header file ```` 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. + +Trivia: ``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```` 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 ```` 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 +========================== + +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 ```` 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 `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 ```` 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 ```` 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 `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 ```` 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 ```` file estimates the amount of memory +required for the RTEMS Workspace. This estimate is only as accurate +as the information given to ```` and may be either +too high or too low for a variety of reasons. Some of the reasons that```` 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, ```` 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:: c + + #include + #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 + +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 ```` instantiate the configuration data + structures. This can only be defined in one source file per + application that includes ```` 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 +----------------- + +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 `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 `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:: 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 + +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 +------------------------------------------- +.. 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:: 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 +-------------------------- + +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 +--------------------------------- +.. 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 +----------------------------------------- + +*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:: 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 ````. + +.. COMMENT: === CONFIGURE_MAXIMUM_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 `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 ```` 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_MAXIMUM_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 +-------------------------------------- +.. 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 +------------------------------------------------------- +.. 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 +------------------------------------------ +.. 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 +------------------------------------ +.. 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 +----------------------------------- +.. 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 +-------------------------------------- +.. 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 +----------------------------------- +.. 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 +--------------------------------- +.. 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 +------------------------------------------- +.. 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 ```` 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 +------------------------------------------------- +.. 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```` 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 +------------------------------------------------------ +.. 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 +----------------------------------------------- +.. 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 +----------------------------------------------------- +.. 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 `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 +--------------------------------------------------- +.. 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 +----------------------------------------------------- +.. 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 +------------------------------------------------ +.. 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 +---------------------------------------------------- +.. 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 +---------------------------------------------- +.. 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 +--------------------------------- +.. 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 `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 +--------------------------------- +.. 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 +--------------------------------------------- +.. 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 +------------------------------ +.. 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 +-------------------------------- +.. 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 +---------------------------------------- +.. 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 +---------------------------------------- +.. 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 +--------------------------------------------------- +.. 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 +------------------------------------ +.. 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 +---------------------------------- +.. 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 +----------------------------------- +.. 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 +------------------------------------------ +.. 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 ```` 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 +------------------------------------------------- +.. 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 ```` 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 +------------------------------------------------------ +.. 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 +----------------------------------------------------- +.. 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 `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 +------------------------------------------------------ +.. 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````. + +.. COMMENT: === CONFIGURE_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 +------------------------- +.. 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 +------------------------------ +.. 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 +----------------------------------------------- +.. 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 +-------------------------------- +.. 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 +------------------------------------------- +.. 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 +---------------------------------------------- +.. 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 ````. + +**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 ````. + +.. COMMENT: === CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY === + +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 +----------------------------------- +.. 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 +-------------------------------------------- +.. 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 +------------------------------------------ +.. 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 +--------------------------- +.. 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 +----------------------------- +.. 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 +--------------------------------------------------------------- +.. 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:: 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 +--------------------------------------------------------- +.. 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:: 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```` 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```` is incorrect. + +.. COMMENT: === CONFIGURE_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 ````. + +**NOTES:** + +This configuration parameter should only be used when it is suspected that +a bug in ```` 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 +----------------------------------------- +.. 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````. + +.. COMMENT: === CONFIGURE_LIBIO_MAXIMUM_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 +----------------------------- +.. 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 +----------------------------- +.. 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 +------------------------------------------ +.. 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 +----------------------------------- +.. 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 +------------------------------------ +.. 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 ```` when``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. + +.. COMMENT: === CONFIGURE_APPLICATION_DISABLE_FILESYSTEM === + +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 +----------------------------------------------- +.. 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 +--------------------------- +.. 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 +----------------------------------------- +.. 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 +---------------------------------------- +.. 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 +----------------------------------------- +.. 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 +--------------------------------------------- +.. 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 +------------------------------------------------- +.. 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 +----------------------------------------------- +.. 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 +----------------------------------- +.. 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 +------------------------------------------- +.. 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 +---------------------------------- +.. 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 +------------------------------------ +.. 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 +--------------------------------------- +.. 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 +--------------------------------------- +.. 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 +----------------------------------------- +.. 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 +------------------------- +.. 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 +------------------------ +.. 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 +------------------------ +.. 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 +------------------------ +.. 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 +------------------------ +.. 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 +------------------------------------ +.. 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 +--------------------- +.. 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 +------------------------------------- +.. 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 +-------------------------------- +.. 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 +----------------------------------------------- +.. 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 +------------------------ +.. 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 +------------------------- +.. 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 +---------------------------- +.. 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````. The BSP specific configuration settings are +defined in ````. + +.. COMMENT: === Disable BSP 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() +--------------------------- +.. 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 +------------------------------ +.. 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 +---------------------------------------------------- +.. 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 +------------------------------------ +.. 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 +-------------------------------------------- +.. 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 +--------------------------------------- +.. 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 ```` when``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` is specified. + +.. COMMENT: === BSP_ZERO_WORKSPACE_AUTOMATICALLY === + +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 +-------------------------------- +.. 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 ````. + +.. COMMENT: === CONFIGURE_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 +---------------------------- +.. 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 +----------------------------------------------------- +.. 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 +------------------------------------ +.. 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 +----------------------------- +.. 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 +------------------------------------- +.. 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 +--------------------------------------- +.. 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 +---------------------------------------- +.. 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 +--------------------------------- +.. 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 +---------------------------- +.. 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 +------------------------------------- +.. 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 +-------------------------------- + +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 +`` 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:: c + + #define CONFIGURE_SMP_MAXIMUM_PROCESSORS 8 + #define CONFIGURE_MAXIMUM_PRIORITY 255 + /* Make the scheduler algorithm available \*/ + #define CONFIGURE_SCHEDULER_PRIORITY_SMP + #include + /* 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 +----------------------------------- +.. 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 +---------------------------------------- +.. 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```` 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 +----------------------------------------------- +.. 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 +---------------------------- +.. 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 +------------------- +.. 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 +--------------------------------- +.. 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 +-------------------------------------------------------- +.. 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 +----------------------------- +.. 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 +--------------------------------- +.. 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 +---------------------------------------------- +.. 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 +------------------------- +.. 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 +----------------------------------------------- +.. 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 +---------------------------------------- +.. 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 +------------------------------ +.. 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 +------------------------------ +.. 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 +-------------------------------------------------- +.. 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 ```` + 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 ````. 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 +-------------------------------------------- +.. 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 +----------------------------------------------------- +.. 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 +------------------------------------------------------ +.. 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 +---------------------------------------------------------------- +.. 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 +--------------------------------------------------------- +.. 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 +---------------------------------------------- +.. 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 +-------------------------------------------------- +.. 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 ```` 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 +------------------------------------- +.. 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```` 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. +---------------------------------------- +.. 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 +---------------------------------- +.. 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`` is 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`` is 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`` is 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`` is 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 +------------------------------------ +.. 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 +----------------------------------------- +.. 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 +----------------------------------------- +.. 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```` 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. + +.. COMMENT: COPYRIGHT (c) 1988-2007. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + -- cgit v1.2.3