From bc9ce6526bdce06b82355dfb9c95e152094d69a3 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 10 Dec 2019 13:49:52 +0100 Subject: c-user: Move basic system configuration Move the basic system configuration to the front. Rename it to "General System Configuration". Update #3836. --- c-user/configuring_a_system.rst | 1376 +++++++++++++++++++-------------------- 1 file changed, 688 insertions(+), 688 deletions(-) (limited to 'c-user/configuring_a_system.rst') diff --git a/c-user/configuring_a_system.rst b/c-user/configuring_a_system.rst index 85c4e0f..0c0cb4a 100644 --- a/c-user/configuring_a_system.rst +++ b/c-user/configuring_a_system.rst @@ -476,334 +476,429 @@ NOTES: #define CONFIGURE_UNLIMITED_OBJECTS #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5 -Classic API Configuration -========================= +General System Configuration +============================ -This section defines the Classic API related system configuration parameters -supported by ````. +This section defines the general system configuration options supported by +````. -.. index:: CONFIGURE_MAXIMUM_TASKS +.. index:: CONFIGURE_EXTRA_TASK_STACKS +.. index:: memory for task tasks -.. _CONFIGURE_MAXIMUM_TASKS: +.. _CONFIGURE_EXTRA_TASK_STACKS: -CONFIGURE_MAXIMUM_TASKS ------------------------ +CONFIGURE_EXTRA_TASK_STACKS +--------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_TASKS`` + ``CONFIGURE_EXTRA_TASK_STACKS`` DATA TYPE: - Unsigned integer (``uint32_t``). + Unsigned integer (``size_t``). RANGE: - Zero or positive. + Undefined or positive. DEFAULT VALUE: - The default value is ``0``. + The default value is 0. DESCRIPTION: - ``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API Tasks that - can be concurrently active. + This configuration parameter is set to the number of bytes the applications + wishes to add to the task stack requirements calculated by + ````. 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. - -.. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_POSIX_THREADS. + 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_MAXIMUM_TIMERS +.. index:: CONFIGURE_INITIAL_EXTENSIONS -.. _CONFIGURE_MAXIMUM_TIMERS: +.. _CONFIGURE_INITIAL_EXTENSIONS: -CONFIGURE_MAXIMUM_TIMERS ------------------------- +CONFIGURE_INITIAL_EXTENSIONS +---------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_TIMERS`` + ``CONFIGURE_INITIAL_EXTENSIONS`` DATA TYPE: - Unsigned integer (``uint32_t``). + List of user extension initializers (``rtems_extensions_table``). RANGE: - Zero or positive. + Undefined or a list of one or more user extensions. DEFAULT VALUE: - The default value is 0. + This is not defined by default. DESCRIPTION: - ``CONFIGURE_MAXIMUM_TIMERS`` is the maximum number of Classic API Timers - that can be concurrently active. + 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: - This object class can be configured in unlimited allocation mode. + None. -.. index:: CONFIGURE_MAXIMUM_SEMAPHORES +.. index:: CONFIGURE_INTERRUPT_STACK_SIZE +.. index:: interrupt stack size -.. _CONFIGURE_MAXIMUM_SEMAPHORES: +.. _CONFIGURE_INTERRUPT_STACK_SIZE: -CONFIGURE_MAXIMUM_SEMAPHORES ----------------------------- +CONFIGURE_INTERRUPT_STACK_SIZE +------------------------------ CONSTANT: - ``CONFIGURE_MAXIMUM_SEMAPHORES`` + ``CONFIGURE_INTERRUPT_STACK_SIZE`` DATA TYPE: - Unsigned integer (``uint32_t``). + Unsigned integer. RANGE: - Zero or positive. + Positive. DEFAULT VALUE: - The default value is 0. + The default value is ``BSP_INTERRUPT_STACK_SIZE`` in case it is defined, + otherwise the default value is ``CPU_STACK_MINIMUM_SIZE``. DESCRIPTION: - ``CONFIGURE_MAXIMUM_SEMAPHORES`` is the maximum number of Classic API - Semaphores that can be concurrently active. + The ``CONFIGURE_INTERRUPT_STACK_SIZE`` configuration option defines the + size of an interrupt stack in bytes. NOTES: - This object class can be configured in unlimited allocation mode. + The interrupt stack size must be aligned according to + ``CPU_INTERRUPT_STACK_ALIGNMENT``. -.. index:: CONFIGURE_MAXIMUM_MRSP_SEMAPHORES + 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. -.. _CONFIGURE_MAXIMUM_MRSP_SEMAPHORES: + Some BSPs use the interrupt stack as the initialization stack which is used + to perform the sequential system initialization before the multithreading + is started. -CONFIGURE_MAXIMUM_MRSP_SEMAPHORES ---------------------------------- + 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_PRIORITY +.. index:: maximum priority +.. index:: number of priority levels + +.. _CONFIGURE_MAXIMUM_PRIORITY: + +CONFIGURE_MAXIMUM_PRIORITY +-------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` + ``CONFIGURE_MAXIMUM_PRIORITY`` DATA TYPE: - Unsigned integer (``uint32_t``). + Unsigned integer (``uint8_t``). RANGE: - Zero or positive. + 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 0. + 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: - ``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` is the maximum number of Classic API - Semaphores using the :ref:`MrsP` that can be concurrently active. + This configuration parameter specified the maximum numeric priority of any + task in the system and one less that the number of priority levels in the + system. + + Reducing the number of priorities in the system reduces the amount of memory + allocated from the RTEMS Workspace. NOTES: - This configuration option is only used in SMP configurations. In - uniprocessor configurations, the :ref:`PriorityCeiling` is used for MrsP - semaphores and thus no extra memory is necessary. + The numerically greatest priority is the logically lowest priority in the + system and will thus be used by the IDLE task. -.. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES + Priority zero (0) is reserved for internal use by RTEMS and is not available + to applications. -.. _CONFIGURE_MAXIMUM_MESSAGE_QUEUES: + With some schedulers, reducing the number of priorities can reduce the + amount of memory used by the scheduler. For example, the Deterministic + Priority Scheduler (DPS) used by default uses three pointers of storage per + priority level. Reducing the number of priorities from 256 levels to + sixteen (16) can reduce memory usage by about three (3) kilobytes. -CONFIGURE_MAXIMUM_MESSAGE_QUEUES --------------------------------- +.. index:: CONFIGURE_MAXIMUM_PROCESSORS + +.. _CONFIGURE_MAXIMUM_PROCESSORS: + +CONFIGURE_MAXIMUM_PROCESSORS +---------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` + ``CONFIGURE_MAXIMUM_PROCESSORS`` DATA TYPE: Unsigned integer (``uint32_t``). RANGE: - Zero or positive. + Positive. DEFAULT VALUE: - The default value is 0. + The default value is 1. DESCRIPTION: - ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` is the maximum number of Classic API - Message Queues that can be concurrently active. + ``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: - This object class can be configured in unlimited allocation mode. + If there are more processors available than configured, the rest will be + ignored. This configuration define is ignored in uniprocessor + configurations. -.. index:: CONFIGURE_MAXIMUM_BARRIERS +.. index:: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE +.. index:: maximum thread name size -.. _CONFIGURE_MAXIMUM_BARRIERS: +.. _CONFIGURE_MAXIMUM_THREAD_NAME_SIZE: -CONFIGURE_MAXIMUM_BARRIERS --------------------------- +CONFIGURE_MAXIMUM_THREAD_NAME_SIZE +---------------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_BARRIERS`` + ``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` DATA TYPE: - Unsigned integer (``uint32_t``). + Unsigned integer (``size_t``). RANGE: - Zero or positive. + No restrictions. DEFAULT VALUE: - The default value is 0. + The default value is 16. This value was chosen for Linux compatibility, + see + `PTHREAD_SETNAME_NP(3) `_. DESCRIPTION: - ``CONFIGURE_MAXIMUM_BARRIERS`` is the maximum number of Classic API - Barriers that can be concurrently active. + This configuration parameter specifies the maximum thread name size + including the terminating `NUL` character. -NOTES: - This object class can be configured in unlimited allocation mode. +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_MAXIMUM_PERIODS +.. index:: CONFIGURE_MICROSECONDS_PER_TICK +.. index:: tick quantum -.. _CONFIGURE_MAXIMUM_PERIODS: +.. _CONFIGURE_MICROSECONDS_PER_TICK: -CONFIGURE_MAXIMUM_PERIODS -------------------------- +CONFIGURE_MICROSECONDS_PER_TICK +------------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_PERIODS`` + ``CONFIGURE_MICROSECONDS_PER_TICK`` DATA TYPE: Unsigned integer (``uint32_t``). RANGE: - Zero or positive. + Positive. DEFAULT VALUE: - The default value is 0. + 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: - ``CONFIGURE_MAXIMUM_PERIODS`` is the maximum number of Classic API Periods - that can be concurrently active. + 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 object class can be configured in unlimited allocation mode. + This configuration parameter has no impact if the Clock Tick Device driver + is not configured. -.. index:: CONFIGURE_MAXIMUM_PARTITIONS + There may be BSP specific limits on the resolution or maximum value of a + clock tick quantum. -.. _CONFIGURE_MAXIMUM_PARTITIONS: +.. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE +.. index:: minimum task stack size -CONFIGURE_MAXIMUM_PARTITIONS ----------------------------- +.. _CONFIGURE_MINIMUM_TASK_STACK_SIZE: + +CONFIGURE_MINIMUM_TASK_STACK_SIZE +--------------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_PARTITIONS`` + ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` DATA TYPE: Unsigned integer (``uint32_t``). RANGE: - Zero or positive. + Positive. DEFAULT VALUE: - The default value is 0. + The default value is architecture-specific. DESCRIPTION: - ``CONFIGURE_MAXIMUM_PARTITIONS`` is the maximum number of Classic API - Partitions that can be concurrently active. + This configuration parameter defines the minimum stack size in bytes for + every user task or thread in the system. NOTES: - This object class can be configured in unlimited allocation mode. + 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 `). -.. index:: CONFIGURE_MAXIMUM_REGIONS + 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. -.. _CONFIGURE_MAXIMUM_REGIONS: + 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. -CONFIGURE_MAXIMUM_REGIONS -------------------------- + 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_MAXIMUM_REGIONS`` + ``CONFIGURE_STACK_CHECKER_ENABLED`` DATA TYPE: - Unsigned integer (``uint32_t``). + Boolean feature macro. RANGE: - Zero or positive. + Defined or undefined. DEFAULT VALUE: - The default value is 0. + This is not defined by default, and thus stack checking is disabled. DESCRIPTION: - ``CONFIGURE_MAXIMUM_REGIONS`` is the maximum number of Classic API Regions - that can be concurrently active. + This configuration parameter is defined when the application wishes to + enable run-time stack bounds checking. NOTES: - None. + In 4.9 and older, this configuration parameter was named ``STACK_CHECKER_ON``. -.. index:: CONFIGURE_MAXIMUM_PORTS + This increases the time required to create tasks as well as adding overhead + to each context switch. -.. _CONFIGURE_MAXIMUM_PORTS: +.. index:: CONFIGURE_TICKS_PER_TIMESLICE +.. index:: ticks per timeslice -CONFIGURE_MAXIMUM_PORTS ------------------------ +.. _CONFIGURE_TICKS_PER_TIMESLICE: + +CONFIGURE_TICKS_PER_TIMESLICE +----------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_PORTS`` + ``CONFIGURE_TICKS_PER_TIMESLICE`` DATA TYPE: Unsigned integer (``uint32_t``). RANGE: - Zero or positive. + Positive. DEFAULT VALUE: - The default value is 0. + The default value is 50. DESCRIPTION: - ``CONFIGURE_MAXIMUM_PORTS`` is the maximum number of Classic API Ports that - can be concurrently active. + This configuration parameter specifies the length of the timeslice quantum + in ticks for each task. NOTES: - This object class can be configured in unlimited allocation mode. + This configuration parameter has no impact if the Clock Tick Device driver + is not configured. -.. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS +.. index:: CONFIGURE_UNIFIED_WORK_AREAS +.. index:: unified work areas +.. index:: separate work areas +.. index:: RTEMS Workspace +.. index:: C Program Heap -.. _CONFIGURE_MAXIMUM_USER_EXTENSIONS: +.. _CONFIGURE_UNIFIED_WORK_AREAS: -CONFIGURE_MAXIMUM_USER_EXTENSIONS ---------------------------------- +CONFIGURE_UNIFIED_WORK_AREAS +---------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` + ``CONFIGURE_UNIFIED_WORK_AREAS`` DATA TYPE: - Unsigned integer (``uint32_t``). + Boolean feature macro. RANGE: - Zero or positive. + Defined or undefined. DEFAULT VALUE: - The default value is 0. + This is not defined by default, which specifies that the C Program Heap and + the RTEMS Workspace will be separate. DESCRIPTION: - ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` is the maximum number of Classic API - User Extensions that can be concurrently active. + When defined, the C Program Heap and the RTEMS Workspace will be one pool + of memory. -NOTES: - This object class can be configured in unlimited allocation mode. + When not defined, there will be separate memory pools for the RTEMS + Workspace and C Program Heap. -Classic API Initialization Tasks Table Configuration -==================================================== +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. -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. + 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. -.. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE +.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY +.. index:: clear C Program Heap +.. index:: clear RTEMS Workspace +.. index:: zero C Program Heap +.. index:: zero RTEMS Workspace -.. _CONFIGURE_RTEMS_INIT_TASKS_TABLE: +.. _CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY: -CONFIGURE_RTEMS_INIT_TASKS_TABLE --------------------------------- +CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY +-------------------------------------- CONSTANT: - ``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` + ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` DATA TYPE: Boolean feature macro. @@ -812,259 +907,261 @@ RANGE: Defined or undefined. DEFAULT VALUE: - This is not defined by default. + This is not defined by default, unless overridden by the BSP. The default + is *NOT* to zero out the RTEMS Workspace or C Program Heap. DESCRIPTION: - ``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. + 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: - The application may choose to use the initialization tasks or threads table - from another API. + Zeroing memory can add significantly to system boot time. It is not + necessary for RTEMS but is often assumed by support libraries. - A compile time error will be generated if the user does not configure any - initialization tasks or threads. +Classic API Configuration +========================= -.. index:: CONFIGURE_INIT_TASK_ENTRY_POINT +This section defines the Classic API related system configuration parameters +supported by ````. -.. _CONFIGURE_INIT_TASK_ENTRY_POINT: +.. index:: CONFIGURE_MAXIMUM_TASKS -CONFIGURE_INIT_TASK_ENTRY_POINT -------------------------------- +.. _CONFIGURE_MAXIMUM_TASKS: + +CONFIGURE_MAXIMUM_TASKS +----------------------- CONSTANT: - ``CONFIGURE_INIT_TASK_ENTRY_POINT`` + ``CONFIGURE_MAXIMUM_TASKS`` DATA TYPE: - Task entry function pointer (``rtems_task_entry``). + Unsigned integer (``uint32_t``). RANGE: - Valid task entry function pointer. + Zero or positive. DEFAULT VALUE: - The default value is ``Init``. + The default value is ``0``. 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. + ``CONFIGURE_MAXIMUM_TASKS`` is the maximum number of Classic API Tasks that + can be concurrently active. NOTES: - The user must implement the function ``Init`` or the function name provided - in this configuration parameter. + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_INIT_TASK_NAME + 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``. -.. _CONFIGURE_INIT_TASK_NAME: + The maximum number of POSIX threads is specified by + :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS `. -CONFIGURE_INIT_TASK_NAME + A future enhancement to ```` could be to eliminate the + assumption that all tasks have floating point enabled. This would require + the addition of a new configuration parameter to specify the number of + tasks which enable floating point support. + +.. COMMENT: XXX - Add xref to CONFIGURE_MAXIMUM_POSIX_THREADS. + +.. index:: CONFIGURE_MAXIMUM_TIMERS + +.. _CONFIGURE_MAXIMUM_TIMERS: + +CONFIGURE_MAXIMUM_TIMERS ------------------------ CONSTANT: - ``CONFIGURE_INIT_TASK_NAME`` + ``CONFIGURE_MAXIMUM_TIMERS`` DATA TYPE: - RTEMS Name (``rtems_name``). + Unsigned integer (``uint32_t``). RANGE: - Any value. + Zero or positive. DEFAULT VALUE: - The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. + The default value is 0. DESCRIPTION: - ``CONFIGURE_INIT_TASK_NAME`` is the name of the single initialization task - defined by the Classic API Initialization Tasks Table. + ``CONFIGURE_MAXIMUM_TIMERS`` is the maximum number of Classic API Timers + that can be concurrently active. NOTES: - None. + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_INIT_TASK_STACK_SIZE +.. index:: CONFIGURE_MAXIMUM_SEMAPHORES -.. _CONFIGURE_INIT_TASK_STACK_SIZE: +.. _CONFIGURE_MAXIMUM_SEMAPHORES: -CONFIGURE_INIT_TASK_STACK_SIZE ------------------------------- +CONFIGURE_MAXIMUM_SEMAPHORES +---------------------------- CONSTANT: - ``CONFIGURE_INIT_TASK_STACK_SIZE`` + ``CONFIGURE_MAXIMUM_SEMAPHORES`` DATA TYPE: - Unsigned integer (``size_t``). + Unsigned integer (``uint32_t``). RANGE: Zero or positive. DEFAULT VALUE: - The default value is RTEMS_MINIMUM_STACK_SIZE. + The default value is 0. DESCRIPTION: - ``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single - initialization task defined by the Classic API Initialization Tasks Table. + ``CONFIGURE_MAXIMUM_SEMAPHORES`` is the maximum number of Classic API + Semaphores that can be concurrently active. 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``. + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_INIT_TASK_PRIORITY +.. index:: CONFIGURE_MAXIMUM_MRSP_SEMAPHORES -.. _CONFIGURE_INIT_TASK_PRIORITY: +.. _CONFIGURE_MAXIMUM_MRSP_SEMAPHORES: -CONFIGURE_INIT_TASK_PRIORITY ----------------------------- +CONFIGURE_MAXIMUM_MRSP_SEMAPHORES +--------------------------------- CONSTANT: - ``CONFIGURE_INIT_TASK_PRIORITY`` + ``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` DATA TYPE: - RTEMS Task Priority (``rtems_task_priority``). + Unsigned integer (``uint32_t``). RANGE: - One (1) to CONFIGURE_MAXIMUM_PRIORITY. + Zero or positive. DEFAULT VALUE: - The default value is 1, which is the highest priority in the Classic API. + The default value is 0. DESCRIPTION: - ``CONFIGURE_INIT_TASK_PRIORITY`` is the initial priority of the single - initialization task defined by the Classic API Initialization Tasks Table. + ``CONFIGURE_MAXIMUM_MRSP_SEMAPHORES`` is the maximum number of Classic API + Semaphores using the :ref:`MrsP` that can be concurrently active. NOTES: - None. - + This configuration option is only used in SMP configurations. In + uniprocessor configurations, the :ref:`PriorityCeiling` is used for MrsP + semaphores and thus no extra memory is necessary. -.. index:: CONFIGURE_INIT_TASK_ATTRIBUTES +.. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES -.. _CONFIGURE_INIT_TASK_ATTRIBUTES: +.. _CONFIGURE_MAXIMUM_MESSAGE_QUEUES: -CONFIGURE_INIT_TASK_ATTRIBUTES ------------------------------- +CONFIGURE_MAXIMUM_MESSAGE_QUEUES +-------------------------------- CONSTANT: - ``CONFIGURE_INIT_TASK_ATTRIBUTES`` + ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` DATA TYPE: - RTEMS Attributes (``rtems_attribute``). + Unsigned integer (``uint32_t``). RANGE: - Valid task attribute sets. + Zero or positive. DEFAULT VALUE: - The default value is ``RTEMS_DEFAULT_ATTRIBUTES``. + The default value is 0. DESCRIPTION: - ``CONFIGURE_INIT_TASK_ATTRIBUTES`` is the task attributes of the single - initialization task defined by the Classic API Initialization Tasks Table. + ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` is the maximum number of Classic API + Message Queues that can be concurrently active. NOTES: - None. + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_INIT_TASK_INITIAL_MODES +.. index:: CONFIGURE_MAXIMUM_BARRIERS -.. _CONFIGURE_INIT_TASK_INITIAL_MODES: +.. _CONFIGURE_MAXIMUM_BARRIERS: -CONFIGURE_INIT_TASK_INITIAL_MODES ---------------------------------- +CONFIGURE_MAXIMUM_BARRIERS +-------------------------- CONSTANT: - ``CONFIGURE_INIT_TASK_INITIAL_MODES`` + ``CONFIGURE_MAXIMUM_BARRIERS`` DATA TYPE: - RTEMS Mode (``rtems_mode``). + Unsigned integer (``uint32_t``). RANGE: - Valid task mode sets. + Zero or positive. DEFAULT VALUE: - The default value is ``RTEMS_NO_PREEMPT``. + The default value is 0. DESCRIPTION: - ``CONFIGURE_INIT_TASK_INITIAL_MODES`` is the initial execution mode of the - single initialization task defined by the Classic API Initialization Tasks - Table. + ``CONFIGURE_MAXIMUM_BARRIERS`` is the maximum number of Classic API + Barriers that can be concurrently active. NOTES: - None. + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_INIT_TASK_ARGUMENTS +.. index:: CONFIGURE_MAXIMUM_PERIODS -.. _CONFIGURE_INIT_TASK_ARGUMENTS: +.. _CONFIGURE_MAXIMUM_PERIODS: -CONFIGURE_INIT_TASK_ARGUMENTS ------------------------------ +CONFIGURE_MAXIMUM_PERIODS +------------------------- CONSTANT: - ``CONFIGURE_INIT_TASK_ARGUMENTS`` + ``CONFIGURE_MAXIMUM_PERIODS`` DATA TYPE: - RTEMS Task Argument (``rtems_task_argument``). + Unsigned integer (``uint32_t``). RANGE: - Complete range of the type. + Zero or positive. 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. + ``CONFIGURE_MAXIMUM_PERIODS`` is the maximum number of Classic API Periods + that can be concurrently active. NOTES: - None. + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_HAS_OWN_INIT_TASK_TABLE +.. index:: CONFIGURE_MAXIMUM_PARTITIONS -.. _CONFIGURE_HAS_OWN_INIT_TASK_TABLE: +.. _CONFIGURE_MAXIMUM_PARTITIONS: -CONFIGURE_HAS_OWN_INIT_TASK_TABLE ---------------------------------- +CONFIGURE_MAXIMUM_PARTITIONS +---------------------------- CONSTANT: - ``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` + ``CONFIGURE_MAXIMUM_PARTITIONS`` DATA TYPE: - Boolean feature macro. + Unsigned integer (``uint32_t``). RANGE: - Defined or undefined. + Zero or positive. DEFAULT VALUE: - This is not defined by default. + The default value is 0. DESCRIPTION: - ``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` is defined if the user wishes to - define their own Classic API Initialization Tasks Table. This table should - be named ``Initialization_tasks``. + ``CONFIGURE_MAXIMUM_PARTITIONS`` is the maximum number of Classic API + Partitions that can be concurrently active. NOTES: - This is a seldom used configuration parameter. The most likely use case is - when an application desires to have more than one initialization task. - -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. + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_MAXIMUM_POSIX_KEYS +.. index:: CONFIGURE_MAXIMUM_REGIONS -.. _CONFIGURE_MAXIMUM_POSIX_KEYS: +.. _CONFIGURE_MAXIMUM_REGIONS: -CONFIGURE_MAXIMUM_POSIX_KEYS ----------------------------- +CONFIGURE_MAXIMUM_REGIONS +------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_KEYS`` + ``CONFIGURE_MAXIMUM_REGIONS`` DATA TYPE: Unsigned integer (``uint32_t``). @@ -1076,21 +1173,21 @@ DEFAULT VALUE: The default value is 0. DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX API Keys + ``CONFIGURE_MAXIMUM_REGIONS`` is the maximum number of Classic API Regions that can be concurrently active. NOTES: - This object class can be configured in unlimited allocation mode. + None. -.. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS +.. index:: CONFIGURE_MAXIMUM_PORTS -.. _CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS +.. _CONFIGURE_MAXIMUM_PORTS: -CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS ---------------------------------------- +CONFIGURE_MAXIMUM_PORTS +----------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` + ``CONFIGURE_MAXIMUM_PORTS`` DATA TYPE: Unsigned integer (``uint32_t``). @@ -1099,30 +1196,24 @@ RANGE: Zero or positive. DEFAULT VALUE: - The default value is - :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS ` * - :ref:`CONFIGURE_MAXIMUM_TASKS ` + - :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS `. + The default value is 0. 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. + ``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. - 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 +.. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS -.. _CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES: +.. _CONFIGURE_MAXIMUM_USER_EXTENSIONS: -CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES --------------------------------------- +CONFIGURE_MAXIMUM_USER_EXTENSIONS +--------------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` + ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` DATA TYPE: Unsigned integer (``uint32_t``). @@ -1134,279 +1225,253 @@ 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. + ``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. -.. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS +Classic API Initialization Tasks Table Configuration +==================================================== -.. _CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS: +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. -CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS --------------------------------------- +.. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE + +.. _CONFIGURE_RTEMS_INIT_TASKS_TABLE: + +CONFIGURE_RTEMS_INIT_TASKS_TABLE +-------------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` + ``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` DATA TYPE: - Unsigned integer (``uint32_t``). + Boolean feature macro. RANGE: - Zero or positive. + Defined or undefined. DEFAULT VALUE: - The default value is 0. + This is not defined by default. DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` is the maximum number of POSIX - API Queued Signals that can be concurrently active. + ``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: - Unlimited objects are not available for queued signals. + The application may choose to use the initialization tasks or threads table + from another API. - Queued signals are only available if RTEMS was built with the - ``--enable-posix`` build configuration option. + A compile time error will be generated if the user does not configure any + initialization tasks or threads. -.. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES +.. index:: CONFIGURE_INIT_TASK_ENTRY_POINT -.. _CONFIGURE_MAXIMUM_POSIX_SEMAPHORES: +.. _CONFIGURE_INIT_TASK_ENTRY_POINT: -CONFIGURE_MAXIMUM_POSIX_SEMAPHORES ----------------------------------- +CONFIGURE_INIT_TASK_ENTRY_POINT +------------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` + ``CONFIGURE_INIT_TASK_ENTRY_POINT`` DATA TYPE: - Unsigned integer (``uint32_t``). + Task entry function pointer (``rtems_task_entry``). RANGE: - Zero or positive. + Valid task entry function pointer. DEFAULT VALUE: - The default value is 0. + The default value is ``Init``. DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` is the maximum number of POSIX API - Named Semaphores that can be concurrently active. + ``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: - 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. + The user must implement the function ``Init`` or the function name provided + in this configuration parameter. -.. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS +.. index:: CONFIGURE_INIT_TASK_NAME -.. _CONFIGURE_MAXIMUM_POSIX_TIMERS: +.. _CONFIGURE_INIT_TASK_NAME: -CONFIGURE_MAXIMUM_POSIX_TIMERS ------------------------------- +CONFIGURE_INIT_TASK_NAME +------------------------ CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` + ``CONFIGURE_INIT_TASK_NAME`` DATA TYPE: - Unsigned integer (``uint32_t``). + RTEMS Name (``rtems_name``). RANGE: - Zero or positive. + Any value. DEFAULT VALUE: - The default value is 0. + The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` is the maximum number of POSIX API - Timers that can be concurrently active. + ``CONFIGURE_INIT_TASK_NAME`` is the name of the single initialization task + defined by the Classic API Initialization Tasks Table. 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. + None. -.. index:: CONFIGURE_MAXIMUM_POSIX_THREADS +.. index:: CONFIGURE_INIT_TASK_STACK_SIZE -.. _CONFIGURE_MAXIMUM_POSIX_THREADS: +.. _CONFIGURE_INIT_TASK_STACK_SIZE: -CONFIGURE_MAXIMUM_POSIX_THREADS -------------------------------- +CONFIGURE_INIT_TASK_STACK_SIZE +------------------------------ CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_THREADS`` + ``CONFIGURE_INIT_TASK_STACK_SIZE`` DATA TYPE: - Unsigned integer (``uint32_t``). + Unsigned integer (``size_t``). RANGE: Zero or positive. DEFAULT VALUE: - The default value is 0. + The default value is RTEMS_MINIMUM_STACK_SIZE. DESCRIPTION: - ``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API - Threads that can be concurrently active. + ``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single + initialization task defined by the Classic API Initialization Tasks Table. 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 + 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``. - 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 +.. index:: CONFIGURE_INIT_TASK_PRIORITY -.. _CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE: +.. _CONFIGURE_INIT_TASK_PRIORITY: -CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE ------------------------------------------ +CONFIGURE_INIT_TASK_PRIORITY +---------------------------- CONSTANT: - ``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` + ``CONFIGURE_INIT_TASK_PRIORITY`` DATA TYPE: - Unsigned integer (``size_t``). + RTEMS Task Priority (``rtems_task_priority``). RANGE: - Positive. + One (1) to CONFIGURE_MAXIMUM_PRIORITY. DEFAULT VALUE: - The default value is two times the value of - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE `. + The default value is 1, which is the highest priority in the Classic API. DESCRIPTION: - This configuration parameter defines the minimum stack size in bytes for - every POSIX thread in the system. + ``CONFIGURE_INIT_TASK_PRIORITY`` is the initial priority of the single + initialization task defined by the Classic API Initialization Tasks Table. NOTES: None. -POSIX Initialization Threads Table Configuration -================================================ - -The ```` configuration system can automatically generate a -POSIX Initialization Threads Table named ``POSIX_Initialization_threads`` with -a single entry. The following parameters control the generation of that table. -.. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE +.. index:: CONFIGURE_INIT_TASK_ATTRIBUTES -.. _CONFIGURE_POSIX_INIT_THREAD_TABLE: +.. _CONFIGURE_INIT_TASK_ATTRIBUTES: -CONFIGURE_POSIX_INIT_THREAD_TABLE ---------------------------------- +CONFIGURE_INIT_TASK_ATTRIBUTES +------------------------------ CONSTANT: - - ``CONFIGURE_POSIX_INIT_THREAD_TABLE`` + ``CONFIGURE_INIT_TASK_ATTRIBUTES`` DATA TYPE: - Boolean feature macro. + RTEMS Attributes (``rtems_attribute``). RANGE: - Defined or undefined. - -DEFAULT VALUE: - This field is not defined by default, as the user MUST select their own API - for initialization tasks. + Valid task attribute sets. -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. +DEFAULT VALUE: + The default value is ``RTEMS_DEFAULT_ATTRIBUTES``. - By default, this field is not defined as the user MUST select their own API - for initialization tasks. +DESCRIPTION: + ``CONFIGURE_INIT_TASK_ATTRIBUTES`` is the task attributes of the single + initialization task defined by the Classic API Initialization Tasks Table. 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. + None. -.. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT +.. index:: CONFIGURE_INIT_TASK_INITIAL_MODES -.. _CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT: +.. _CONFIGURE_INIT_TASK_INITIAL_MODES: -CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT ---------------------------------------- +CONFIGURE_INIT_TASK_INITIAL_MODES +--------------------------------- CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` + ``CONFIGURE_INIT_TASK_INITIAL_MODES`` DATA TYPE: - POSIX thread function pointer (``void *(*entry_point)(void *)``). + RTEMS Mode (``rtems_mode``). RANGE: - Undefined or a valid POSIX thread function pointer. + Valid task mode sets. DEFAULT VALUE: - The default value is ``POSIX_Init``. + The default value is ``RTEMS_NO_PREEMPT``. 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. + ``CONFIGURE_INIT_TASK_INITIAL_MODES`` is the initial execution mode of the + single initialization task defined by the Classic API Initialization Tasks + Table. NOTES: - The user must implement the function ``POSIX_Init`` or the function name - provided in this configuration parameter. + None. -.. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE +.. index:: CONFIGURE_INIT_TASK_ARGUMENTS -.. _CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE: +.. _CONFIGURE_INIT_TASK_ARGUMENTS: -CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE --------------------------------------- +CONFIGURE_INIT_TASK_ARGUMENTS +----------------------------- CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` + ``CONFIGURE_INIT_TASK_ARGUMENTS`` DATA TYPE: - Unsigned integer (``size_t``). + RTEMS Task Argument (``rtems_task_argument``). RANGE: - Zero or positive. + Complete range of the type. DEFAULT VALUE: - The default value is 2 \* RTEMS_MINIMUM_STACK_SIZE. + The default value is 0. DESCRIPTION: - ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the single - initialization thread defined by the POSIX API Initialization Threads - Table. + ``CONFIGURE_INIT_TASK_ARGUMENTS`` is the task argument 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``. + None. -.. index:: CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE +.. index:: CONFIGURE_HAS_OWN_INIT_TASK_TABLE -.. _CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE: +.. _CONFIGURE_HAS_OWN_INIT_TASK_TABLE: -CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE ------------------------------------------ +CONFIGURE_HAS_OWN_INIT_TASK_TABLE +--------------------------------- CONSTANT: - ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` + ``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` DATA TYPE: Boolean feature macro. @@ -1418,456 +1483,391 @@ DEFAULT VALUE: This is not defined by default. DESCRIPTION: - ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` is defined if the user wishes - to define their own POSIX API Initialization Threads Table. This table - should be named ``POSIX_Initialization_threads``. + ``CONFIGURE_HAS_OWN_INIT_TASK_TABLE`` is defined if the user wishes to + define their own Classic API Initialization Tasks Table. This table should + be named ``Initialization_tasks``. NOTES: This is a seldom used configuration parameter. The most likely use case is when an application desires to have more than one initialization task. -Basic System Information -======================== +POSIX API Configuration +======================= -This section defines the general system configuration parameters supported by -````. +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_UNIFIED_WORK_AREAS -.. index:: unified work areas -.. index:: separate work areas -.. index:: RTEMS Workspace -.. index:: C Program Heap +.. index:: CONFIGURE_MAXIMUM_POSIX_KEYS -.. _CONFIGURE_UNIFIED_WORK_AREAS: +.. _CONFIGURE_MAXIMUM_POSIX_KEYS: -CONFIGURE_UNIFIED_WORK_AREAS +CONFIGURE_MAXIMUM_POSIX_KEYS ---------------------------- CONSTANT: - ``CONFIGURE_UNIFIED_WORK_AREAS`` + ``CONFIGURE_MAXIMUM_POSIX_KEYS`` DATA TYPE: - Boolean feature macro. + Unsigned integer (``uint32_t``). RANGE: - Defined or undefined. + Zero or positive. DEFAULT VALUE: - This is not defined by default, which specifies that the C Program Heap and - the RTEMS Workspace will be separate. + The default value is 0. 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. + ``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX API Keys + that can be concurrently active. 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. + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_MAXIMUM_PROCESSORS +.. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS -.. _CONFIGURE_MAXIMUM_PROCESSORS: +.. _CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS -CONFIGURE_MAXIMUM_PROCESSORS ----------------------------- +CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS +--------------------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_PROCESSORS`` + ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` DATA TYPE: Unsigned integer (``uint32_t``). RANGE: - Positive. + Zero or positive. DEFAULT VALUE: - The default value is 1. + The default value is + :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS ` * + :ref:`CONFIGURE_MAXIMUM_TASKS ` + + :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS `. 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. + ``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: - If there are more processors available than configured, the rest will be - ignored. This configuration define is ignored in uniprocessor - configurations. + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_MICROSECONDS_PER_TICK -.. index:: tick quantum + A key value pair is created by :c:func:`pthread_setspecific` if the value + is not :c:macro:`NULL`, otherwise it is deleted. -.. _CONFIGURE_MICROSECONDS_PER_TICK: +.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES -CONFIGURE_MICROSECONDS_PER_TICK -------------------------------- +.. _CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES: + +CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES +-------------------------------------- CONSTANT: - ``CONFIGURE_MICROSECONDS_PER_TICK`` + ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` DATA TYPE: Unsigned integer (``uint32_t``). RANGE: - Positive. + Zero or 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. + The default value is 0. 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. + ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` is the maximum number of POSIX + API Message Queues that can be concurrently active. 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. + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_TICKS_PER_TIMESLICE -.. index:: ticks per timeslice +.. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS -.. _CONFIGURE_TICKS_PER_TIMESLICE: +.. _CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS: -CONFIGURE_TICKS_PER_TIMESLICE ------------------------------ +CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS +-------------------------------------- CONSTANT: - ``CONFIGURE_TICKS_PER_TIMESLICE`` + ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` DATA TYPE: Unsigned integer (``uint32_t``). RANGE: - Positive. + Zero or positive. DEFAULT VALUE: - The default value is 50. + The default value is 0. DESCRIPTION: - This configuration parameter specifies the length of the timeslice quantum - in ticks for each task. + ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` is the maximum number of POSIX + API Queued Signals that can be concurrently active. NOTES: - This configuration parameter has no impact if the Clock Tick Device driver - is not configured. + Unlimited objects are not available for queued signals. -.. index:: CONFIGURE_MAXIMUM_PRIORITY -.. index:: maximum priority -.. index:: number of priority levels + Queued signals are only available if RTEMS was built with the + ``--enable-posix`` build configuration option. -.. _CONFIGURE_MAXIMUM_PRIORITY: +.. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES -CONFIGURE_MAXIMUM_PRIORITY --------------------------- +.. _CONFIGURE_MAXIMUM_POSIX_SEMAPHORES: + +CONFIGURE_MAXIMUM_POSIX_SEMAPHORES +---------------------------------- CONSTANT: - ``CONFIGURE_MAXIMUM_PRIORITY`` + ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` DATA TYPE: - Unsigned integer (``uint8_t``). + Unsigned integer (``uint32_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. + Zero or positive. 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. + The default value is 0. DESCRIPTION: - This configuration parameter specified the maximum numeric priority of any - task in the system and one less that the number of priority levels in the - system. - - Reducing the number of priorities in the system reduces the amount of memory - allocated from the RTEMS Workspace. - -NOTES: - The numerically greatest priority is the logically lowest priority in the - system and will thus be used by the IDLE task. + ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` is the maximum number of POSIX API + Named Semaphores that can be concurrently active. - Priority zero (0) is reserved for internal use by RTEMS and is not available - to applications. +NOTES: + This object class can be configured in unlimited allocation mode. - With some schedulers, reducing the number of priorities can reduce the - amount of memory used by the scheduler. For example, the Deterministic - Priority Scheduler (DPS) used by default uses three pointers of storage per - priority level. Reducing the number of priorities from 256 levels to - sixteen (16) can reduce memory usage by about three (3) kilobytes. + 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_THREAD_NAME_SIZE -.. index:: maximum thread name size +.. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS -.. _CONFIGURE_MAXIMUM_THREAD_NAME_SIZE: +.. _CONFIGURE_MAXIMUM_POSIX_TIMERS: -CONFIGURE_MAXIMUM_THREAD_NAME_SIZE ----------------------------------- +CONFIGURE_MAXIMUM_POSIX_TIMERS +------------------------------ CONSTANT: - ``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` + ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` DATA TYPE: - Unsigned integer (``size_t``). + Unsigned integer (``uint32_t``). RANGE: - No restrictions. + Zero or positive. DEFAULT VALUE: - The default value is 16. This value was chosen for Linux compatibility, - see - `PTHREAD_SETNAME_NP(3) `_. + The default value is 0. DESCRIPTION: - This configuration parameter specifies the maximum thread name size - including the terminating `NUL` character. + ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` is the maximum number of POSIX API + Timers that can be concurrently active. -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. +NOTES: + This object class can be configured in unlimited allocation mode. -.. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE -.. index:: minimum task stack size + Timers are only available if RTEMS was built with the + ``--enable-posix`` build configuration option. -.. _CONFIGURE_MINIMUM_TASK_STACK_SIZE: +.. index:: CONFIGURE_MAXIMUM_POSIX_THREADS -CONFIGURE_MINIMUM_TASK_STACK_SIZE ---------------------------------- +.. _CONFIGURE_MAXIMUM_POSIX_THREADS: + +CONFIGURE_MAXIMUM_POSIX_THREADS +------------------------------- CONSTANT: - ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` + ``CONFIGURE_MAXIMUM_POSIX_THREADS`` DATA TYPE: Unsigned integer (``uint32_t``). RANGE: - Positive. + Zero or positive. DEFAULT VALUE: - The default value is architecture-specific. + The default value is 0. DESCRIPTION: - This configuration parameter defines the minimum stack size in bytes for - every user task or thread in the system. + ``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API + Threads that can be concurrently active. 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 object class can be configured in unlimited allocation mode. - 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. + 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``. - 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. + The maximum number of Classic API Tasks is specified by + :ref:`CONFIGURE_MAXIMUM_TASKS `. - 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 - `. + All POSIX threads have floating point enabled. -.. index:: CONFIGURE_INTERRUPT_STACK_SIZE -.. index:: interrupt stack size +.. index:: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE +.. index:: minimum POSIX thread stack size -.. _CONFIGURE_INTERRUPT_STACK_SIZE: +.. _CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE: -CONFIGURE_INTERRUPT_STACK_SIZE ------------------------------- +CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE +----------------------------------------- CONSTANT: - ``CONFIGURE_INTERRUPT_STACK_SIZE`` + ``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` DATA TYPE: - Unsigned integer. + Unsigned integer (``size_t``). 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``. + The default value is two times the value of + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE `. DESCRIPTION: - The ``CONFIGURE_INTERRUPT_STACK_SIZE`` configuration option defines the - size of an interrupt stack in bytes. + This configuration parameter defines the minimum stack size in bytes for + every POSIX thread in the system. 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. + None. - The interrupt stacks are covered by the :ref:`stack checker - `. However, using a too small interrupt - stack size may still result in undefined behaviour. +POSIX Initialization Threads Table Configuration +================================================ - In releases before RTEMS 5.1 the default value was - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE - ` instead of ``CPU_STACK_MINIMUM_SIZE``. +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_EXTRA_TASK_STACKS -.. index:: memory for task tasks +.. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE -.. _CONFIGURE_EXTRA_TASK_STACKS: +.. _CONFIGURE_POSIX_INIT_THREAD_TABLE: -CONFIGURE_EXTRA_TASK_STACKS ---------------------------- +CONFIGURE_POSIX_INIT_THREAD_TABLE +--------------------------------- CONSTANT: - ``CONFIGURE_EXTRA_TASK_STACKS`` + + ``CONFIGURE_POSIX_INIT_THREAD_TABLE`` DATA TYPE: - Unsigned integer (``size_t``). + Boolean feature macro. RANGE: - Undefined or positive. + Defined or undefined. DEFAULT VALUE: - The default value is 0. + This field is not defined by default, as the user MUST select their own API + for initialization tasks. DESCRIPTION: - This configuration parameter is set to the number of bytes the applications - wishes to add to the task stack requirements calculated by - ````. + ``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: - This parameter is very important. If the application creates tasks with - stacks larger then the minimum, then that memory is NOT accounted for by - ````. + The application may choose to use the initialization tasks or threads table + from another API. -.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY -.. index:: clear C Program Heap -.. index:: clear RTEMS Workspace -.. index:: zero C Program Heap -.. index:: zero RTEMS Workspace + A compile time error will be generated if the user does not configure any + initialization tasks or threads. -.. _CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY: +.. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT -CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY --------------------------------------- +.. _CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT: + +CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT +--------------------------------------- CONSTANT: - ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` + ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` DATA TYPE: - Boolean feature macro. + POSIX thread function pointer (``void *(*entry_point)(void *)``). RANGE: - Defined or undefined. + Undefined or a valid POSIX thread function pointer. DEFAULT VALUE: - This is not defined by default, unless overridden by the BSP. The default - is *NOT* to zero out the RTEMS Workspace or C Program Heap. + The default value is ``POSIX_Init``. 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. + ``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: - Zeroing memory can add significantly to system boot time. It is not - necessary for RTEMS but is often assumed by support libraries. + The user must implement the function ``POSIX_Init`` or the function name + provided in this configuration parameter. -.. index:: CONFIGURE_STACK_CHECKER_ENABLED +.. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE -.. _CONFIGURE_STACK_CHECKER_ENABLED: +.. _CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE: -CONFIGURE_STACK_CHECKER_ENABLED -------------------------------- +CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE +-------------------------------------- CONSTANT: - ``CONFIGURE_STACK_CHECKER_ENABLED`` + ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` DATA TYPE: - Boolean feature macro. + Unsigned integer (``size_t``). RANGE: - Defined or undefined. + Zero or positive. DEFAULT VALUE: - This is not defined by default, and thus stack checking is disabled. + The default value is 2 \* RTEMS_MINIMUM_STACK_SIZE. DESCRIPTION: - This configuration parameter is defined when the application wishes to - enable run-time stack bounds checking. + ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` is the stack size of the single + initialization thread defined by the POSIX API Initialization Threads + Table. 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. + 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_INITIAL_EXTENSIONS +.. index:: CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE -.. _CONFIGURE_INITIAL_EXTENSIONS: +.. _CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE: -CONFIGURE_INITIAL_EXTENSIONS ----------------------------- +CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE +----------------------------------------- CONSTANT: - ``CONFIGURE_INITIAL_EXTENSIONS`` + ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` DATA TYPE: - List of user extension initializers (``rtems_extensions_table``). + Boolean feature macro. RANGE: - Undefined or a list of one or more user extensions. + Defined or undefined. 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. + ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE`` is defined if the user wishes + to define their own POSIX API Initialization Threads Table. This table + should be named ``POSIX_Initialization_threads``. NOTES: - None. + This is a seldom used configuration parameter. The most likely use case is + when an application desires to have more than one initialization task. Configuring Custom Task Stack Allocation ======================================== -- cgit v1.2.3