diff options
Diffstat (limited to 'c-user/config/general.rst')
| -rw-r--r-- | c-user/config/general.rst | 1342 |
1 files changed, 845 insertions, 497 deletions
diff --git a/c-user/config/general.rst b/c-user/config/general.rst index 1a43b03..61bfa1e 100644 --- a/c-user/config/general.rst +++ b/c-user/config/general.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) 2020, 2023 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2022 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 @@ -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,90 @@ 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: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: 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. + +.. rubric:: 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. + +See also :ref:`CONFIGURE_MALLOC_DIRTY`. + +.. Generated from spec:/acfg/if/disable-bsp-settings + +.. raw:: latex + + \clearpage -OPTION TYPE: - This configuration option is a boolean feature define. +.. index:: CONFIGURE_DISABLE_BSP_SETTINGS -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. _CONFIGURE_DISABLE_BSP_SETTINGS: -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. +CONFIGURE_DISABLE_BSP_SETTINGS +------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_DISABLE_BSP_SETTINGS`` + +.. 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. + +.. rubric:: DESCRIPTION: -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. +In case this configuration option is defined, then the optional BSP provided +settings listed below are disabled. - See also :ref:`CONFIGURE_MALLOC_DIRTY`. +The optional BSP provided default values for the following application +configuration options are disabled: + +* :ref:`CONFIGURE_IDLE_TASK_BODY` + +* :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` + +* :ref:`CONFIGURE_INTERRUPT_STACK_SIZE` + +The optional BSP provided initial extension set is disabled (see +:term:`initial extension sets`). The optional BSP provided +prerequisite IO device drivers are disabled (see +Device Driver Configuration). The optional BSP provided support for +:c:func:`sbrk` is disabled. + +This configuration option provides an all or nothing choice with respect to +the optional BSP provided settings. .. Generated from spec:/acfg/if/disable-newlib-reentrancy +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_DISABLE_NEWLIB_REENTRANCY .. _CONFIGURE_DISABLE_NEWLIB_REENTRANCY: @@ -67,28 +129,37 @@ NOTES: CONFIGURE_DISABLE_NEWLIB_REENTRANCY ----------------------------------- -CONSTANT: - ``CONFIGURE_DISABLE_NEWLIB_REENTRANCY`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is a boolean feature define. +``CONFIGURE_DISABLE_NEWLIB_REENTRANCY`` -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 Newlib reentrancy - support per thread is disabled and a global reentrancy structure is used. +This configuration option is a boolean feature define. -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:: 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 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 +167,49 @@ NOTES: CONFIGURE_EXECUTIVE_RAM_SIZE ---------------------------- -CONSTANT: - ``CONFIGURE_EXECUTIVE_RAM_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_EXECUTIVE_RAM_SIZE`` -OPTION TYPE: - This configuration option is an integer define. +.. rubric:: OPTION TYPE: -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. +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. +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. - * It shall be less than or equal to `UINTPTR_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +.. 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 RTEMS Workspace size in +bytes. -DESCRIPTION: - The value of this configuration option defines the RTEMS Workspace size in - bytes. +.. rubric:: NOTES: -NOTES: - This is an advanced configuration option. Use it only if you know exactly - what you are doing. +This is an advanced configuration option. Use it only if you know exactly +what you are doing. + +.. 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 + `UINTPTR_MAX <https://en.cppreference.com/w/c/types/integer>`_. + +* 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 +218,83 @@ 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: + +The default value is 0. + +.. rubric:: 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:: 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>``. + +.. 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 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/init -OPTION TYPE: - This configuration option is an integer define. +.. raw:: latex -DEFAULT VALUE: - The default value is 0. + \clearpage -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +.. index:: CONFIGURE_INIT - * It shall be greater than or equal to zero. +.. _CONFIGURE_INIT: - * 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 +-------------- -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:: CONSTANT: -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>``. +``CONFIGURE_INIT`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +There is no default configuration associated with this configuration option. +If ``<rtems/confdefs.h>`` is included and this configuration option is not +defined, then only white space is included. + +.. rubric:: DESCRIPTION: + +While this configuration option is defined, when the ``<rtems/confdefs.h>`` +is included, the system settings defined by present application configuration +options are statically allocated and initialized. All user provided +application configuration options defined before the include of +``<rtems/confdefs.h>`` are evaluated. They define the actual system +settings. .. Generated from spec:/acfg/if/initial-extensions +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INITIAL_EXTENSIONS .. _CONFIGURE_INITIAL_EXTENSIONS: @@ -176,30 +302,40 @@ NOTES: CONFIGURE_INITIAL_EXTENSIONS ---------------------------- -CONSTANT: - ``CONFIGURE_INITIAL_EXTENSIONS`` +.. rubric:: CONSTANT: -OPTION TYPE: - This configuration option is an initializer define. +``CONFIGURE_INITIAL_EXTENSIONS`` -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_extensions_table`. +This configuration option is an initializer define. -DESCRIPTION: - The value of this configuration option is used to initialize the table of - initial user extensions. +.. rubric:: DEFAULT VALUE: -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. +The default value is the empty list. + +.. 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 +:c:macro:`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 :ref:`InterfaceRtemsExtensionsTable`. .. Generated from spec:/acfg/if/interrupt-stack-size +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_INTERRUPT_STACK_SIZE .. index:: interrupt stack size @@ -208,54 +344,67 @@ 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: + +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_INTERRUPT_STACK_SIZE` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_INTERRUPT_STACK_SIZE`, otherwise the default value is +:c:macro:`CPU_STACK_MINIMUM_SIZE`. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the size of an interrupt stack +in bytes. -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:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +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 greater than or equal to a BSP-specific and - application-specific minimum value. +Some BSPs use the interrupt stack as the initialization stack which is used +to perform the sequential system initialization before the multithreading +is started. - * 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 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. - * It shall be aligned according to - :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`. +In releases before RTEMS 5.1 the default value was +:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of +:c:macro:`CPU_STACK_MINIMUM_SIZE`. -DESCRIPTION: - The value of this configuration option defines the size of an interrupt stack - in bytes. +.. rubric:: CONSTRAINTS: -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. +The following constraints apply to this configuration option: - Some BSPs use the interrupt stack as the initialization stack which is used - to perform the sequential system initialization before the multithreading - is started. +* The value of the configuration option shall be greater than or equal to a + BSP-specific and application-specific minimum value. - 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 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>`_. - 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 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 +412,38 @@ NOTES: CONFIGURE_MALLOC_DIRTY ---------------------- -CONSTANT: - ``CONFIGURE_MALLOC_DIRTY`` +.. rubric:: CONSTANT: + +``CONFIGURE_MALLOC_DIRTY`` + +.. 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 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. -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: -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. +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 +452,47 @@ NOTES: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 3. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the maximum number of file +like objects that can be concurrently open. -DEFAULT VALUE: - The default value is 3. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value of three file descriptors allows RTEMS to support standard +input, output, and error I/O streams on :file:`/dev/console`. - * It shall be greater than or equal to zero. +.. 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 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 maximum number of file - like objects that can be concurrently open. +* The value of the configuration option shall be less than or equal to + `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_. -NOTES: - The default value of three file descriptors allows RTEMS to support standard - input, output, and error I/O streams on :file:`/dev/console`. +* 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 +500,113 @@ NOTES: CONFIGURE_MAXIMUM_PROCESSORS ---------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_PROCESSORS`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_PROCESSORS`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 1. + +.. rubric:: 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. + +.. rubric:: NOTES: + +If there are more processors available than configured, the rest will be +ignored. + +This configuration option is only evaluated in SMP configurations of RTEMS +(e.g. RTEMS was built with the SMP build configuration option enabled). +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-local-storage-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE + +.. _CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE: -OPTION TYPE: - This configuration option is an integer define. +CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE +------------------------------------------- -DEFAULT VALUE: - The default value is 1. +.. rubric:: CONSTANT: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +``CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`` - * It shall be greater than or equal to one. +.. rubric:: OPTION TYPE: - * It shall be less than or equal to :c:macro:`CPU_MAXIMUM_PROCESSORS`. +This configuration option is an integer define. -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. +.. rubric:: DEFAULT VALUE: -NOTES: - If there are more processors available than configured, the rest will be - ignored. +The default value is 0. - 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:: 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:: NOTES: + +This configuration option can be used to reserve space for the dynamic linking +of modules with thread-local storage objects. + +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. + +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 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. + +.. 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 an integral multiple of + :c:macro:`RTEMS_TASK_STORAGE_ALIGNMENT`. .. 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 +615,52 @@ NOTES: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE ---------------------------------- -CONSTANT: - ``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE`` +.. rubric:: CONSTANT: + +``CONFIGURE_MAXIMUM_THREAD_NAME_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 16. +.. rubric:: DEFAULT VALUE: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +The default value is 16. - * It shall be greater than or equal to zero. +.. rubric:: DESCRIPTION: - * It shall be less than or equal to `SIZE_MAX - <https://en.cppreference.com/w/c/types/limits>`_. +The value of this configuration option defines the maximum thread name size +including the terminating ``NUL`` character. - * 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 thread name size - including the terminating ``NUL`` character. +The default value was chosen for Linux compatibility, see +`pthread_setname_np() <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_. -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 size of the thread control block is increased by the maximum thread name +size. - The size of the thread control block is increased by the maximum thread name - size. +This configuration option is available since RTEMS 5.1. - This configuration option is available since RTEMS 5.1. +.. 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/memory-overhead +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_MEMORY_OVERHEAD .. _CONFIGURE_MEMORY_OVERHEAD: @@ -419,43 +668,53 @@ NOTES: CONFIGURE_MEMORY_OVERHEAD ------------------------- -CONSTANT: - ``CONFIGURE_MEMORY_OVERHEAD`` +.. rubric:: CONSTANT: + +``CONFIGURE_MEMORY_OVERHEAD`` + +.. 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 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 number of kilobytes the +application wishes to add to the RTEMS Workspace size calculated by +``<rtems/confdefs.h>``. - * 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: -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>``. +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`. -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`. +.. 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/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 +725,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 +820,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 +886,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 +951,38 @@ NOTES: CONFIGURE_STACK_CHECKER_ENABLED ------------------------------- -CONSTANT: - ``CONFIGURE_STACK_CHECKER_ENABLED`` +.. rubric:: CONSTANT: + +``CONFIGURE_STACK_CHECKER_ENABLED`` + +.. 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 stack checker is - enabled. +.. rubric:: DESCRIPTION: -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 case this configuration option is defined, then the stack checker is +enabled. - In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``. +.. 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 +991,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. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an integer define. +The value of this configuration option defines the length of the timeslice +quantum in ticks for each task. -DEFAULT VALUE: - The default value is 50. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall satisfy all of the following - constraints: +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 greater than or equal to zero. +.. rubric:: CONSTRAINTS: - * It shall be less than or equal to `UINT32_MAX - <https://en.cppreference.com/w/c/types/integer>`_. +The following constraints apply to this configuration option: -DESCRIPTION: - The value of this configuration option defines the length of the timeslice - quantum in ticks for each task. +* The value of the configuration option shall be greater than or equal to one. -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 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 +1039,42 @@ NOTES: CONFIGURE_UNIFIED_WORK_AREAS ---------------------------- -CONSTANT: - ``CONFIGURE_UNIFIED_WORK_AREAS`` +.. rubric:: CONSTANT: + +``CONFIGURE_UNIFIED_WORK_AREAS`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then there will be separate memory +pools for the RTEMS Workspace and C Program Heap. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: DESCRIPTION: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then there will be separate memory - pools for the RTEMS Workspace and C Program Heap. +In case this configuration option is defined, then the RTEMS Workspace and +the C Program Heap will be one pool of memory. -DESCRIPTION: - In case this configuration option is defined, then the RTEMS Workspace and - the C Program Heap will be one pool of memory. +.. rubric:: NOTES: -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. +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. +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 +1082,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 :ref:`InterfaceRtemsResourceUnlimited` 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 +1127,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: + +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 unlimited objects are used +by default. -DESCRIPTION: - In case this configuration option is defined, then unlimited objects are used - by default. +.. rubric:: NOTES: -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. +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. - This option does not override an explicit configuration for a particular - object class by the user. +This option does not override an explicit configuration for a particular +object class by the user. - See also :ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`. +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 +1169,35 @@ NOTES: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION --------------------------------------- -CONSTANT: - ``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` +.. rubric:: CONSTANT: + +``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION`` + +.. 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 system initialization +is verbose. -DESCRIPTION: - In case this configuration option is defined, then the system initialization - is verbose. +.. rubric:: NOTES: -NOTES: - You may use this feature to debug system initialization issues. The - :c:func:`printk` function is used to print the information. +You may use this feature to debug system initialization issues. The +:ref:`InterfacePrintk` 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 +1209,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. |