diff options
| author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-11-16 08:17:31 +0100 |
|---|---|---|
| committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-11-17 09:08:53 +0100 |
| commit | 1c8ce332e273bb9f10cdb18e32e977cb9301fbad (patch) | |
| tree | 8622528cf6fb748d6196ba5b9a46bf8c10b941bc /c-user/config | |
| parent | c-user: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS (diff) | |
| download | rtems-docs-1c8ce332e273bb9f10cdb18e32e977cb9301fbad.tar.bz2 | |
c-user: Use rubric for configuration options
Clear the page for each configuration options similar to the directives.
Use a rubric instead of a definition list for the application
configuration options similar to the directive documentation pages. For
direcives and application configuration options use the same rubric
order.
Generalize value constraints to constraints.
This patch does not change hand written content.
Diffstat (limited to 'c-user/config')
| -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. |