From a526872600d6df878fc55a7ac2d5d6bb079d095e Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Sun, 8 Mar 2020 18:19:42 +0100 Subject: c-user: Split up configuring_a_system.rst Introduce an index file for this chapter. This helps to generate some sections from the specification in the future. Start with moving "Introduction" up to "Unlimited Objects" to a new file. Update #3836. --- c-user/config/index.rst | 4565 +++++++++++++++++++++++++++++++++++ c-user/config/intro.rst | 412 ++++ c-user/configuring_a_system.rst | 4970 --------------------------------------- c-user/index.rst | 2 +- 4 files changed, 4978 insertions(+), 4971 deletions(-) create mode 100644 c-user/config/index.rst create mode 100644 c-user/config/intro.rst delete mode 100644 c-user/configuring_a_system.rst diff --git a/c-user/config/index.rst b/c-user/config/index.rst new file mode 100644 index 0000000..982a258 --- /dev/null +++ b/c-user/config/index.rst @@ -0,0 +1,4565 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2010 Gedare Bloom +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +.. index:: configuring a system +.. _Configuring a System: + +Configuring a System +******************** + +.. toctree:: + + intro + +General System Configuration +============================ + +This section defines the general system configuration options supported by +````. + +.. index:: CONFIGURE_DIRTY_MEMORY + +.. _CONFIGURE_DIRTY_MEMORY: + +CONFIGURE_DIRTY_MEMORY +---------------------- + +CONSTANT: + ``CONFIGURE_DIRTY_MEMORY`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + By default, the memory used by the RTEMS Workspace and the C Program Heap + is uninitialized memory. + +DESCRIPTION: + This macro indicates whether RTEMS should dirty the memory used by the + RTEMS Workspace and the C Program Heap as part of its initialization. If + defined, the memory areas are dirtied with a ``0xCF`` byte pattern. + Otherwise, they are not. + +NOTES: + Dirtying memory can add significantly to system boot time. It may assist in + finding code that incorrectly assumes the contents of free memory areas is + cleared to zero during system initialization. In case + :ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` is also defined, then the + memory is first dirtied and then zeroed. + +.. index:: CONFIGURE_EXTRA_TASK_STACKS +.. index:: memory for task tasks + +.. _CONFIGURE_EXTRA_TASK_STACKS: + +CONFIGURE_EXTRA_TASK_STACKS +--------------------------- + +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 + ````. + +.. index:: CONFIGURE_INITIAL_EXTENSIONS + +.. _CONFIGURE_INITIAL_EXTENSIONS: + +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. + +.. index:: CONFIGURE_INTERRUPT_STACK_SIZE +.. index:: interrupt stack size + +.. _CONFIGURE_INTERRUPT_STACK_SIZE: + +CONFIGURE_INTERRUPT_STACK_SIZE +------------------------------ + +CONSTANT: + ``CONFIGURE_INTERRUPT_STACK_SIZE`` + +DATA TYPE: + Unsigned integer. + +RANGE: + Positive. + +DEFAULT VALUE: + The default value is ``BSP_INTERRUPT_STACK_SIZE`` in case it is defined, + otherwise the default value is ``CPU_STACK_MINIMUM_SIZE``. + +DESCRIPTION: + The ``CONFIGURE_INTERRUPT_STACK_SIZE`` configuration option defines the + size of an interrupt stack in bytes. + +NOTES: + The interrupt stack size must be aligned according to + ``CPU_INTERRUPT_STACK_ALIGNMENT``. + + There is one interrupt stack available for each configured processor + (:ref:`CONFIGURE_MAXIMUM_PROCESSORS `). The + interrupt stack areas are statically allocated in a special linker section + (``.rtemsstack.interrupt``). The placement of this linker section is + BSP-specific. + + Some BSPs use the interrupt stack as the initialization stack which is used + to perform the sequential system initialization before the multithreading + is started. + + The interrupt stacks are covered by the :ref:`stack checker + `. However, using a too small interrupt + stack size may still result in undefined behaviour. + + In releases before RTEMS 5.1 the default value was + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE + ` instead of ``CPU_STACK_MINIMUM_SIZE``. + +.. index:: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS +.. index:: maximum file descriptors + +.. _CONFIGURE_MAXIMUM_FILE_DESCRIPTORS: + +CONFIGURE_MAXIMUM_FILE_DESCRIPTORS +---------------------------------- + +CONSTANT: + ``CONFIGURE_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. + +.. index:: CONFIGURE_MAXIMUM_PRIORITY +.. index:: maximum priority +.. index:: number of priority levels + +.. _CONFIGURE_MAXIMUM_PRIORITY: + +CONFIGURE_MAXIMUM_PRIORITY +-------------------------- + +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: + For the schedulers + + * :ref:`SchedulerPriority`, which is the default in uniprocessor + configurations and can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY` configuration option, + + * :ref:`SchedulerSMPPriority` which can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP` configuration option, and + + * :ref:`SchedulerSMPPriorityAffinity` which can be configured through the + :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP` configuration option + + this configuration option specifies the maximum numeric priority of any task + for these schedulers and one less that the number of priority levels for + these schedulers. For all other schedulers provided by RTEMS, this + configuration option has no effect. + +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. + + Reducing the number of priorities through this configuration option reduces + the amount of memory allocated by the schedulers listed above. These + schedulers use a chain control structure per priority and this structure + consists of three pointers. On a 32-bit architecture, the allocated memory + is 12 bytes * (``CONFIGURE_MAXIMUM_PRIORITY`` + 1), e.g. 3072 bytes for 256 + priority levels (default), 48 bytes for 4 priority levels + (``CONFIGURE_MAXIMUM_PRIORITY == 3``). + +.. index:: CONFIGURE_MAXIMUM_PROCESSORS + +.. _CONFIGURE_MAXIMUM_PROCESSORS: + +CONFIGURE_MAXIMUM_PROCESSORS +---------------------------- + +CONSTANT: + ``CONFIGURE_MAXIMUM_PROCESSORS`` + +DATA TYPE: + Unsigned integer (``uint32_t``). + +RANGE: + Positive. + +DEFAULT VALUE: + The default value is 1. + +DESCRIPTION: + ``CONFIGURE_MAXIMUM_PROCESSORS`` must be set to the maximum number of + processors an application intends to use. The number of actually available + processors depends on the hardware and may be less. It is recommended to + use the smallest value suitable for the application in order to save + memory. Each processor needs an idle thread and interrupt stack for + example. + +NOTES: + If there are more processors available than configured, the rest will be + ignored. This configuration define is ignored in uniprocessor + configurations. + +.. index:: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE +.. index:: maximum thread name size + +.. _CONFIGURE_MAXIMUM_THREAD_NAME_SIZE: + +CONFIGURE_MAXIMUM_THREAD_NAME_SIZE +---------------------------------- + +CONSTANT: + ``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` + +DATA TYPE: + Unsigned integer (``size_t``). + +RANGE: + No restrictions. + +DEFAULT VALUE: + The default value is 16. This value was chosen for Linux compatibility, + see + `PTHREAD_SETNAME_NP(3) `_. + +DESCRIPTION: + This configuration parameter specifies the maximum thread name size + including the terminating `NUL` character. + +NOTE: + The size of the thread control block is increased by the maximum thread name + size. This configuration option is available since RTEMS 5.1. + +.. index:: CONFIGURE_MEMORY_OVERHEAD + +.. _CONFIGURE_MEMORY_OVERHEAD: + +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: + This 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. + +.. index:: CONFIGURE_MICROSECONDS_PER_TICK +.. index:: tick quantum + +.. _CONFIGURE_MICROSECONDS_PER_TICK: + +CONFIGURE_MICROSECONDS_PER_TICK +------------------------------- + +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. + +.. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE +.. index:: minimum task stack size + +.. _CONFIGURE_MINIMUM_TASK_STACK_SIZE: + +CONFIGURE_MINIMUM_TASK_STACK_SIZE +--------------------------------- + +CONSTANT: + ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` + +DATA TYPE: + Unsigned integer (``uint32_t``). + +RANGE: + Positive. + +DEFAULT VALUE: + The default value is architecture-specific. + +DESCRIPTION: + This configuration parameter defines the minimum stack size in bytes for + every user task or thread in the system. + +NOTES: + Adjusting this parameter should be done with caution. Examining the actual + stack usage using the stack checker usage reporting facility is recommended + (see also :ref:`CONFIGURE_STACK_CHECKER_ENABLED `). + + 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. + + By default, this configuration parameter defines also the minimum stack + size of POSIX threads. This can be changed with the + :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE ` + configuration option. + + In releases before RTEMS 5.1 the ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` was + used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE + `. + +.. index:: CONFIGURE_STACK_CHECKER_ENABLED + +.. _CONFIGURE_STACK_CHECKER_ENABLED: + +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. + +.. index:: CONFIGURE_TICKS_PER_TIMESLICE +.. index:: ticks per timeslice + +.. _CONFIGURE_TICKS_PER_TIMESLICE: + +CONFIGURE_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. + +.. index:: CONFIGURE_UNIFIED_WORK_AREAS +.. index:: unified work areas +.. index:: separate work areas +.. index:: RTEMS Workspace +.. index:: C Program Heap + +.. _CONFIGURE_UNIFIED_WORK_AREAS: + +CONFIGURE_UNIFIED_WORK_AREAS +---------------------------- + +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. + +.. _CONFIGURE_UNLIMITED_ALLOCATION_SIZE: + +CONFIGURE_UNLIMITED_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. + +.. index:: CONFIGURE_UNLIMITED_OBJECTS + +.. _CONFIGURE_UNLIMITED_OBJECTS: + +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. + +.. index:: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION + +.. _CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION: + +CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION +--------------------------------------- + +CONSTANT: + ``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default, and thus the system initialization is + quiet. + +DESCRIPTION: + This configuration option enables to print some information during system + initialization. + +NOTES: + You may use this feature to debug system initialization issues. The + printk() function is used to print the information. + +.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY +.. index:: clear C Program Heap +.. index:: clear RTEMS Workspace +.. index:: zero C Program Heap +.. index:: zero RTEMS Workspace + +.. _CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY: + +CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY +-------------------------------------- + +CONSTANT: + ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. 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. In case + :ref:`CONFIGURE_DIRTY_MEMORY` is also defined, then the memory is first + dirtied and then zeroed. + +Classic API Configuration +========================= + +This section defines the Classic API related system configuration parameters +supported by ````. + +.. index:: CONFIGURE_MAXIMUM_BARRIERS + +.. _CONFIGURE_MAXIMUM_BARRIERS: + +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. + +.. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES + +.. _CONFIGURE_MAXIMUM_MESSAGE_QUEUES: + +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. You have + to account for the memory used to store the messages of each message queue, + see :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. + +.. index:: CONFIGURE_MAXIMUM_PARTITIONS + +.. _CONFIGURE_MAXIMUM_PARTITIONS: + +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. + +.. index:: CONFIGURE_MAXIMUM_PERIODS + +.. _CONFIGURE_MAXIMUM_PERIODS: + +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. + +.. index:: CONFIGURE_MAXIMUM_PORTS + +.. _CONFIGURE_MAXIMUM_PORTS: + +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. + +.. index:: CONFIGURE_MAXIMUM_REGIONS + +.. _CONFIGURE_MAXIMUM_REGIONS: + +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. + +.. index:: CONFIGURE_MAXIMUM_SEMAPHORES + +.. _CONFIGURE_MAXIMUM_SEMAPHORES: + +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. + + In SMP configurations, the size of a Semaphore Control Block depends on the + scheduler count (see :ref:`ConfigurationSchedulerTable`). The semaphores + using the :ref:`MrsP` need a ceiling priority per scheduler. + +.. index:: CONFIGURE_MAXIMUM_TASKS + +.. _CONFIGURE_MAXIMUM_TASKS: + +CONFIGURE_MAXIMUM_TASKS +----------------------- + +CONSTANT: + ``CONFIGURE_MAXIMUM_TASKS`` + +DATA TYPE: + Unsigned integer (``uint32_t``). + +RANGE: + Zero or positive. + +DEFAULT VALUE: + The default value is ``0``. + +DESCRIPTION: + ``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API Tasks that + can be concurrently active. + +NOTES: + This object class can be configured in unlimited allocation mode. + + The calculations for the required memory in the RTEMS Workspace for tasks + assume that each task has a minimum stack size and has floating point + support enabled. The configuration parameter + ``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify task stack requirements + *ABOVE* the minimum size required. See :ref:`Reserve Task/Thread Stack + Memory Above Minimum` for more information about + ``CONFIGURE_EXTRA_TASK_STACKS``. + + The maximum number of POSIX threads is specified by + :ref:`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. + +.. index:: CONFIGURE_MAXIMUM_TIMERS + +.. _CONFIGURE_MAXIMUM_TIMERS: + +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. + +.. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS + +.. _CONFIGURE_MAXIMUM_USER_EXTENSIONS: + +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. + +Classic API Initialization Task 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. + +.. index:: CONFIGURE_INIT_TASK_ARGUMENTS + +.. _CONFIGURE_INIT_TASK_ARGUMENTS: + +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. + +.. index:: CONFIGURE_INIT_TASK_ATTRIBUTES + +.. _CONFIGURE_INIT_TASK_ATTRIBUTES: + +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. + +.. index:: CONFIGURE_INIT_TASK_ENTRY_POINT + +.. _CONFIGURE_INIT_TASK_ENTRY_POINT: + +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. + +.. index:: CONFIGURE_INIT_TASK_INITIAL_MODES + +.. _CONFIGURE_INIT_TASK_INITIAL_MODES: + +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. + +.. index:: CONFIGURE_INIT_TASK_NAME + +.. _CONFIGURE_INIT_TASK_NAME: + +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. + +.. index:: CONFIGURE_INIT_TASK_PRIORITY + +.. _CONFIGURE_INIT_TASK_PRIORITY: + +CONFIGURE_INIT_TASK_PRIORITY +---------------------------- + +CONSTANT: + ``CONFIGURE_INIT_TASK_PRIORITY`` + +DATA TYPE: + RTEMS Task Priority (``rtems_task_priority``). + +RANGE: + One (1) to the maximum user priority value of the scheduler. + +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. + +.. index:: CONFIGURE_INIT_TASK_STACK_SIZE + +.. _CONFIGURE_INIT_TASK_STACK_SIZE: + +CONFIGURE_INIT_TASK_STACK_SIZE +------------------------------ + +CONSTANT: + ``CONFIGURE_INIT_TASK_STACK_SIZE`` + +DATA TYPE: + Unsigned integer (``size_t``). + +RANGE: + Zero or positive. + +DEFAULT VALUE: + The default value is RTEMS_MINIMUM_STACK_SIZE. + +DESCRIPTION: + ``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single + initialization task defined by the Classic API Initialization Tasks Table. + +NOTES: + If the stack size specified is greater than the configured minimum, it must + be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve + Task/Thread Stack Memory Above Minimum` for more information about + ``CONFIGURE_EXTRA_TASK_STACKS``. + +.. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE + +.. _CONFIGURE_RTEMS_INIT_TASKS_TABLE: + +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. + +POSIX API Configuration +======================= + +The parameters in this section are used to configure resources for the POSIX +API supported by RTEMS. Most POSIX API objects are available by default since +RTEMS 5.1. The queued signals and timers are only available if RTEMS was built +with the ``--enable-posix`` build configuration option. + +.. index:: CONFIGURE_MAXIMUM_POSIX_KEYS + +.. _CONFIGURE_MAXIMUM_POSIX_KEYS: + +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. + +.. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS + +.. _CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS: + +CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS +--------------------------------------- + +CONSTANT: + ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` + +DATA TYPE: + Unsigned integer (``uint32_t``). + +RANGE: + Zero or positive. + +DEFAULT VALUE: + The default value is + :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS ` * + :ref:`CONFIGURE_MAXIMUM_TASKS ` + + :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS `. + +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` is the maximum number of key + value pairs used by POSIX API Keys that can be concurrently active. + +NOTES: + This object class can be configured in unlimited allocation mode. + + A key value pair is created by :c:func:`pthread_setspecific` if the value + is not :c:macro:`NULL`, otherwise it is deleted. + +.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES + +.. _CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES: + +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. You have + to account for the memory used to store the messages of each message queue, + see :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. + +.. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS + +.. _CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS: + +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: + Unlimited objects are not available for queued signals. + + Queued signals are only available if RTEMS was built with the + ``--enable-posix`` build configuration option. + +.. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES + +.. _CONFIGURE_MAXIMUM_POSIX_SEMAPHORES: + +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 + Named Semaphores that can be concurrently active. + +NOTES: + This object class can be configured in unlimited allocation mode. + + Named semaphores are created with ``sem_open()``. Semaphores initialized + with ``sem_init()`` are not affected by this configuration option since the + storage space for these semaphores is user-provided. + +.. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS + +.. _CONFIGURE_MAXIMUM_POSIX_TIMERS: + +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. + + Timers are only available if RTEMS was built with the + ``--enable-posix`` build configuration option. + +.. index:: CONFIGURE_MAXIMUM_POSIX_THREADS + +.. _CONFIGURE_MAXIMUM_POSIX_THREADS: + +CONFIGURE_MAXIMUM_POSIX_THREADS +------------------------------- + +CONSTANT: + ``CONFIGURE_MAXIMUM_POSIX_THREADS`` + +DATA TYPE: + Unsigned integer (``uint32_t``). + +RANGE: + Zero or positive. + +DEFAULT VALUE: + The default value is 0. + +DESCRIPTION: + ``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API + Threads that can be concurrently active. + +NOTES: + This object class can be configured in unlimited allocation mode. + + This calculations for the required memory in the RTEMS Workspace for + threads assume that each thread has a minimum stack size and has floating + point support enabled. The configuration parameter + ``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify thread stack + requirements *ABOVE* the minimum size required. See :ref:`Reserve + Task/Thread Stack Memory Above Minimum` for more information about + ``CONFIGURE_EXTRA_TASK_STACKS``. + + The maximum number of Classic API Tasks is specified by + :ref:`CONFIGURE_MAXIMUM_TASKS `. + + All POSIX threads have floating point enabled. + +.. index:: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE +.. index:: minimum POSIX thread stack size + +.. _CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE: + +CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE +----------------------------------------- + +CONSTANT: + ``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` + +DATA TYPE: + Unsigned integer (``size_t``). + +RANGE: + Positive. + +DEFAULT VALUE: + The default value is two times the value of + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE `. + +DESCRIPTION: + This configuration parameter defines the minimum stack size in bytes for + every POSIX thread in the system. + +NOTES: + None. + +POSIX Initialization Thread 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. + +.. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT + +.. _CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT: + +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. + +.. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE + +.. _CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE: + +CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE +-------------------------------------- + +CONSTANT: + ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` + +DATA TYPE: + Unsigned integer (``size_t``). + +RANGE: + Zero or positive. + +DEFAULT VALUE: + The default value is 2 \* RTEMS_MINIMUM_STACK_SIZE. + +DESCRIPTION: + ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the single + initialization thread defined by the POSIX API Initialization Threads + Table. + +NOTES: + If the stack size specified is greater than the configured minimum, it must + be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve + Task/Thread Stack Memory Above Minimum` for more information about + ``CONFIGURE_EXTRA_TASK_STACKS``. + +.. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE + +.. _CONFIGURE_POSIX_INIT_THREAD_TABLE: + +CONFIGURE_POSIX_INIT_THREAD_TABLE +--------------------------------- + +CONSTANT: + ``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. + +Task Stack Allocator Configuration +================================== + +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. + +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR +.. index:: task stack allocator + +.. _CONFIGURE_TASK_STACK_ALLOCATOR: + +CONFIGURE_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`` + +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT + +.. _CONFIGURE_TASK_STACK_ALLOCATOR_INIT: + +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`` + +.. index:: CONFIGURE_TASK_STACK_DEALLOCATOR +.. index:: task stack deallocator + +.. _CONFIGURE_TASK_STACK_DEALLOCATOR: + +CONFIGURE_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`` + +Message Queue Buffer Configuration +================================== + +This section describes the configuration parameters related to specifying the +amount of memory reserved for message queue message buffers. See +:ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and +:ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`. + +.. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY +.. index:: configure message queue buffer memory + +.. _CONFIGURE_MESSAGE_BUFFER_MEMORY: + +CONFIGURE_MESSAGE_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 + :ref:`CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE` can be used to assist in + calculating the message buffer memory required. In this example, there are + two message queues used in this application. The first message queue has + maximum of 24 pending messages with the message structure defined by the + type ``one_message_type``. The other message queue has maximum of 500 + pending messages with the message structure defined by the type + ``other_message_type``. + + .. code-block:: c + + #define CONFIGURE_MESSAGE_BUFFER_MEMORY \ + (CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 24, sizeof(one_message_type) \ + ) + \ + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 500, sizeof(other_message_type) \ + ) + +.. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE +.. index:: memory for a single message queue's buffers + +.. _CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE: + +CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE +----------------------------------- + +CONSTANT: + ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)`` + +DATA TYPE: + Unsigned integer (``size_t``). + +RANGE: + Positive. + +DEFAULT VALUE: + The default value is None. + +DESCRIPTION: + This is a helper macro which is used to assist in computing the total + amount of memory required for message buffers. Each message queue will + have its own configuration with maximum message size and maximum number of + pending messages. + + The interface for this macro is as follows: + + .. code-block:: c + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per) + + Where ``max_messages`` is the maximum number of pending messages and + ``size_per`` is the size in bytes of the user message. + +NOTES: + This macro is only used in support of :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. + +Filesystem Configuration +======================== + +By default, the In-Memory Filesystem (IMFS) is used as the base filesystem (also +known as root filesystem). In order to save some memory for your application, +you can disable the filesystem support with the +:ref:`CONFIGURE_APPLICATION_DISABLE_FILESYSTEM` configuration option. +Alternatively, you can strip down the features of the base filesystem with the +:ref:`CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM` and +:ref:`CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM` configuration options. These +three configuration options are mutually exclusive. They are intended for an +advanced application configuration. + +Features of the IMFS can be disabled and enabled with the following +configuration options: + +* :ref:`CONFIGURE_IMFS_DISABLE_CHMOD` + +* :ref:`CONFIGURE_IMFS_DISABLE_CHOWN` + +* :ref:`CONFIGURE_IMFS_DISABLE_LINK` + +* :ref:`CONFIGURE_IMFS_DISABLE_MKNOD` + +* :ref:`CONFIGURE_IMFS_DISABLE_MKNOD_FILE` + +* :ref:`CONFIGURE_IMFS_DISABLE_MOUNT` + +* :ref:`CONFIGURE_IMFS_DISABLE_READDIR` + +* :ref:`CONFIGURE_IMFS_DISABLE_READLINK` + +* :ref:`CONFIGURE_IMFS_DISABLE_RENAME` + +* :ref:`CONFIGURE_IMFS_DISABLE_RMNOD` + +* :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK` + +* :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT` + +* :ref:`CONFIGURE_IMFS_DISABLE_UTIME` + +* :ref:`CONFIGURE_IMFS_ENABLE_MKFIFO` + +.. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM + +.. _CONFIGURE_APPLICATION_DISABLE_FILESYSTEM: + +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. + +.. index:: CONFIGURE_IMFS_ENABLE_MKFIFO + +.. _CONFIGURE_IMFS_ENABLE_MKFIFO: + +CONFIGURE_IMFS_ENABLE_MKFIFO +---------------------------- + +CONSTANT: + ``CONFIGURE_IMFS_ENABLE_MKFIFO`` + +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 FIFOs + is enabled in the root IMFS. + +.. index:: CONFIGURE_IMFS_DISABLE_CHMOD + +.. _CONFIGURE_IMFS_DISABLE_CHMOD: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_CHOWN + +.. _CONFIGURE_IMFS_DISABLE_CHOWN: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_LINK + +.. _CONFIGURE_IMFS_DISABLE_LINK: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_MKNOD + +.. _CONFIGURE_IMFS_DISABLE_MKNOD: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE + +.. _CONFIGURE_IMFS_DISABLE_MKNOD_FILE: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_MOUNT + +.. _CONFIGURE_IMFS_DISABLE_MOUNT: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_READDIR + +.. _CONFIGURE_IMFS_DISABLE_READDIR: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_READLINK + +.. _CONFIGURE_IMFS_DISABLE_READLINK: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_RENAME + +.. _CONFIGURE_IMFS_DISABLE_RENAME: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_RMNOD + +.. _CONFIGURE_IMFS_DISABLE_RMNOD: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_SYMLINK + +.. _CONFIGURE_IMFS_DISABLE_SYMLINK: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT + +.. _CONFIGURE_IMFS_DISABLE_UNMOUNT: + +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. + +.. index:: CONFIGURE_IMFS_DISABLE_UTIME + +.. _CONFIGURE_IMFS_DISABLE_UTIME: + +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. + +.. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK + +.. _CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK: + +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. + +.. index:: CONFIGURE_MAXIMUM_DEVICES + +.. _CONFIGURE_MAXIMUM_DEVICES: + +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. + +.. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM + +.. _CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM: + +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. + +.. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM + +.. _CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM: + +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``. + +Block Device Cache Configuration +================================ + +This section defines Block Device Cache (bdbuf) related configuration +parameters. + +.. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK + +.. _CONFIGURE_APPLICATION_NEEDS_LIBBLOCK: + +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. + +.. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE + +.. _CONFIGURE_BDBUF_CACHE_MEMORY_SIZE: + +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. + +.. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE + +.. _CONFIGURE_BDBUF_BUFFER_MAX_SIZE: + +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. + +.. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE + +.. _CONFIGURE_BDBUF_BUFFER_MIN_SIZE: + +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. + +.. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS + +.. _CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS: + +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. + +.. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS + +.. _CONFIGURE_BDBUF_MAX_WRITE_BLOCKS: + +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. + +.. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY + +.. _CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY: + +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. + +.. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE + +.. _CONFIGURE_BDBUF_TASK_STACK_SIZE: + +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. + +.. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD + +.. _CONFIGURE_SWAPOUT_BLOCK_HOLD: + +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. + +.. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD + +.. _CONFIGURE_SWAPOUT_SWAP_PERIOD: + +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. + +.. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY + +.. _CONFIGURE_SWAPOUT_TASK_PRIORITY: + +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. + +.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY + +.. _CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY: + +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. + +.. index:: CONFIGURE_SWAPOUT_WORKER_TASKS + +.. _CONFIGURE_SWAPOUT_WORKER_TASKS: + +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. + +BSP Related Configuration Options +================================= + +This section describes configuration options related to the BSP. Some +configuration options may have a BSP-specific setting which is defined by +````. The BSP-specific settings can be disabled by the +:ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option. + +.. index:: BSP_IDLE_TASK_BODY + +.. _BSP_IDLE_TASK_BODY: + +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 + +.. index:: BSP_IDLE_TASK_STACK_SIZE + +.. _BSP_IDLE_TASK_STACK_SIZE: + +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``. + +.. index:: BSP_INITIAL_EXTENSION + +.. _BSP_INITIAL_EXTENSION: + +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. + +.. index:: BSP_INTERRUPT_STACK_SIZE + +.. _BSP_INTERRUPT_STACK_SIZE: + +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. + +.. index:: BSP_MAXIMUM_DEVICES + +.. _BSP_MAXIMUM_DEVICES: + +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. + +.. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS + +.. _CONFIGURE_BSP_PREREQUISITE_DRIVERS: + +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. + +.. index:: CONFIGURE_DISABLE_BSP_SETTINGS + +.. _CONFIGURE_DISABLE_BSP_SETTINGS: + +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. + +.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK + +.. _CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK: + +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. + +Idle Task Configuration +======================= + +This section defines the IDLE task related configuration parameters supported +by ````. + +.. index:: CONFIGURE_IDLE_TASK_BODY + +.. _CONFIGURE_IDLE_TASK_BODY: + +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. + +.. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION + +.. _CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION: + +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. + +.. index:: CONFIGURE_IDLE_TASK_STACK_SIZE + +.. _CONFIGURE_IDLE_TASK_STACK_SIZE: + +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. + +General Scheduler Configuration +=============================== + +This section defines the configuration parameters related to selecting a +scheduling algorithm for an application. A scheduler configuration is optional +and only necessary in very specific circumstances. A normal application +configuration does not need any of the configuration options described in this +section. By default, the :ref:`Deterministic Priority Scheduler +` algorithm is used in uniprocessor configurations. In case +SMP is enabled and the configured maximum processors +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS `) is greater +than one, then the :ref:`Earliest Deadline First (EDF) SMP Scheduler +` is selected as the default scheduler algorithm. + +For the :ref:`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 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. + +.. index:: CONFIGURE_SCHEDULER_CBS + +.. _CONFIGURE_SCHEDULER_CBS: + +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: + If defined, then the :ref:`Constant Bandwidth Server (CBS) Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for exactly one processor. + +.. index:: CONFIGURE_SCHEDULER_EDF + +.. _CONFIGURE_SCHEDULER_EDF: + +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: + If defined, then the :ref:`Earliest Deadline First (EDF) Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for exactly one processor. + +.. index:: CONFIGURE_SCHEDULER_EDF_SMP + +.. _CONFIGURE_SCHEDULER_EDF_SMP: + +CONFIGURE_SCHEDULER_EDF_SMP +--------------------------- + +CONSTANT: + ``CONFIGURE_SCHEDULER_EDF_SMP`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined, then the :ref:`Earliest Deadline First (EDF) SMP Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + This scheduler algorithm is only available when RTEMS is built with SMP + support enabled. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for up to 32 processors. + + This scheduler algorithm is the default in SMP configurations if + :ref:`CONFIGURE_MAXIMUM_PROCESSORS ` is + greater than one. + +.. index:: CONFIGURE_SCHEDULER_NAME + +.. _CONFIGURE_SCHEDULER_NAME: + +CONFIGURE_SCHEDULER_NAME +------------------------ + +CONSTANT: + ``CONFIGURE_SCHEDULER_NAME`` + +DATA TYPE: + RTEMS Name (``rtems_name``). + +RANGE: + Any value. + +DEFAULT VALUE: + The default name is + + - ``"MEDF"`` for the :ref:`EDF SMP Scheduler `, + - ``"MPA "`` for the :ref:`Arbitrary Processor Affinity Priority SMP Scheduler `, + - ``"MPD "`` for the :ref:`Deterministic Priority SMP Scheduler `, + - ``"MPS "`` for the :ref:`Simple Priority SMP Scheduler `, + - ``"UCBS"`` for the :ref:`Uniprocessor CBS Scheduler `, + - ``"UEDF"`` for the :ref:`Uniprocessor EDF Scheduler `, + - ``"UPD "`` for the :ref:`Uniprocessor Deterministic Priority Scheduler `, and + - ``"UPS "`` for the :ref:`Uniprocessor Simple Priority Scheduler `. + +DESCRIPTION: + Schedulers can be identified via ``rtems_scheduler_ident``. The name of + the scheduler is determined by the configuration. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + +.. index:: CONFIGURE_SCHEDULER_PRIORITY + +.. _CONFIGURE_SCHEDULER_PRIORITY: + +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: + If defined, then the :ref:`Deterministic Priority Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for exactly one processor. + + This scheduler algorithm is the default when + :ref:`CONFIGURE_MAXIMUM_PROCESSORS ` is + exactly one. + + The memory allocated for this scheduler depends on the + :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. index:: CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP + +.. _CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP: + +CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP +----------------------------------------- + +CONSTANT: + ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined, then the :ref:`Arbitrary Processor Affinity SMP Scheduler + ` algorithm is made available to the + application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + This scheduler algorithm is only available when RTEMS is built with SMP + support enabled. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for up to 32 processors. + + The memory allocated for this scheduler depends on the + :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP + +.. _CONFIGURE_SCHEDULER_PRIORITY_SMP: + +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: + If defined, then the :ref:`Deterministic Priority SMP Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + This scheduler algorithm is only available when RTEMS is built with SMP + support enabled. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for up to 32 processors. + + The memory allocated for this scheduler depends on the + :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. index:: CONFIGURE_SCHEDULER_SIMPLE + +.. _CONFIGURE_SCHEDULER_SIMPLE: + +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: + If defined, then the :ref:`Simple Priority Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for exactly one processor. + +.. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP + +.. _CONFIGURE_SCHEDULER_SIMPLE_SMP: + +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: + If defined, then the :ref:`Simple Priority SMP Scheduler + ` algorithm is made available to the + application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + This scheduler algorithm is only available when RTEMS is built with SMP + support enabled. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for up to 32 processors. + +.. index:: CONFIGURE_SCHEDULER_USER + +.. _CONFIGURE_SCHEDULER_USER: + +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`` must be defined to a static definition of + the scheduler data structures of the user scheduler. + + - ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` must be defined to a scheduler + table entry 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: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + 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. + +.. _ConfigurationSchedulersClustered: + +Clustered Scheduler Configuration +================================= + +A clustered scheduler configuration is optional. It is an advanced +configuration area and only necessary in specific circumstances. + +Clustered scheduling helps to control the worst-case latencies in a +multiprocessor system (SMP). The goal is to reduce the amount of shared state +in the system and thus prevention of lock contention. Modern multiprocessor +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. + +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 algorithm is used for which cluster? + +The schedulers are statically configured. + +Configuration Step 1 - Scheduler Algorithms +------------------------------------------- + +Firstly, the application must select which scheduling algorithms are available +with the following defines + +- :ref:`CONFIGURE_SCHEDULER_EDF_SMP `, + +- :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP `, + +- :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP `, and + +- :ref:`CONFIGURE_SCHEDULER_SIMPLE_SMP `. + +This is necessary to calculate the per-thread overhead introduced by the +scheduler algorithms. After these definitions the configuration file must +``#include `` to have access to scheduler-specific +configuration macros. + +It is possible to make more than one scheduler algorithm available to the +application. For example a :ref:`Simple Priority SMP Scheduler +` could be used in a partition for low latency +tasks in addition to an :ref:`EDF SMP Scheduler ` for a +general-purpose cluster. Since the per-thread overhead depends on the +scheduler algorithm only the scheduler algorithms used by the application +should be configured. + +Configuration Step 2 - Schedulers +--------------------------------- + +Each scheduler needs some data structures. Use the following macros to create +the scheduler data structures for a particular scheduler identified in the +configuration by ``name``. + +- ``RTEMS_SCHEDULER_EDF_SMP(name, max_cpu_count)``, + +- ``RTEMS_SCHEDULER_PRIORITY_AFFINITY_SMP(name, prio_count)``, + +- ``RTEMS_SCHEDULER_PRIORITY_SMP(name, prio_count)``, and + +- ``RTEMS_SCHEDULER_SIMPLE_SMP(name)``. + +The ``name`` parameter is used as part of a designator for scheduler-specific +data structures, so the usual C/C++ designator rules apply. This ``name`` is +not the scheduler object name. Additional parameters are scheduler-specific. + +.. _ConfigurationSchedulerTable: + +Configuration Step 3 - Scheduler Table +-------------------------------------- + +The schedulers are registered in the system via the scheduler table. To +populate the scheduler table define ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` to a +list of the following scheduler table entry initializers + +- ``RTEMS_SCHEDULER_TABLE_EDF_SMP(name, obj_name)``, + +- ``RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP(name, obj_name)``, + +- ``RTEMS_SCHEDULER_TABLE_PRIORITY_SMP(name, obj_name)``, and + +- ``RTEMS_SCHEDULER_TABLE_SIMPLE_SMP(name, obj_name)``. + +The ``name`` parameter must correspond to the parameter defining the scheduler +data structures of configuration step 2. The ``obj_name`` determines the +scheduler object name and can be used in :ref:`rtems_scheduler_ident() +` to get the scheduler object identifier. The scheduler +index is defined by the index of the scheduler table. It is a configuration +error to add a scheduler multiple times to the scheduler table. + +Configuration Step 4 - Processor to Scheduler Assignment +-------------------------------------------------------- + +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 +(:ref:`CONFIGURE_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_SCHEDULER_ASSIGNMENTS`` to a list of + +- ``RTEMS_SCHEDULER_ASSIGN(scheduler_index, attr)`` and + +- ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` + +macros. The ``scheduler_index`` parameter must be a valid index into the +scheduler table defined by configuration step 3. 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``. + +It is possible to add/remove processors to/from schedulers at run-time, see +:ref:`rtems_scheduler_add_processor() ` and +:ref:`rtems_scheduler_remove_processor() `. + +Configuration 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 SMP schedulers +capable of dealing with 256 priority levels. The scheduler with index zero has +the name ``"IO "``. The scheduler with index one has the name ``"WORK"``. The +scheduler assignments of the first, third and fourth processor are mandatory, +so the system must have at least four processors, otherwise a fatal run-time +error will occur during system startup. The processor assignments for the +fifth up to the eighth processor are optional so that the same application can +be used for the normal and high-performance product lines. The second +processor has no scheduler assigned and runs Linux. A hypervisor will ensure +that the two systems cannot interfere in an undesirable way. + +.. code-block:: c + + #define CONFIGURE_MAXIMUM_PROCESSORS 8 + #define CONFIGURE_MAXIMUM_PRIORITY 255 + + /* Configuration Step 1 - Scheduler Algorithms */ + #define CONFIGURE_SCHEDULER_PRIORITY_SMP + #include + + /* Configuration Step 2 - Schedulers */ + RTEMS_SCHEDULER_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1); + RTEMS_SCHEDULER_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1); + + /* Configuration Step 3 - Scheduler Table */ + #define CONFIGURE_SCHEDULER_TABLE_ENTRIES \ + RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \ + io, \ + rtems_build_name('I', 'O', ' ', ' ') \ + ), \ + RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \ + work, \ + rtems_build_name('W', 'O', 'R', 'K') \ + ) + + /* Configuration Step 4 - Processor to Scheduler Assignment */ + #define CONFIGURE_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) + +Configuration Errors +-------------------- + +In case one of the scheduler indices in ``CONFIGURE_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``. + +- ``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_SCHEDULER_ASSIGNMENTS`` definition. + +- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not allowed + to start multitasking on a processor with no scheduler assigned. + +Device Driver Configuration +=========================== + +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. + +.. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER + +.. _CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER: + +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. + +.. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS + +.. _CONFIGURE_APPLICATION_EXTRA_DRIVERS: + +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. + +.. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER: + +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 a 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. + +.. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER: + +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 the :file:`/dev/console` + device file. This device is used to initialize the standard input, output, + and error file descriptors. + + BSPs should be constructed in a manner that allows ``printk()`` to work + properly without the need for the console driver to be configured. + + The + + * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, + + * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and + + * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` + + configuration options are mutually exclusive. + +.. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER: + +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. + +.. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER +.. index:: /dev/null + +.. _CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER +--------------------------------------- + +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. + +.. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER: + +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. + +.. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER +------------------------------------------------- + +CONSTANT: + ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` is defined if the + application wishes to include the Simple Console Device Driver. + +NOTES: + This device driver is responsible for providing the :file:`/dev/console` + device file. This device is used to initialize the standard input, output, + and error file descriptors. + + This device driver reads via ``getchark()``. + + This device driver writes via ``rtems_putc()``. + + The Termios framework is not used. There is no support to change device + settings, e.g. baud, stop bits, parity, etc. + + The + + * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, + + * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and + + * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` + + configuration options are mutually exclusive. + +.. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER +------------------------------------------------------ + +CONSTANT: + ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` is defined if + the application wishes to include the Simple Task Console Device Driver. + +NOTES: + This device driver is responsible for providing the :file:`/dev/console` + device file. This device is used to initialize the standard input, output, + and error file descriptors. + + This device driver reads via ``getchark()``. + + This device driver writes into a write buffer. The count of characters + written into the write buffer is returned. It might be less than the + requested count, in case the write buffer is full. The write is + non-blocking and may be called from interrupt context. A dedicated task + reads from the write buffer and outputs the characters via + ``rtems_putc()``. This task runs with the least important priority. The + write buffer size is 2047 characters and it is not configurable. + + Use ``fsync(STDOUT_FILENO)`` or ``fdatasync(STDOUT_FILENO)`` to drain the + write buffer. + + The Termios framework is not used. There is no support to change device + settings, e.g. baud, stop bits, parity, etc. + + The + + * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, + + * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and + + * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` + + configuration options are mutually exclusive. + +.. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER: + +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. + +.. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER: + +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. + +.. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER + +.. _CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER: + +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. + +.. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER +.. index:: /dev/zero + +.. _CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER: + +CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER +--------------------------------------- + +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. + +.. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS + +.. _CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS: + +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. + +.. index:: CONFIGURE_MAXIMUM_DRIVERS + +.. _CONFIGURE_MAXIMUM_DRIVERS: + +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. + +Multiprocessing Configuration +============================= + +This section defines the multiprocessing related system configuration +parameters supported by ````. They are only used if RTEMS +was built with the ``--enable-multiprocessing`` build configuration option. +The multiprocessing (MPCI) support must not be confused with the SMP support. + +Additionally, this class of Configuration Constants are only applicable if +``CONFIGURE_MP_APPLICATION`` is defined. + +.. index:: CONFIGURE_MP_APPLICATION + +.. _CONFIGURE_MP_APPLICATION: + +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 built with the + ``--enable-multiprocessing`` build configuration option. + +.. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS + +.. _CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS: + +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. + +.. index:: CONFIGURE_MP_MAXIMUM_NODES + +.. _CONFIGURE_MP_MAXIMUM_NODES: + +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. + +.. index:: CONFIGURE_MP_MAXIMUM_PROXIES + +.. _CONFIGURE_MP_MAXIMUM_PROXIES: + +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 + +.. index:: CONFIGURE_MP_MPCI_TABLE_POINTER + +.. _CONFIGURE_MP_MPCI_TABLE_POINTER: + +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. + +.. index:: CONFIGURE_MP_NODE_NUMBER + +.. _CONFIGURE_MP_NODE_NUMBER: + +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. + +PCI Library Configuration +========================= + +This section defines the system configuration parameters supported by +``rtems/confdefs.h`` related to configuring the PCI Library for RTEMS. + +The PCI Library startup behaviour can be configured in four different ways +depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined: + +.. index:: PCI_LIB_AUTO + +``PCI_LIB_AUTO`` + Used to enable the PCI auto configuration software. PCI will be automatically + probed, PCI buses enumerated, all devices and bridges will be initialized + using Plug & Play software routines. The PCI device tree will be populated + based on the PCI devices found in the system, PCI devices will be configured + by allocating address region resources automatically in PCI space according + to the BSP or host bridge driver set up. + +.. index:: PCI_LIB_READ + +``PCI_LIB_READ`` + Used to enable the PCI read configuration software. The current PCI + configuration is read to create the RAM representation (the PCI device tree) + of the PCI devices present. PCI devices are assumed to already have been + initialized and PCI buses enumerated, it is therefore required that a BIOS or + a boot loader has set up configuration space prior to booting into RTEMS. + +.. index:: PCI_LIB_STATIC + +``PCI_LIB_STATIC`` + Used to enable the PCI static configuration software. The user provides a PCI + tree with information how all PCI devices are to be configured at compile + time by linking in a custom ``struct pci_bus pci_hb`` tree. The static PCI + library will not probe PCI for devices, instead it will assume that all + devices defined by the user are present, it will enumerate the PCI buses and + configure all PCI devices in static configuration accordingly. Since probe + and allocation software is not needed the startup is faster, has smaller + footprint and does not require dynamic memory allocation. + +.. index:: PCI_LIB_PERIPHERAL + +``PCI_LIB_PERIPHERAL`` + Used to enable the PCI peripheral configuration. It is similar to + ``PCI_LIB_STATIC``, but it will never write the configuration to the PCI + devices since PCI peripherals are not allowed to access PCI configuration + space. + +Note that selecting ``PCI_LIB_STATIC`` or ``PCI_LIB_PERIPHERAL`` but not +defining ``pci_hb`` will reuslt in link errors. Note also that in these modes +Plug & Play is not performed. + +Event Recording Configuration +============================= + +.. index:: CONFIGURE_RECORD_EXTENSIONS_ENABLED + +.. _CONFIGURE_RECORD_EXTENSIONS_ENABLED: + +CONFIGURE_RECORD_EXTENSIONS_ENABLED +----------------------------------- + +CONSTANT: + ``CONFIGURE_RECORD_EXTENSIONS_ENABLED`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS + ` is also defined properly, then the + record extensions are enabled. + +NOTES: + The record extensions capture thread create, start, restart, delete, + switch, begin, exitted and terminate events. + +.. index:: CONFIGURE_RECORD_PER_PROCESSOR_ITEMS + +.. _CONFIGURE_RECORD_PER_PROCESSOR_ITEMS: + +CONFIGURE_RECORD_PER_PROCESSOR_ITEMS +------------------------------------ + +CONSTANT: + ``CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`` + +DATA TYPE: + Unsigned integer (``unsigned int``). + +RANGE: + A power of two greater than or equal to 16. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined, then a record item buffer of the specified item count is + statically allocated for each configured processor + (:ref:`CONFIGURE_MAXIMUM_PROCESSORS `). + +NOTES: + None. + +.. _ConfigAda: + +Ada Configuration +================= + +The GNU Ada runtime library (libgnarl) uses threads, mutexes, condition +variables, and signals from the pthreads API. It uses also thread-local storage +for the Ada Task Control Block (ATCB). From these resources only the threads +need to be accounted for in the configuration. You should include the Ada tasks +in your setting of the :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS` configuration +option. + +Obsolete Configuration Options +============================== + +.. index:: CONFIGURE_BDBUF_BUFFER_COUNT + +CONFIGURE_BDBUF_BUFFER_COUNT +---------------------------- + +This configuration option was introduced in RTEMS 4.7.0 and is obsolete since +RTEMS 4.10.0. + +.. index:: CONFIGURE_BDBUF_BUFFER_SIZE + +CONFIGURE_BDBUF_BUFFER_SIZE +--------------------------- + +This configuration option was introduced in RTEMS 4.7.0 and is obsolete since +RTEMS 4.10.0. + +.. index:: CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS + +CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS +-------------------------------------- + +This configuration option was introduced in RTEMS 4.9.0 and is obsolete since +RTEMS 5.1. + +.. index:: CONFIGURE_ENABLE_GO + +CONFIGURE_ENABLE_GO +------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_GNAT_RTEMS + +CONFIGURE_GNAT_RTEMS +-------------------- + +This configuration option was present in all RTEMS versions since at 1997 and is +obsolete since RTEMS 5.1. See also :ref:`ConfigAda`. + +.. index:: CONFIGURE_HAS_OWN_CONFIGURATION_TABLE + +CONFIGURE_HAS_OWN_CONFIGURATION_TABLE +------------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_HAS_OWN_BDBUF_TABLE + +CONFIGURE_HAS_OWN_BDBUF_TABLE +----------------------------- + +This configuration option was introduced in RTEMS 4.7.0 and is obsolete since +RTEMS 4.10.0. + +.. index:: CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE + +CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE +------------------------------------- + +This configuration option was present in all RTEMS versions since at least 1995 +and is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_HAS_OWN_INIT_TASK_TABLE + +.. _CONFIGURE_HAS_OWN_INIT_TASK_TABLE: + +CONFIGURE_HAS_OWN_INIT_TASK_TABLE +--------------------------------- + +This configuration option was present in all RTEMS versions since at least 1995 +and is obsolete since RTEMS 5.1. If you used this configuration option or you +think that there should be a way to configure more than one Classic API +initialization task, then please ask on the :r:list:`users`. + +.. index:: CONFIGURE_HAS_OWN_MOUNT_TABLE + +CONFIGURE_HAS_OWN_MOUNT_TABLE +----------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE + +CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE +--------------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS + +CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS +-------------------------------- + +This configuration option was present in all RTEMS versions since at 1998 and is +obsolete since RTEMS 5.1. See also :ref:`CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`. + +.. index:: CONFIGURE_MAXIMUM_ADA_TASKS + +CONFIGURE_MAXIMUM_ADA_TASKS +--------------------------- + +This configuration option was present in all RTEMS versions since at 1997 and is +obsolete since RTEMS 5.1. See also :ref:`ConfigAda`. + +.. index:: CONFIGURE_MAXIMUM_FAKE_ADA_TASKS + +CONFIGURE_MAXIMUM_FAKE_ADA_TASKS +-------------------------------- + +This configuration option was present in all RTEMS versions since at 1997 and is +obsolete since RTEMS 5.1. See also :ref:`ConfigAda`. + +.. index:: CONFIGURE_MAXIMUM_GO_CHANNELS + +CONFIGURE_MAXIMUM_GO_CHANNELS +----------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_GOROUTINES + +CONFIGURE_MAXIMUM_GOROUTINES +---------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_MRSP_SEMAPHORES + +CONFIGURE_MAXIMUM_MRSP_SEMAPHORES +--------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_NUMBER_OF_TERMIOS_PORTS + +CONFIGURE_NUMBER_OF_TERMIOS_PORTS +--------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_BARRIERS + +CONFIGURE_MAXIMUM_POSIX_BARRIERS +-------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES + +CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES +------------------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS + +CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS +------------------------------- + +This configuration option was introduced in RTEMS 4.10.0 and is obsolete since +RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_MUTEXES + +CONFIGURE_MAXIMUM_POSIX_MUTEXES +------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_RWLOCKS + +CONFIGURE_MAXIMUM_POSIX_RWLOCKS +------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_MAXIMUM_POSIX_SPINLOCKS + +CONFIGURE_MAXIMUM_POSIX_SPINLOCKS +--------------------------------- + +This configuration option is obsolete since RTEMS 5.1. + +.. index:: CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE + +.. _CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE: + +CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE +----------------------------------------- + +This configuration option was present in all RTEMS versions since at least 1995 +and is obsolete since RTEMS 5.1. If you used this configuration option or you +think that there should be a way to configure more than one POSIX initialization +thread, then please ask on the :r:list:`users`. + +.. index:: CONFIGURE_SMP_APPLICATION + +CONFIGURE_SMP_APPLICATION +------------------------- + +This configuration option was introduced in RTEMS 4.11.0 and is obsolete since +RTEMS 5.1. + +.. index:: CONFIGURE_SMP_MAXIMUM_PROCESSORS + +CONFIGURE_SMP_MAXIMUM_PROCESSORS +-------------------------------- + +This configuration option was introduced in RTEMS 4.11.0 and is obsolete since +RTEMS 5.1. See also :ref:`CONFIGURE_MAXIMUM_PROCESSORS`. + +.. index:: CONFIGURE_TERMIOS_DISABLED + +CONFIGURE_TERMIOS_DISABLED +-------------------------- + +This configuration option is obsolete since RTEMS 5.1. diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst new file mode 100644 index 0000000..636a7b8 --- /dev/null +++ b/c-user/config/intro.rst @@ -0,0 +1,412 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +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 must not 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:: + +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. + +.. sidebar: Trivia: + + The term ``confdefs`` is shorthand for a *Configuration Defaults*. + +As a general rule, application developers only specify values for the +configuration parameters of interest to them. They define what resources or +features they require. In most cases, when a parameter is not specified, it +defaults to zero (0) instances, a standards compliant value, or disabled as +appropriate. For example, by default there will be 256 task priority levels but +this can be lowered by the application. This number of priority levels is +required to be compliant with the RTEID/ORKID standards upon which the Classic +API is based. There are similar cases where the default is selected to be +compliant with 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. + +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. + +.. _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 :ref:`Specify Memory Overhead` for more +details. + +The memory area for the RTEMS Workspace is determined by the BSP. In case the +RTEMS Workspace is too large for the available memory, then a fatal run-time +error occurs and the system terminates. + +The file ```` 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 :ref:`ConfigUnlimitedObjects` 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. + +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. + +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) + +Configuration Example +===================== + +In the following example, the configuration information for a system with a +single message queue, four (4) tasks, and a timeslice of fifty (50) +milliseconds is as follows: + +.. code-block:: c + + #include + #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. + +.. _ConfigUnlimitedObjects: + +Unlimited Objects +================= + +In real-time embedded systems the RAM is normally a limited, critical resource +and dynamic allocation is avoided as much as possible to ensure predictable, +deterministic execution times. For such cases, see :ref:`Sizing the RTEMS +Workspace` for an overview of how to tune the size of the workspace. +Frequently when users are porting software to RTEMS the precise resource +requirements of the software is unknown. In these situations users do not need +to control the size of the workspace very tightly because they just want to get +the new software to run; later they can tune the workspace size as needed. + +The following object classes in the Classic API can be configured in unlimited +mode: + +- Barriers + +- Message Queues + +- Partitions + +- Periods + +- Ports + +- Regions + +- Semaphores + +- Tasks + +- Timers + +Additionally, the following object classes from the POSIX API can be configured +in unlimited mode: + +- Keys -- :c:func:`pthread_key_create` + +- Key Value Pairs -- :c:func:`pthread_setspecific` + +- Message Queues -- :c:func:`mq_open` + +- Named Semaphores -- :c:func:`sem_open` + +- Shared Memory -- :c:func:`shm_open` + +- Threads -- :c:func:`pthread_create` + +- Timers -- :c:func:`timer_create` + +.. warning:: + + The following object classes can *not* be configured in unlimited mode: + + - Drivers + + - File Descriptors + + - POSIX Queued Signals + + - User Extensions + +Due to the memory requirements of unlimited objects it is strongly recommended +to use them only in combination with the unified work areas. See :ref:`Separate +or Unified Work Areas` for more information on unified work areas. + +The following example demonstrates how the two simple configuration defines for +unlimited objects and unified works areas can replace many seperate +configuration defines for supported object classes: + +.. code-block:: c + + #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER + #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER + #define CONFIGURE_UNIFIED_WORK_AREAS + #define CONFIGURE_UNLIMITED_OBJECTS + #define CONFIGURE_RTEMS_INIT_TASKS_TABLE + #define CONFIGURE_INIT + #include + +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. + +.. index:: rtems_resource_unlimited + +.. _ConfigUnlimitedObjectsClass: + +Unlimited Objects by Class +-------------------------- + +When the number of objects is not known ahead of time, RTEMS provides an +auto-extending mode that can be enabled individually for each object type by +using the macro ``rtems_resource_unlimited``. This takes a value as a +parameter, and is used to set the object maximum number field in an API +Configuration table. The value is an allocation unit size. When RTEMS is +required to grow the object table it is grown by this size. The kernel will +return the object memory back to the RTEMS Workspace when an object is +destroyed. The kernel will only return an allocated block of objects to the +RTEMS Workspace if at least half the allocation size of free objects remain +allocated. RTEMS always keeps one allocation block of objects allocated. Here +is an example of using ``rtems_resource_unlimited``: + +.. code-block:: c + + #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5) + +.. index:: rtems_resource_is_unlimited +.. index:: rtems_resource_maximum_per_allocation + +Object maximum specifications can be evaluated with the +``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation`` +macros. + +.. _ConfigUnlimitedObjectsDefault: + +Unlimited Objects by Default +---------------------------- + +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 +(:ref:`CONFIGURE_UNLIMITED_OBJECTS`) and specifying the allocation size +(:ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`). + +.. code-block:: c + + #define CONFIGURE_UNLIMITED_OBJECTS + #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5 diff --git a/c-user/configuring_a_system.rst b/c-user/configuring_a_system.rst deleted file mode 100644 index 75b1c7b..0000000 --- a/c-user/configuring_a_system.rst +++ /dev/null @@ -1,4970 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2010 Gedare Bloom -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: configuring a system -.. _Configuring a System: - -Configuring a System -******************** - -Introduction -============ - -RTEMS must be configured for an application. This configuration encompasses a -variety of information including the length of each clock tick, the maximum -number of each information RTEMS object that can be created, the application -initialization tasks, the task scheduling algorithm to be used, and the device -drivers in the application. - -Although this information is contained in data structures that are used by -RTEMS at system initialization time, the data structures themselves must not 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:: - -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. - -.. sidebar: Trivia: - - The term ``confdefs`` is shorthand for a *Configuration Defaults*. - -As a general rule, application developers only specify values for the -configuration parameters of interest to them. They define what resources or -features they require. In most cases, when a parameter is not specified, it -defaults to zero (0) instances, a standards compliant value, or disabled as -appropriate. For example, by default there will be 256 task priority levels but -this can be lowered by the application. This number of priority levels is -required to be compliant with the RTEID/ORKID standards upon which the Classic -API is based. There are similar cases where the default is selected to be -compliant with 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. - -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. - -.. _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 :ref:`Specify Memory Overhead` for more -details. - -The memory area for the RTEMS Workspace is determined by the BSP. In case the -RTEMS Workspace is too large for the available memory, then a fatal run-time -error occurs and the system terminates. - -The file ```` 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 :ref:`ConfigUnlimitedObjects` 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. - -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. - -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) - -Configuration Example -===================== - -In the following example, the configuration information for a system with a -single message queue, four (4) tasks, and a timeslice of fifty (50) -milliseconds is as follows: - -.. code-block:: c - - #include - #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. - -.. _ConfigUnlimitedObjects: - -Unlimited Objects -================= - -In real-time embedded systems the RAM is normally a limited, critical resource -and dynamic allocation is avoided as much as possible to ensure predictable, -deterministic execution times. For such cases, see :ref:`Sizing the RTEMS -Workspace` for an overview of how to tune the size of the workspace. -Frequently when users are porting software to RTEMS the precise resource -requirements of the software is unknown. In these situations users do not need -to control the size of the workspace very tightly because they just want to get -the new software to run; later they can tune the workspace size as needed. - -The following object classes in the Classic API can be configured in unlimited -mode: - -- Barriers - -- Message Queues - -- Partitions - -- Periods - -- Ports - -- Regions - -- Semaphores - -- Tasks - -- Timers - -Additionally, the following object classes from the POSIX API can be configured -in unlimited mode: - -- Keys -- :c:func:`pthread_key_create` - -- Key Value Pairs -- :c:func:`pthread_setspecific` - -- Message Queues -- :c:func:`mq_open` - -- Named Semaphores -- :c:func:`sem_open` - -- Shared Memory -- :c:func:`shm_open` - -- Threads -- :c:func:`pthread_create` - -- Timers -- :c:func:`timer_create` - -.. warning:: - - The following object classes can *not* be configured in unlimited mode: - - - Drivers - - - File Descriptors - - - POSIX Queued Signals - - - User Extensions - -Due to the memory requirements of unlimited objects it is strongly recommended -to use them only in combination with the unified work areas. See :ref:`Separate -or Unified Work Areas` for more information on unified work areas. - -The following example demonstrates how the two simple configuration defines for -unlimited objects and unified works areas can replace many seperate -configuration defines for supported object classes: - -.. code-block:: c - - #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER - #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER - #define CONFIGURE_UNIFIED_WORK_AREAS - #define CONFIGURE_UNLIMITED_OBJECTS - #define CONFIGURE_RTEMS_INIT_TASKS_TABLE - #define CONFIGURE_INIT - #include - -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. - -.. index:: rtems_resource_unlimited - -.. _ConfigUnlimitedObjectsClass: - -Unlimited Objects by Class --------------------------- - -When the number of objects is not known ahead of time, RTEMS provides an -auto-extending mode that can be enabled individually for each object type by -using the macro ``rtems_resource_unlimited``. This takes a value as a -parameter, and is used to set the object maximum number field in an API -Configuration table. The value is an allocation unit size. When RTEMS is -required to grow the object table it is grown by this size. The kernel will -return the object memory back to the RTEMS Workspace when an object is -destroyed. The kernel will only return an allocated block of objects to the -RTEMS Workspace if at least half the allocation size of free objects remain -allocated. RTEMS always keeps one allocation block of objects allocated. Here -is an example of using ``rtems_resource_unlimited``: - -.. code-block:: c - - #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5) - -.. index:: rtems_resource_is_unlimited -.. index:: rtems_resource_maximum_per_allocation - -Object maximum specifications can be evaluated with the -``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation`` -macros. - -.. _ConfigUnlimitedObjectsDefault: - -Unlimited Objects by Default ----------------------------- - -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 -(:ref:`CONFIGURE_UNLIMITED_OBJECTS`) and specifying the allocation size -(:ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`). - -.. code-block:: c - - #define CONFIGURE_UNLIMITED_OBJECTS - #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5 - -General System Configuration -============================ - -This section defines the general system configuration options supported by -````. - -.. index:: CONFIGURE_DIRTY_MEMORY - -.. _CONFIGURE_DIRTY_MEMORY: - -CONFIGURE_DIRTY_MEMORY ----------------------- - -CONSTANT: - ``CONFIGURE_DIRTY_MEMORY`` - -DATA TYPE: - Boolean feature macro. - -RANGE: - Defined or undefined. - -DEFAULT VALUE: - By default, the memory used by the RTEMS Workspace and the C Program Heap - is uninitialized memory. - -DESCRIPTION: - This macro indicates whether RTEMS should dirty the memory used by the - RTEMS Workspace and the C Program Heap as part of its initialization. If - defined, the memory areas are dirtied with a ``0xCF`` byte pattern. - Otherwise, they are not. - -NOTES: - Dirtying memory can add significantly to system boot time. It may assist in - finding code that incorrectly assumes the contents of free memory areas is - cleared to zero during system initialization. In case - :ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` is also defined, then the - memory is first dirtied and then zeroed. - -.. index:: CONFIGURE_EXTRA_TASK_STACKS -.. index:: memory for task tasks - -.. _CONFIGURE_EXTRA_TASK_STACKS: - -CONFIGURE_EXTRA_TASK_STACKS ---------------------------- - -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 - ````. - -.. index:: CONFIGURE_INITIAL_EXTENSIONS - -.. _CONFIGURE_INITIAL_EXTENSIONS: - -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. - -.. index:: CONFIGURE_INTERRUPT_STACK_SIZE -.. index:: interrupt stack size - -.. _CONFIGURE_INTERRUPT_STACK_SIZE: - -CONFIGURE_INTERRUPT_STACK_SIZE ------------------------------- - -CONSTANT: - ``CONFIGURE_INTERRUPT_STACK_SIZE`` - -DATA TYPE: - Unsigned integer. - -RANGE: - Positive. - -DEFAULT VALUE: - The default value is ``BSP_INTERRUPT_STACK_SIZE`` in case it is defined, - otherwise the default value is ``CPU_STACK_MINIMUM_SIZE``. - -DESCRIPTION: - The ``CONFIGURE_INTERRUPT_STACK_SIZE`` configuration option defines the - size of an interrupt stack in bytes. - -NOTES: - The interrupt stack size must be aligned according to - ``CPU_INTERRUPT_STACK_ALIGNMENT``. - - There is one interrupt stack available for each configured processor - (:ref:`CONFIGURE_MAXIMUM_PROCESSORS `). The - interrupt stack areas are statically allocated in a special linker section - (``.rtemsstack.interrupt``). The placement of this linker section is - BSP-specific. - - Some BSPs use the interrupt stack as the initialization stack which is used - to perform the sequential system initialization before the multithreading - is started. - - The interrupt stacks are covered by the :ref:`stack checker - `. However, using a too small interrupt - stack size may still result in undefined behaviour. - - In releases before RTEMS 5.1 the default value was - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE - ` instead of ``CPU_STACK_MINIMUM_SIZE``. - -.. index:: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS -.. index:: maximum file descriptors - -.. _CONFIGURE_MAXIMUM_FILE_DESCRIPTORS: - -CONFIGURE_MAXIMUM_FILE_DESCRIPTORS ----------------------------------- - -CONSTANT: - ``CONFIGURE_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. - -.. index:: CONFIGURE_MAXIMUM_PRIORITY -.. index:: maximum priority -.. index:: number of priority levels - -.. _CONFIGURE_MAXIMUM_PRIORITY: - -CONFIGURE_MAXIMUM_PRIORITY --------------------------- - -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: - For the schedulers - - * :ref:`SchedulerPriority`, which is the default in uniprocessor - configurations and can be configured through the - :ref:`CONFIGURE_SCHEDULER_PRIORITY` configuration option, - - * :ref:`SchedulerSMPPriority` which can be configured through the - :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP` configuration option, and - - * :ref:`SchedulerSMPPriorityAffinity` which can be configured through the - :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP` configuration option - - this configuration option specifies the maximum numeric priority of any task - for these schedulers and one less that the number of priority levels for - these schedulers. For all other schedulers provided by RTEMS, this - configuration option has no effect. - -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. - - Reducing the number of priorities through this configuration option reduces - the amount of memory allocated by the schedulers listed above. These - schedulers use a chain control structure per priority and this structure - consists of three pointers. On a 32-bit architecture, the allocated memory - is 12 bytes * (``CONFIGURE_MAXIMUM_PRIORITY`` + 1), e.g. 3072 bytes for 256 - priority levels (default), 48 bytes for 4 priority levels - (``CONFIGURE_MAXIMUM_PRIORITY == 3``). - -.. index:: CONFIGURE_MAXIMUM_PROCESSORS - -.. _CONFIGURE_MAXIMUM_PROCESSORS: - -CONFIGURE_MAXIMUM_PROCESSORS ----------------------------- - -CONSTANT: - ``CONFIGURE_MAXIMUM_PROCESSORS`` - -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. - -DEFAULT VALUE: - The default value is 1. - -DESCRIPTION: - ``CONFIGURE_MAXIMUM_PROCESSORS`` must be set to the maximum number of - processors an application intends to use. The number of actually available - processors depends on the hardware and may be less. It is recommended to - use the smallest value suitable for the application in order to save - memory. Each processor needs an idle thread and interrupt stack for - example. - -NOTES: - If there are more processors available than configured, the rest will be - ignored. This configuration define is ignored in uniprocessor - configurations. - -.. index:: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE -.. index:: maximum thread name size - -.. _CONFIGURE_MAXIMUM_THREAD_NAME_SIZE: - -CONFIGURE_MAXIMUM_THREAD_NAME_SIZE ----------------------------------- - -CONSTANT: - ``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` - -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - No restrictions. - -DEFAULT VALUE: - The default value is 16. This value was chosen for Linux compatibility, - see - `PTHREAD_SETNAME_NP(3) `_. - -DESCRIPTION: - This configuration parameter specifies the maximum thread name size - including the terminating `NUL` character. - -NOTE: - The size of the thread control block is increased by the maximum thread name - size. This configuration option is available since RTEMS 5.1. - -.. index:: CONFIGURE_MEMORY_OVERHEAD - -.. _CONFIGURE_MEMORY_OVERHEAD: - -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: - This 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. - -.. index:: CONFIGURE_MICROSECONDS_PER_TICK -.. index:: tick quantum - -.. _CONFIGURE_MICROSECONDS_PER_TICK: - -CONFIGURE_MICROSECONDS_PER_TICK -------------------------------- - -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. - -.. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE -.. index:: minimum task stack size - -.. _CONFIGURE_MINIMUM_TASK_STACK_SIZE: - -CONFIGURE_MINIMUM_TASK_STACK_SIZE ---------------------------------- - -CONSTANT: - ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` - -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Positive. - -DEFAULT VALUE: - The default value is architecture-specific. - -DESCRIPTION: - This configuration parameter defines the minimum stack size in bytes for - every user task or thread in the system. - -NOTES: - Adjusting this parameter should be done with caution. Examining the actual - stack usage using the stack checker usage reporting facility is recommended - (see also :ref:`CONFIGURE_STACK_CHECKER_ENABLED `). - - 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. - - By default, this configuration parameter defines also the minimum stack - size of POSIX threads. This can be changed with the - :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE ` - configuration option. - - In releases before RTEMS 5.1 the ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` was - used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE - `. - -.. index:: CONFIGURE_STACK_CHECKER_ENABLED - -.. _CONFIGURE_STACK_CHECKER_ENABLED: - -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. - -.. index:: CONFIGURE_TICKS_PER_TIMESLICE -.. index:: ticks per timeslice - -.. _CONFIGURE_TICKS_PER_TIMESLICE: - -CONFIGURE_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. - -.. index:: CONFIGURE_UNIFIED_WORK_AREAS -.. index:: unified work areas -.. index:: separate work areas -.. index:: RTEMS Workspace -.. index:: C Program Heap - -.. _CONFIGURE_UNIFIED_WORK_AREAS: - -CONFIGURE_UNIFIED_WORK_AREAS ----------------------------- - -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. - -.. _CONFIGURE_UNLIMITED_ALLOCATION_SIZE: - -CONFIGURE_UNLIMITED_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. - -.. index:: CONFIGURE_UNLIMITED_OBJECTS - -.. _CONFIGURE_UNLIMITED_OBJECTS: - -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. - -.. index:: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION - -.. _CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION: - -CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION ---------------------------------------- - -CONSTANT: - ``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` - -DATA TYPE: - Boolean feature macro. - -RANGE: - Defined or undefined. - -DEFAULT VALUE: - This is not defined by default, and thus the system initialization is - quiet. - -DESCRIPTION: - This configuration option enables to print some information during system - initialization. - -NOTES: - You may use this feature to debug system initialization issues. The - printk() function is used to print the information. - -.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY -.. index:: clear C Program Heap -.. index:: clear RTEMS Workspace -.. index:: zero C Program Heap -.. index:: zero RTEMS Workspace - -.. _CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY: - -CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY --------------------------------------- - -CONSTANT: - ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` - -DATA TYPE: - Boolean feature macro. - -RANGE: - Defined or undefined. - -DEFAULT VALUE: - This is not defined by default. 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. In case - :ref:`CONFIGURE_DIRTY_MEMORY` is also defined, then the memory is first - dirtied and then zeroed. - -Classic API Configuration -========================= - -This section defines the Classic API related system configuration parameters -supported by ````. - -.. index:: CONFIGURE_MAXIMUM_BARRIERS - -.. _CONFIGURE_MAXIMUM_BARRIERS: - -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. - -.. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES - -.. _CONFIGURE_MAXIMUM_MESSAGE_QUEUES: - -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. You have - to account for the memory used to store the messages of each message queue, - see :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. - -.. index:: CONFIGURE_MAXIMUM_PARTITIONS - -.. _CONFIGURE_MAXIMUM_PARTITIONS: - -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. - -.. index:: CONFIGURE_MAXIMUM_PERIODS - -.. _CONFIGURE_MAXIMUM_PERIODS: - -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. - -.. index:: CONFIGURE_MAXIMUM_PORTS - -.. _CONFIGURE_MAXIMUM_PORTS: - -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. - -.. index:: CONFIGURE_MAXIMUM_REGIONS - -.. _CONFIGURE_MAXIMUM_REGIONS: - -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. - -.. index:: CONFIGURE_MAXIMUM_SEMAPHORES - -.. _CONFIGURE_MAXIMUM_SEMAPHORES: - -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. - - In SMP configurations, the size of a Semaphore Control Block depends on the - scheduler count (see :ref:`ConfigurationSchedulerTable`). The semaphores - using the :ref:`MrsP` need a ceiling priority per scheduler. - -.. index:: CONFIGURE_MAXIMUM_TASKS - -.. _CONFIGURE_MAXIMUM_TASKS: - -CONFIGURE_MAXIMUM_TASKS ------------------------ - -CONSTANT: - ``CONFIGURE_MAXIMUM_TASKS`` - -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. - -DEFAULT VALUE: - The default value is ``0``. - -DESCRIPTION: - ``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API Tasks that - can be concurrently active. - -NOTES: - This object class can be configured in unlimited allocation mode. - - The calculations for the required memory in the RTEMS Workspace for tasks - assume that each task has a minimum stack size and has floating point - support enabled. The configuration parameter - ``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify task stack requirements - *ABOVE* the minimum size required. See :ref:`Reserve Task/Thread Stack - Memory Above Minimum` for more information about - ``CONFIGURE_EXTRA_TASK_STACKS``. - - The maximum number of POSIX threads is specified by - :ref:`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. - -.. index:: CONFIGURE_MAXIMUM_TIMERS - -.. _CONFIGURE_MAXIMUM_TIMERS: - -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. - -.. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS - -.. _CONFIGURE_MAXIMUM_USER_EXTENSIONS: - -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. - -Classic API Initialization Task 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. - -.. index:: CONFIGURE_INIT_TASK_ARGUMENTS - -.. _CONFIGURE_INIT_TASK_ARGUMENTS: - -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. - -.. index:: CONFIGURE_INIT_TASK_ATTRIBUTES - -.. _CONFIGURE_INIT_TASK_ATTRIBUTES: - -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. - -.. index:: CONFIGURE_INIT_TASK_ENTRY_POINT - -.. _CONFIGURE_INIT_TASK_ENTRY_POINT: - -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. - -.. index:: CONFIGURE_INIT_TASK_INITIAL_MODES - -.. _CONFIGURE_INIT_TASK_INITIAL_MODES: - -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. - -.. index:: CONFIGURE_INIT_TASK_NAME - -.. _CONFIGURE_INIT_TASK_NAME: - -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. - -.. index:: CONFIGURE_INIT_TASK_PRIORITY - -.. _CONFIGURE_INIT_TASK_PRIORITY: - -CONFIGURE_INIT_TASK_PRIORITY ----------------------------- - -CONSTANT: - ``CONFIGURE_INIT_TASK_PRIORITY`` - -DATA TYPE: - RTEMS Task Priority (``rtems_task_priority``). - -RANGE: - One (1) to the maximum user priority value of the scheduler. - -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. - -.. index:: CONFIGURE_INIT_TASK_STACK_SIZE - -.. _CONFIGURE_INIT_TASK_STACK_SIZE: - -CONFIGURE_INIT_TASK_STACK_SIZE ------------------------------- - -CONSTANT: - ``CONFIGURE_INIT_TASK_STACK_SIZE`` - -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Zero or positive. - -DEFAULT VALUE: - The default value is RTEMS_MINIMUM_STACK_SIZE. - -DESCRIPTION: - ``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single - initialization task defined by the Classic API Initialization Tasks Table. - -NOTES: - If the stack size specified is greater than the configured minimum, it must - be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve - Task/Thread Stack Memory Above Minimum` for more information about - ``CONFIGURE_EXTRA_TASK_STACKS``. - -.. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE - -.. _CONFIGURE_RTEMS_INIT_TASKS_TABLE: - -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. - -POSIX API Configuration -======================= - -The parameters in this section are used to configure resources for the POSIX -API supported by RTEMS. Most POSIX API objects are available by default since -RTEMS 5.1. The queued signals and timers are only available if RTEMS was built -with the ``--enable-posix`` build configuration option. - -.. index:: CONFIGURE_MAXIMUM_POSIX_KEYS - -.. _CONFIGURE_MAXIMUM_POSIX_KEYS: - -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. - -.. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS - -.. _CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS: - -CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS ---------------------------------------- - -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` - -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. - -DEFAULT VALUE: - The default value is - :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS ` * - :ref:`CONFIGURE_MAXIMUM_TASKS ` + - :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS `. - -DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` is the maximum number of key - value pairs used by POSIX API Keys that can be concurrently active. - -NOTES: - This object class can be configured in unlimited allocation mode. - - A key value pair is created by :c:func:`pthread_setspecific` if the value - is not :c:macro:`NULL`, otherwise it is deleted. - -.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES - -.. _CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES: - -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. You have - to account for the memory used to store the messages of each message queue, - see :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. - -.. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS - -.. _CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS: - -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: - Unlimited objects are not available for queued signals. - - Queued signals are only available if RTEMS was built with the - ``--enable-posix`` build configuration option. - -.. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES - -.. _CONFIGURE_MAXIMUM_POSIX_SEMAPHORES: - -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 - Named Semaphores that can be concurrently active. - -NOTES: - This object class can be configured in unlimited allocation mode. - - Named semaphores are created with ``sem_open()``. Semaphores initialized - with ``sem_init()`` are not affected by this configuration option since the - storage space for these semaphores is user-provided. - -.. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS - -.. _CONFIGURE_MAXIMUM_POSIX_TIMERS: - -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. - - Timers are only available if RTEMS was built with the - ``--enable-posix`` build configuration option. - -.. index:: CONFIGURE_MAXIMUM_POSIX_THREADS - -.. _CONFIGURE_MAXIMUM_POSIX_THREADS: - -CONFIGURE_MAXIMUM_POSIX_THREADS -------------------------------- - -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_THREADS`` - -DATA TYPE: - Unsigned integer (``uint32_t``). - -RANGE: - Zero or positive. - -DEFAULT VALUE: - The default value is 0. - -DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API - Threads that can be concurrently active. - -NOTES: - This object class can be configured in unlimited allocation mode. - - This calculations for the required memory in the RTEMS Workspace for - threads assume that each thread has a minimum stack size and has floating - point support enabled. The configuration parameter - ``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify thread stack - requirements *ABOVE* the minimum size required. See :ref:`Reserve - Task/Thread Stack Memory Above Minimum` for more information about - ``CONFIGURE_EXTRA_TASK_STACKS``. - - The maximum number of Classic API Tasks is specified by - :ref:`CONFIGURE_MAXIMUM_TASKS `. - - All POSIX threads have floating point enabled. - -.. index:: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE -.. index:: minimum POSIX thread stack size - -.. _CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE: - -CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE ------------------------------------------ - -CONSTANT: - ``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` - -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Positive. - -DEFAULT VALUE: - The default value is two times the value of - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE `. - -DESCRIPTION: - This configuration parameter defines the minimum stack size in bytes for - every POSIX thread in the system. - -NOTES: - None. - -POSIX Initialization Thread 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. - -.. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT - -.. _CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT: - -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. - -.. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE - -.. _CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE: - -CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE --------------------------------------- - -CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` - -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Zero or positive. - -DEFAULT VALUE: - The default value is 2 \* RTEMS_MINIMUM_STACK_SIZE. - -DESCRIPTION: - ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the single - initialization thread defined by the POSIX API Initialization Threads - Table. - -NOTES: - If the stack size specified is greater than the configured minimum, it must - be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve - Task/Thread Stack Memory Above Minimum` for more information about - ``CONFIGURE_EXTRA_TASK_STACKS``. - -.. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE - -.. _CONFIGURE_POSIX_INIT_THREAD_TABLE: - -CONFIGURE_POSIX_INIT_THREAD_TABLE ---------------------------------- - -CONSTANT: - ``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. - -Task Stack Allocator Configuration -================================== - -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. - -.. index:: CONFIGURE_TASK_STACK_ALLOCATOR -.. index:: task stack allocator - -.. _CONFIGURE_TASK_STACK_ALLOCATOR: - -CONFIGURE_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`` - -.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT - -.. _CONFIGURE_TASK_STACK_ALLOCATOR_INIT: - -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`` - -.. index:: CONFIGURE_TASK_STACK_DEALLOCATOR -.. index:: task stack deallocator - -.. _CONFIGURE_TASK_STACK_DEALLOCATOR: - -CONFIGURE_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`` - -Message Queue Buffer Configuration -================================== - -This section describes the configuration parameters related to specifying the -amount of memory reserved for message queue message buffers. See -:ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and -:ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`. - -.. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY -.. index:: configure message queue buffer memory - -.. _CONFIGURE_MESSAGE_BUFFER_MEMORY: - -CONFIGURE_MESSAGE_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 - :ref:`CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE` can be used to assist in - calculating the message buffer memory required. In this example, there are - two message queues used in this application. The first message queue has - maximum of 24 pending messages with the message structure defined by the - type ``one_message_type``. The other message queue has maximum of 500 - pending messages with the message structure defined by the type - ``other_message_type``. - - .. code-block:: c - - #define CONFIGURE_MESSAGE_BUFFER_MEMORY \ - (CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ - 24, sizeof(one_message_type) \ - ) + \ - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ - 500, sizeof(other_message_type) \ - ) - -.. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE -.. index:: memory for a single message queue's buffers - -.. _CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE: - -CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE ------------------------------------ - -CONSTANT: - ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)`` - -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Positive. - -DEFAULT VALUE: - The default value is None. - -DESCRIPTION: - This is a helper macro which is used to assist in computing the total - amount of memory required for message buffers. Each message queue will - have its own configuration with maximum message size and maximum number of - pending messages. - - The interface for this macro is as follows: - - .. code-block:: c - - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per) - - Where ``max_messages`` is the maximum number of pending messages and - ``size_per`` is the size in bytes of the user message. - -NOTES: - This macro is only used in support of :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. - -Filesystem Configuration -======================== - -By default, the In-Memory Filesystem (IMFS) is used as the base filesystem (also -known as root filesystem). In order to save some memory for your application, -you can disable the filesystem support with the -:ref:`CONFIGURE_APPLICATION_DISABLE_FILESYSTEM` configuration option. -Alternatively, you can strip down the features of the base filesystem with the -:ref:`CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM` and -:ref:`CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM` configuration options. These -three configuration options are mutually exclusive. They are intended for an -advanced application configuration. - -Features of the IMFS can be disabled and enabled with the following -configuration options: - -* :ref:`CONFIGURE_IMFS_DISABLE_CHMOD` - -* :ref:`CONFIGURE_IMFS_DISABLE_CHOWN` - -* :ref:`CONFIGURE_IMFS_DISABLE_LINK` - -* :ref:`CONFIGURE_IMFS_DISABLE_MKNOD` - -* :ref:`CONFIGURE_IMFS_DISABLE_MKNOD_FILE` - -* :ref:`CONFIGURE_IMFS_DISABLE_MOUNT` - -* :ref:`CONFIGURE_IMFS_DISABLE_READDIR` - -* :ref:`CONFIGURE_IMFS_DISABLE_READLINK` - -* :ref:`CONFIGURE_IMFS_DISABLE_RENAME` - -* :ref:`CONFIGURE_IMFS_DISABLE_RMNOD` - -* :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK` - -* :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT` - -* :ref:`CONFIGURE_IMFS_DISABLE_UTIME` - -* :ref:`CONFIGURE_IMFS_ENABLE_MKFIFO` - -.. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM - -.. _CONFIGURE_APPLICATION_DISABLE_FILESYSTEM: - -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. - -.. index:: CONFIGURE_IMFS_ENABLE_MKFIFO - -.. _CONFIGURE_IMFS_ENABLE_MKFIFO: - -CONFIGURE_IMFS_ENABLE_MKFIFO ----------------------------- - -CONSTANT: - ``CONFIGURE_IMFS_ENABLE_MKFIFO`` - -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 FIFOs - is enabled in the root IMFS. - -.. index:: CONFIGURE_IMFS_DISABLE_CHMOD - -.. _CONFIGURE_IMFS_DISABLE_CHMOD: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_CHOWN - -.. _CONFIGURE_IMFS_DISABLE_CHOWN: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_LINK - -.. _CONFIGURE_IMFS_DISABLE_LINK: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_MKNOD - -.. _CONFIGURE_IMFS_DISABLE_MKNOD: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE - -.. _CONFIGURE_IMFS_DISABLE_MKNOD_FILE: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_MOUNT - -.. _CONFIGURE_IMFS_DISABLE_MOUNT: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_READDIR - -.. _CONFIGURE_IMFS_DISABLE_READDIR: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_READLINK - -.. _CONFIGURE_IMFS_DISABLE_READLINK: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_RENAME - -.. _CONFIGURE_IMFS_DISABLE_RENAME: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_RMNOD - -.. _CONFIGURE_IMFS_DISABLE_RMNOD: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_SYMLINK - -.. _CONFIGURE_IMFS_DISABLE_SYMLINK: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT - -.. _CONFIGURE_IMFS_DISABLE_UNMOUNT: - -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. - -.. index:: CONFIGURE_IMFS_DISABLE_UTIME - -.. _CONFIGURE_IMFS_DISABLE_UTIME: - -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. - -.. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK - -.. _CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK: - -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. - -.. index:: CONFIGURE_MAXIMUM_DEVICES - -.. _CONFIGURE_MAXIMUM_DEVICES: - -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. - -.. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM - -.. _CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM: - -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. - -.. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM - -.. _CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM: - -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``. - -Block Device Cache Configuration -================================ - -This section defines Block Device Cache (bdbuf) related configuration -parameters. - -.. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK - -.. _CONFIGURE_APPLICATION_NEEDS_LIBBLOCK: - -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. - -.. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE - -.. _CONFIGURE_BDBUF_CACHE_MEMORY_SIZE: - -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. - -.. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE - -.. _CONFIGURE_BDBUF_BUFFER_MAX_SIZE: - -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. - -.. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE - -.. _CONFIGURE_BDBUF_BUFFER_MIN_SIZE: - -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. - -.. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS - -.. _CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS: - -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. - -.. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS - -.. _CONFIGURE_BDBUF_MAX_WRITE_BLOCKS: - -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. - -.. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY - -.. _CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY: - -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. - -.. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE - -.. _CONFIGURE_BDBUF_TASK_STACK_SIZE: - -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. - -.. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD - -.. _CONFIGURE_SWAPOUT_BLOCK_HOLD: - -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. - -.. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD - -.. _CONFIGURE_SWAPOUT_SWAP_PERIOD: - -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. - -.. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY - -.. _CONFIGURE_SWAPOUT_TASK_PRIORITY: - -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. - -.. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY - -.. _CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY: - -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. - -.. index:: CONFIGURE_SWAPOUT_WORKER_TASKS - -.. _CONFIGURE_SWAPOUT_WORKER_TASKS: - -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. - -BSP Related Configuration Options -================================= - -This section describes configuration options related to the BSP. Some -configuration options may have a BSP-specific setting which is defined by -````. The BSP-specific settings can be disabled by the -:ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option. - -.. index:: BSP_IDLE_TASK_BODY - -.. _BSP_IDLE_TASK_BODY: - -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 - -.. index:: BSP_IDLE_TASK_STACK_SIZE - -.. _BSP_IDLE_TASK_STACK_SIZE: - -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``. - -.. index:: BSP_INITIAL_EXTENSION - -.. _BSP_INITIAL_EXTENSION: - -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. - -.. index:: BSP_INTERRUPT_STACK_SIZE - -.. _BSP_INTERRUPT_STACK_SIZE: - -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. - -.. index:: BSP_MAXIMUM_DEVICES - -.. _BSP_MAXIMUM_DEVICES: - -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. - -.. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS - -.. _CONFIGURE_BSP_PREREQUISITE_DRIVERS: - -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. - -.. index:: CONFIGURE_DISABLE_BSP_SETTINGS - -.. _CONFIGURE_DISABLE_BSP_SETTINGS: - -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. - -.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK - -.. _CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK: - -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. - -Idle Task Configuration -======================= - -This section defines the IDLE task related configuration parameters supported -by ````. - -.. index:: CONFIGURE_IDLE_TASK_BODY - -.. _CONFIGURE_IDLE_TASK_BODY: - -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. - -.. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION - -.. _CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION: - -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. - -.. index:: CONFIGURE_IDLE_TASK_STACK_SIZE - -.. _CONFIGURE_IDLE_TASK_STACK_SIZE: - -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. - -General Scheduler Configuration -=============================== - -This section defines the configuration parameters related to selecting a -scheduling algorithm for an application. A scheduler configuration is optional -and only necessary in very specific circumstances. A normal application -configuration does not need any of the configuration options described in this -section. By default, the :ref:`Deterministic Priority Scheduler -` algorithm is used in uniprocessor configurations. In case -SMP is enabled and the configured maximum processors -(:ref:`CONFIGURE_MAXIMUM_PROCESSORS `) is greater -than one, then the :ref:`Earliest Deadline First (EDF) SMP Scheduler -` is selected as the default scheduler algorithm. - -For the :ref:`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 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. - -.. index:: CONFIGURE_SCHEDULER_CBS - -.. _CONFIGURE_SCHEDULER_CBS: - -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: - If defined, then the :ref:`Constant Bandwidth Server (CBS) Scheduler - ` algorithm is made available to the application. - -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. - - In case no explicit :ref:`clustered scheduler configuration - ` is present, then it is used as the - scheduler for exactly one processor. - -.. index:: CONFIGURE_SCHEDULER_EDF - -.. _CONFIGURE_SCHEDULER_EDF: - -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: - If defined, then the :ref:`Earliest Deadline First (EDF) Scheduler - ` algorithm is made available to the application. - -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. - - In case no explicit :ref:`clustered scheduler configuration - ` is present, then it is used as the - scheduler for exactly one processor. - -.. index:: CONFIGURE_SCHEDULER_EDF_SMP - -.. _CONFIGURE_SCHEDULER_EDF_SMP: - -CONFIGURE_SCHEDULER_EDF_SMP ---------------------------- - -CONSTANT: - ``CONFIGURE_SCHEDULER_EDF_SMP`` - -DATA TYPE: - Boolean feature macro. - -RANGE: - Defined or undefined. - -DEFAULT VALUE: - This is not defined by default. - -DESCRIPTION: - If defined, then the :ref:`Earliest Deadline First (EDF) SMP Scheduler - ` algorithm is made available to the application. - -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. - - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. - - In case no explicit :ref:`clustered scheduler configuration - ` is present, then it is used as the - scheduler for up to 32 processors. - - This scheduler algorithm is the default in SMP configurations if - :ref:`CONFIGURE_MAXIMUM_PROCESSORS ` is - greater than one. - -.. index:: CONFIGURE_SCHEDULER_NAME - -.. _CONFIGURE_SCHEDULER_NAME: - -CONFIGURE_SCHEDULER_NAME ------------------------- - -CONSTANT: - ``CONFIGURE_SCHEDULER_NAME`` - -DATA TYPE: - RTEMS Name (``rtems_name``). - -RANGE: - Any value. - -DEFAULT VALUE: - The default name is - - - ``"MEDF"`` for the :ref:`EDF SMP Scheduler `, - - ``"MPA "`` for the :ref:`Arbitrary Processor Affinity Priority SMP Scheduler `, - - ``"MPD "`` for the :ref:`Deterministic Priority SMP Scheduler `, - - ``"MPS "`` for the :ref:`Simple Priority SMP Scheduler `, - - ``"UCBS"`` for the :ref:`Uniprocessor CBS Scheduler `, - - ``"UEDF"`` for the :ref:`Uniprocessor EDF Scheduler `, - - ``"UPD "`` for the :ref:`Uniprocessor Deterministic Priority Scheduler `, and - - ``"UPS "`` for the :ref:`Uniprocessor Simple Priority Scheduler `. - -DESCRIPTION: - Schedulers can be identified via ``rtems_scheduler_ident``. The name of - the scheduler is determined by the configuration. - -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. - -.. index:: CONFIGURE_SCHEDULER_PRIORITY - -.. _CONFIGURE_SCHEDULER_PRIORITY: - -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: - If defined, then the :ref:`Deterministic Priority Scheduler - ` algorithm is made available to the application. - -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. - - In case no explicit :ref:`clustered scheduler configuration - ` is present, then it is used as the - scheduler for exactly one processor. - - This scheduler algorithm is the default when - :ref:`CONFIGURE_MAXIMUM_PROCESSORS ` is - exactly one. - - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. - -.. index:: CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP - -.. _CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP: - -CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP ------------------------------------------ - -CONSTANT: - ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP`` - -DATA TYPE: - Boolean feature macro. - -RANGE: - Defined or undefined. - -DEFAULT VALUE: - This is not defined by default. - -DESCRIPTION: - If defined, then the :ref:`Arbitrary Processor Affinity SMP Scheduler - ` algorithm is made available to the - application. - -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. - - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. - - In case no explicit :ref:`clustered scheduler configuration - ` is present, then it is used as the - scheduler for up to 32 processors. - - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. - -.. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP - -.. _CONFIGURE_SCHEDULER_PRIORITY_SMP: - -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: - If defined, then the :ref:`Deterministic Priority SMP Scheduler - ` algorithm is made available to the application. - -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. - - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. - - In case no explicit :ref:`clustered scheduler configuration - ` is present, then it is used as the - scheduler for up to 32 processors. - - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. - -.. index:: CONFIGURE_SCHEDULER_SIMPLE - -.. _CONFIGURE_SCHEDULER_SIMPLE: - -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: - If defined, then the :ref:`Simple Priority Scheduler - ` algorithm is made available to the application. - -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. - - In case no explicit :ref:`clustered scheduler configuration - ` is present, then it is used as the - scheduler for exactly one processor. - -.. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP - -.. _CONFIGURE_SCHEDULER_SIMPLE_SMP: - -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: - If defined, then the :ref:`Simple Priority SMP Scheduler - ` algorithm is made available to the - application. - -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. - - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. - - In case no explicit :ref:`clustered scheduler configuration - ` is present, then it is used as the - scheduler for up to 32 processors. - -.. index:: CONFIGURE_SCHEDULER_USER - -.. _CONFIGURE_SCHEDULER_USER: - -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`` must be defined to a static definition of - the scheduler data structures of the user scheduler. - - - ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` must be defined to a scheduler - table entry 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: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. - - 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. - -.. _ConfigurationSchedulersClustered: - -Clustered Scheduler Configuration -================================= - -A clustered scheduler configuration is optional. It is an advanced -configuration area and only necessary in specific circumstances. - -Clustered scheduling helps to control the worst-case latencies in a -multiprocessor system (SMP). The goal is to reduce the amount of shared state -in the system and thus prevention of lock contention. Modern multiprocessor -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. - -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 algorithm is used for which cluster? - -The schedulers are statically configured. - -Configuration Step 1 - Scheduler Algorithms -------------------------------------------- - -Firstly, the application must select which scheduling algorithms are available -with the following defines - -- :ref:`CONFIGURE_SCHEDULER_EDF_SMP `, - -- :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP `, - -- :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP `, and - -- :ref:`CONFIGURE_SCHEDULER_SIMPLE_SMP `. - -This is necessary to calculate the per-thread overhead introduced by the -scheduler algorithms. After these definitions the configuration file must -``#include `` to have access to scheduler-specific -configuration macros. - -It is possible to make more than one scheduler algorithm available to the -application. For example a :ref:`Simple Priority SMP Scheduler -` could be used in a partition for low latency -tasks in addition to an :ref:`EDF SMP Scheduler ` for a -general-purpose cluster. Since the per-thread overhead depends on the -scheduler algorithm only the scheduler algorithms used by the application -should be configured. - -Configuration Step 2 - Schedulers ---------------------------------- - -Each scheduler needs some data structures. Use the following macros to create -the scheduler data structures for a particular scheduler identified in the -configuration by ``name``. - -- ``RTEMS_SCHEDULER_EDF_SMP(name, max_cpu_count)``, - -- ``RTEMS_SCHEDULER_PRIORITY_AFFINITY_SMP(name, prio_count)``, - -- ``RTEMS_SCHEDULER_PRIORITY_SMP(name, prio_count)``, and - -- ``RTEMS_SCHEDULER_SIMPLE_SMP(name)``. - -The ``name`` parameter is used as part of a designator for scheduler-specific -data structures, so the usual C/C++ designator rules apply. This ``name`` is -not the scheduler object name. Additional parameters are scheduler-specific. - -.. _ConfigurationSchedulerTable: - -Configuration Step 3 - Scheduler Table --------------------------------------- - -The schedulers are registered in the system via the scheduler table. To -populate the scheduler table define ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` to a -list of the following scheduler table entry initializers - -- ``RTEMS_SCHEDULER_TABLE_EDF_SMP(name, obj_name)``, - -- ``RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP(name, obj_name)``, - -- ``RTEMS_SCHEDULER_TABLE_PRIORITY_SMP(name, obj_name)``, and - -- ``RTEMS_SCHEDULER_TABLE_SIMPLE_SMP(name, obj_name)``. - -The ``name`` parameter must correspond to the parameter defining the scheduler -data structures of configuration step 2. The ``obj_name`` determines the -scheduler object name and can be used in :ref:`rtems_scheduler_ident() -` to get the scheduler object identifier. The scheduler -index is defined by the index of the scheduler table. It is a configuration -error to add a scheduler multiple times to the scheduler table. - -Configuration Step 4 - Processor to Scheduler Assignment --------------------------------------------------------- - -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 -(:ref:`CONFIGURE_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_SCHEDULER_ASSIGNMENTS`` to a list of - -- ``RTEMS_SCHEDULER_ASSIGN(scheduler_index, attr)`` and - -- ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` - -macros. The ``scheduler_index`` parameter must be a valid index into the -scheduler table defined by configuration step 3. 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``. - -It is possible to add/remove processors to/from schedulers at run-time, see -:ref:`rtems_scheduler_add_processor() ` and -:ref:`rtems_scheduler_remove_processor() `. - -Configuration 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 SMP schedulers -capable of dealing with 256 priority levels. The scheduler with index zero has -the name ``"IO "``. The scheduler with index one has the name ``"WORK"``. The -scheduler assignments of the first, third and fourth processor are mandatory, -so the system must have at least four processors, otherwise a fatal run-time -error will occur during system startup. The processor assignments for the -fifth up to the eighth processor are optional so that the same application can -be used for the normal and high-performance product lines. The second -processor has no scheduler assigned and runs Linux. A hypervisor will ensure -that the two systems cannot interfere in an undesirable way. - -.. code-block:: c - - #define CONFIGURE_MAXIMUM_PROCESSORS 8 - #define CONFIGURE_MAXIMUM_PRIORITY 255 - - /* Configuration Step 1 - Scheduler Algorithms */ - #define CONFIGURE_SCHEDULER_PRIORITY_SMP - #include - - /* Configuration Step 2 - Schedulers */ - RTEMS_SCHEDULER_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1); - RTEMS_SCHEDULER_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1); - - /* Configuration Step 3 - Scheduler Table */ - #define CONFIGURE_SCHEDULER_TABLE_ENTRIES \ - RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \ - io, \ - rtems_build_name('I', 'O', ' ', ' ') \ - ), \ - RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \ - work, \ - rtems_build_name('W', 'O', 'R', 'K') \ - ) - - /* Configuration Step 4 - Processor to Scheduler Assignment */ - #define CONFIGURE_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) - -Configuration Errors --------------------- - -In case one of the scheduler indices in ``CONFIGURE_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``. - -- ``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_SCHEDULER_ASSIGNMENTS`` definition. - -- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not allowed - to start multitasking on a processor with no scheduler assigned. - -Device Driver Configuration -=========================== - -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. - -.. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER - -.. _CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER: - -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. - -.. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS - -.. _CONFIGURE_APPLICATION_EXTRA_DRIVERS: - -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. - -.. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER - -.. _CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER: - -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 a 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. - -.. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER - -.. _CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER: - -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 the :file:`/dev/console` - device file. This device is used to initialize the standard input, output, - and error file descriptors. - - BSPs should be constructed in a manner that allows ``printk()`` to work - properly without the need for the console driver to be configured. - - The - - * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, - - * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and - - * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` - - configuration options are mutually exclusive. - -.. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER - -.. _CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER: - -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. - -.. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER -.. index:: /dev/null - -.. _CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER: - -CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER ---------------------------------------- - -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. - -.. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER - -.. _CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER: - -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. - -.. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER - -.. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER: - -CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER -------------------------------------------------- - -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` - -DATA TYPE: - Boolean feature macro. - -RANGE: - Defined or undefined. - -DEFAULT VALUE: - This is not defined by default. - -DESCRIPTION: - ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` is defined if the - application wishes to include the Simple Console Device Driver. - -NOTES: - This device driver is responsible for providing the :file:`/dev/console` - device file. This device is used to initialize the standard input, output, - and error file descriptors. - - This device driver reads via ``getchark()``. - - This device driver writes via ``rtems_putc()``. - - The Termios framework is not used. There is no support to change device - settings, e.g. baud, stop bits, parity, etc. - - The - - * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, - - * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and - - * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` - - configuration options are mutually exclusive. - -.. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER - -.. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER: - -CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER ------------------------------------------------------- - -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` - -DATA TYPE: - Boolean feature macro. - -RANGE: - Defined or undefined. - -DEFAULT VALUE: - This is not defined by default. - -DESCRIPTION: - ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` is defined if - the application wishes to include the Simple Task Console Device Driver. - -NOTES: - This device driver is responsible for providing the :file:`/dev/console` - device file. This device is used to initialize the standard input, output, - and error file descriptors. - - This device driver reads via ``getchark()``. - - This device driver writes into a write buffer. The count of characters - written into the write buffer is returned. It might be less than the - requested count, in case the write buffer is full. The write is - non-blocking and may be called from interrupt context. A dedicated task - reads from the write buffer and outputs the characters via - ``rtems_putc()``. This task runs with the least important priority. The - write buffer size is 2047 characters and it is not configurable. - - Use ``fsync(STDOUT_FILENO)`` or ``fdatasync(STDOUT_FILENO)`` to drain the - write buffer. - - The Termios framework is not used. There is no support to change device - settings, e.g. baud, stop bits, parity, etc. - - The - - * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, - - * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and - - * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` - - configuration options are mutually exclusive. - -.. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER - -.. _CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER: - -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. - -.. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER - -.. _CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER: - -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. - -.. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER - -.. _CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER: - -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. - -.. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER -.. index:: /dev/zero - -.. _CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER: - -CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER ---------------------------------------- - -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. - -.. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS - -.. _CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS: - -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. - -.. index:: CONFIGURE_MAXIMUM_DRIVERS - -.. _CONFIGURE_MAXIMUM_DRIVERS: - -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. - -Multiprocessing Configuration -============================= - -This section defines the multiprocessing related system configuration -parameters supported by ````. They are only used if RTEMS -was built with the ``--enable-multiprocessing`` build configuration option. -The multiprocessing (MPCI) support must not be confused with the SMP support. - -Additionally, this class of Configuration Constants are only applicable if -``CONFIGURE_MP_APPLICATION`` is defined. - -.. index:: CONFIGURE_MP_APPLICATION - -.. _CONFIGURE_MP_APPLICATION: - -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 built with the - ``--enable-multiprocessing`` build configuration option. - -.. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS - -.. _CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS: - -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. - -.. index:: CONFIGURE_MP_MAXIMUM_NODES - -.. _CONFIGURE_MP_MAXIMUM_NODES: - -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. - -.. index:: CONFIGURE_MP_MAXIMUM_PROXIES - -.. _CONFIGURE_MP_MAXIMUM_PROXIES: - -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 - -.. index:: CONFIGURE_MP_MPCI_TABLE_POINTER - -.. _CONFIGURE_MP_MPCI_TABLE_POINTER: - -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. - -.. index:: CONFIGURE_MP_NODE_NUMBER - -.. _CONFIGURE_MP_NODE_NUMBER: - -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. - -PCI Library Configuration -========================= - -This section defines the system configuration parameters supported by -``rtems/confdefs.h`` related to configuring the PCI Library for RTEMS. - -The PCI Library startup behaviour can be configured in four different ways -depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined: - -.. index:: PCI_LIB_AUTO - -``PCI_LIB_AUTO`` - Used to enable the PCI auto configuration software. PCI will be automatically - probed, PCI buses enumerated, all devices and bridges will be initialized - using Plug & Play software routines. The PCI device tree will be populated - based on the PCI devices found in the system, PCI devices will be configured - by allocating address region resources automatically in PCI space according - to the BSP or host bridge driver set up. - -.. index:: PCI_LIB_READ - -``PCI_LIB_READ`` - Used to enable the PCI read configuration software. The current PCI - configuration is read to create the RAM representation (the PCI device tree) - of the PCI devices present. PCI devices are assumed to already have been - initialized and PCI buses enumerated, it is therefore required that a BIOS or - a boot loader has set up configuration space prior to booting into RTEMS. - -.. index:: PCI_LIB_STATIC - -``PCI_LIB_STATIC`` - Used to enable the PCI static configuration software. The user provides a PCI - tree with information how all PCI devices are to be configured at compile - time by linking in a custom ``struct pci_bus pci_hb`` tree. The static PCI - library will not probe PCI for devices, instead it will assume that all - devices defined by the user are present, it will enumerate the PCI buses and - configure all PCI devices in static configuration accordingly. Since probe - and allocation software is not needed the startup is faster, has smaller - footprint and does not require dynamic memory allocation. - -.. index:: PCI_LIB_PERIPHERAL - -``PCI_LIB_PERIPHERAL`` - Used to enable the PCI peripheral configuration. It is similar to - ``PCI_LIB_STATIC``, but it will never write the configuration to the PCI - devices since PCI peripherals are not allowed to access PCI configuration - space. - -Note that selecting ``PCI_LIB_STATIC`` or ``PCI_LIB_PERIPHERAL`` but not -defining ``pci_hb`` will reuslt in link errors. Note also that in these modes -Plug & Play is not performed. - -Event Recording Configuration -============================= - -.. index:: CONFIGURE_RECORD_EXTENSIONS_ENABLED - -.. _CONFIGURE_RECORD_EXTENSIONS_ENABLED: - -CONFIGURE_RECORD_EXTENSIONS_ENABLED ------------------------------------ - -CONSTANT: - ``CONFIGURE_RECORD_EXTENSIONS_ENABLED`` - -DATA TYPE: - Boolean feature macro. - -RANGE: - Defined or undefined. - -DEFAULT VALUE: - This is not defined by default. - -DESCRIPTION: - If defined and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS - ` is also defined properly, then the - record extensions are enabled. - -NOTES: - The record extensions capture thread create, start, restart, delete, - switch, begin, exitted and terminate events. - -.. index:: CONFIGURE_RECORD_PER_PROCESSOR_ITEMS - -.. _CONFIGURE_RECORD_PER_PROCESSOR_ITEMS: - -CONFIGURE_RECORD_PER_PROCESSOR_ITEMS ------------------------------------- - -CONSTANT: - ``CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`` - -DATA TYPE: - Unsigned integer (``unsigned int``). - -RANGE: - A power of two greater than or equal to 16. - -DEFAULT VALUE: - This is not defined by default. - -DESCRIPTION: - If defined, then a record item buffer of the specified item count is - statically allocated for each configured processor - (:ref:`CONFIGURE_MAXIMUM_PROCESSORS `). - -NOTES: - None. - -.. _ConfigAda: - -Ada Configuration -================= - -The GNU Ada runtime library (libgnarl) uses threads, mutexes, condition -variables, and signals from the pthreads API. It uses also thread-local storage -for the Ada Task Control Block (ATCB). From these resources only the threads -need to be accounted for in the configuration. You should include the Ada tasks -in your setting of the :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS` configuration -option. - -Obsolete Configuration Options -============================== - -.. index:: CONFIGURE_BDBUF_BUFFER_COUNT - -CONFIGURE_BDBUF_BUFFER_COUNT ----------------------------- - -This configuration option was introduced in RTEMS 4.7.0 and is obsolete since -RTEMS 4.10.0. - -.. index:: CONFIGURE_BDBUF_BUFFER_SIZE - -CONFIGURE_BDBUF_BUFFER_SIZE ---------------------------- - -This configuration option was introduced in RTEMS 4.7.0 and is obsolete since -RTEMS 4.10.0. - -.. index:: CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS - -CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS --------------------------------------- - -This configuration option was introduced in RTEMS 4.9.0 and is obsolete since -RTEMS 5.1. - -.. index:: CONFIGURE_ENABLE_GO - -CONFIGURE_ENABLE_GO -------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_GNAT_RTEMS - -CONFIGURE_GNAT_RTEMS --------------------- - -This configuration option was present in all RTEMS versions since at 1997 and is -obsolete since RTEMS 5.1. See also :ref:`ConfigAda`. - -.. index:: CONFIGURE_HAS_OWN_CONFIGURATION_TABLE - -CONFIGURE_HAS_OWN_CONFIGURATION_TABLE -------------------------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_HAS_OWN_BDBUF_TABLE - -CONFIGURE_HAS_OWN_BDBUF_TABLE ------------------------------ - -This configuration option was introduced in RTEMS 4.7.0 and is obsolete since -RTEMS 4.10.0. - -.. index:: CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE - -CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE -------------------------------------- - -This configuration option was present in all RTEMS versions since at least 1995 -and is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_HAS_OWN_INIT_TASK_TABLE - -.. _CONFIGURE_HAS_OWN_INIT_TASK_TABLE: - -CONFIGURE_HAS_OWN_INIT_TASK_TABLE ---------------------------------- - -This configuration option was present in all RTEMS versions since at least 1995 -and is obsolete since RTEMS 5.1. If you used this configuration option or you -think that there should be a way to configure more than one Classic API -initialization task, then please ask on the :r:list:`users`. - -.. index:: CONFIGURE_HAS_OWN_MOUNT_TABLE - -CONFIGURE_HAS_OWN_MOUNT_TABLE ------------------------------ - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE - -CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE ---------------------------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS - -CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS --------------------------------- - -This configuration option was present in all RTEMS versions since at 1998 and is -obsolete since RTEMS 5.1. See also :ref:`CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`. - -.. index:: CONFIGURE_MAXIMUM_ADA_TASKS - -CONFIGURE_MAXIMUM_ADA_TASKS ---------------------------- - -This configuration option was present in all RTEMS versions since at 1997 and is -obsolete since RTEMS 5.1. See also :ref:`ConfigAda`. - -.. index:: CONFIGURE_MAXIMUM_FAKE_ADA_TASKS - -CONFIGURE_MAXIMUM_FAKE_ADA_TASKS --------------------------------- - -This configuration option was present in all RTEMS versions since at 1997 and is -obsolete since RTEMS 5.1. See also :ref:`ConfigAda`. - -.. index:: CONFIGURE_MAXIMUM_GO_CHANNELS - -CONFIGURE_MAXIMUM_GO_CHANNELS ------------------------------ - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_MAXIMUM_GOROUTINES - -CONFIGURE_MAXIMUM_GOROUTINES ----------------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_MAXIMUM_MRSP_SEMAPHORES - -CONFIGURE_MAXIMUM_MRSP_SEMAPHORES ---------------------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_NUMBER_OF_TERMIOS_PORTS - -CONFIGURE_NUMBER_OF_TERMIOS_PORTS ---------------------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_MAXIMUM_POSIX_BARRIERS - -CONFIGURE_MAXIMUM_POSIX_BARRIERS --------------------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES - -CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES -------------------------------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS - -CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS -------------------------------- - -This configuration option was introduced in RTEMS 4.10.0 and is obsolete since -RTEMS 5.1. - -.. index:: CONFIGURE_MAXIMUM_POSIX_MUTEXES - -CONFIGURE_MAXIMUM_POSIX_MUTEXES -------------------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_MAXIMUM_POSIX_RWLOCKS - -CONFIGURE_MAXIMUM_POSIX_RWLOCKS -------------------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_MAXIMUM_POSIX_SPINLOCKS - -CONFIGURE_MAXIMUM_POSIX_SPINLOCKS ---------------------------------- - -This configuration option is obsolete since RTEMS 5.1. - -.. index:: CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE - -.. _CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE: - -CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE ------------------------------------------ - -This configuration option was present in all RTEMS versions since at least 1995 -and is obsolete since RTEMS 5.1. If you used this configuration option or you -think that there should be a way to configure more than one POSIX initialization -thread, then please ask on the :r:list:`users`. - -.. index:: CONFIGURE_SMP_APPLICATION - -CONFIGURE_SMP_APPLICATION -------------------------- - -This configuration option was introduced in RTEMS 4.11.0 and is obsolete since -RTEMS 5.1. - -.. index:: CONFIGURE_SMP_MAXIMUM_PROCESSORS - -CONFIGURE_SMP_MAXIMUM_PROCESSORS --------------------------------- - -This configuration option was introduced in RTEMS 4.11.0 and is obsolete since -RTEMS 5.1. See also :ref:`CONFIGURE_MAXIMUM_PROCESSORS`. - -.. index:: CONFIGURE_TERMIOS_DISABLED - -CONFIGURE_TERMIOS_DISABLED --------------------------- - -This configuration option is obsolete since RTEMS 5.1. diff --git a/c-user/index.rst b/c-user/index.rst index 30cd165..e958481 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -47,7 +47,7 @@ RTEMS Classic API Guide (|version|). fatal_error board_support_packages user_extensions - configuring_a_system + config/index self_contained_objects multiprocessing symmetric_multiprocessing_services -- cgit v1.2.3