diff options
| -rw-r--r-- | c-user/config/bdbuf.rst | 509 | ||||
| -rw-r--r-- | c-user/config/bsp-related.rst | 332 | ||||
| -rw-r--r-- | c-user/config/classic-api.rst | 724 | ||||
| -rw-r--r-- | c-user/config/classic-init-task.rst | 391 | ||||
| -rw-r--r-- | c-user/config/device-driver.rst | 868 | ||||
| -rw-r--r-- | c-user/config/event-record.rst | 176 | ||||
| -rw-r--r-- | c-user/config/filesystem.rst | 952 | ||||
| -rw-r--r-- | c-user/config/general.rst | 1187 | ||||
| -rw-r--r-- | c-user/config/idle-task.rst | 159 | ||||
| -rw-r--r-- | c-user/config/mpci.rst | 343 | ||||
| -rw-r--r-- | c-user/config/posix-api.rst | 575 | ||||
| -rw-r--r-- | c-user/config/posix-init-thread.rst | 127 | ||||
| -rw-r--r-- | c-user/config/scheduler-general.rst | 725 | ||||
| -rw-r--r-- | c-user/config/task-stack-alloc.rst | 268 |
14 files changed, 4307 insertions, 3029 deletions
diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst index c5381e1..a897fa9 100644 --- a/c-user/config/bdbuf.rst +++ b/c-user/config/bdbuf.rst @@ -28,6 +28,10 @@ This section describes configuration options related to the Block Device Cache .. Generated from spec:/acfg/if/appl-needs-libblock +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_LIBBLOCK .. _CONFIGURE_APPLICATION_NEEDS_LIBBLOCK: @@ -35,27 +39,36 @@ This section describes configuration options related to the Block Device Cache CONFIGURE_APPLICATION_NEEDS_LIBBLOCK ------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Block Device Cache is - initialized during system initialization. +In case this configuration option is defined, then the Block Device Cache is +initialized during system initialization. -NOTES: - Each option of the Block Device Cache (bdbuf) 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 filesystems. +.. rubric:: NOTES: + +Each option of the Block Device Cache (bdbuf) 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 filesystems. .. Generated from spec:/acfg/if/bdbuf-buffer-max-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_BUFFER_MAX_SIZE .. _CONFIGURE_BDBUF_BUFFER_MAX_SIZE: @@ -63,33 +76,38 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MAX_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MAX_SIZE`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 4096. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 4096. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be an integral multiple of - :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. +The value of this configuration option defines the maximum size of a buffer +in bytes. -DESCRIPTION: - The value of this configuration option defines the maximum size of a buffer - in bytes. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be an integral multiple of + :ref:`CONFIGURE_BDBUF_BUFFER_MIN_SIZE`. .. Generated from spec:/acfg/if/bdbuf-buffer-min-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_BUFFER_MIN_SIZE .. _CONFIGURE_BDBUF_BUFFER_MIN_SIZE: @@ -97,33 +115,38 @@ NOTES: CONFIGURE_BDBUF_BUFFER_MIN_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_BUFFER_MIN_SIZE`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 512. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to zero. +The default value is 512. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the minimum size of a buffer - in bytes. +The value of this configuration option defines the minimum size of a buffer +in bytes. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-cache-memory-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE .. _CONFIGURE_BDBUF_CACHE_MEMORY_SIZE: @@ -131,33 +154,38 @@ NOTES: CONFIGURE_BDBUF_CACHE_MEMORY_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_BDBUF_CACHE_MEMORY_SIZE`` -DEFAULT VALUE: - The default value is 32768. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to zero. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to `SIZE_MAX - <https://en.cppreference.com/w/c/types/limits>`_. +The default value is 32768. -DESCRIPTION: - The value of this configuration option defines the size of the cache memory - in bytes. +.. rubric:: DESCRIPTION: -NOTES: - None. +The value of this configuration option defines the size of the cache memory +in bytes. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. .. Generated from spec:/acfg/if/bdbuf-max-read-ahead-blocks +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS .. _CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS: @@ -165,35 +193,44 @@ NOTES: CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS ------------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum blocks per +read-ahead request. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +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. -DESCRIPTION: - The value of this configuration option defines the maximum blocks per - read-ahead request. +.. rubric:: CONSTRAINTS: -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. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-max-write-blocks +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS .. _CONFIGURE_BDBUF_MAX_WRITE_BLOCKS: @@ -201,33 +238,38 @@ NOTES: CONFIGURE_BDBUF_MAX_WRITE_BLOCKS -------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_MAX_WRITE_BLOCKS`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 16. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to zero. +The default value is 16. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the maximum blocks per write - request. +The value of this configuration option defines the maximum blocks per write +request. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-read-ahead-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY .. _CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY: @@ -235,28 +277,34 @@ NOTES: CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY ---------------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY`` -DEFAULT VALUE: - The default value is 15. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities depends on the scheduler - configuration. +This configuration option is an integer define. -DESCRIPTION: - The value of this configuration option defines the read-ahead task priority. +.. rubric:: DEFAULT VALUE: -NOTES: - None. +The default value is 15. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the read-ahead task priority. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. .. Generated from spec:/acfg/if/bdbuf-task-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BDBUF_TASK_STACK_SIZE .. _CONFIGURE_BDBUF_TASK_STACK_SIZE: @@ -264,39 +312,45 @@ NOTES: CONFIGURE_BDBUF_TASK_STACK_SIZE ------------------------------- -CONSTANT: - ``CONFIGURE_BDBUF_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_BDBUF_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. -DEFAULT VALUE: - The default value is :c:macro:`RTEMS_MINIMUM_STACK_SIZE`. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the task stack size of the +Block Device Cache tasks in bytes. - * It shall be greater than or equal to - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +The following constraints apply to this configuration option: - * It shall be small enough so that the task stack space calculation carried - out by ``<rtems/confdefs.h>`` does not overflow an integer of type - `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -DESCRIPTION: - The value of this configuration option defines the task stack size of the - Block Device Cache tasks in bytes. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -NOTES: - None. +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-swapout-block-hold +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_BLOCK_HOLD .. _CONFIGURE_SWAPOUT_BLOCK_HOLD: @@ -304,33 +358,38 @@ NOTES: CONFIGURE_SWAPOUT_BLOCK_HOLD ---------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_BLOCK_HOLD`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_BLOCK_HOLD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 1000. +The default value is 1000. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to zero. +The value of this configuration option defines the swapout task maximum block +hold time in milliseconds. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the swapout task maximum block - hold time in milliseconds. +The following constraints apply to this configuration option: -NOTES: - None. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-swapout-swap-period +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_SWAP_PERIOD .. _CONFIGURE_SWAPOUT_SWAP_PERIOD: @@ -338,33 +397,38 @@ NOTES: CONFIGURE_SWAPOUT_SWAP_PERIOD ----------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_SWAP_PERIOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_SWAP_PERIOD`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 250. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 250. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the swapout task swap period +in milliseconds. -DESCRIPTION: - The value of this configuration option defines the swapout task swap period - in milliseconds. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-swapout-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_TASK_PRIORITY .. _CONFIGURE_SWAPOUT_TASK_PRIORITY: @@ -372,28 +436,34 @@ NOTES: CONFIGURE_SWAPOUT_TASK_PRIORITY ------------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_TASK_PRIORITY`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 15. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities depends on the scheduler - configuration. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option defines the swapout task priority. +The default value is 15. -NOTES: - None. +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the swapout task priority. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. .. Generated from spec:/acfg/if/bdbuf-swapout-worker-tasks +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_WORKER_TASKS .. _CONFIGURE_SWAPOUT_WORKER_TASKS: @@ -401,32 +471,37 @@ NOTES: CONFIGURE_SWAPOUT_WORKER_TASKS ------------------------------ -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASKS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_SWAPOUT_WORKER_TASKS`` -DEFAULT VALUE: - The default value is 0. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to zero. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +The default value is 0. -DESCRIPTION: - The value of this configuration option defines the swapout worker task count. +.. rubric:: DESCRIPTION: -NOTES: - None. +The value of this configuration option defines the swapout worker task count. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/bdbuf-swapout-worker-taskp-riority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY .. _CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY: @@ -434,23 +509,25 @@ NOTES: CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY -------------------------------------- -CONSTANT: - ``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 15. -DEFAULT VALUE: - The default value is 15. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities depends on the scheduler - configuration. +The value of this configuration option defines the swapout worker task +priority. -DESCRIPTION: - The value of this configuration option defines the swapout worker task - priority. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. diff --git a/c-user/config/bsp-related.rst b/c-user/config/bsp-related.rst index 45f31a8..b13a91d 100644 --- a/c-user/config/bsp-related.rst +++ b/c-user/config/bsp-related.rst @@ -30,6 +30,10 @@ configuration options may have a BSP-specific setting which is defined by .. Generated from spec:/acfg/if/bsp-idle-task-body +.. raw:: latex + + \clearpage + .. index:: BSP_IDLE_TASK_BODY .. _BSP_IDLE_TASK_BODY: @@ -37,36 +41,46 @@ configuration options may have a BSP-specific setting which is defined by BSP_IDLE_TASK_BODY ------------------ -CONSTANT: - ``BSP_IDLE_TASK_BODY`` +.. rubric:: CONSTANT: + +``BSP_IDLE_TASK_BODY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an initializer define. +The default value is BSP-specific. -DEFAULT VALUE: - The default value is BSP-specific. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *idle_body )( uintptr_t )``. +If -DESCRIPTION: - If +* this configuration option is defined by the BSP - * this configuration option is defined by the BSP +* and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, +then the value of this configuration option defines the default value of +:ref:`CONFIGURE_IDLE_TASK_BODY`. - then the value of this configuration option defines the default value of - :ref:`CONFIGURE_IDLE_TASK_BODY`. +.. rubric:: NOTES: -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. +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. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *idle_body )( uintptr_t )``. .. Generated from spec:/acfg/if/bsp-idle-task-stack-size +.. raw:: latex + + \clearpage + .. index:: BSP_IDLE_TASK_STACK_SIZE .. _BSP_IDLE_TASK_STACK_SIZE: @@ -74,41 +88,47 @@ NOTES: BSP_IDLE_TASK_STACK_SIZE ------------------------ -CONSTANT: - ``BSP_IDLE_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``BSP_IDLE_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is BSP-specific. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is BSP-specific. - * It shall be greater than or equal to a BSP-specific and - application-specific minimum value. +.. rubric:: DESCRIPTION: - * It shall be small enough so that the IDLE task stack area calculation - carried out by ``<rtems/confdefs.h>`` does not overflow an integer of - type `size_t <https://en.cppreference.com/w/c/types/size_t>`_. +If -DESCRIPTION: - If +* this configuration option is defined by the BSP - * this configuration option is defined by the BSP +* and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, +then the value of this configuration option defines the default value of +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE`. - then the value of this configuration option defines the default value of - :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE`. +.. rubric:: CONSTRAINTS: -NOTES: - None. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +* The value of the configuration option shall be small enough so that the IDLE + task stack area calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. .. Generated from spec:/acfg/if/bsp-initial-extension +.. raw:: latex + + \clearpage + .. index:: BSP_INITIAL_EXTENSION .. _BSP_INITIAL_EXTENSION: @@ -116,35 +136,45 @@ NOTES: BSP_INITIAL_EXTENSION --------------------- -CONSTANT: - ``BSP_INITIAL_EXTENSION`` +.. rubric:: CONSTANT: + +``BSP_INITIAL_EXTENSION`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an initializer define. +This configuration option is an initializer define. -DEFAULT VALUE: - The default value is BSP-specific. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_extensions_table`. +The default value is BSP-specific. -DESCRIPTION: - If +.. rubric:: DESCRIPTION: - * this configuration option is defined by the BSP +If - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, +* this configuration option is defined by the BSP - then the value of this configuration option is used to initialize the table - of initial user extensions. +* and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, -NOTES: - The value of this configuration option is placed after the entries of all - other initial user extensions. +then the value of this configuration option is used to initialize the table +of initial user extensions. + +.. rubric:: NOTES: + +The value of this configuration option is placed after the entries of all +other initial user extensions. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :c:type:`rtems_extensions_table`. .. Generated from spec:/acfg/if/bsp-interrupt-stack-size +.. raw:: latex + + \clearpage + .. index:: BSP_INTERRUPT_STACK_SIZE .. _BSP_INTERRUPT_STACK_SIZE: @@ -152,44 +182,50 @@ NOTES: BSP_INTERRUPT_STACK_SIZE ------------------------ -CONSTANT: - ``BSP_INTERRUPT_STACK_SIZE`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``BSP_INTERRUPT_STACK_SIZE`` -DEFAULT VALUE: - The default value is BSP-specific. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to a BSP-specific and - application-specific minimum value. +.. rubric:: DEFAULT VALUE: - * It shall be small enough so that the interrupt stack area calculation - carried out by ``<rtems/confdefs.h>`` does not overflow an integer of - type `size_t <https://en.cppreference.com/w/c/types/size_t>`_. +The default value is BSP-specific. - * It shall be aligned according to - :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. +.. rubric:: DESCRIPTION: -DESCRIPTION: - If +If - * this configuration option is defined by the BSP +* this configuration option is defined by the BSP - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, +* and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - then the value of this configuration option defines the default value of - :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. +then the value of this configuration option defines the default value of +:ref:`CONFIGURE_INTERRUPT_STACK_SIZE`. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +* The value of the configuration option shall be small enough so that the + interrupt stack area calculation carried out by ``<rtems/confdefs.h>`` does + not overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. + +* The value of the configuration option shall be aligned according to + :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. .. Generated from spec:/acfg/if/bsp-prerequisite-drivers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_BSP_PREREQUISITE_DRIVERS .. _CONFIGURE_BSP_PREREQUISITE_DRIVERS: @@ -197,36 +233,46 @@ NOTES: CONFIGURE_BSP_PREREQUISITE_DRIVERS ---------------------------------- -CONSTANT: - ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is BSP-specific. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an initializer define. +If -DEFAULT VALUE: - The default value is BSP-specific. +* this configuration option is defined by the BSP -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_extensions_table`. +* and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, -DESCRIPTION: - If +then the value of this configuration option is used to add BSP-provided +prerequisite drivers to the Device Driver Table. - * this configuration option is defined by the BSP +.. rubric:: NOTES: - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, +The value of this configuration option is placed before the entries of all +other initial user extensions (including +:ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`). - then the value of this configuration option is used to add BSP-provided - prerequisite drivers to the Device Driver Table. +.. rubric:: CONSTRAINTS: -NOTES: - The value of this configuration option is placed before the entries of all - other initial user extensions (including - :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`). +The value of the configuration option shall be a list of initializers for +structures of type :c:type:`rtems_extensions_table`. .. Generated from spec:/acfg/if/disable-bsp-settings +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_DISABLE_BSP_SETTINGS .. _CONFIGURE_DISABLE_BSP_SETTINGS: @@ -234,37 +280,42 @@ NOTES: CONFIGURE_DISABLE_BSP_SETTINGS ------------------------------ -CONSTANT: - ``CONFIGURE_DISABLE_BSP_SETTINGS`` +.. rubric:: CONSTANT: + +``CONFIGURE_DISABLE_BSP_SETTINGS`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the following BSP related - configuration options are undefined: +.. rubric:: DEFAULT CONFIGURATION: - * :ref:`BSP_IDLE_TASK_BODY` +If this configuration option is undefined, then the described feature is not +enabled. - * :ref:`BSP_IDLE_TASK_STACK_SIZE` +.. rubric:: DESCRIPTION: - * :ref:`BSP_INITIAL_EXTENSION` +In case this configuration option is defined, then the following BSP related +configuration options are undefined: - * :ref:`BSP_INTERRUPT_STACK_SIZE` +* :ref:`BSP_IDLE_TASK_BODY` - * :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` +* :ref:`BSP_IDLE_TASK_STACK_SIZE` - * :ref:`CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK` +* :ref:`BSP_INITIAL_EXTENSION` -NOTES: - None. +* :ref:`BSP_INTERRUPT_STACK_SIZE` + +* :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` + +* :ref:`CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK` .. Generated from spec:/acfg/if/malloc-bsp-supports-sbrk +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK .. _CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK: @@ -272,28 +323,33 @@ NOTES: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK ---------------------------------- -CONSTANT: - ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` +.. rubric:: CONSTANT: + +``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If -DESCRIPTION: - If +* this configuration option is defined by the BSP - * this configuration option is defined by the BSP +* and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - * and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, +then not all memory is made available to the C Program Heap immediately at +system initialization time. When :c:func:`malloc` or other standard +memory allocation functions are unable to allocate memory, they will call the +BSP supplied :c:func:`sbrk` function to obtain more memory. - then not all memory is made available to the C Program Heap immediately at - system initialization time. When :c:func:`malloc` or other standard - memory allocation functions are unable to allocate memory, they will call the - BSP supplied :c:func:`sbrk` function to obtain more memory. +.. rubric:: NOTES: -NOTES: - This option should not be defined by the application. Only the BSP knows how - it allocates memory to the C Program Heap. +This option should not be defined by the application. Only the BSP knows how +it allocates memory to the C Program Heap. diff --git a/c-user/config/classic-api.rst b/c-user/config/classic-api.rst index 4643572..4981918 100644 --- a/c-user/config/classic-api.rst +++ b/c-user/config/classic-api.rst @@ -27,6 +27,10 @@ This section describes configuration options related to the Classic API. .. Generated from spec:/acfg/if/max-barriers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_BARRIERS .. _CONFIGURE_MAXIMUM_BARRIERS: @@ -34,42 +38,51 @@ This section describes configuration options related to the Classic API. CONFIGURE_MAXIMUM_BARRIERS -------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_BARRIERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_BARRIERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of Classic +API Barriers that can be concurrently active. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: CONSTRAINTS: - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Barriers that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-message-queues +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_MESSAGE_QUEUES .. _CONFIGURE_MAXIMUM_MESSAGE_QUEUES: @@ -77,44 +90,53 @@ NOTES: CONFIGURE_MAXIMUM_MESSAGE_QUEUES -------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_MESSAGE_QUEUES`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 0. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to 65535. +The value of this configuration option defines the maximum number of Classic +API Message Queues that can be concurrently active. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: NOTES: - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. You have to account for the memory used to +store the messages of each message queue, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Message Queues that can be concurrently active. +.. rubric:: CONSTRAINTS: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. You have to account for the memory used to - store the messages of each message queue, see - :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-partitions +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_PARTITIONS .. _CONFIGURE_MAXIMUM_PARTITIONS: @@ -122,42 +144,51 @@ NOTES: CONFIGURE_MAXIMUM_PARTITIONS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PARTITIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PARTITIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the maximum number of Classic +API Partitions that can be concurrently active. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be greater than or equal to zero. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to 65535. +The following constraints apply to this configuration option: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +* The value of the configuration option shall be greater than or equal to zero. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +* The value of the configuration option shall be less than or equal to 65535. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Partitions that can be concurrently active. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-periods +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_PERIODS .. _CONFIGURE_MAXIMUM_PERIODS: @@ -165,42 +196,51 @@ NOTES: CONFIGURE_MAXIMUM_PERIODS ------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PERIODS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PERIODS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of Classic +API Periods that can be concurrently active. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: CONSTRAINTS: - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Periods that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-ports +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_PORTS .. _CONFIGURE_MAXIMUM_PORTS: @@ -208,42 +248,51 @@ NOTES: CONFIGURE_MAXIMUM_PORTS ----------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PORTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PORTS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 0. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to 65535. +The value of this configuration option defines the maximum number of Classic +API Ports that can be concurrently active. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: NOTES: - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Ports that can be concurrently active. +.. rubric:: CONSTRAINTS: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-regions +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_REGIONS .. _CONFIGURE_MAXIMUM_REGIONS: @@ -251,42 +300,51 @@ NOTES: CONFIGURE_MAXIMUM_REGIONS ------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_REGIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_REGIONS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the maximum number of Classic +API Regions that can be concurrently active. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be greater than or equal to zero. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to 65535. +The following constraints apply to this configuration option: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +* The value of the configuration option shall be greater than or equal to zero. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +* The value of the configuration option shall be less than or equal to 65535. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Regions that can be concurrently active. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-semaphores +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_SEMAPHORES .. _CONFIGURE_MAXIMUM_SEMAPHORES: @@ -294,46 +352,55 @@ NOTES: CONFIGURE_MAXIMUM_SEMAPHORES ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_SEMAPHORES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_SEMAPHORES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of Classic +API Semaphore that can be concurrently active. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +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. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Semaphore that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be greater than or equal to zero. - 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. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-tasks +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_TASKS .. _CONFIGURE_MAXIMUM_TASKS: @@ -341,59 +408,69 @@ NOTES: CONFIGURE_MAXIMUM_TASKS ----------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_TASKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_TASKS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 0. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to 65535. +The value of this configuration option defines the maximum number of Classic +API Tasks that can be concurrently active. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: NOTES: - * It shall be small enough so that the task stack space calculation carried - out by ``<rtems/confdefs.h>`` does not overflow an integer of type - `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +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 option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used +to specify task stack requirements *above* the minimum size required. -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Tasks that can be concurrently active. +The maximum number of POSIX threads is specified by +:ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +A future enhancement to ``<rtems/confdefs.h>`` could be to eliminate the +assumption that all tasks have floating point enabled. This would require +the addition of a new configuration parameter to specify the number of +tasks which enable floating point support. - 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 option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used - to specify task stack requirements *above* the minimum size required. +.. rubric:: CONSTRAINTS: - The maximum number of POSIX threads is specified by - :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`. +The following constraints apply to this configuration option: - A future enhancement to ``<rtems/confdefs.h>`` could be to eliminate the - assumption that all tasks have floating point enabled. This would require - the addition of a new configuration parameter to specify the number of - tasks which enable floating point support. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-thread-local-storage-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE .. _CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE: @@ -401,53 +478,62 @@ NOTES: CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE ------------------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +If the value of this configuration option is greater than zero, then it +defines the maximum thread-local storage size, otherwise the thread-local +storage size is defined by the linker depending on the thread-local storage +objects used by the application in the statically-linked executable. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option can be used to reserve space for the dynamic linking +of modules with thread-local storage objects. - * It shall be greater than or equal to zero. +If the thread-local storage size defined by the thread-local storage +objects used by the application in the statically-linked executable is greater +than a non-zero value of this configuration option, then a fatal error will +occur during system initialization. - * It shall be less than or equal to `SIZE_MAX - <https://en.cppreference.com/w/c/types/limits>`_. +Use :c:func:`RTEMS_ALIGN_UP` and +:c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT` to adjust the size to meet the +minimum alignment requirement of a thread-local storage area. - * It shall be an integral multiple of - :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`. +The actual thread-local storage size is determined when the application +executable is linked. The ``rtems-exeinfo`` command line tool included in +the RTEMS Tools can be used to obtain the thread-local storage size and +alignment of an application executable. -DESCRIPTION: - If the value of this configuration option is greater than zero, then it - defines the maximum thread-local storage size, otherwise the thread-local - storage size is defined by the linker depending on the thread-local storage - objects used by the application in the statically-linked executable. +.. rubric:: CONSTRAINTS: -NOTES: - This configuration option can be used to reserve space for the dynamic linking - of modules with thread-local storage objects. +The following constraints apply to this configuration option: - If the thread-local storage size defined by the thread-local storage - objects used by the application in the statically-linked executable is greater - than a non-zero value of this configuration option, then a fatal error will - occur during system initialization. +* The value of the configuration option shall be greater than or equal to zero. - Use :c:func:`RTEMS_ALIGN_UP` and - :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT` to adjust the size to meet the - minimum alignment requirement of a thread-local storage area. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. - The actual thread-local storage size is determined when the application - executable is linked. The ``rtems-exeinfo`` command line tool included in - the RTEMS Tools can be used to obtain the thread-local storage size and - alignment of an application executable. +* The value of the configuration option shall be an integral multiple of + :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`. .. Generated from spec:/acfg/if/max-timers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_TIMERS .. _CONFIGURE_MAXIMUM_TIMERS: @@ -455,42 +541,51 @@ NOTES: CONFIGURE_MAXIMUM_TIMERS ------------------------ -CONSTANT: - ``CONFIGURE_MAXIMUM_TIMERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_TIMERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of Classic +API Timers that can be concurrently active. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: CONSTRAINTS: - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API Timers that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-user-extensions +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_USER_EXTENSIONS .. _CONFIGURE_MAXIMUM_USER_EXTENSIONS: @@ -498,36 +593,45 @@ NOTES: CONFIGURE_MAXIMUM_USER_EXTENSIONS --------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_USER_EXTENSIONS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 0. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to 65535. +The value of this configuration option defines the maximum number of Classic +API User Extensions that can be concurrently active. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of Classic - API User Extensions that can be concurrently active. +This object class cannot be configured in unlimited allocation mode. -NOTES: - This object class cannot be configured in unlimited allocation mode. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/min-tasks-with-user-provided-storage +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE .. _CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE: @@ -535,31 +639,37 @@ NOTES: CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE -------------------------------------------------- -CONSTANT: - ``CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the minimum count of Classic +API Tasks which are constructed by :c:func:`rtems_task_construct`. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +By default, the calculation for the required memory in the RTEMS Workspace +for tasks assumes that all Classic API Tasks are created by +:c:func:`rtems_task_create`. This configuration option can be used to +reduce the required memory for the system-provided task storage areas since +tasks constructed by :c:func:`rtems_task_construct` use a user-provided +task storage area. - * It shall be greater than or equal to zero. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to :ref:`CONFIGURE_MAXIMUM_TASKS`. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the minimum count of Classic - API Tasks which are constructed by :c:func:`rtems_task_construct`. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - By default, the calculation for the required memory in the RTEMS Workspace - for tasks assumes that all Classic API Tasks are created by - :c:func:`rtems_task_create`. This configuration option can be used to - reduce the required memory for the system-provided task storage areas since - tasks constructed by :c:func:`rtems_task_construct` use a user-provided - task storage area. +* The value of the configuration option shall be less than or equal to + :ref:`CONFIGURE_MAXIMUM_TASKS`. diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst index 9c0435b..0cc400d 100644 --- a/c-user/config/classic-init-task.rst +++ b/c-user/config/classic-init-task.rst @@ -28,6 +28,10 @@ initialization task. .. Generated from spec:/acfg/if/init-task-arguments +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_ARGUMENTS .. _CONFIGURE_INIT_TASK_ARGUMENTS: @@ -35,28 +39,34 @@ initialization task. CONFIGURE_INIT_TASK_ARGUMENTS ----------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_ARGUMENTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ARGUMENTS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be convertible to an integer - of type :c:type:`rtems_task_argument`. +The default value is 0. -DESCRIPTION: - The value of this configuration option defines task argument of the Classic - API initialization task. +.. rubric:: DESCRIPTION: -NOTES: - None. +The value of this configuration option defines task argument of the Classic +API initialization task. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be convertible to an integer of +type :c:type:`rtems_task_argument`. .. Generated from spec:/acfg/if/init-task-attributes +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_ATTRIBUTES .. _CONFIGURE_INIT_TASK_ATTRIBUTES: @@ -64,27 +74,33 @@ NOTES: CONFIGURE_INIT_TASK_ATTRIBUTES ------------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_ATTRIBUTES`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_INIT_TASK_ATTRIBUTES`` -DEFAULT VALUE: - The default value is :c:macro:`RTEMS_DEFAULT_ATTRIBUTES`. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid task attribute set. +This configuration option is an integer define. -DESCRIPTION: - The value of this configuration option defines the task attributes of the - Classic API initialization task. +.. rubric:: DEFAULT VALUE: -NOTES: - None. +The default value is :c:macro:`RTEMS_DEFAULT_ATTRIBUTES`. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the task attributes of the +Classic API initialization task. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid task attribute set. .. Generated from spec:/acfg/if/init-task-construct-storage-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE .. _CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE: @@ -92,60 +108,70 @@ NOTES: CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE ------------------------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - This configuration option has no default value. If it is not specified, then - the Classic API initialization task will be created with the stack size - defined by the :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` configuration option. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option has no default value. If it is not specified, then +the Classic API initialization task will be created with the stack size +defined by the :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` configuration option. - * It shall be greater than or equal to - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: DESCRIPTION: - * It shall be defined using :c:func:`RTEMS_TASK_STORAGE_SIZE`. +The value of this configuration option defines the task storage size of the +Classic API initialization task. -DESCRIPTION: - The value of this configuration option defines the task storage size of the - Classic API initialization task. +.. rubric:: NOTES: -NOTES: - If this configuration option is specified, then +If this configuration option is specified, then - * a task storage area of the specified size is statically allocated by - ``<rtems/confdefs.h>`` for the Classic API initialization task, +* a task storage area of the specified size is statically allocated by + ``<rtems/confdefs.h>`` for the Classic API initialization task, - * the Classic API initialization task is constructed by - :c:func:`rtems_task_construct` instead of using - :c:func:`rtems_task_create`, +* the Classic API initialization task is constructed by + :c:func:`rtems_task_construct` instead of using + :c:func:`rtems_task_create`, - * the maximum thread-local storage size defined by - :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` is used for the Classic API - initialization task, +* the maximum thread-local storage size defined by + :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` is used for the Classic API + initialization task, - * the Classic API initialization task should be accounted for in - :ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`, and +* the Classic API initialization task should be accounted for in + :ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE`, and - * the task storage area used for the Classic API initialization task is not - reclaimed by the system if the task is deleted. +* the task storage area used for the Classic API initialization task is not + reclaimed by the system if the task is deleted. - The +The - * :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` and +* :ref:`CONFIGURE_INIT_TASK_STACK_SIZE` and - * ``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` +* ``CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE`` - configuration options are mutually exclusive. +configuration options are mutually exclusive. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be defined using + :c:func:`RTEMS_TASK_STORAGE_SIZE`. .. Generated from spec:/acfg/if/init-task-entrypoint +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_ENTRY_POINT .. _CONFIGURE_INIT_TASK_ENTRY_POINT: @@ -153,29 +179,39 @@ NOTES: CONFIGURE_INIT_TASK_ENTRY_POINT ------------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_ENTRY_POINT`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_ENTRY_POINT`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an initializer define. +This configuration option is an initializer define. -DEFAULT VALUE: - The default value is ``Init``. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *entry_point )( rtems_task_argument )``. +The default value is ``Init``. -DESCRIPTION: - The value of this configuration option initializes the entry point of the - Classic API initialization task. +.. rubric:: DESCRIPTION: -NOTES: - The application shall provide the function referenced by this configuration - option. +The value of this configuration option initializes the entry point of the +Classic API initialization task. + +.. rubric:: NOTES: + +The application shall provide the function referenced by this configuration +option. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *entry_point )( rtems_task_argument )``. .. Generated from spec:/acfg/if/init-task-initial-modes +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_INITIAL_MODES .. _CONFIGURE_INIT_TASK_INITIAL_MODES: @@ -183,28 +219,34 @@ NOTES: CONFIGURE_INIT_TASK_INITIAL_MODES --------------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_INITIAL_MODES`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_INITIAL_MODES`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - In SMP configurations, the default value is :c:macro:`RTEMS_DEFAULT_MODES` - otherwise the default value is :c:macro:`RTEMS_NO_PREEMPT`. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid task mode set. +In SMP configurations, the default value is :c:macro:`RTEMS_DEFAULT_MODES` +otherwise the default value is :c:macro:`RTEMS_NO_PREEMPT`. -DESCRIPTION: - The value of this configuration option defines the initial execution mode of - the Classic API initialization task. +.. rubric:: DESCRIPTION: -NOTES: - None. +The value of this configuration option defines the initial execution mode of +the Classic API initialization task. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid task mode set. .. Generated from spec:/acfg/if/init-task-name +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_NAME .. _CONFIGURE_INIT_TASK_NAME: @@ -212,28 +254,38 @@ NOTES: CONFIGURE_INIT_TASK_NAME ------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_NAME`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_NAME`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. -DEFAULT VALUE: - The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be convertible to an integer - of type :c:type:`rtems_name`. +The value of this configuration option defines the name of the Classic API +initialization task. + +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the name of the Classic API - initialization task. +Use :c:func:`rtems_build_name` to define the task name. -NOTES: - Use :c:func:`rtems_build_name` to define the task name. +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be convertible to an integer of +type :c:type:`rtems_name`. .. Generated from spec:/acfg/if/init-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_PRIORITY .. _CONFIGURE_INIT_TASK_PRIORITY: @@ -241,29 +293,35 @@ NOTES: CONFIGURE_INIT_TASK_PRIORITY ---------------------------- -CONSTANT: - ``CONFIGURE_INIT_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 1. +The default value is 1. -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities depends on the scheduler - configuration. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the initial priority of the - Classic API initialization task. +The value of this configuration option defines the initial priority of the +Classic API initialization task. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. .. Generated from spec:/acfg/if/init-task-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INIT_TASK_STACK_SIZE .. _CONFIGURE_INIT_TASK_STACK_SIZE: @@ -271,41 +329,51 @@ NOTES: CONFIGURE_INIT_TASK_STACK_SIZE ------------------------------ -CONSTANT: - ``CONFIGURE_INIT_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_INIT_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +The value of this configuration option defines the task stack size of the +Classic API initialization task. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: NOTES: - * It shall be greater than or equal to - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +The - * It shall be small enough so that the task stack space calculation carried - out by ``<rtems/confdefs.h>`` does not overflow an integer of type - `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +* ``CONFIGURE_INIT_TASK_STACK_SIZE`` and -DESCRIPTION: - The value of this configuration option defines the task stack size of the - Classic API initialization task. +* :ref:`CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE` -NOTES: - The +configuration options are mutually exclusive. - * ``CONFIGURE_INIT_TASK_STACK_SIZE`` and +.. rubric:: CONSTRAINTS: - * :ref:`CONFIGURE_INIT_TASK_CONSTRUCT_STORAGE_SIZE` +The following constraints apply to this configuration option: - configuration options are mutually exclusive. +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/rtems-init-tasks-table +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE .. _CONFIGURE_RTEMS_INIT_TASKS_TABLE: @@ -313,28 +381,33 @@ NOTES: CONFIGURE_RTEMS_INIT_TASKS_TABLE -------------------------------- -CONSTANT: - ``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` +.. rubric:: CONSTANT: + +``CONFIGURE_RTEMS_INIT_TASKS_TABLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then exactly one Classic API +initialization task is configured. -DESCRIPTION: - In case this configuration option is defined, then exactly one Classic API - initialization task is configured. +.. rubric:: NOTES: -NOTES: - The application shall define exactly one of the following configuration - options +The application shall define exactly one of the following configuration +options - * ``CONFIGURE_RTEMS_INIT_TASKS_TABLE``, +* ``CONFIGURE_RTEMS_INIT_TASKS_TABLE``, - * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or +* :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or - * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` +* :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` - otherwise a compile time error in the configuration file will occur. +otherwise a compile time error in the configuration file will occur. diff --git a/c-user/config/device-driver.rst b/c-user/config/device-driver.rst index 5d1081a..d84da0a 100644 --- a/c-user/config/device-driver.rst +++ b/c-user/config/device-driver.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 .. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -28,6 +28,10 @@ Note that network device drivers are not covered by the following options. .. Generated from spec:/acfg/if/appl-does-not-need-clock-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER .. _CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER: @@ -35,37 +39,46 @@ Note that network device drivers are not covered by the following options. CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER ------------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then a Clock Driver may be - initialized during system initialization. +If this configuration option is undefined, then a Clock Driver may be +initialized during system initialization. -DESCRIPTION: - In case this configuration option is defined, then **no** Clock Driver is - initialized during system initialization. +.. rubric:: DESCRIPTION: -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. +In case this configuration option is defined, then **no** Clock Driver is +initialized during system initialization. - The application shall define exactly one of the following configuration options +.. rubric:: NOTES: - * :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, +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. - * ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER``, or +The application shall define exactly one of the following configuration options - * :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, +* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, - otherwise a compile time error in the configuration file will occur. +* ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER``, or + +* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, + +otherwise a compile time error in the configuration file will occur. .. Generated from spec:/acfg/if/appl-extra-drivers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_EXTRA_DRIVERS .. _CONFIGURE_APPLICATION_EXTRA_DRIVERS: @@ -73,32 +86,42 @@ NOTES: CONFIGURE_APPLICATION_EXTRA_DRIVERS ----------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an initializer define. +``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` -DEFAULT VALUE: - The default value is the empty list. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_driver_address_table`. +This configuration option is an initializer define. -DESCRIPTION: - The value of this configuration option is used to initialize the Device - Driver Table. +.. rubric:: DEFAULT VALUE: -NOTES: - The value of this configuration option is placed after the entries of other - device driver configuration options. +The default value is the empty list. - See :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` for an alternative - placement of application device driver initializers. +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the Device +Driver Table. + +.. rubric:: NOTES: + +The value of this configuration option is placed after the entries of other +device driver configuration options. + +See :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` for an alternative +placement of application device driver initializers. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :c:type:`rtems_driver_address_table`. .. Generated from spec:/acfg/if/appl-needs-ata-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER: @@ -106,28 +129,37 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER -------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the ATA Driver is - initialized during system initialization. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - Most BSPs do not include support for an ATA Driver. +If this configuration option is undefined, then the described feature is not +enabled. - If this option is defined and the BSP does not have this device driver, then - the user will get a link time error for an undefined symbol. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the ATA Driver is +initialized during system initialization. + +.. rubric:: NOTES: + +Most BSPs do not include support for an ATA Driver. + +If this option is defined and the BSP does not have this device driver, then +the user will get a link time error for an undefined symbol. .. Generated from spec:/acfg/if/appl-needs-clock-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER: @@ -135,36 +167,45 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER ---------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the Clock Driver is - initialized during system initialization. +.. rubric:: DESCRIPTION: -NOTES: - The Clock Driver is responsible for providing a regular interrupt - which invokes a clock tick directive. +In case this configuration option is defined, then the Clock Driver is +initialized during system initialization. - The application shall define exactly one of the following configuration options +.. rubric:: NOTES: - * ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, +The Clock Driver is responsible for providing a regular interrupt +which invokes a clock tick directive. - * :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or +The application shall define exactly one of the following configuration options - * :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, +* ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, - otherwise a compile time error in the configuration file will occur. +* :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or + +* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`, + +otherwise a compile time error in the configuration file will occur. .. Generated from spec:/acfg/if/appl-needs-console-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER: @@ -172,40 +213,49 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER ------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Console Driver is - initialized during system initialization. +In case this configuration option is defined, then the Console Driver is +initialized during system initialization. -NOTES: - The Console 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. +.. rubric:: NOTES: - BSPs should be constructed in a manner that allows :c:func:`printk` to work - properly without the need for the Console Driver to be configured. +The Console 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. - The +BSPs should be constructed in a manner that allows :c:func:`printk` to work +properly without the need for the Console Driver to be configured. - * ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, +The - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and +* ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and - configuration options are mutually exclusive. +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` + +configuration options are mutually exclusive. .. Generated from spec:/acfg/if/appl-needs-framebuffer-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER: @@ -213,29 +263,38 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER ----------------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the Frame Buffer Driver is - initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - Most BSPs do not include support for a Frame Buffer Driver. This is - because many boards do not include the required hardware. +.. rubric:: DESCRIPTION: - If this option is defined and the BSP does not have this device driver, then - the user will get a link time error for an undefined symbol. +In case this configuration option is defined, then the Frame Buffer Driver is +initialized during system initialization. + +.. rubric:: NOTES: + +Most BSPs do not include support for a Frame Buffer Driver. This is +because many boards do not include the required hardware. + +If this option is defined and the BSP does not have this device driver, then +the user will get a link time error for an undefined symbol. .. Generated from spec:/acfg/if/appl-needs-ide-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER: @@ -243,28 +302,37 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER -------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the IDE Driver is - initialized during system initialization. +.. rubric:: DESCRIPTION: -NOTES: - Most BSPs do not include support for an IDE Driver. +In case this configuration option is defined, then the IDE Driver is +initialized during system initialization. - If this option is defined and the BSP does not have this device driver, then - the user will get a link time error for an undefined symbol. +.. rubric:: NOTES: + +Most BSPs do not include support for an IDE Driver. + +If this option is defined and the BSP does not have this device driver, then +the user will get a link time error for an undefined symbol. .. Generated from spec:/acfg/if/appl-needs-null-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER .. index:: /dev/null @@ -273,25 +341,34 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER --------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the :file:`/dev/null` - Driver is initialized during system initialization. +This configuration option is a boolean feature define. -NOTES: - This device driver is supported by all BSPs. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the :file:`/dev/null` +Driver is initialized during system initialization. + +.. rubric:: NOTES: + +This device driver is supported by all BSPs. .. Generated from spec:/acfg/if/appl-needs-rtc-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER: @@ -299,29 +376,38 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER -------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the Real-Time Clock Driver - is initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - Most BSPs do not include support for a real-time clock (RTC). This is because - many boards do not include the required hardware. +.. rubric:: DESCRIPTION: - 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. +In case this configuration option is defined, then the Real-Time Clock Driver +is initialized during system initialization. + +.. rubric:: NOTES: + +Most BSPs do not include support for a real-time clock (RTC). 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. .. Generated from spec:/acfg/if/appl-needs-simple-console-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER: @@ -329,44 +415,53 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER ------------------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the Simple Console Driver - is initialized during system initialization. +.. rubric:: DESCRIPTION: -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. +In case this configuration option is defined, then the Simple Console Driver +is initialized during system initialization. - This device driver reads via :c:func:`getchark`. +.. rubric:: NOTES: - This device driver writes via :c:func:`rtems_putc`. +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. - The Termios framework is not used. There is no support to change device - settings, e.g. baud, stop bits, parity, etc. +This device driver reads via :c:func:`getchark`. - The +This device driver writes via :c:func:`rtems_putc`. - * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, +The Termios framework is not used. There is no support to change device +settings, e.g. baud, stop bits, parity, etc. - * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and +The - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, - configuration options are mutually exclusive. +* ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER``, and + +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` + +configuration options are mutually exclusive. .. Generated from spec:/acfg/if/appl-needs-simple-task-console-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER: @@ -374,53 +469,62 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER ------------------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the Simple Task Console +Driver is initialized during system initialization. -DESCRIPTION: - In case this configuration option is defined, then the Simple Task Console - Driver is initialized during system initialization. +.. rubric:: NOTES: -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 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 :c:func:`getchark`. +This device driver reads via :c:func:`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 - :c:func:`rtems_putc`. This task runs with the least important priority. - The write buffer size is 2047 characters and it is not configurable. +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 +:c:func:`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. +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 Termios framework is not used. There is no support to change device +settings, e.g. baud, stop bits, parity, etc. - The +The - * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, +* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER`, and - * ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` +* ``CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER`` - configuration options are mutually exclusive. +configuration options are mutually exclusive. .. Generated from spec:/acfg/if/appl-needs-stub-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER: @@ -428,26 +532,35 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER --------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the Stub Driver is - initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - This device driver simply provides entry points that return successful and - is primarily a test fixture. It is supported by all BSPs. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Stub Driver is +initialized during system initialization. + +.. rubric:: NOTES: + +This device driver simply provides entry points that return successful and +is primarily a test fixture. It is supported by all BSPs. .. Generated from spec:/acfg/if/appl-needs-timer-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER: @@ -455,36 +568,45 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER ---------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the Benchmark Timer Driver is - initialized during system initialization. +In case this configuration option is defined, then the Benchmark Timer Driver is +initialized during system initialization. -NOTES: - The Benchmark Timer Driver is intended for the benchmark tests of the RTEMS - Testsuite. Applications should not use this driver. +.. rubric:: NOTES: - The application shall define exactly one of the following configuration options +The Benchmark Timer Driver is intended for the benchmark tests of the RTEMS +Testsuite. Applications should not use this driver. - * :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, +The application shall define exactly one of the following configuration options - * :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or +* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, - * ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER``, +* :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`, or - otherwise a compile time error will occur. +* ``CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER``, + +otherwise a compile time error will occur. .. Generated from spec:/acfg/if/appl-needs-watchdog-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER .. _CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER: @@ -492,29 +614,38 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER ------------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the Watchdog Driver is - initialized during system initialization. +.. rubric:: DEFAULT CONFIGURATION: -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 configuration option is undefined, then the described feature is not +enabled. - 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. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Watchdog Driver is +initialized during system initialization. + +.. rubric:: 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. .. Generated from spec:/acfg/if/appl-needs-zero-driver +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER .. index:: /dev/zero @@ -523,25 +654,34 @@ NOTES: CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER --------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the :file:`/dev/zero` - Driver is initialized during system initialization. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - This device driver is supported by all BSPs. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the :file:`/dev/zero` +Driver is initialized during system initialization. + +.. rubric:: NOTES: + +This device driver is supported by all BSPs. .. Generated from spec:/acfg/if/appl-prerequisite-drivers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS .. _CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS: @@ -549,33 +689,43 @@ NOTES: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS ------------------------------------------ -CONSTANT: - ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an initializer define. +The default value is the empty list. -DEFAULT VALUE: - The default value is the empty list. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_driver_address_table`. +The value of this configuration option is used to initialize the Device +Driver Table. -DESCRIPTION: - The value of this configuration option is used to initialize the Device - Driver Table. +.. rubric:: NOTES: -NOTES: - The value of this configuration option is placed after the entries defined by - :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver - configuration options. +The value of this configuration option is placed after the entries defined by +:ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver +configuration options. - See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement - of application device driver initializers. +See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement +of application device driver initializers. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :c:type:`rtems_driver_address_table`. .. Generated from spec:/acfg/if/ata-driver-task-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_ATA_DRIVER_TASK_PRIORITY .. _CONFIGURE_ATA_DRIVER_TASK_PRIORITY: @@ -583,29 +733,39 @@ NOTES: CONFIGURE_ATA_DRIVER_TASK_PRIORITY ---------------------------------- -CONSTANT: - ``CONFIGURE_ATA_DRIVER_TASK_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_ATA_DRIVER_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 140. -DEFAULT VALUE: - The default value is 140. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be a valid Classic API task - priority. The set of valid task priorities depends on the scheduler - configuration. +The value of this configuration option defines the ATA task priority. -DESCRIPTION: - The value of this configuration option defines the ATA task priority. +.. rubric:: NOTES: -NOTES: - This configuration option is only evaluated if the configuration option - :ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` is defined. +This configuration option is only evaluated if the configuration option +:ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` is defined. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a valid Classic API task +priority. The set of valid task priorities depends on the scheduler +configuration. .. Generated from spec:/acfg/if/exception-to-signal-mapping +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING .. _CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING: @@ -613,29 +773,38 @@ NOTES: CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING ------------------------------------- -CONSTANT: - ``CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXCEPTION_TO_SIGNAL_MAPPING`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the machine exception to +POSIX signal mapping is configured during system initialization. -DESCRIPTION: - In case this configuration option is defined, then the machine exception to - POSIX signal mapping is configured during system initialization. +.. rubric:: NOTES: -NOTES: - This device driver is responsible for setting up a mapping from machine - exceptions to POSIX signals so that applications may consume them and alter - task execution as necessary. +This device driver is responsible for setting up a mapping from machine +exceptions to POSIX signals so that applications may consume them and alter +task execution as necessary. - This is especially useful for applications written in Ada or C++. +This is especially useful for applications written in Ada or C++. .. Generated from spec:/acfg/if/max-drivers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_DRIVERS .. _CONFIGURE_MAXIMUM_DRIVERS: @@ -643,69 +812,74 @@ NOTES: CONFIGURE_MAXIMUM_DRIVERS ------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_DRIVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_DRIVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +This is computed by default, and is set to the number of statically +configured device drivers configured using the following configuration +options: + +* :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` -OPTION TYPE: - This configuration option is an integer define. +* :ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` -DEFAULT VALUE: - This is computed by default, and is set to the number of statically - configured device drivers configured using the following configuration - options: +* :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER` - * :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` +* :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_ATA_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK` - * :ref:`CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_IDE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK` +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_SIMPLE_TASK_CONSOLE_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER` +* :ref:`CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER` - * :ref:`CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER` +* :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` - * :ref:`CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER` +* :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` - * :ref:`CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER` +.. rubric:: DESCRIPTION: - * :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` +The value of this configuration option defines the number of device drivers. - * :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +If the application will dynamically install device drivers, then the +configuration option value shall be larger than the number of statically +configured device drivers. - * It shall be less than or equal to `SIZE_MAX - <https://en.cppreference.com/w/c/types/limits>`_. +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal than the number of statically - configured device drivers. +The following constraints apply to this configuration option: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. -DESCRIPTION: - The value of this configuration option defines the number of device drivers. +* The value of the configuration option shall be greater than or equal than the + number of statically configured device drivers. -NOTES: - If the application will dynamically install device drivers, then the - configuration option value shall be larger than the number of statically - configured device drivers. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. diff --git a/c-user/config/event-record.rst b/c-user/config/event-record.rst index fa1d011..31a4fa9 100644 --- a/c-user/config/event-record.rst +++ b/c-user/config/event-record.rst @@ -26,6 +26,10 @@ This section describes configuration options related to the event recording. .. Generated from spec:/acfg/if/record-extensions-enabled +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RECORD_EXTENSIONS_ENABLED .. _CONFIGURE_RECORD_EXTENSIONS_ENABLED: @@ -33,31 +37,40 @@ This section describes configuration options related to the event recording. CONFIGURE_RECORD_EXTENSIONS_ENABLED ----------------------------------- -CONSTANT: - ``CONFIGURE_RECORD_EXTENSIONS_ENABLED`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_EXTENSIONS_ENABLED`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case +If this configuration option is undefined, then the described feature is not +enabled. - * this configuration option is defined +.. rubric:: DESCRIPTION: - * and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, +In case - then the event record extensions are enabled. +* this configuration option is defined -NOTES: - The record extensions capture thread create, start, restart, delete, switch, - begin, exitted and terminate events. +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, + +then the event record extensions are enabled. + +.. rubric:: NOTES: + +The record extensions capture thread create, start, restart, delete, switch, +begin, exitted and terminate events. .. Generated from spec:/acfg/if/record-fatal-dump-base64 +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RECORD_FATAL_DUMP_BASE64 .. _CONFIGURE_RECORD_FATAL_DUMP_BASE64: @@ -65,33 +78,42 @@ NOTES: CONFIGURE_RECORD_FATAL_DUMP_BASE64 ---------------------------------- -CONSTANT: - ``CONFIGURE_RECORD_FATAL_DUMP_BASE64`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_FATAL_DUMP_BASE64`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case +.. rubric:: DESCRIPTION: - * this configuration option is defined +In case - * and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, +* this configuration option is defined - * and :ref:`CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB` is undefined, +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, - then the event records are dumped in Base64 encoding in a fatal error - extension (see :ref:`Terminate`). +* and :ref:`CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB` is undefined, -NOTES: - This extension can be used to produce crash dumps. +then the event records are dumped in Base64 encoding in a fatal error +extension (see :ref:`Terminate`). + +.. rubric:: NOTES: + +This extension can be used to produce crash dumps. .. Generated from spec:/acfg/if/record-fatal-dump-base64-zlib +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB .. _CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB: @@ -99,32 +121,41 @@ NOTES: CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB --------------------------------------- -CONSTANT: - ``CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case +.. rubric:: DESCRIPTION: - * this configuration option is defined +In case - * and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, +* this configuration option is defined - then the event records are compressed by zlib and dumped in Base64 encoding - in a fatal error extension (see :ref:`Terminate`). +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, -NOTES: - The zlib compression needs about 512KiB of RAM. This extension can be used - to produce crash dumps. +then the event records are compressed by zlib and dumped in Base64 encoding +in a fatal error extension (see :ref:`Terminate`). + +.. rubric:: NOTES: + +The zlib compression needs about 512KiB of RAM. This extension can be used +to produce crash dumps. .. Generated from spec:/acfg/if/record-per-processor-items +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_RECORD_PER_PROCESSOR_ITEMS .. _CONFIGURE_RECORD_PER_PROCESSOR_ITEMS: @@ -132,35 +163,40 @@ NOTES: CONFIGURE_RECORD_PER_PROCESSOR_ITEMS ------------------------------------ -CONSTANT: - ``CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`` +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the event record item count +per processor. -DEFAULT VALUE: - The default value is 0. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The event record buffers are statically allocated for each configured +processor (:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). If the value of this +configuration option is zero, then nothing is allocated. - * It shall be greater than or equal to 16. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to `SIZE_MAX - <https://en.cppreference.com/w/c/types/limits>`_. +The following constraints apply to this configuration option: - * It shall be a power of two. +* The value of the configuration option shall be greater than or equal to 16. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. -DESCRIPTION: - The value of this configuration option defines the event record item count - per processor. +* The value of the configuration option shall be a power of two. -NOTES: - The event record buffers are statically allocated for each configured - processor (:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). If the value of this - configuration option is zero, then nothing is allocated. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. diff --git a/c-user/config/filesystem.rst b/c-user/config/filesystem.rst index 05ca826..6e053f2 100644 --- a/c-user/config/filesystem.rst +++ b/c-user/config/filesystem.rst @@ -67,6 +67,10 @@ configuration options: .. Generated from spec:/acfg/if/appl-disable-filesystem +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM .. _CONFIGURE_APPLICATION_DISABLE_FILESYSTEM: @@ -74,28 +78,37 @@ configuration options: CONFIGURE_APPLICATION_DISABLE_FILESYSTEM ---------------------------------------- -CONSTANT: - ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` +.. rubric:: CONSTANT: + +``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then a base filesystem and the - configured filesystems are initialized during system initialization. +If this configuration option is undefined, then a base filesystem and the +configured filesystems are initialized during system initialization. -DESCRIPTION: - In case this configuration option is defined, then **no base filesystem** is - initialized during system initialization and **no filesystems** are - configured. +.. rubric:: DESCRIPTION: -NOTES: - Filesystems shall be initialized to support file descriptor based device - drivers and basic input/output functions such as :c:func:`printf`. - Filesystems can be disabled to reduce the memory footprint of an application. +In case this configuration option is defined, then **no base filesystem** is +initialized during system initialization and **no filesystems** are +configured. + +.. rubric:: NOTES: + +Filesystems shall be initialized to support file descriptor based device +drivers and basic input/output functions such as :c:func:`printf`. +Filesystems can be disabled to reduce the memory footprint of an application. .. Generated from spec:/acfg/if/filesystem-all +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_ALL .. _CONFIGURE_FILESYSTEM_ALL: @@ -103,39 +116,44 @@ NOTES: CONFIGURE_FILESYSTEM_ALL ------------------------ -CONSTANT: - ``CONFIGURE_FILESYSTEM_ALL`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_ALL`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the following - configuration options will be defined as well +.. rubric:: DEFAULT CONFIGURATION: - * :ref:`CONFIGURE_FILESYSTEM_DOSFS`, +If this configuration option is undefined, then the described feature is not +enabled. - * :ref:`CONFIGURE_FILESYSTEM_FTPFS`, +.. rubric:: DESCRIPTION: - * :ref:`CONFIGURE_FILESYSTEM_IMFS`, +In case this configuration option is defined, then the following +configuration options will be defined as well - * :ref:`CONFIGURE_FILESYSTEM_JFFS2`, +* :ref:`CONFIGURE_FILESYSTEM_DOSFS`, - * :ref:`CONFIGURE_FILESYSTEM_NFS`, +* :ref:`CONFIGURE_FILESYSTEM_FTPFS`, - * :ref:`CONFIGURE_FILESYSTEM_RFS`, and +* :ref:`CONFIGURE_FILESYSTEM_IMFS`, - * :ref:`CONFIGURE_FILESYSTEM_TFTPFS`. +* :ref:`CONFIGURE_FILESYSTEM_JFFS2`, -NOTES: - None. +* :ref:`CONFIGURE_FILESYSTEM_NFS`, + +* :ref:`CONFIGURE_FILESYSTEM_RFS`, and + +* :ref:`CONFIGURE_FILESYSTEM_TFTPFS`. .. Generated from spec:/acfg/if/filesystem-dosfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_DOSFS .. _CONFIGURE_FILESYSTEM_DOSFS: @@ -143,27 +161,36 @@ NOTES: CONFIGURE_FILESYSTEM_DOSFS -------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_DOSFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_DOSFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the DOS (FAT) filesystem +is registered, so that instances of this filesystem can be mounted by the +application. -DESCRIPTION: - In case this configuration option is defined, then the DOS (FAT) filesystem - is registered, so that instances of this filesystem can be mounted by the - application. +.. rubric:: NOTES: -NOTES: - This filesystem requires a Block Device Cache configuration, see - :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. +This filesystem requires a Block Device Cache configuration, see +:ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. .. Generated from spec:/acfg/if/filesystem-ftpfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_FTPFS .. _CONFIGURE_FILESYSTEM_FTPFS: @@ -171,26 +198,31 @@ NOTES: CONFIGURE_FILESYSTEM_FTPFS -------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_FTPFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_FTPFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the FTP filesystem (FTP - client) is registered, so that instances of this filesystem - can be mounted by the application. +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the FTP filesystem (FTP +client) is registered, so that instances of this filesystem +can be mounted by the application. .. Generated from spec:/acfg/if/filesystem-imfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_IMFS .. _CONFIGURE_FILESYSTEM_IMFS: @@ -198,28 +230,37 @@ NOTES: CONFIGURE_FILESYSTEM_IMFS ------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_IMFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_IMFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the In-Memory Filesystem - (IMFS) is registered, so that instances of this filesystem can be mounted by - the application. +.. rubric:: DESCRIPTION: -NOTES: - Applications will rarely need this configuration option. This configuration - option is intended for test programs. You do not need to define this - configuration option for the base filesystem (also known as root filesystem). +In case this configuration option is defined, then the In-Memory Filesystem +(IMFS) is registered, so that instances of this filesystem can be mounted by +the application. + +.. rubric:: NOTES: + +Applications will rarely need this configuration option. This configuration +option is intended for test programs. You do not need to define this +configuration option for the base filesystem (also known as root filesystem). .. Generated from spec:/acfg/if/filesystem-jffs2 +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_JFFS2 .. _CONFIGURE_FILESYSTEM_JFFS2: @@ -227,26 +268,31 @@ NOTES: CONFIGURE_FILESYSTEM_JFFS2 -------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_JFFS2`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_JFFS2`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the JFFS2 filesystem - is registered, so that instances of this filesystem can be mounted by the - application. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - None. +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the JFFS2 filesystem +is registered, so that instances of this filesystem can be mounted by the +application. .. Generated from spec:/acfg/if/filesystem-nfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_NFS .. _CONFIGURE_FILESYSTEM_NFS: @@ -254,26 +300,31 @@ NOTES: CONFIGURE_FILESYSTEM_NFS ------------------------ -CONSTANT: - ``CONFIGURE_FILESYSTEM_NFS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_FILESYSTEM_NFS`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the Network Filesystem - (NFS) client is registered, so that instances of this filesystem can be - mounted by the application. +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Network Filesystem +(NFS) client is registered, so that instances of this filesystem can be +mounted by the application. .. Generated from spec:/acfg/if/filesystem-rfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_RFS .. _CONFIGURE_FILESYSTEM_RFS: @@ -281,27 +332,36 @@ NOTES: CONFIGURE_FILESYSTEM_RFS ------------------------ -CONSTANT: - ``CONFIGURE_FILESYSTEM_RFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_RFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the RTEMS Filesystem (RFS) +is registered, so that instances of this filesystem can be mounted by the +application. -DESCRIPTION: - In case this configuration option is defined, then the RTEMS Filesystem (RFS) - is registered, so that instances of this filesystem can be mounted by the - application. +.. rubric:: NOTES: -NOTES: - This filesystem requires a Block Device Cache configuration, see - :ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. +This filesystem requires a Block Device Cache configuration, see +:ref:`CONFIGURE_APPLICATION_NEEDS_LIBBLOCK`. .. Generated from spec:/acfg/if/filesystem-tftpfs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_FILESYSTEM_TFTPFS .. _CONFIGURE_FILESYSTEM_TFTPFS: @@ -309,26 +369,31 @@ NOTES: CONFIGURE_FILESYSTEM_TFTPFS --------------------------- -CONSTANT: - ``CONFIGURE_FILESYSTEM_TFTPFS`` +.. rubric:: CONSTANT: + +``CONFIGURE_FILESYSTEM_TFTPFS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the TFTP filesystem (TFTP - client) is registered, so that instances of this filesystem can be mounted by - the application. +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the TFTP filesystem (TFTP +client) is registered, so that instances of this filesystem can be mounted by +the application. .. Generated from spec:/acfg/if/imfs-disable-chmod +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_CHMOD .. _CONFIGURE_IMFS_DISABLE_CHMOD: @@ -336,25 +401,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_CHMOD ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_CHMOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_CHMOD`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - changing the mode of files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support changing the mode of files (no support for :c:func:`chmod`). +If this configuration option is undefined, then the root IMFS supports +changing the mode of files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support changing the mode of files (no support for :c:func:`chmod`). .. Generated from spec:/acfg/if/imfs-disable-chown +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_CHOWN .. _CONFIGURE_IMFS_DISABLE_CHOWN: @@ -362,25 +432,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_CHOWN ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_CHOWN`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_CHOWN`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - changing the ownership of files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support changing the ownership of files (no support for :c:func:`chown`). +If this configuration option is undefined, then the root IMFS supports +changing the ownership of files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support changing the ownership of files (no support for :c:func:`chown`). .. Generated from spec:/acfg/if/imfs-disable-link +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_LINK .. _CONFIGURE_IMFS_DISABLE_LINK: @@ -388,25 +463,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_LINK --------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_LINK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_LINK`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports hard - links. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support hard links (no support for :c:func:`link`). +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - None. +If this configuration option is undefined, then the root IMFS supports hard +links. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support hard links (no support for :c:func:`link`). .. Generated from spec:/acfg/if/imfs-disable-mknod +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_MKNOD .. _CONFIGURE_IMFS_DISABLE_MKNOD: @@ -414,25 +494,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_MKNOD ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MKNOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_MKNOD`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports making - files. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support making files (no support for :c:func:`mknod`). +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - None. +If this configuration option is undefined, then the root IMFS supports making +files. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support making files (no support for :c:func:`mknod`). .. Generated from spec:/acfg/if/imfs-disable-mknod-device +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE .. _CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE: @@ -440,25 +525,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE ----------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_IMFS_DISABLE_MKNOD_DEVICE`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports making - device files. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support making device files. +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports making +device files. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support making device files. .. Generated from spec:/acfg/if/imfs-disable-mknod-file +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_MKNOD_FILE .. _CONFIGURE_IMFS_DISABLE_MKNOD_FILE: @@ -466,25 +556,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_MKNOD_FILE --------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MKNOD_FILE`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_IMFS_DISABLE_MKNOD_FILE`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports making - regular files. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support making regular files. +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports making +regular files. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support making regular files. .. Generated from spec:/acfg/if/imfs-disable-mount +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_MOUNT .. _CONFIGURE_IMFS_DISABLE_MOUNT: @@ -492,26 +587,31 @@ NOTES: CONFIGURE_IMFS_DISABLE_MOUNT ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_MOUNT`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_IMFS_DISABLE_MOUNT`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - mounting other filesystems. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support mounting other filesystems (no support for - :c:func:`mount`). +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +mounting other filesystems. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support mounting other filesystems (no support for +:c:func:`mount`). .. Generated from spec:/acfg/if/imfs-disable-readdir +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_READDIR .. _CONFIGURE_IMFS_DISABLE_READDIR: @@ -519,26 +619,31 @@ NOTES: CONFIGURE_IMFS_DISABLE_READDIR ------------------------------ -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_READDIR`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_IMFS_DISABLE_READDIR`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - reading directories. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support reading directories (no support for :c:func:`readdir`). It is - still possible to open files in a directory. +This configuration option is a boolean feature define. -NOTES: - None. +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the root IMFS supports +reading directories. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support reading directories (no support for :c:func:`readdir`). It is +still possible to open files in a directory. .. Generated from spec:/acfg/if/imfs-disable-readlink +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_READLINK .. _CONFIGURE_IMFS_DISABLE_READLINK: @@ -546,25 +651,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_READLINK ------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_READLINK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_READLINK`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - reading symbolic links. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support reading symbolic links (no support for :c:func:`readlink`). +If this configuration option is undefined, then the root IMFS supports +reading symbolic links. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support reading symbolic links (no support for :c:func:`readlink`). .. Generated from spec:/acfg/if/imfs-disable-rename +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_RENAME .. _CONFIGURE_IMFS_DISABLE_RENAME: @@ -572,25 +682,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_RENAME ----------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_RENAME`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_RENAME`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - renaming files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support renaming files (no support for :c:func:`rename`). +If this configuration option is undefined, then the root IMFS supports +renaming files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support renaming files (no support for :c:func:`rename`). .. Generated from spec:/acfg/if/imfs-disable-rmnod +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_RMNOD .. _CONFIGURE_IMFS_DISABLE_RMNOD: @@ -598,25 +713,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_RMNOD ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_RMNOD`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_RMNOD`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - removing files. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support removing files (no support for :c:func:`rmnod`). +If this configuration option is undefined, then the root IMFS supports +removing files. -NOTES: - None. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the root IMFS does not +support removing files (no support for :c:func:`rmnod`). .. Generated from spec:/acfg/if/imfs-disable-symlink +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_SYMLINK .. _CONFIGURE_IMFS_DISABLE_SYMLINK: @@ -624,25 +744,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_SYMLINK ------------------------------ -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_SYMLINK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_SYMLINK`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - creating symbolic links. +If this configuration option is undefined, then the root IMFS supports +creating symbolic links. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support creating symbolic links (no support for :c:func:`symlink`). +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the root IMFS does not +support creating symbolic links (no support for :c:func:`symlink`). .. Generated from spec:/acfg/if/imfs-disable-unmount +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_UNMOUNT .. _CONFIGURE_IMFS_DISABLE_UNMOUNT: @@ -650,26 +775,31 @@ NOTES: CONFIGURE_IMFS_DISABLE_UNMOUNT ------------------------------ -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_UNMOUNT`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_UNMOUNT`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - unmounting other filesystems. +If this configuration option is undefined, then the root IMFS supports +unmounting other filesystems. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support unmounting other filesystems (no support for - :c:func:`unmount`). +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the root IMFS does not +support unmounting other filesystems (no support for +:c:func:`unmount`). .. Generated from spec:/acfg/if/imfs-disable-utime +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_DISABLE_UTIME .. _CONFIGURE_IMFS_DISABLE_UTIME: @@ -677,25 +807,30 @@ NOTES: CONFIGURE_IMFS_DISABLE_UTIME ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_DISABLE_UTIME`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_DISABLE_UTIME`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS supports - changing file times. +If this configuration option is undefined, then the root IMFS supports +changing file times. -DESCRIPTION: - In case this configuration option is defined, then the root IMFS does not - support changing file times (no support for :c:func:`utime`). +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the root IMFS does not +support changing file times (no support for :c:func:`utime`). .. Generated from spec:/acfg/if/imfs-enable-mkfifo +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_ENABLE_MKFIFO .. _CONFIGURE_IMFS_ENABLE_MKFIFO: @@ -703,25 +838,30 @@ NOTES: CONFIGURE_IMFS_ENABLE_MKFIFO ---------------------------- -CONSTANT: - ``CONFIGURE_IMFS_ENABLE_MKFIFO`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_ENABLE_MKFIFO`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the root IMFS does not - support making FIFOs (no support for :c:func:`mkfifo`). +If this configuration option is undefined, then the root IMFS does not +support making FIFOs (no support for :c:func:`mkfifo`). -DESCRIPTION: - In case this configuration option is defined, then the root IMFS supports - making FIFOs. +.. rubric:: DESCRIPTION: -NOTES: - None. +In case this configuration option is defined, then the root IMFS supports +making FIFOs. .. Generated from spec:/acfg/if/imfs-memfile-bytes-per-block +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK .. _CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK: @@ -729,52 +869,62 @@ NOTES: CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK -------------------------------------- -CONSTANT: - ``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` +.. rubric:: CONSTANT: + +``CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 128. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall be equal to 16, 32, 64, 128, - 256, or 512. +The default value is 128. -DESCRIPTION: - The value of this configuration option defines the block size for in-memory - files managed by the IMFS. +.. rubric:: DESCRIPTION: -NOTES: - 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. +The value of this configuration option defines the block size for in-memory +files managed by the IMFS. - 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: +.. rubric:: NOTES: - * when the block size is 16 bytes, the maximum file size is 1,328 bytes. +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. - * when the block size is 32 bytes, the maximum file size is 18,656 bytes. +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 64 bytes, the maximum file size is 279,488 bytes. +* when the block size is 16 bytes, the maximum file size is 1,328 bytes. - * when the block size is 128 bytes, the maximum file size is 4,329,344 bytes. +* when the block size is 32 bytes, the maximum file size is 18,656 bytes. - * when the block size is 256 bytes, the maximum file size is 68,173,568 bytes. +* when the block size is 64 bytes, the maximum file size is 279,488 bytes. - * when the block size is 512 bytes, the maximum file size is 1,082,195,456 - 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. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be equal to 16, 32, 64, 128, 256, +or 512. .. Generated from spec:/acfg/if/use-devfs-as-base-filesystem +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM .. _CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM: @@ -782,57 +932,66 @@ NOTES: CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM -------------------------------------- -CONSTANT: - ``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` +.. rubric:: CONSTANT: + +``CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then an IMFS with a reduced - feature set will be the base filesystem (also known as root filesystem). +.. rubric:: DESCRIPTION: -NOTES: - In case this configuration option is defined, then the following - configuration options will be defined as well +In case this configuration option is defined, then an IMFS with a reduced +feature set will be the base filesystem (also known as root filesystem). - * :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, +.. rubric:: NOTES: - * :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, +In case this configuration option is defined, then the following +configuration options will be defined as well - * :ref:`CONFIGURE_IMFS_DISABLE_LINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, - * :ref:`CONFIGURE_IMFS_DISABLE_MKNOD_FILE`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, - * :ref:`CONFIGURE_IMFS_DISABLE_MOUNT`, +* :ref:`CONFIGURE_IMFS_DISABLE_LINK`, - * :ref:`CONFIGURE_IMFS_DISABLE_READDIR`, +* :ref:`CONFIGURE_IMFS_DISABLE_MKNOD_FILE`, - * :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_MOUNT`, - * :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, +* :ref:`CONFIGURE_IMFS_DISABLE_READDIR`, - * :ref:`CONFIGURE_IMFS_DISABLE_RMNOD`, +* :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, - * :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, - * :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and +* :ref:`CONFIGURE_IMFS_DISABLE_RMNOD`, - * :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. +* :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, - In addition, a simplified path evaluation is enabled. It allows only a look - up of absolute paths. +* :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and - This configuration of the IMFS is basically a device-only filesystem. It is - comparable in functionality to the pseudo-filesystem name space provided - before RTEMS release 4.5.0. +* :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. + +In addition, a simplified path evaluation is enabled. It allows only a look +up of absolute paths. + +This configuration of the IMFS is basically a device-only filesystem. It is +comparable in functionality to the pseudo-filesystem name space provided +before RTEMS release 4.5.0. .. Generated from spec:/acfg/if/use-miniimfs-as-base-filesystem +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM .. _CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM: @@ -840,36 +999,41 @@ NOTES: CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM ----------------------------------------- -CONSTANT: - ``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM`` +.. rubric:: CONSTANT: + +``CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then an IMFS with a reduced +feature set will be the base filesystem (also known as root filesystem). -DESCRIPTION: - In case this configuration option is defined, then an IMFS with a reduced - feature set will be the base filesystem (also known as root filesystem). +.. rubric:: NOTES: -NOTES: - In case this configuration option is defined, then the following - configuration options will be defined as well +In case this configuration option is defined, then the following +configuration options will be defined as well - * :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHMOD`, - * :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, +* :ref:`CONFIGURE_IMFS_DISABLE_CHOWN`, - * :ref:`CONFIGURE_IMFS_DISABLE_LINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_LINK`, - * :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_READLINK`, - * :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, +* :ref:`CONFIGURE_IMFS_DISABLE_RENAME`, - * :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, +* :ref:`CONFIGURE_IMFS_DISABLE_SYMLINK`, - * :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and +* :ref:`CONFIGURE_IMFS_DISABLE_UTIME`, and - * :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. +* :ref:`CONFIGURE_IMFS_DISABLE_UNMOUNT`. diff --git a/c-user/config/general.rst b/c-user/config/general.rst index 1a43b03..a1f242a 100644 --- a/c-user/config/general.rst +++ b/c-user/config/general.rst @@ -27,6 +27,10 @@ This section describes general system configuration options. .. Generated from spec:/acfg/if/dirty-memory +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_DIRTY_MEMORY .. _CONFIGURE_DIRTY_MEMORY: @@ -34,32 +38,41 @@ This section describes general system configuration options. CONFIGURE_DIRTY_MEMORY ---------------------- -CONSTANT: - ``CONFIGURE_DIRTY_MEMORY`` +.. rubric:: CONSTANT: + +``CONFIGURE_DIRTY_MEMORY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the memory areas used for - the RTEMS Workspace and the C Program Heap are dirtied with a ``0xCF`` byte - pattern during system initialization. +In case this configuration option is defined, then the memory areas used for +the RTEMS Workspace and the C Program Heap are dirtied with a ``0xCF`` byte +pattern during system initialization. -NOTES: - Dirtying memory can add significantly to system initialization 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. +.. rubric:: NOTES: - See also :ref:`CONFIGURE_MALLOC_DIRTY`. +Dirtying memory can add significantly to system initialization 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. + +See also :ref:`CONFIGURE_MALLOC_DIRTY`. .. Generated from spec:/acfg/if/disable-newlib-reentrancy +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_DISABLE_NEWLIB_REENTRANCY .. _CONFIGURE_DISABLE_NEWLIB_REENTRANCY: @@ -67,28 +80,37 @@ NOTES: CONFIGURE_DISABLE_NEWLIB_REENTRANCY ----------------------------------- -CONSTANT: - ``CONFIGURE_DISABLE_NEWLIB_REENTRANCY`` +.. rubric:: CONSTANT: + +``CONFIGURE_DISABLE_NEWLIB_REENTRANCY`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the Newlib reentrancy - support per thread is disabled and a global reentrancy structure is used. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - You can enable this option to reduce the size of the :term:`TCB`. Use this - option with care, since it can lead to race conditions and undefined system - behaviour. For example, :c:macro:`errno` is no longer a thread-local - variable if this option is enabled. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Newlib reentrancy +support per thread is disabled and a global reentrancy structure is used. + +.. rubric:: NOTES: + +You can enable this option to reduce the size of the :term:`TCB`. Use this +option with care, since it can lead to race conditions and undefined system +behaviour. For example, :c:macro:`errno` is no longer a thread-local +variable if this option is enabled. .. Generated from spec:/acfg/if/executive-ram-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_EXECUTIVE_RAM_SIZE .. _CONFIGURE_EXECUTIVE_RAM_SIZE: @@ -96,40 +118,49 @@ NOTES: CONFIGURE_EXECUTIVE_RAM_SIZE ---------------------------- -CONSTANT: - ``CONFIGURE_EXECUTIVE_RAM_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXECUTIVE_RAM_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +If this configuration option is undefined, then the RTEMS Workspace and task +stack space size is calculated by ``<rtems/confdefs.h>`` based on the values +configuration options. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the RTEMS Workspace size in +bytes. -DEFAULT VALUE: - If this configuration option is undefined, then the RTEMS Workspace and task - stack space size is calculated by ``<rtems/confdefs.h>`` based on the values - configuration options. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This is an advanced configuration option. Use it only if you know exactly +what you are doing. - * It shall be greater than or equal to zero. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to `UINTPTR_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +The following constraints apply to this configuration option: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +* The value of the configuration option shall be greater than or equal to zero. -DESCRIPTION: - The value of this configuration option defines the RTEMS Workspace size in - bytes. +* The value of the configuration option shall be less than or equal to + `UINTPTR_MAX <https://en.cppreference.com/w/c/types/integer>`_. -NOTES: - This is an advanced configuration option. Use it only if you know exactly - what you are doing. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/extra-task-stacks +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_EXTRA_TASK_STACKS .. index:: memory for task tasks @@ -138,37 +169,47 @@ NOTES: CONFIGURE_EXTRA_TASK_STACKS --------------------------- -CONSTANT: - ``CONFIGURE_EXTRA_TASK_STACKS`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXTRA_TASK_STACKS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the number of bytes the +applications wishes to add to the task stack requirements calculated by +``<rtems/confdefs.h>``. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be small enough so that the task stack space calculation carried - out by ``<rtems/confdefs.h>`` does not overflow an integer of type - `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +This parameter is very important. If the application creates tasks with +stacks larger then the minimum, then that memory is **not** accounted for by +``<rtems/confdefs.h>``. -DESCRIPTION: - The value of this configuration option defines the number of bytes the - applications wishes to add to the task stack requirements calculated by - ``<rtems/confdefs.h>``. +.. rubric:: CONSTRAINTS: -NOTES: - This parameter is very important. If the application creates tasks with - stacks larger then the minimum, then that memory is **not** accounted for by - ``<rtems/confdefs.h>``. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/initial-extensions +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INITIAL_EXTENSIONS .. _CONFIGURE_INITIAL_EXTENSIONS: @@ -176,30 +217,40 @@ NOTES: CONFIGURE_INITIAL_EXTENSIONS ---------------------------- -CONSTANT: - ``CONFIGURE_INITIAL_EXTENSIONS`` +.. rubric:: CONSTANT: + +``CONFIGURE_INITIAL_EXTENSIONS`` -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is the empty list. +This configuration option is an initializer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a list of initializers for - structures of type :c:type:`rtems_extensions_table`. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option is used to initialize the table of - initial user extensions. +The default value is the empty list. -NOTES: - The value of this configuration option is placed before the entries of - :ref:`BSP_INITIAL_EXTENSION` and after the entries of all other initial - user extensions. +.. rubric:: DESCRIPTION: + +The value of this configuration option is used to initialize the table of +initial user extensions. + +.. rubric:: NOTES: + +The value of this configuration option is placed before the entries of +:ref:`BSP_INITIAL_EXTENSION` and after the entries of all other initial +user extensions. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a list of initializers for +structures of type :c:type:`rtems_extensions_table`. .. Generated from spec:/acfg/if/interrupt-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INTERRUPT_STACK_SIZE .. index:: interrupt stack size @@ -208,54 +259,64 @@ NOTES: CONFIGURE_INTERRUPT_STACK_SIZE ------------------------------ -CONSTANT: - ``CONFIGURE_INTERRUPT_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_INTERRUPT_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is :ref:`BSP_INTERRUPT_STACK_SIZE` in case it is defined, +otherwise the default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`. -DEFAULT VALUE: - The default value is :ref:`BSP_INTERRUPT_STACK_SIZE` in case it is defined, - otherwise the default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the size of an interrupt stack +in bytes. - * It shall be greater than or equal to a BSP-specific and - application-specific minimum value. +.. rubric:: NOTES: - * It shall be small enough so that the interrupt stack area calculation - carried out by ``<rtems/confdefs.h>`` does not overflow an integer of - type `size_t <https://en.cppreference.com/w/c/types/size_t>`_. +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. - * It shall be aligned according to - :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. +Some BSPs use the interrupt stack as the initialization stack which is used +to perform the sequential system initialization before the multithreading +is started. -DESCRIPTION: - The value of this configuration option defines the size of an interrupt stack - in bytes. +The interrupt stacks are covered by the stack checker, see +:ref:`CONFIGURE_STACK_CHECKER_ENABLED`. However, using a too small interrupt stack +size may still result in undefined behaviour. -NOTES: - 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. +In releases before RTEMS 5.1 the default value was +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of +:c:macro:`CPU_STACK_MINIMUM_SIZE`. - Some BSPs use the interrupt stack as the initialization stack which is used - to perform the sequential system initialization before the multithreading - is started. +.. rubric:: CONSTRAINTS: - The interrupt stacks are covered by the stack checker, see - :ref:`CONFIGURE_STACK_CHECKER_ENABLED`. However, using a too small interrupt stack - size may still result in undefined behaviour. +The following constraints apply to this configuration option: - In releases before RTEMS 5.1 the default value was - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of - :c:macro:`CPU_STACK_MINIMUM_SIZE`. +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. + +* The value of the configuration option shall be small enough so that the + interrupt stack area calculation carried out by ``<rtems/confdefs.h>`` does + not overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. + +* The value of the configuration option shall be aligned according to + :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. .. Generated from spec:/acfg/if/malloc-dirty +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MALLOC_DIRTY .. _CONFIGURE_MALLOC_DIRTY: @@ -263,29 +324,38 @@ NOTES: CONFIGURE_MALLOC_DIRTY ---------------------- -CONSTANT: - ``CONFIGURE_MALLOC_DIRTY`` +.. rubric:: CONSTANT: + +``CONFIGURE_MALLOC_DIRTY`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then each memory area returned - by C Program Heap allocator functions such as :c:func:`malloc` is dirtied - with a ``0xCF`` byte pattern before it is handed over to the application. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - The dirtying performed by this option is carried out for each successful - memory allocation from the C Program Heap in contrast to - :ref:`CONFIGURE_DIRTY_MEMORY` which dirties the memory only once during the - system initialization. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then each memory area returned +by C Program Heap allocator functions such as :c:func:`malloc` is dirtied +with a ``0xCF`` byte pattern before it is handed over to the application. + +.. rubric:: NOTES: + +The dirtying performed by this option is carried out for each successful +memory allocation from the C Program Heap in contrast to +:ref:`CONFIGURE_DIRTY_MEMORY` which dirties the memory only once during the +system initialization. .. Generated from spec:/acfg/if/max-file-descriptors +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS .. index:: maximum file descriptors @@ -294,38 +364,47 @@ NOTES: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` -DEFAULT VALUE: - The default value is 3. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to zero. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to `SIZE_MAX - <https://en.cppreference.com/w/c/types/limits>`_. +The default value is 3. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the maximum number of file - like objects that can be concurrently open. +The value of this configuration option defines the maximum number of file +like objects that can be concurrently open. -NOTES: - The default value of three file descriptors allows RTEMS to support standard - input, output, and error I/O streams on :file:`/dev/console`. +.. rubric:: NOTES: + +The default value of three file descriptors allows RTEMS to support standard +input, output, and error I/O streams on :file:`/dev/console`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/max-processors +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_PROCESSORS .. _CONFIGURE_MAXIMUM_PROCESSORS: @@ -333,40 +412,50 @@ NOTES: CONFIGURE_MAXIMUM_PROCESSORS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PROCESSORS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PROCESSORS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 1. +The default value is 1. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to one. +The value of this configuration option defines 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 task stack and interrupt stack for example. - * It shall be less than or equal to :c:macro:`CPU_MAXIMUM_PROCESSORS`. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines 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 task stack and interrupt stack for example. +If there are more processors available than configured, the rest will be +ignored. -NOTES: - If there are more processors available than configured, the rest will be - ignored. +This configuration option is only evaluated in SMP configurations (e.g. RTEMS +was built with the ``--enable-smp`` build configuration option). In all +other configurations it has no effect. - This configuration option is only evaluated in SMP configurations (e.g. RTEMS - was built with the ``--enable-smp`` build configuration option). In all - other configurations it has no effect. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to one. + +* The value of the configuration option shall be less than or equal to + :c:macro:`CPU_MAXIMUM_PROCESSORS`. .. Generated from spec:/acfg/if/max-thread-name-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE .. index:: maximum thread name size @@ -375,43 +464,52 @@ NOTES: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 16. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the maximum thread name size +including the terminating ``NUL`` character. -DEFAULT VALUE: - The default value is 16. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value was chosen for Linux compatibility, see +`pthread_setname_np() <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_. - * It shall be greater than or equal to zero. +The size of the thread control block is increased by the maximum thread name +size. - * It shall be less than or equal to `SIZE_MAX - <https://en.cppreference.com/w/c/types/limits>`_. +This configuration option is available since RTEMS 5.1. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum thread name size - including the terminating ``NUL`` character. +The following constraints apply to this configuration option: -NOTES: - The default value was chosen for Linux compatibility, see - `pthread_setname_np() <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_. +* The value of the configuration option shall be greater than or equal to zero. - The size of the thread control block is increased by the maximum thread name - size. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. - This configuration option is available since RTEMS 5.1. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/memory-overhead +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MEMORY_OVERHEAD .. _CONFIGURE_MEMORY_OVERHEAD: @@ -419,43 +517,53 @@ NOTES: CONFIGURE_MEMORY_OVERHEAD ------------------------- -CONSTANT: - ``CONFIGURE_MEMORY_OVERHEAD`` +.. rubric:: CONSTANT: + +``CONFIGURE_MEMORY_OVERHEAD`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the number of kilobytes the +application wishes to add to the RTEMS Workspace size calculated by +``<rtems/confdefs.h>``. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +This configuration option should only be used when it is suspected that a bug +in ``<rtems/confdefs.h>`` has resulted in an underestimation. Typically the +memory allocation will be too low when an application does not account for +all message queue buffers or task stacks, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. - * It shall be small enough so that the RTEMS Workspace size calculation - carried out by ``<rtems/confdefs.h>`` does not overflow an integer of - type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the number of kilobytes the - application wishes to add to the RTEMS Workspace size calculated by - ``<rtems/confdefs.h>``. +The following constraints apply to this configuration option: -NOTES: - This configuration option should only be used when it is suspected that a bug - in ``<rtems/confdefs.h>`` has resulted in an underestimation. Typically the - memory allocation will be too low when an application does not account for - all message queue buffers or task stacks, see - :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/message-buffer-memory +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY .. index:: configure message queue buffer memory .. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE @@ -466,82 +574,92 @@ NOTES: CONFIGURE_MESSAGE_BUFFER_MEMORY ------------------------------- -CONSTANT: - ``CONFIGURE_MESSAGE_BUFFER_MEMORY`` - -OPTION TYPE: - This configuration option is an integer define. - -DEFAULT VALUE: - The default value is 0. - -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: - - * It shall be greater than or equal to zero. - - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. - - * It shall be small enough so that the RTEMS Workspace size calculation - carried out by ``<rtems/confdefs.h>`` does not overflow an integer of - type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. - -DESCRIPTION: - The value of this configuration option defines the number of bytes reserved - for message queue buffers in the RTEMS Workspace. - -NOTES: - The configuration options :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and - :ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES` define only how many message - queues can be created by the application. The memory for the message - buffers is configured by this option. For each message queue you have to - reserve some memory for the message buffers. The size depends on the - maximum number of pending messages and the maximum size of the messages of - a message queue. Use the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` macro - to specify the message buffer memory for each message queue and sum them up - to define the value for ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``. - - The interface for the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help - macro is as follows: - - .. code-block:: c - - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( max_messages, max_msg_size ) - - Where ``max_messages`` is the maximum number of pending messages and - ``max_msg_size`` is the maximum size in bytes of the messages of the - corresponding message queue. Both parameters shall be compile time - constants. Not using this help macro (e.g. just using - ``max_messages * max_msg_size``) may result in an underestimate of the - RTEMS Workspace size. - - The following example illustrates how the - ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help macro 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 a - maximum of 24 pending messages with the message structure defined by the - type ``one_message_type``. The other message queue has a 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 ) \ - ) \ - ) +.. rubric:: CONSTANT: + +``CONFIGURE_MESSAGE_BUFFER_MEMORY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the number of bytes reserved +for message queue buffers in the RTEMS Workspace. + +.. rubric:: NOTES: + +The configuration options :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and +:ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES` define only how many message +queues can be created by the application. The memory for the message +buffers is configured by this option. For each message queue you have to +reserve some memory for the message buffers. The size depends on the +maximum number of pending messages and the maximum size of the messages of +a message queue. Use the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` macro +to specify the message buffer memory for each message queue and sum them up +to define the value for ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``. + +The interface for the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help +macro is as follows: + +.. code-block:: c + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( max_messages, max_msg_size ) + +Where ``max_messages`` is the maximum number of pending messages and +``max_msg_size`` is the maximum size in bytes of the messages of the +corresponding message queue. Both parameters shall be compile time +constants. Not using this help macro (e.g. just using +``max_messages * max_msg_size``) may result in an underestimate of the +RTEMS Workspace size. + +The following example illustrates how the +``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help macro 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 a +maximum of 24 pending messages with the message structure defined by the +type ``one_message_type``. The other message queue has a 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 ) \ + ) \ + ) + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/microseconds-per-tick +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MICROSECONDS_PER_TICK .. index:: clock tick quantum .. index:: tick quantum @@ -551,55 +669,64 @@ NOTES: CONFIGURE_MICROSECONDS_PER_TICK ------------------------------- -CONSTANT: - ``CONFIGURE_MICROSECONDS_PER_TICK`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MICROSECONDS_PER_TICK`` -DEFAULT VALUE: - The default value is 10000. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to a value defined by the :term:`Clock - Driver`. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to a value defined by the :term:`Clock - Driver`. +The default value is 10000. - * The resulting clock ticks per second should be an integer. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the length of time in - microseconds between clock ticks (clock tick quantum). +The value of this configuration option defines the length of time in +microseconds between clock ticks (clock tick quantum). - 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. +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 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. +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 option has no impact if the Clock Driver is not - configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. +.. rubric:: NOTES: - There may be Clock Driver specific limits on the resolution or maximum value - of a clock tick quantum. +This configuration option has no impact if the Clock Driver is not +configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. + +There may be Clock Driver specific limits on the resolution or maximum value +of a clock tick quantum. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to a + value defined by the :term:`Clock Driver`. + +* The value of the configuration option shall be less than or equal to a value + defined by the :term:`Clock Driver`. + +* The resulting clock ticks per second should be an integer. .. Generated from spec:/acfg/if/min-task-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE .. index:: minimum task stack size @@ -608,54 +735,64 @@ NOTES: CONFIGURE_MINIMUM_TASK_STACK_SIZE --------------------------------- -CONSTANT: - ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`. +The default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be small enough so that the task stack space calculation carried - out by ``<rtems/confdefs.h>`` does not overflow an integer of type - `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the minimum stack size in +bytes for every user task or thread in the system. - * It shall be greater than or equal to a BSP-specific and - application-specific minimum value. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the minimum stack size in - bytes for every user task or thread in the system. +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`). -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 shall be done with caution as it could increase the +possibility of a blown task stack. - 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 shall 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. - 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. - 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`. - 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`. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. .. Generated from spec:/acfg/if/stack-checker-enabled +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_STACK_CHECKER_ENABLED .. _CONFIGURE_STACK_CHECKER_ENABLED: @@ -663,29 +800,38 @@ NOTES: CONFIGURE_STACK_CHECKER_ENABLED ------------------------------- -CONSTANT: - ``CONFIGURE_STACK_CHECKER_ENABLED`` +.. rubric:: CONSTANT: + +``CONFIGURE_STACK_CHECKER_ENABLED`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the stack checker is - enabled. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - The stack checker performs run-time stack bounds checking. This increases - the time required to create tasks as well as adding overhead to each context - switch. +If this configuration option is undefined, then the described feature is not +enabled. - In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the stack checker is +enabled. + +.. rubric:: NOTES: + +The stack checker performs run-time stack bounds checking. This increases +the time required to create tasks as well as adding overhead to each context +switch. + +In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``. .. Generated from spec:/acfg/if/ticks-per-time-slice +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TICKS_PER_TIMESLICE .. index:: ticks per timeslice @@ -694,34 +840,43 @@ NOTES: CONFIGURE_TICKS_PER_TIMESLICE ----------------------------- -CONSTANT: - ``CONFIGURE_TICKS_PER_TIMESLICE`` +.. rubric:: CONSTANT: + +``CONFIGURE_TICKS_PER_TIMESLICE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 50. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 50. +The value of this configuration option defines the length of the timeslice +quantum in ticks for each task. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: NOTES: - * It shall be greater than or equal to zero. +This configuration option has no impact if the Clock Driver is not +configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the length of the timeslice - quantum in ticks for each task. +The following constraints apply to this configuration option: -NOTES: - This configuration option has no impact if the Clock Driver is not - configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/unified-work-areas +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_UNIFIED_WORK_AREAS .. index:: unified work areas .. index:: separate work areas @@ -733,33 +888,42 @@ NOTES: CONFIGURE_UNIFIED_WORK_AREAS ---------------------------- -CONSTANT: - ``CONFIGURE_UNIFIED_WORK_AREAS`` +.. rubric:: CONSTANT: + +``CONFIGURE_UNIFIED_WORK_AREAS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then there will be separate memory - pools for the RTEMS Workspace and C Program Heap. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the RTEMS Workspace and - the C Program Heap will be one pool of memory. +If this configuration option is undefined, then 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. +.. rubric:: DESCRIPTION: - In high memory environments, this is desirable when you want to use the - :ref:`ConfigUnlimitedObjects` 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. +In case this configuration option is defined, then the RTEMS Workspace and +the C Program Heap will be one pool of memory. + +.. rubric:: 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 +:ref:`ConfigUnlimitedObjects` 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. .. Generated from spec:/acfg/if/unlimited-allocation-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_UNLIMITED_ALLOCATION_SIZE .. _CONFIGURE_UNLIMITED_ALLOCATION_SIZE: @@ -767,34 +931,44 @@ NOTES: CONFIGURE_UNLIMITED_ALLOCATION_SIZE ----------------------------------- -CONSTANT: - ``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_UNLIMITED_ALLOCATION_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 8. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +If :ref:`CONFIGURE_UNLIMITED_OBJECTS` is defined, then the value of this +configuration option defines the default objects maximum of all object +classes supporting :ref:`ConfigUnlimitedObjects` to +``rtems_resource_unlimited( CONFIGURE_UNLIMITED_ALLOCATION_SIZE )``. -DEFAULT VALUE: - The default value is 8. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall meet the constraints of all - object classes to which it is applied. +By allowing users to declare all resources as being unlimited the user can +avoid identifying and limiting the resources used. -DESCRIPTION: - If :ref:`CONFIGURE_UNLIMITED_OBJECTS` is defined, then the value of this - configuration option defines the default objects maximum of all object - classes supporting :ref:`ConfigUnlimitedObjects` to - ``rtems_resource_unlimited( CONFIGURE_UNLIMITED_ALLOCATION_SIZE )``. +The object maximum of each class can be configured also individually using +the :c:func:`rtems_resource_unlimited` macro. -NOTES: - By allowing users to declare all resources as being unlimited the user can - avoid identifying and limiting the resources used. +.. rubric:: CONSTRAINTS: - The object maximum of each class can be configured also individually using - the :c:func:`rtems_resource_unlimited` macro. +The value of the configuration option shall meet the constraints of all object +classes to which it is applied. .. Generated from spec:/acfg/if/unlimited-objects +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_UNLIMITED_OBJECTS .. _CONFIGURE_UNLIMITED_OBJECTS: @@ -802,32 +976,41 @@ NOTES: CONFIGURE_UNLIMITED_OBJECTS --------------------------- -CONSTANT: - ``CONFIGURE_UNLIMITED_OBJECTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_UNLIMITED_OBJECTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then unlimited objects are used - by default. +In case this configuration option is defined, then unlimited objects are used +by default. -NOTES: - When using unlimited objects, it is common practice to also specify - :ref:`CONFIGURE_UNIFIED_WORK_AREAS` so the system operates with a single pool - of memory for both RTEMS Workspace and C Program Heap. +.. rubric:: NOTES: - This option does not override an explicit configuration for a particular - object class by the user. +When using unlimited objects, it is common practice to also specify +:ref:`CONFIGURE_UNIFIED_WORK_AREAS` so the system operates with a single pool +of memory for both RTEMS Workspace and C Program Heap. - See also :ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`. +This option does not override an explicit configuration for a particular +object class by the user. + +See also :ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`. .. Generated from spec:/acfg/if/verbose-system-init +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION .. _CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION: @@ -835,26 +1018,35 @@ NOTES: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION --------------------------------------- -CONSTANT: - ``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` +.. rubric:: CONSTANT: + +``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the system initialization - is verbose. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - You may use this feature to debug system initialization issues. The - :c:func:`printk` function is used to print the information. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the system initialization +is verbose. + +.. rubric:: NOTES: + +You may use this feature to debug system initialization issues. The +:c:func:`printk` function is used to print the information. .. Generated from spec:/acfg/if/zero-workspace-automatically +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY .. index:: clear C Program Heap .. index:: clear RTEMS Workspace @@ -866,23 +1058,28 @@ NOTES: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY -------------------------------------- -CONSTANT: - ``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` +.. rubric:: CONSTANT: + +``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the memory areas used for +the RTEMS Workspace and the C Program Heap are zeroed with a ``0x00`` byte +pattern during system initialization. -DESCRIPTION: - In case this configuration option is defined, then the memory areas used for - the RTEMS Workspace and the C Program Heap are zeroed with a ``0x00`` byte - pattern during system initialization. +.. rubric:: NOTES: -NOTES: - Zeroing memory can add significantly to the system initialization 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. +Zeroing memory can add significantly to the system initialization 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. diff --git a/c-user/config/idle-task.rst b/c-user/config/idle-task.rst index 1234f42..5cf8364 100644 --- a/c-user/config/idle-task.rst +++ b/c-user/config/idle-task.rst @@ -27,6 +27,10 @@ This section describes configuration options related to the idle tasks. .. Generated from spec:/acfg/if/idle-task-body +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IDLE_TASK_BODY .. _CONFIGURE_IDLE_TASK_BODY: @@ -34,33 +38,43 @@ This section describes configuration options related to the idle tasks. CONFIGURE_IDLE_TASK_BODY ------------------------ -CONSTANT: - ``CONFIGURE_IDLE_TASK_BODY`` +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_BODY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an initializer define. +If :ref:`BSP_IDLE_TASK_BODY` is defined, then this will be the default value, +otherwise the default value is ``_CPU_Thread_Idle_body``. -DEFAULT VALUE: - If :ref:`BSP_IDLE_TASK_BODY` is defined, then this will be the default value, - otherwise the default value is ``_CPU_Thread_Idle_body``. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *idle_body )( uintptr_t )``. +The value of this configuration option initializes the IDLE thread body. -DESCRIPTION: - The value of this configuration option initializes the IDLE thread body. +.. rubric:: NOTES: -NOTES: - IDLE threads shall not block. A blocking IDLE thread results in undefined - system behaviour because the scheduler assume that at least one ready thread - exists. +IDLE threads shall not block. A blocking IDLE thread results in undefined +system behaviour because the scheduler assume that at least one ready thread +exists. - IDLE threads can be used to initialize the application, see configuration - option :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`. +IDLE threads can be used to initialize the application, see configuration +option :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *idle_body )( uintptr_t )``. .. Generated from spec:/acfg/if/idle-task-init-appl +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION .. _CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION: @@ -68,47 +82,56 @@ NOTES: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION ------------------------------------------- -CONSTANT: - ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the user is assumed to - provide one or more initialization tasks. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - This configuration option is defined 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. +If this configuration option is undefined, then the user is assumed to +provide one or more initialization tasks. -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 shall make itself preemptible and enter an idle - body loop. +.. rubric:: DESCRIPTION: - The IDLE task shall run at the lowest priority of all tasks in the system. +This configuration option is defined 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. - If this configuration option is defined, then it is mandatory to configure a - user IDLE task with the :ref:`CONFIGURE_IDLE_TASK_BODY` configuration option, - otherwise a compile time error in the configuration file will occur. +.. rubric:: NOTES: - The application shall define exactly one of the following configuration - options +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 shall make itself preemptible and enter an idle +body loop. - * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, +The IDLE task shall run at the lowest priority of all tasks in the system. - * :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or +If this configuration option is defined, then it is mandatory to configure a +user IDLE task with the :ref:`CONFIGURE_IDLE_TASK_BODY` configuration option, +otherwise a compile time error in the configuration file will occur. - * ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` +The application shall define exactly one of the following configuration +options - otherwise a compile time error in the configuration file will occur. +* :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, + +* :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or + +* ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`` + +otherwise a compile time error in the configuration file will occur. .. Generated from spec:/acfg/if/idle-task-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_IDLE_TASK_STACK_SIZE .. _CONFIGURE_IDLE_TASK_STACK_SIZE: @@ -116,30 +139,36 @@ NOTES: CONFIGURE_IDLE_TASK_STACK_SIZE ------------------------------ -CONSTANT: - ``CONFIGURE_IDLE_TASK_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the task stack size for an +IDLE task. -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +In SMP configurations, there is one IDLE task per configured processor, see +:ref:`CONFIGURE_MAXIMUM_PROCESSORS`. - * It shall be greater than or equal to a BSP-specific and - application-specific minimum value. +.. rubric:: CONSTRAINTS: - * It shall be small enough so that the IDLE task stack area calculation - carried out by ``<rtems/confdefs.h>`` does not overflow an integer of - type `size_t <https://en.cppreference.com/w/c/types/size_t>`_. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the task stack size for an - IDLE task. +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. -NOTES: - In SMP configurations, there is one IDLE task per configured processor, see - :ref:`CONFIGURE_MAXIMUM_PROCESSORS`. +* The value of the configuration option shall be small enough so that the IDLE + task stack area calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst index 800aa30..09c541f 100644 --- a/c-user/config/mpci.rst +++ b/c-user/config/mpci.rst @@ -32,6 +32,10 @@ SMP support. .. Generated from spec:/acfg/if/mp-extra-server-stack +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK .. _CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK: @@ -39,39 +43,49 @@ SMP support. CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK ----------------------------------------- -CONSTANT: - ``CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXTRA_MPCI_RECEIVE_SERVER_STACK`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 0. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is 0. +The value of this configuration option defines the number of bytes the +applications wishes to add to the MPCI task stack on top of +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: NOTES: - * It shall be greater than or equal to zero. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: - * It shall be small enough so that the MPCI receive server stack area - calculation carried out by ``<rtems/confdefs.h>`` does not overflow an - integer of type `size_t <https://en.cppreference.com/w/c/types/size_t>`_. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the number of bytes the - applications wishes to add to the MPCI task stack on top of - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be small enough so that the MPCI + receive server stack area calculation carried out by ``<rtems/confdefs.h>`` + does not overflow an integer of type `size_t + <https://en.cppreference.com/w/c/types/size_t>`_. .. Generated from spec:/acfg/if/mp-appl +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_APPLICATION .. _CONFIGURE_MP_APPLICATION: @@ -79,29 +93,38 @@ NOTES: CONFIGURE_MP_APPLICATION ------------------------ -CONSTANT: - ``CONFIGURE_MP_APPLICATION`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_APPLICATION`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the multiprocessing services +are not initialized. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the multiprocessing services - are not initialized. +.. rubric:: DESCRIPTION: -DESCRIPTION: - This configuration option is defined to indicate that the application intends - to be part of a multiprocessing configuration. Additional configuration - options are assumed to be provided. +This configuration option is defined to indicate that the application intends +to be part of a multiprocessing configuration. Additional configuration +options are assumed to be provided. -NOTES: - This configuration option shall be undefined if the multiprocessing support - is not enabled (e.g. RTEMS was built without the ``--enable-multiprocessing`` - build configuration option). Otherwise a compile time error in the - configuration file will occur. +.. rubric:: NOTES: + +This configuration option shall be undefined if the multiprocessing support +is not enabled (e.g. RTEMS was built without the ``--enable-multiprocessing`` +build configuration option). Otherwise a compile time error in the +configuration file will occur. .. Generated from spec:/acfg/if/mp-max-global-objects +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS .. _CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS: @@ -109,37 +132,46 @@ NOTES: CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS ----------------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 32. -DEFAULT VALUE: - The default value is 32. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of +concurrently active global objects in a multiprocessor system. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +This value corresponds to the total number of objects which can be created +with the :c:macro:`RTEMS_GLOBAL` attribute. -DESCRIPTION: - The value of this configuration option defines the maximum number of - concurrently active global objects in a multiprocessor system. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -NOTES: - This value corresponds to the total number of objects which can be created - with the :c:macro:`RTEMS_GLOBAL` attribute. +.. rubric:: CONSTRAINTS: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/mp-max-nodes +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MAXIMUM_NODES .. _CONFIGURE_MP_MAXIMUM_NODES: @@ -147,34 +179,43 @@ NOTES: CONFIGURE_MP_MAXIMUM_NODES -------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_NODES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_NODES`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 2. +The default value is 2. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to zero. +The value of this configuration option defines the maximum number of nodes in +a multiprocessor system. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of nodes in - a multiprocessor system. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. -NOTES: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/mp-max-proxies +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MAXIMUM_PROXIES .. _CONFIGURE_MP_MAXIMUM_PROXIES: @@ -182,40 +223,49 @@ NOTES: CONFIGURE_MP_MAXIMUM_PROXIES ---------------------------- -CONSTANT: - ``CONFIGURE_MP_MAXIMUM_PROXIES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MAXIMUM_PROXIES`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 32. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 32. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the maximum number of +concurrently active thread/task proxies on this node in a multiprocessor +system. -DESCRIPTION: - The value of this configuration option defines the maximum number of - concurrently active thread/task proxies on this node in a multiprocessor - system. +.. rubric:: NOTES: -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, see - :ref:`MPCIProxies`. +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, see +:ref:`MPCIProxies`. - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/mp-mpci-table-pointer +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_MPCI_TABLE_POINTER .. _CONFIGURE_MP_MPCI_TABLE_POINTER: @@ -223,33 +273,43 @@ NOTES: CONFIGURE_MP_MPCI_TABLE_POINTER ------------------------------- -CONSTANT: - ``CONFIGURE_MP_MPCI_TABLE_POINTER`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_MPCI_TABLE_POINTER`` -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is ``&MPCI_table``. +This configuration option is an initializer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be a pointer to - :c:type:`rtems_mpci_table`. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option initializes the MPCI Configuration - Table. +The default value 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. +.. rubric:: DESCRIPTION: - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +The value of this configuration option initializes the MPCI Configuration +Table. + +.. rubric:: 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. + +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be a pointer to +:c:type:`rtems_mpci_table`. .. Generated from spec:/acfg/if/mp-node-number +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MP_NODE_NUMBER .. _CONFIGURE_MP_NODE_NUMBER: @@ -257,33 +317,38 @@ NOTES: CONFIGURE_MP_NODE_NUMBER ------------------------ -CONSTANT: - ``CONFIGURE_MP_NODE_NUMBER`` +.. rubric:: CONSTANT: + +``CONFIGURE_MP_NODE_NUMBER`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``NODE_NUMBER``. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the node number of this node +in a multiprocessor system. -DEFAULT VALUE: - The default value is ``NODE_NUMBER``. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +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. - * It shall be greater than or equal to zero. +This configuration option is only evaluated if +:ref:`CONFIGURE_MP_APPLICATION` is defined. - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the node number of this node - in a multiprocessor system. +The following constraints apply to this configuration option: -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. +* The value of the configuration option shall be greater than or equal to zero. - This configuration option is only evaluated if - :ref:`CONFIGURE_MP_APPLICATION` is defined. +* The value of the configuration option shall be less than or equal to + `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst index 148f895..12e6410 100644 --- a/c-user/config/posix-api.rst +++ b/c-user/config/posix-api.rst @@ -30,6 +30,10 @@ build configuration option. .. Generated from spec:/acfg/if/max-posix-keys +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_KEYS .. _CONFIGURE_MAXIMUM_POSIX_KEYS: @@ -37,42 +41,51 @@ build configuration option. CONFIGURE_MAXIMUM_POSIX_KEYS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_KEYS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_KEYS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 0. +The default value is 0. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to zero. +The value of this configuration option defines the maximum number of POSIX +API Keys that can be concurrently active. - * It shall be less than or equal to 65535. +.. rubric:: NOTES: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Keys that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-key-value-pairs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS .. _CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS: @@ -80,48 +93,57 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS --------------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is +:ref:`CONFIGURE_MAXIMUM_POSIX_KEYS` * +( :ref:`CONFIGURE_MAXIMUM_TASKS` + +:ref:`CONFIGURE_MAXIMUM_POSIX_THREADS` ). -DEFAULT VALUE: - The default value is - :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS` * - ( :ref:`CONFIGURE_MAXIMUM_TASKS` + - :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS` ). +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of key +value pairs used by POSIX API Keys that can be concurrently active. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +A key value pair is created by :c:func:`pthread_setspecific` if the value +is not `NULL <https://en.cppreference.com/w/c/types/NULL>`_, otherwise it is deleted. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of key - value pairs used by POSIX API Keys that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be greater than or equal to zero. - A key value pair is created by :c:func:`pthread_setspecific` if the value - is not `NULL <https://en.cppreference.com/w/c/types/NULL>`_, otherwise it is deleted. +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-message-queues +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES .. _CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES: @@ -129,48 +151,58 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES -------------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an integer define. +``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` -DEFAULT VALUE: - The default value is 0. +.. rubric:: OPTION TYPE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +This configuration option is an integer define. - * It shall be greater than or equal to zero. +.. rubric:: DEFAULT VALUE: - * It shall be less than or equal to 65535. +The default value is 0. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: DESCRIPTION: - * It shall be small enough so that the RTEMS Workspace size calculation - carried out by ``<rtems/confdefs.h>`` does not overflow an integer of - type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the maximum number of POSIX +API Message Queues that can be concurrently active. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Message Queues that can be concurrently active. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. You have to account for the memory used to +store the messages of each message queue, see +:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. You have to account for the memory used to - store the messages of each message queue, see - :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-queued-signals +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS .. _CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS: @@ -178,45 +210,56 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS -------------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 0. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to zero. +The default value is 0. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: DESCRIPTION: - * It shall be small enough so that the RTEMS Workspace size calculation - carried out by ``<rtems/confdefs.h>`` does not overflow an integer of - type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +The value of this configuration option defines the maximum number of POSIX +API Queued Signals that can be concurrently active. - * It shall be zero if the POSIX API is not enabled (e.g. RTEMS was built - without the ``RTEMS_POSIX_API = True`` build configuration option). - Otherwise a compile time error in the configuration file will occur. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Queued Signals that can be concurrently active. +Unlimited objects are not available for queued signals. -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. - Queued signals are only available if RTEMS was built with the - ``--enable-posix`` build configuration option. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option shall be zero if the POSIX API is not + enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True`` build + configuration option). Otherwise a compile time error in the configuration + file will occur. .. Generated from spec:/acfg/if/max-posix-semaphores +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES .. _CONFIGURE_MAXIMUM_POSIX_SEMAPHORES: @@ -224,51 +267,61 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is 0. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to zero. +The default value is 0. - * It shall be less than or equal to 65535. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +The value of this configuration option defines the maximum number of POSIX +API Named Semaphores that can be concurrently active. - * It shall be small enough so that the RTEMS Workspace size calculation - carried out by ``<rtems/confdefs.h>`` does not overflow an integer of - type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: NOTES: - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Named Semaphores that can be concurrently active. +Named semaphores are created with :c:func:`sem_open`. Semaphores +initialized with :c:func:`sem_init` are not affected by this +configuration option since the storage space for these semaphores is +user-provided. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +.. rubric:: CONSTRAINTS: - Named semaphores are created with :c:func:`sem_open`. Semaphores - initialized with :c:func:`sem_init` are not affected by this - configuration option since the storage space for these semaphores is - user-provided. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-shms +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_SHMS .. _CONFIGURE_MAXIMUM_POSIX_SHMS: @@ -276,46 +329,56 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_SHMS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_SHMS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_SHMS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an integer define. +This configuration option is an integer define. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 0. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to 65535. +The value of this configuration option defines the maximum number of POSIX +API Shared Memory objects that can be concurrently active. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +.. rubric:: NOTES: - * It shall be small enough so that the RTEMS Workspace size calculation - carried out by ``<rtems/confdefs.h>`` does not overflow an integer of - type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +.. rubric:: CONSTRAINTS: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Shared Memory objects that can be concurrently active. +The following constraints apply to this configuration option: -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the RTEMS + Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-threads +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_THREADS .. _CONFIGURE_MAXIMUM_POSIX_THREADS: @@ -323,51 +386,61 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_THREADS ------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_THREADS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_THREADS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 0. +The default value is 0. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DESCRIPTION: - * It shall be greater than or equal to zero. +The value of this configuration option defines the maximum number of POSIX +API Threads that can be concurrently active. - * It shall be less than or equal to 65535. +.. rubric:: NOTES: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be small enough so that the task stack space calculation carried - out by ``<rtems/confdefs.h>`` does not overflow an integer of type - `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +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 option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used +to specify thread stack requirements **above** the minimum size required. -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Threads that can be concurrently active. +The maximum number of Classic API Tasks is specified by +:ref:`CONFIGURE_MAXIMUM_TASKS`. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +All POSIX threads have floating point enabled. - 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 option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used - to specify thread stack requirements **above** the minimum size required. +.. rubric:: CONSTRAINTS: - The maximum number of Classic API Tasks is specified by - :ref:`CONFIGURE_MAXIMUM_TASKS`. +The following constraints apply to this configuration option: - All POSIX threads have floating point enabled. +* The value of the configuration option shall be greater than or equal to zero. + +* The value of the configuration option shall be less than or equal to 65535. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/max-posix-timers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS .. _CONFIGURE_MAXIMUM_POSIX_TIMERS: @@ -375,49 +448,59 @@ NOTES: CONFIGURE_MAXIMUM_POSIX_TIMERS ------------------------------ -CONSTANT: - ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_POSIX_TIMERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is 0. -DEFAULT VALUE: - The default value is 0. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the maximum number of POSIX +API Timers that can be concurrently active. - * It shall be greater than or equal to zero. +.. rubric:: NOTES: - * It shall be less than or equal to 65535. +This object class can be configured in unlimited allocation mode, see +:ref:`ConfigUnlimitedObjects`. - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +Timers are only available if RTEMS was built with the +``--enable-posix`` build configuration option. - * It may be defined through :c:func:`rtems_resource_unlimited` the enable - unlimited objects for the object class, if the value passed to - :c:func:`rtems_resource_unlimited` satisfies all other constraints of the - configuration option. +.. rubric:: CONSTRAINTS: - * It shall be zero if the POSIX API is not enabled (e.g. RTEMS was built - without the ``RTEMS_POSIX_API = True`` build configuration option). - Otherwise a compile time error in the configuration file will occur. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number of POSIX - API Timers that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This object class can be configured in unlimited allocation mode, see - :ref:`ConfigUnlimitedObjects`. +* The value of the configuration option shall be less than or equal to 65535. - Timers are only available if RTEMS was built with the - ``--enable-posix`` build configuration option. +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. + +* The value of the configuration option may be defined through + :c:func:`rtems_resource_unlimited` the enable unlimited objects for the + object class, if the value passed to :c:func:`rtems_resource_unlimited` + satisfies all other constraints of the configuration option. + +* The value of the configuration option shall be zero if the POSIX API is not + enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True`` build + configuration option). Otherwise a compile time error in the configuration + file will occur. .. Generated from spec:/acfg/if/min-posix-thread-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE .. index:: minimum POSIX thread stack size @@ -426,30 +509,32 @@ NOTES: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE ----------------------------------------- -CONSTANT: - ``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is two times the value of +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. -DEFAULT VALUE: - The default value is two times the value of - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The value of this configuration option defines the minimum stack size in +bytes for every POSIX thread in the system. - * It shall be small enough so that the task stack space calculation carried - out by ``<rtems/confdefs.h>`` does not overflow an integer of type - `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: CONSTRAINTS: - * It shall be greater than or equal to a BSP-specific and - application-specific minimum value. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the minimum stack size in - bytes for every POSIX thread in the system. +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. -NOTES: - None. +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst index 8623f2c..c038ec8 100644 --- a/c-user/config/posix-init-thread.rst +++ b/c-user/config/posix-init-thread.rst @@ -28,6 +28,10 @@ initialization thread. .. Generated from spec:/acfg/if/posix-init-thread-entry-point +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT .. _CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT: @@ -35,29 +39,39 @@ initialization thread. CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT --------------------------------------- -CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an initializer define. +The default value is ``POSIX_Init``. -DEFAULT VALUE: - The default value is ``POSIX_Init``. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *entry_point )( void * )``. +The value of this configuration option initializes the entry point of the +POSIX API initialization thread. -DESCRIPTION: - The value of this configuration option initializes the entry point of the - POSIX API initialization thread. +.. rubric:: NOTES: -NOTES: - The application shall provide the function referenced by this configuration - option. +The application shall provide the function referenced by this configuration +option. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *entry_point )( void * )``. .. Generated from spec:/acfg/if/posix-init-thread-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE .. _CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE: @@ -65,35 +79,41 @@ NOTES: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE -------------------------------------- -CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`. +This configuration option is an integer define. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: DEFAULT VALUE: - * It shall be greater than or equal to - :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +The default value is :ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`. - * It shall be small enough so that the task stack space calculation carried - out by ``<rtems/confdefs.h>`` does not overflow an integer of type - `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option defines the thread stack size of the - POSIX API initialization thread. +The value of this configuration option defines the thread stack size of the +POSIX API initialization thread. -NOTES: - None. +.. rubric:: CONSTRAINTS: + +The following constraints apply to this configuration option: + +* The value of the configuration option shall be greater than or equal to + :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +* The value of the configuration option shall be small enough so that the task + stack space calculation carried out by ``<rtems/confdefs.h>`` does not + overflow an integer of type `uintptr_t + <https://en.cppreference.com/w/c/types/integer>`_. .. Generated from spec:/acfg/if/posix-init-thread-table +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_POSIX_INIT_THREAD_TABLE .. _CONFIGURE_POSIX_INIT_THREAD_TABLE: @@ -101,28 +121,33 @@ NOTES: CONFIGURE_POSIX_INIT_THREAD_TABLE --------------------------------- -CONSTANT: - ``CONFIGURE_POSIX_INIT_THREAD_TABLE`` +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_INIT_THREAD_TABLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then exactly one POSIX +initialization thread is configured. -DESCRIPTION: - In case this configuration option is defined, then exactly one POSIX - initialization thread is configured. +.. rubric:: NOTES: -NOTES: - The application shall define exactly one of the following configuration - options +The application shall define exactly one of the following configuration +options - * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, +* :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, - * ``CONFIGURE_POSIX_INIT_THREAD_TABLE``, or +* ``CONFIGURE_POSIX_INIT_THREAD_TABLE``, or - * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` +* :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` - otherwise a compile time error in the configuration file will occur. +otherwise a compile time error in the configuration file will occur. diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst index d78b14a..7c42039 100644 --- a/c-user/config/scheduler-general.rst +++ b/c-user/config/scheduler-general.rst @@ -49,6 +49,10 @@ configuration option. .. Generated from spec:/acfg/if/cbs-max-servers +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_CBS_MAXIMUM_SERVERS .. _CONFIGURE_CBS_MAXIMUM_SERVERS: @@ -56,38 +60,47 @@ configuration option. CONFIGURE_CBS_MAXIMUM_SERVERS ----------------------------- -CONSTANT: - ``CONFIGURE_CBS_MAXIMUM_SERVERS`` +.. rubric:: CONSTANT: + +``CONFIGURE_CBS_MAXIMUM_SERVERS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is :ref:`CONFIGURE_MAXIMUM_TASKS`. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is :ref:`CONFIGURE_MAXIMUM_TASKS`. +The value of this configuration option defines the maximum number Constant +Bandwidth Servers that can be concurrently active. -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. rubric:: NOTES: - * It shall be greater than or equal to zero. +This configuration option is only evaluated if the configuration option +:ref:`CONFIGURE_SCHEDULER_CBS` is defined. - * It shall be less than or equal to `SIZE_MAX - <https://en.cppreference.com/w/c/types/limits>`_. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to a BSP-specific and application-specific - value which depends on the size of the memory available to the - application. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the maximum number Constant - Bandwidth Servers that can be concurrently active. +* The value of the configuration option shall be greater than or equal to zero. -NOTES: - This configuration option is only evaluated if the configuration option - :ref:`CONFIGURE_SCHEDULER_CBS` is defined. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. + +* The value of the configuration option shall be less than or equal to a + BSP-specific and application-specific value which depends on the size of the + memory available to the application. .. Generated from spec:/acfg/if/max-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MAXIMUM_PRIORITY .. index:: maximum priority .. index:: number of priority levels @@ -97,57 +110,67 @@ NOTES: CONFIGURE_MAXIMUM_PRIORITY -------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is 255. +The default value is 255. -VALUE CONSTRAINTS: - The value of this configuration option shall be equal to 3, 7, 31, 63, 127, - or 255. +.. rubric:: DESCRIPTION: -DESCRIPTION: - For the following schedulers +For the following schedulers - * :ref:`SchedulerPriority`, which is the default in uniprocessor - configurations and can be configured through the - :ref:`CONFIGURE_SCHEDULER_PRIORITY` configuration option, +* :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:`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 +* :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. +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. +.. rubric:: NOTES: - Priority zero is reserved for internal use by RTEMS and is not available to - applications. +The numerically greatest priority is the logically lowest priority in the +system and will thus be used by the IDLE task. - 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``). +Priority zero is reserved for internal use by RTEMS and is not available to +applications. - The default value is 255, because RTEMS shall support 256 priority levels to - be compliant with various standards. These priorities range from 0 to 255. +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``). + +The default value is 255, because RTEMS shall support 256 priority levels to +be compliant with various standards. These priorities range from 0 to 255. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be equal to 3, 7, 31, 63, 127, or +255. .. Generated from spec:/acfg/if/scheduler-assignments +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_ASSIGNMENTS .. _CONFIGURE_SCHEDULER_ASSIGNMENTS: @@ -155,41 +178,51 @@ NOTES: CONFIGURE_SCHEDULER_ASSIGNMENTS ------------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_ASSIGNMENTS`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_ASSIGNMENTS`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an initializer define. +This configuration option is an initializer define. -DEFAULT VALUE: - The default value of this configuration option is computed so that the - default scheduler is assigned to each configured processor (up to 32). +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value of this configuration option is computed so that the +default scheduler is assigned to each configured processor (up to 32). - * It shall be a list of the following macros: +.. rubric:: DESCRIPTION: - * ``RTEMS_SCHEDULER_ASSIGN( processor_index, attributes )`` +The value of this configuration option is used to initialize the initial +scheduler to processor assignments. - * ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` +.. rubric:: NOTES: - * It shall be a list of exactly :ref:`CONFIGURE_MAXIMUM_PROCESSORS` - elements. +This configuration option is only evaluated in SMP configurations. -DESCRIPTION: - The value of this configuration option is used to initialize the initial - scheduler to processor assignments. +This is an advanced configuration option, see +:ref:`ConfigurationSchedulersClustered`. -NOTES: - This configuration option is only evaluated in SMP configurations. +.. rubric:: CONSTRAINTS: - This is an advanced configuration option, see - :ref:`ConfigurationSchedulersClustered`. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be a list of the following + macros: + + * ``RTEMS_SCHEDULER_ASSIGN( processor_index, attributes )`` + + * ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` + +* The value of the configuration option shall be a list of exactly + :ref:`CONFIGURE_MAXIMUM_PROCESSORS` elements. .. Generated from spec:/acfg/if/scheduler-cbs +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_CBS .. _CONFIGURE_SCHEDULER_CBS: @@ -197,30 +230,39 @@ NOTES: CONFIGURE_SCHEDULER_CBS ----------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_CBS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_SCHEDULER_CBS`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the - :ref:`SchedulerCBS` - algorithm is made available to the application. +This configuration option is a boolean feature define. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: DEFAULT CONFIGURATION: - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for exactly one processor. +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerCBS` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. .. Generated from spec:/acfg/if/scheduler-edf +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_EDF .. _CONFIGURE_SCHEDULER_EDF: @@ -228,30 +270,39 @@ NOTES: CONFIGURE_SCHEDULER_EDF ----------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_EDF`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_SCHEDULER_EDF`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the - :ref:`SchedulerEDF` - algorithm is made available to the application. +This configuration option is a boolean feature define. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: DEFAULT CONFIGURATION: - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for exactly one processor. +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerEDF` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. .. Generated from spec:/acfg/if/scheduler-edf-smp +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_EDF_SMP .. _CONFIGURE_SCHEDULER_EDF_SMP: @@ -259,37 +310,46 @@ NOTES: CONFIGURE_SCHEDULER_EDF_SMP --------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_EDF_SMP`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_EDF_SMP`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerSMPEDF` +algorithm is made available to the application. -DESCRIPTION: - In case this configuration option is defined, then the - :ref:`SchedulerSMPEDF` - algorithm is made available to the application. +.. rubric:: NOTES: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +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. +This scheduler algorithm is only available when RTEMS is built with SMP +support enabled. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for up to 32 processors. +In case no explicit :ref:`ConfigurationSchedulersClustered` +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. +This scheduler algorithm is the default in SMP configurations if +:ref:`CONFIGURE_MAXIMUM_PROCESSORS` is +greater than one. .. Generated from spec:/acfg/if/scheduler-name +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_NAME .. _CONFIGURE_SCHEDULER_NAME: @@ -297,49 +357,59 @@ NOTES: CONFIGURE_SCHEDULER_NAME ------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_NAME`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_NAME`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an integer define. +The default value is -DEFAULT VALUE: - The default value is +* ``"MEDF"`` for the :ref:`SchedulerSMPEDF`, - * ``"MEDF"`` for the :ref:`SchedulerSMPEDF`, +* ``"MPA "`` for the :ref:`SchedulerSMPPriorityAffinity`, - * ``"MPA "`` for the :ref:`SchedulerSMPPriorityAffinity`, +* ``"MPD "`` for the :ref:`SchedulerSMPPriority`, - * ``"MPD "`` for the :ref:`SchedulerSMPPriority`, +* ``"MPS "`` for the :ref:`SchedulerSMPPrioritySimple`, - * ``"MPS "`` for the :ref:`SchedulerSMPPrioritySimple`, +* ``"UCBS"`` for the :ref:`SchedulerCBS`, - * ``"UCBS"`` for the :ref:`SchedulerCBS`, +* ``"UEDF"`` for the :ref:`SchedulerEDF`, - * ``"UEDF"`` for the :ref:`SchedulerEDF`, +* ``"UPD "`` for the :ref:`SchedulerPriority`, and - * ``"UPD "`` for the :ref:`SchedulerPriority`, and +* ``"UPS "`` for the :ref:`SchedulerPrioritySimple`. - * ``"UPS "`` for the :ref:`SchedulerPrioritySimple`. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be convertible to an integer - of type :c:type:`rtems_name`. +The value of this configuration option defines the name of the default +scheduler. -DESCRIPTION: - The value of this configuration option defines the name of the default - scheduler. +.. rubric:: NOTES: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. - Schedulers can be identified via :c:func:`rtems_scheduler_ident`. +Schedulers can be identified via :c:func:`rtems_scheduler_ident`. - Use :c:func:`rtems_build_name` to define the scheduler name. +Use :c:func:`rtems_build_name` to define the scheduler name. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be convertible to an integer of +type :c:type:`rtems_name`. .. Generated from spec:/acfg/if/scheduler-priority +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_PRIORITY .. _CONFIGURE_SCHEDULER_PRIORITY: @@ -347,37 +417,46 @@ NOTES: CONFIGURE_SCHEDULER_PRIORITY ---------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_PRIORITY`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DEFAULT CONFIGURATION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +If this configuration option is undefined, then the described feature is not +enabled. -DESCRIPTION: - In case this configuration option is defined, then the - :ref:`SchedulerPriority` - algorithm is made available to the application. +.. rubric:: DESCRIPTION: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +In case this configuration option is defined, then the +:ref:`SchedulerPriority` +algorithm is made available to the application. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for exactly one processor. +.. rubric:: NOTES: - This scheduler algorithm is the default when - :ref:`CONFIGURE_MAXIMUM_PROCESSORS` is - exactly one. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. +In case no explicit :ref:`ConfigurationSchedulersClustered` +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. .. Generated from spec:/acfg/if/scheduler-priority-affinity-smp +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP .. _CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP: @@ -385,36 +464,45 @@ NOTES: CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP ----------------------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the - :ref:`SchedulerSMPPriorityAffinity` - algorithm is made available to the application. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: DESCRIPTION: - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +In case this configuration option is defined, then the +:ref:`SchedulerSMPPriorityAffinity` +algorithm is made available to the application. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for up to 32 processors. +.. rubric:: NOTES: - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. +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:`ConfigurationSchedulersClustered` +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. .. Generated from spec:/acfg/if/scheduler-priority-smp +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP .. _CONFIGURE_SCHEDULER_PRIORITY_SMP: @@ -422,36 +510,45 @@ NOTES: CONFIGURE_SCHEDULER_PRIORITY_SMP -------------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_PRIORITY_SMP`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_PRIORITY_SMP`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the - :ref:`SchedulerSMPPriority` - algorithm is made available to the application. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: DESCRIPTION: - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +In case this configuration option is defined, then the +:ref:`SchedulerSMPPriority` +algorithm is made available to the application. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for up to 32 processors. +.. rubric:: NOTES: - The memory allocated for this scheduler depends on the - :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. +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:`ConfigurationSchedulersClustered` +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. .. Generated from spec:/acfg/if/scheduler-simple +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_SIMPLE .. _CONFIGURE_SCHEDULER_SIMPLE: @@ -459,30 +556,39 @@ NOTES: CONFIGURE_SCHEDULER_SIMPLE -------------------------- -CONSTANT: - ``CONFIGURE_SCHEDULER_SIMPLE`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_SIMPLE`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the - :ref:`SchedulerPrioritySimple` - algorithm is made available to the application. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +If this configuration option is undefined, then the described feature is not +enabled. - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for exactly one processor. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the +:ref:`SchedulerPrioritySimple` +algorithm is made available to the application. + +.. rubric:: NOTES: + +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. + +In case no explicit :ref:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for exactly one processor. .. Generated from spec:/acfg/if/scheduler-simple-smp +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP .. _CONFIGURE_SCHEDULER_SIMPLE_SMP: @@ -490,33 +596,42 @@ NOTES: CONFIGURE_SCHEDULER_SIMPLE_SMP ------------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_SIMPLE_SMP`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_SIMPLE_SMP`` -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: OPTION TYPE: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is a boolean feature define. -DESCRIPTION: - In case this configuration option is defined, then the - :ref:`SchedulerSMPPrioritySimple` - algorithm is made available to the application. +.. rubric:: DEFAULT CONFIGURATION: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +If this configuration option is undefined, then the described feature is not +enabled. - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +.. rubric:: DESCRIPTION: - In case no explicit :ref:`ConfigurationSchedulersClustered` - is present, then it is used as the scheduler for up to 32 processors. +In case this configuration option is defined, then the +:ref:`SchedulerSMPPrioritySimple` +algorithm is made available to the application. + +.. rubric:: 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:`ConfigurationSchedulersClustered` +is present, then it is used as the scheduler for up to 32 processors. .. Generated from spec:/acfg/if/scheduler-strong-apa +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_STRONG_APA .. _CONFIGURE_SCHEDULER_STRONG_APA: @@ -524,31 +639,40 @@ NOTES: CONFIGURE_SCHEDULER_STRONG_APA ------------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_STRONG_APA`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_SCHEDULER_STRONG_APA`` -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: OPTION TYPE: -DESCRIPTION: - In case this configuration option is defined, then the Strong APA algorithm - is made available to the application. +This configuration option is a boolean feature define. -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +.. rubric:: DEFAULT CONFIGURATION: - This scheduler algorithm is only available when RTEMS is built with SMP - support enabled. +If this configuration option is undefined, then the described feature is not +enabled. - This scheduler algorithm is not correctly implemented. Do not use it. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the Strong APA algorithm +is made available to the application. + +.. rubric:: 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. + +This scheduler algorithm is not correctly implemented. Do not use it. .. Generated from spec:/acfg/if/scheduler-user +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_SCHEDULER_USER .. _CONFIGURE_SCHEDULER_USER: @@ -556,42 +680,47 @@ NOTES: CONFIGURE_SCHEDULER_USER ------------------------ -CONSTANT: - ``CONFIGURE_SCHEDULER_USER`` +.. rubric:: CONSTANT: + +``CONFIGURE_SCHEDULER_USER`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +In case this configuration option is defined, then the user shall provide a +scheduler algorithm to the application. -DESCRIPTION: - In case this configuration option is defined, then the user shall provide a - scheduler algorithm to the application. +.. rubric:: NOTES: -NOTES: - This scheduler configuration option is an advanced configuration option. - Think twice before you use it. +This scheduler configuration option is an advanced configuration option. +Think twice before you use it. - RTEMS allows the application to provide its own task/thread scheduling - algorithm. In order to do this, one shall define - ``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its own - scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined then the - following additional macros shall be defined: +RTEMS allows the application to provide its own task/thread scheduling +algorithm. In order to do this, one shall define +``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its own +scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined then the +following additional macros shall be defined: - * ``CONFIGURE_SCHEDULER`` shall be defined to a static definition of - the scheduler data structures of the user scheduler. +* ``CONFIGURE_SCHEDULER`` shall be defined to a static definition of + the scheduler data structures of the user scheduler. - * ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` shall be defined to a scheduler - table entry initializer for the user scheduler. +* ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` shall be defined to a scheduler + table entry initializer for the user scheduler. - * ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` shall be defined to the type of - the per-thread information of the user scheduler. +* ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` shall be defined to the type of + the per-thread information of the user scheduler. - 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. +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. diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst index 792c4b8..187bff5 100644 --- a/c-user/config/task-stack-alloc.rst +++ b/c-user/config/task-stack-alloc.rst @@ -31,6 +31,10 @@ overflows are detected in hardware. .. Generated from spec:/acfg/if/task-stack-allocator +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_ALLOCATOR .. index:: task stack allocator @@ -39,35 +43,45 @@ overflows are detected in hardware. CONFIGURE_TASK_STACK_ALLOCATOR ------------------------------ -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: -OPTION TYPE: - This configuration option is an initializer define. +The default value is ``_Workspace_Allocate``, which indicates that task +stacks will be allocated from the RTEMS Workspace. -DEFAULT VALUE: - The default value is ``_Workspace_Allocate``, which indicates that task - stacks will be allocated from the RTEMS Workspace. +.. rubric:: DESCRIPTION: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *allocate )( size_t )``. +The value of this configuration option initializes the stack allocator +allocate handler. -DESCRIPTION: - The value of this configuration option initializes the stack allocator - allocate handler. +.. rubric:: NOTES: -NOTES: - A correctly configured system shall configure the following to be consistent: +A correctly configured system shall configure the following to be consistent: - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` - * ``CONFIGURE_TASK_STACK_ALLOCATOR`` +* ``CONFIGURE_TASK_STACK_ALLOCATOR`` - * :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *allocate )( size_t )``. .. Generated from spec:/acfg/if/task-stack-no-workspace +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE .. _CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE: @@ -75,26 +89,35 @@ NOTES: CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE ------------------------------------------------ -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is a boolean feature define. +This configuration option is a boolean feature define. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DEFAULT CONFIGURATION: -DESCRIPTION: - In case this configuration option is defined, then the system is informed - that the task stack allocator does not use the RTEMS Workspace. +If this configuration option is undefined, then the described feature is not +enabled. -NOTES: - This configuration option may be used if a custom task stack allocator is - configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the system is informed +that the task stack allocator does not use the RTEMS Workspace. + +.. rubric:: NOTES: + +This configuration option may be used if a custom task stack allocator is +configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. .. Generated from spec:/acfg/if/task-stack-allocator-for-idle +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE .. index:: task stack allocator for IDLE tasks @@ -103,34 +126,44 @@ NOTES: CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE --------------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is ``_Stack_Allocator_allocate_for_idle_default``, which - indicates that IDLE task stacks will be allocated from an area statically - allocated by ``<rtems/confdefs.h>``. +This configuration option is an initializer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *allocate )( uint32_t, size_t )``. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option is the address for the stack allocator - allocate handler used to allocate the task stack of each - :term:`IDLE task`. +The default value is ``_Stack_Allocator_allocate_for_idle_default``, which +indicates that IDLE task stacks will be allocated from an area statically +allocated by ``<rtems/confdefs.h>``. -NOTES: - This configuration option is independent of the other thread stack allocator - configuration options. It is assumed that any memory allocated for the stack - of an :term:`IDLE task` will not be from the RTEMS Workspace or the - memory statically allocated by default. +.. rubric:: DESCRIPTION: + +The value of this configuration option is the address for the stack allocator +allocate handler used to allocate the task stack of each +:term:`IDLE task`. + +.. rubric:: NOTES: + +This configuration option is independent of the other thread stack allocator +configuration options. It is assumed that any memory allocated for the stack +of an :term:`IDLE task` will not be from the RTEMS Workspace or the +memory statically allocated by default. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *allocate )( uint32_t, size_t )``. .. Generated from spec:/acfg/if/task-stack-allocator-init +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT .. _CONFIGURE_TASK_STACK_ALLOCATOR_INIT: @@ -138,35 +171,45 @@ NOTES: CONFIGURE_TASK_STACK_ALLOCATOR_INIT ----------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is `NULL <https://en.cppreference.com/w/c/types/NULL>`_. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is `NULL <https://en.cppreference.com/w/c/types/NULL>`_. +The value of this configuration option initializes the stack allocator +initialization handler. -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *initialize )( size_t )`` or to `NULL - <https://en.cppreference.com/w/c/types/NULL>`_. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option initializes the stack allocator - initialization handler. +A correctly configured system shall configure the following to be consistent: -NOTES: - A correctly configured system shall configure the following to be consistent: +* ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` - * ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` - * :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *initialize )( size_t )`` or to `NULL +<https://en.cppreference.com/w/c/types/NULL>`_. .. Generated from spec:/acfg/if/task-stack-deallocator +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_DEALLOCATOR .. index:: task stack deallocator @@ -175,35 +218,45 @@ NOTES: CONFIGURE_TASK_STACK_DEALLOCATOR -------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_DEALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: DEFAULT VALUE: -DEFAULT VALUE: - The default value is ``_Workspace_Free``, which indicates that task stacks - will be allocated from the RTEMS Workspace. +The default value is ``_Workspace_Free``, which indicates that task stacks +will be allocated from the RTEMS Workspace. -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *deallocate )( void * )``. +.. rubric:: DESCRIPTION: -DESCRIPTION: - The value of this configuration option initializes the stack allocator - deallocate handler. +The value of this configuration option initializes the stack allocator +deallocate handler. -NOTES: - A correctly configured system shall configure the following to be consistent: +.. rubric:: NOTES: - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +A correctly configured system shall configure the following to be consistent: - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` - * ``CONFIGURE_TASK_STACK_DEALLOCATOR`` +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` + +* ``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *deallocate )( void * )``. .. Generated from spec:/acfg/if/task-stack-from-alloc +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_FROM_ALLOCATOR .. index:: task stack allocator @@ -212,26 +265,31 @@ NOTES: CONFIGURE_TASK_STACK_FROM_ALLOCATOR ----------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_FROM_ALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_FROM_ALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is a macro which supports the system heap allocator. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an initializer define. +The value of this configuration option is used to calculate the task stack +space size. -DEFAULT VALUE: - The default value is a macro which supports the system heap allocator. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a macro which - accepts exactly one parameter and returns an unsigned integer. The - parameter will be an allocation size and the macro shall return this size - plus the overhead of the allocator to manage an allocation request for this - size. +This configuration option may be used if a custom task stack allocator is +configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. -DESCRIPTION: - The value of this configuration option is used to calculate the task stack - space size. +.. rubric:: CONSTRAINTS: -NOTES: - This configuration option may be used if a custom task stack allocator is - configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. +The value of the configuration option shall be defined to a macro which accepts +exactly one parameter and returns an unsigned integer. The parameter will be +an allocation size and the macro shall return this size plus the overhead of +the allocator to manage an allocation request for this size. |