diff options
Diffstat (limited to '')
| -rw-r--r-- | c-user/config/bdbuf.rst | 2 | ||||
| -rw-r--r-- | c-user/config/bsp-related.rst | 355 | ||||
| -rw-r--r-- | c-user/config/classic-api.rst | 107 | ||||
| -rw-r--r-- | c-user/config/classic-init-task.rst | 17 | ||||
| -rw-r--r-- | c-user/config/device-driver.rst | 23 | ||||
| -rw-r--r-- | c-user/config/directives.rst | 1550 | ||||
| -rw-r--r-- | c-user/config/event-record.rst | 43 | ||||
| -rw-r--r-- | c-user/config/face-technical-standard.rst | 76 | ||||
| -rw-r--r-- | c-user/config/filesystem.rst | 39 | ||||
| -rw-r--r-- | c-user/config/general.rst | 175 | ||||
| -rw-r--r-- | c-user/config/idle-task.rst | 96 | ||||
| -rw-r--r-- | c-user/config/index.rst | 4 | ||||
| -rw-r--r-- | c-user/config/intro.rst | 123 | ||||
| -rw-r--r-- | c-user/config/introduction.rst | 227 | ||||
| -rw-r--r-- | c-user/config/mpci.rst | 4 | ||||
| -rw-r--r-- | c-user/config/posix-api.rst | 46 | ||||
| -rw-r--r-- | c-user/config/posix-init-thread.rst | 7 | ||||
| -rw-r--r-- | c-user/config/scheduler-general.rst | 13 | ||||
| -rw-r--r-- | c-user/config/task-stack-alloc.rst | 39 |
19 files changed, 2337 insertions, 609 deletions
diff --git a/c-user/config/bdbuf.rst b/c-user/config/bdbuf.rst index a897fa9..2d27d54 100644 --- a/c-user/config/bdbuf.rst +++ b/c-user/config/bdbuf.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically diff --git a/c-user/config/bsp-related.rst b/c-user/config/bsp-related.rst deleted file mode 100644 index b13a91d..0000000 --- a/c-user/config/bsp-related.rst +++ /dev/null @@ -1,355 +0,0 @@ -.. 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) - -.. This file is part of the RTEMS quality process and was automatically -.. generated. If you find something that needs to be fixed or -.. worded better please post a report or patch to an RTEMS mailing list -.. or raise a bug report: -.. -.. https://www.rtems.org/bugs.html -.. -.. For information on updating and regenerating please refer to the How-To -.. section in the Software Requirements Engineering chapter of the -.. RTEMS Software Engineering manual. The manual is provided as a part of -.. a release. For development sources please refer to the online -.. documentation at: -.. -.. https://docs.rtems.org - -.. Generated from spec:/acfg/if/group-bsp - -BSP Related Configuration Options -================================= - -This section describes configuration options related to the BSP. Some -configuration options may have a BSP-specific setting which is defined by -``<bsp.h>``. The BSP-specific settings can be disabled by the -:ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option. - -.. Generated from spec:/acfg/if/bsp-idle-task-body - -.. raw:: latex - - \clearpage - -.. index:: BSP_IDLE_TASK_BODY - -.. _BSP_IDLE_TASK_BODY: - -BSP_IDLE_TASK_BODY ------------------- - -.. rubric:: CONSTANT: - -``BSP_IDLE_TASK_BODY`` - -.. rubric:: OPTION TYPE: - -This configuration option is an initializer define. - -.. rubric:: DEFAULT VALUE: - -The default value is BSP-specific. - -.. rubric:: DESCRIPTION: - -If - -* this configuration option is defined by the BSP - -* 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`. - -.. rubric:: 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. - -.. 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: - -BSP_IDLE_TASK_STACK_SIZE ------------------------- - -.. rubric:: CONSTANT: - -``BSP_IDLE_TASK_STACK_SIZE`` - -.. rubric:: OPTION TYPE: - -This configuration option is an integer define. - -.. rubric:: DEFAULT VALUE: - -The default value is BSP-specific. - -.. rubric:: DESCRIPTION: - -If - -* this configuration option is defined by the BSP - -* 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`. - -.. 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 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: - -BSP_INITIAL_EXTENSION ---------------------- - -.. rubric:: CONSTANT: - -``BSP_INITIAL_EXTENSION`` - -.. rubric:: OPTION TYPE: - -This configuration option is an initializer define. - -.. rubric:: DEFAULT VALUE: - -The default value is BSP-specific. - -.. rubric:: DESCRIPTION: - -If - -* this configuration option is defined by the BSP - -* and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - -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: - -BSP_INTERRUPT_STACK_SIZE ------------------------- - -.. rubric:: CONSTANT: - -``BSP_INTERRUPT_STACK_SIZE`` - -.. rubric:: OPTION TYPE: - -This configuration option is an integer define. - -.. rubric:: DEFAULT VALUE: - -The default value is BSP-specific. - -.. rubric:: DESCRIPTION: - -If - -* this configuration option is defined by the BSP - -* 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`. - -.. 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: - -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: - -If - -* this configuration option is defined by the BSP - -* and :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` is undefined, - -then the value of this configuration option is used to add BSP-provided -prerequisite drivers to the Device Driver Table. - -.. rubric:: NOTES: - -The value of this configuration option is placed before the entries of all -other initial user extensions (including -:ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`). - -.. 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/disable-bsp-settings - -.. raw:: latex - - \clearpage - -.. index:: CONFIGURE_DISABLE_BSP_SETTINGS - -.. _CONFIGURE_DISABLE_BSP_SETTINGS: - -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: - -In case this configuration option is defined, then the following BSP related -configuration options are undefined: - -* :ref:`BSP_IDLE_TASK_BODY` - -* :ref:`BSP_IDLE_TASK_STACK_SIZE` - -* :ref:`BSP_INITIAL_EXTENSION` - -* :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: - -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. - -.. rubric:: DESCRIPTION: - -If - -* this configuration option is defined by the BSP - -* 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. - -.. rubric:: NOTES: - -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 4981918..212f666 100644 --- a/c-user/config/classic-api.rst +++ b/c-user/config/classic-api.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -73,8 +73,8 @@ The following constraints apply to this configuration option: 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-message-queues @@ -127,8 +127,8 @@ The following constraints apply to this configuration option: 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-partitions @@ -179,8 +179,8 @@ The following constraints apply to this configuration option: 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-periods @@ -231,8 +231,8 @@ The following constraints apply to this configuration option: 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-ports @@ -283,8 +283,8 @@ The following constraints apply to this configuration option: 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-regions @@ -335,8 +335,8 @@ The following constraints apply to this configuration option: 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-semaphores @@ -391,8 +391,8 @@ The following constraints apply to this configuration option: 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-tasks @@ -461,73 +461,10 @@ The following constraints apply to this configuration option: <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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` 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: - -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: - -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-timers .. raw:: latex @@ -576,8 +513,8 @@ The following constraints apply to this configuration option: 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-user-extensions @@ -654,15 +591,15 @@ The default value is 0. .. rubric:: DESCRIPTION: The value of this configuration option defines the minimum count of Classic -API Tasks which are constructed by :c:func:`rtems_task_construct`. +API Tasks which are constructed by :ref:`InterfaceRtemsTaskConstruct`. .. rubric:: 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 +:ref:`InterfaceRtemsTaskCreate`. 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 +tasks constructed by :ref:`InterfaceRtemsTaskConstruct` use a user-provided task storage area. .. rubric:: CONSTRAINTS: diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst index 0cc400d..f65bb8a 100644 --- a/c-user/config/classic-init-task.rst +++ b/c-user/config/classic-init-task.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -59,7 +59,7 @@ API initialization task. .. rubric:: CONSTRAINTS: The value of the configuration option shall be convertible to an integer of -type :c:type:`rtems_task_argument`. +type :ref:`InterfaceRtemsTaskArgument`. .. Generated from spec:/acfg/if/init-task-attributes @@ -135,8 +135,8 @@ If this configuration option is specified, then ``<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`, + :ref:`InterfaceRtemsTaskConstruct` instead of using + :ref:`InterfaceRtemsTaskCreate`, * the maximum thread-local storage size defined by :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` is used for the Classic API @@ -164,7 +164,7 @@ The following constraints apply to this configuration option: :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. * The value of the configuration option shall be defined using - :c:func:`RTEMS_TASK_STORAGE_SIZE`. + :ref:`InterfaceRTEMSTASKSTORAGESIZE`. .. Generated from spec:/acfg/if/init-task-entrypoint @@ -273,7 +273,7 @@ initialization task. .. rubric:: NOTES: -Use :c:func:`rtems_build_name` to define the task name. +Use :ref:`InterfaceRtemsBuildName` to define the task name. .. rubric:: CONSTRAINTS: @@ -401,7 +401,7 @@ initialization task is configured. .. rubric:: NOTES: -The application shall define exactly one of the following configuration +The application shall define at least one of the following configuration options * ``CONFIGURE_RTEMS_INIT_TASKS_TABLE``, @@ -411,3 +411,6 @@ options * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` otherwise a compile time error in the configuration file will occur. + +The Classic API initialization task performs the +:ref:`GlobalConstruction`. diff --git a/c-user/config/device-driver.rst b/c-user/config/device-driver.rst index d84da0a..1e31575 100644 --- a/c-user/config/device-driver.rst +++ b/c-user/config/device-driver.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -114,7 +114,7 @@ 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`. +structures of type :ref:`InterfaceRtemsDriverAddressTable`. .. Generated from spec:/acfg/if/appl-needs-ata-driver @@ -237,7 +237,7 @@ 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. -BSPs should be constructed in a manner that allows :c:func:`printk` to work +BSPs should be constructed in a manner that allows :ref:`InterfacePrintk` to work properly without the need for the Console Driver to be configured. The @@ -439,9 +439,9 @@ 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 :ref:`InterfaceGetchark`. -This device driver writes via :c:func:`rtems_putc`. +This device driver writes via :ref:`InterfaceRtemsPutc`. The Termios framework is not used. There is no support to change device settings, e.g. baud, stop bits, parity, etc. @@ -493,14 +493,14 @@ 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 :ref:`InterfaceGetchark`. 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. +:ref:`InterfaceRtemsPutc`. 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 @@ -709,7 +709,7 @@ Driver Table. .. rubric:: 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 +:c:macro:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver configuration options. See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement @@ -718,7 +718,7 @@ 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`. +structures of type :ref:`InterfaceRtemsDriverAddressTable`. .. Generated from spec:/acfg/if/ata-driver-task-priority @@ -858,7 +858,10 @@ options: * :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` -* :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +the :term:`BSP` provides +:c:macro:`CONFIGURE_BSP_PREREQUISITE_DRIVERS`, then the BSP-provided +prerequisite device drivers are also taken into account. .. rubric:: DESCRIPTION: diff --git a/c-user/config/directives.rst b/c-user/config/directives.rst new file mode 100644 index 0000000..25351e9 --- /dev/null +++ b/c-user/config/directives.rst @@ -0,0 +1,1550 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG +.. 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 +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _ApplicationConfigurationInformationDirectives: + +Directives +========== + +This section details the directives of the Application Configuration +Information. A subsection is dedicated to each of this manager's directives and +lists the calling sequence, parameters, description, return values, and notes +of the directive. + +.. Generated from spec:/rtems/config/if/get-build-label + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_build_label() + +.. _InterfaceRtemsGetBuildLabel: + +rtems_get_build_label() +----------------------- + +Gets the RTEMS build label. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_build_label( void ); + +.. rubric:: DESCRIPTION: + +The build label is a user-provided string defined by the build configuration +through the ``RTEMS_BUILD_LABEL`` build option. The format of the string is +completely user-defined. + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS build label. + +.. rubric:: NOTES: + +The build label can be used to distinguish test suite results obtained from +different build configurations. A use case is to record test results with +performance data to track performance regressions. For this a database of +performance limits is required. The build label and the target hash obtained +from :ref:`InterfaceRtemsGetTargetHash` can be used as a key to obtain +performance limits. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-copyright-notice + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_copyright_notice() + +.. _InterfaceRtemsGetCopyrightNotice: + +rtems_get_copyright_notice() +---------------------------- + +Gets the RTEMS copyright notice. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_copyright_notice( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS copyright notice. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-target-hash + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_target_hash() + +.. _InterfaceRtemsGetTargetHash: + +rtems_get_target_hash() +----------------------- + +Gets the RTEMS target hash. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_target_hash( void ); + +.. rubric:: DESCRIPTION: + +The target hash is calculated from BSP-specific values which characterize a +target system. The target hash is encoded as a base64url string. The target +hash algorithm is unspecified. + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS target hash. + +.. rubric:: NOTES: + +For example, the device tree, settings of the memory controller, processor and +bus frequencies, a serial number of a chip may be used to calculate the target +hash. + +The target hash can be used to distinguish test suite results obtained from +different target systems. See also :ref:`InterfaceRtemsGetBuildLabel`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-version-string + +.. raw:: latex + + \clearpage + +.. index:: rtems_get_version_string() + +.. _InterfaceRtemsGetVersionString: + +rtems_get_version_string() +-------------------------- + +Gets the RTEMS version string. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_get_version_string( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the RTEMS version string. + +.. rubric:: NOTES: + +The version string has no particular format. Parsing the string may break +across RTEMS releases. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-do-zero-of-workspace + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_do_zero_of_workspace() + +.. _InterfaceRtemsConfigurationGetDoZeroOfWorkspace: + +rtems_configuration_get_do_zero_of_workspace() +---------------------------------------------- + +Indicates if the RTEMS Workspace is configured to be zeroed during system +initialization for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_do_zero_of_workspace( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the RTEMS Workspace is configured to be zeroed during system +initialization for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the :ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` +application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-idle-task-stack-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_idle_task_stack_size() + +.. _InterfaceRtemsConfigurationGetIdleTaskStackSize: + +rtems_configuration_get_idle_task_stack_size() +---------------------------------------------- + +Gets the IDLE task stack size in bytes of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_configuration_get_idle_task_stack_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the IDLE task stack size in bytes of this application. + +.. rubric:: NOTES: + +The IDLE task stack size is defined by the +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-idle-task + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_idle_task() + +.. _InterfaceRtemsConfigurationGetIdleTask: + +rtems_configuration_get_idle_task() +----------------------------------- + +Gets the IDLE task body of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( uintptr_t ) rtems_configuration_get_idle_task( void ); + +.. rubric:: RETURN VALUES: + +Returns the IDLE task body of this application. + +.. rubric:: NOTES: + +The IDLE task body is defined by the :ref:`CONFIGURE_IDLE_TASK_BODY` +application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-interrupt-stack-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_interrupt_stack_size() + +.. _InterfaceRtemsConfigurationGetInterruptStackSize: + +rtems_configuration_get_interrupt_stack_size() +---------------------------------------------- + +Gets the interrupt stack size in bytes of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + size_t rtems_configuration_get_interrupt_stack_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the interrupt stack size in bytes of this application. + +.. rubric:: NOTES: + +The interrupt stack size is defined by the +:ref:`CONFIGURE_INTERRUPT_STACK_SIZE` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-barriers + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_barriers() + +.. _InterfaceRtemsConfigurationGetMaximumBarriers: + +rtems_configuration_get_maximum_barriers() +------------------------------------------ + +Gets the resource number of :ref:`RTEMSAPIClassicBarrier` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_barriers( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicBarrier` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_BARRIERS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-extensions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_extensions() + +.. _InterfaceRtemsConfigurationGetMaximumExtensions: + +rtems_configuration_get_maximum_extensions() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicUserExt` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_extensions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicUserExt` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_USER_EXTENSIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-message-queues + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_message_queues() + +.. _InterfaceRtemsConfigurationGetMaximumMessageQueues: + +rtems_configuration_get_maximum_message_queues() +------------------------------------------------ + +Gets the resource number of :ref:`RTEMSAPIClassicMessage` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_message_queues( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicMessage` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-partitions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_partitions() + +.. _InterfaceRtemsConfigurationGetMaximumPartitions: + +rtems_configuration_get_maximum_partitions() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicPart` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_partitions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicPart` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PARTITIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-periods + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_periods() + +.. _InterfaceRtemsConfigurationGetMaximumPeriods: + +rtems_configuration_get_maximum_periods() +----------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicRatemon` objects configured +for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_periods( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicRatemon` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PERIODS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-ports + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_ports() + +.. _InterfaceRtemsConfigurationGetMaximumPorts: + +rtems_configuration_get_maximum_ports() +--------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicDPMem` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_ports( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicDPMem` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_PORTS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-processors + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_processors() + +.. _InterfaceRtemsConfigurationGetMaximumProcessors: + +rtems_configuration_get_maximum_processors() +-------------------------------------------- + +Gets the maximum number of processors configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_processors( void ); + +.. rubric:: RETURN VALUES: + +Returns the maximum number of processors configured for this application. + +.. rubric:: NOTES: + +The actual number of processors available to the application is returned by +:ref:`InterfaceRtemsSchedulerGetProcessorMaximum` which less than or equal to +the configured maximum number of processors +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). + +In uniprocessor configurations, this macro is a compile time constant which +evaluates to one. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-regions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_regions() + +.. _InterfaceRtemsConfigurationGetMaximumRegions: + +rtems_configuration_get_maximum_regions() +----------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicRegion` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_regions( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicRegion` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_REGIONS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-semaphores + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_semaphores() + +.. _InterfaceRtemsConfigurationGetMaximumSemaphores: + +rtems_configuration_get_maximum_semaphores() +-------------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicSem` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_semaphores( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicSem` objects configured for +this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_SEMAPHORES` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-tasks + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_tasks() + +.. _InterfaceRtemsConfigurationGetMaximumTasks: + +rtems_configuration_get_maximum_tasks() +--------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicTasks` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_tasks( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicTasks` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_TASKS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-maximum-timers + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_maximum_timers() + +.. _InterfaceRtemsConfigurationGetMaximumTimers: + +rtems_configuration_get_maximum_timers() +---------------------------------------- + +Gets the resource number of :ref:`RTEMSAPIClassicTimer` objects configured for +this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_maximum_timers( void ); + +.. rubric:: RETURN VALUES: + +Returns the resource number of :ref:`RTEMSAPIClassicTimer` objects configured +for this application. + +.. rubric:: NOTES: + +The resource number is defined by the :ref:`CONFIGURE_MAXIMUM_TIMERS` +application configuration option. See also +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-microseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_microseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetMicrosecondsPerTick: + +rtems_configuration_get_microseconds_per_tick() +----------------------------------------------- + +Gets the number of microseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_microseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of microseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of microseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-milliseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_milliseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetMillisecondsPerTick: + +rtems_configuration_get_milliseconds_per_tick() +----------------------------------------------- + +Gets the number of milliseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_milliseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of milliseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of milliseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-nanoseconds-per-tick + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_nanoseconds_per_tick() + +.. _InterfaceRtemsConfigurationGetNanosecondsPerTick: + +rtems_configuration_get_nanoseconds_per_tick() +---------------------------------------------- + +Gets the number of microseconds per clock tick configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_nanoseconds_per_tick( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of microseconds per clock tick configured for this +application. + +.. rubric:: NOTES: + +The number of nanoseconds per :term:`clock tick` is defined by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-number-of-initial-extensions + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_number_of_initial_extensions() + +.. _InterfaceRtemsConfigurationGetNumberOfInitialExtensions: + +rtems_configuration_get_number_of_initial_extensions() +------------------------------------------------------ + +Gets the number of initial extensions configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_number_of_initial_extensions( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of initial extensions configured for this application. + +.. rubric:: NOTES: + +The number of initial extensions is defined by the +:ref:`CONFIGURE_INITIAL_EXTENSIONS` application configuration option and +related options. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocate-for-idle-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_for_idle_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateForIdleHook: + +rtems_configuration_get_stack_allocate_for_idle_hook() +------------------------------------------------------ + +Gets the task stack allocator allocate hook used to allocate the stack of each +:term:`IDLE task` configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( uint32_t, size_t * ) + rtems_configuration_get_stack_allocate_for_idle_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator allocate hook used to allocate the stack of +each :term:`IDLE task` configured for this application. + +.. rubric:: NOTES: + +The task stack allocator allocate hook for idle tasks is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE` application configuration +option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocate-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateHook: + +rtems_configuration_get_stack_allocate_hook() +--------------------------------------------- + +Gets the task stack allocator allocate hook configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void *( * )( size_t ) rtems_configuration_get_stack_allocate_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator allocate hook configured for this application. + +.. rubric:: NOTES: + +The task stack allocator allocate hook is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocate-init-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocate_init_hook() + +.. _InterfaceRtemsConfigurationGetStackAllocateInitHook: + +rtems_configuration_get_stack_allocate_init_hook() +-------------------------------------------------- + +Gets the task stack allocator initialization hook configured for this +application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void ( * )( size_t ) rtems_configuration_get_stack_allocate_init_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator initialization hook configured for this +application. + +.. rubric:: NOTES: + +The task stack allocator initialization hook is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-allocator-avoids-work-space + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_allocator_avoids_work_space() + +.. _InterfaceRtemsConfigurationGetStackAllocatorAvoidsWorkSpace: + +rtems_configuration_get_stack_allocator_avoids_work_space() +----------------------------------------------------------- + +Indicates if the task stack allocator is configured to avoid the RTEMS +Workspace for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_stack_allocator_avoids_work_space( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the task stack allocator is configured to avoid the RTEMS +Workspace for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the +:ref:`CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE` application +configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-free-hook + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_free_hook() + +.. _InterfaceRtemsConfigurationGetStackFreeHook: + +rtems_configuration_get_stack_free_hook() +----------------------------------------- + +Gets the task stack allocator free hook configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void ( * )( void * ) rtems_configuration_get_stack_free_hook( void ); + +.. rubric:: RETURN VALUES: + +Returns the task stack allocator free hook configured for this application. + +.. rubric:: NOTES: + +The task stack allocator free hook is defined by the +:ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-stack-space-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_stack_space_size() + +.. _InterfaceRtemsConfigurationGetStackSpaceSize: + +rtems_configuration_get_stack_space_size() +------------------------------------------ + +Gets the configured size in bytes of the memory space used to allocate thread +stacks for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uintptr_t rtems_configuration_get_stack_space_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the configured size in bytes of the memory space used to allocate +thread stacks for this application. + +.. rubric:: NOTES: + +The size takes only threads and tasks into account with are known at the +application configuration time. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-ticks-per-timeslice + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_ticks_per_timeslice() + +.. _InterfaceRtemsConfigurationGetTicksPerTimeslice: + +rtems_configuration_get_ticks_per_timeslice() +--------------------------------------------- + +Gets the clock ticks per timeslice configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_configuration_get_ticks_per_timeslice( void ); + +.. rubric:: RETURN VALUES: + +Returns the clock ticks per timeslice configured for this application. + +.. rubric:: NOTES: + +The :term:`clock ticks <clock tick>` per timeslice is defined by the +:ref:`CONFIGURE_TICKS_PER_TIMESLICE` application configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-unified-work-area + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_unified_work_area() + +.. _InterfaceRtemsConfigurationGetUnifiedWorkArea: + +rtems_configuration_get_unified_work_area() +------------------------------------------- + +Indicates if the RTEMS Workspace and C Program Heap are configured to be +unified for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_configuration_get_unified_work_area( void ); + +.. rubric:: RETURN VALUES: + +Returns true, if the RTEMS Workspace and C Program Heap are configured to be +unified for this application, otherwise false. + +.. rubric:: NOTES: + +The setting is defined by the :ref:`CONFIGURE_UNIFIED_WORK_AREAS` application +configuration option. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-user-extension-table + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_user_extension_table() + +.. _InterfaceRtemsConfigurationGetUserExtensionTable: + +rtems_configuration_get_user_extension_table() +---------------------------------------------- + +Gets the initial extensions table configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const rtems_extensions_table *rtems_configuration_get_user_extension_table( + void + ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the initial extensions table configured for this +application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-user-multiprocessing-table + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_user_multiprocessing_table() + +.. _InterfaceRtemsConfigurationGetUserMultiprocessingTable: + +rtems_configuration_get_user_multiprocessing_table() +---------------------------------------------------- + +Gets the MPCI configuration table configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const MPCI_Configuration *rtems_configuration_get_user_multiprocessing_table( + void + ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the MPCI configuration table configured for this +application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-work-space-size + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_work_space_size() + +.. _InterfaceRtemsConfigurationGetWorkSpaceSize: + +rtems_configuration_get_work_space_size() +----------------------------------------- + +Gets the RTEMS Workspace size in bytes configured for this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uintptr_t rtems_configuration_get_work_space_size( void ); + +.. rubric:: RETURN VALUES: + +Returns the RTEMS Workspace size in bytes configured for this application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/get-api-configuration + +.. raw:: latex + + \clearpage + +.. index:: rtems_configuration_get_rtems_api_configuration() + +.. _InterfaceRtemsConfigurationGetRtemsApiConfiguration: + +rtems_configuration_get_rtems_api_configuration() +------------------------------------------------- + +Gets the Classic API Configuration Table of this application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const rtems_api_configuration_table * + rtems_configuration_get_rtems_api_configuration( void ); + +.. rubric:: RETURN VALUES: + +Returns a pointer to the Classic API Configuration Table of this application. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/resource-is-unlimited + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_is_unlimited() + +.. _InterfaceRtemsResourceIsUnlimited: + +rtems_resource_is_unlimited() +----------------------------- + +Indicates if the resource is unlimited. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + bool rtems_resource_is_unlimited( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number. + +.. rubric:: RETURN VALUES: + +Returns true, if the resource is unlimited, otherwise false. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/resource-maximum-per-allocation + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_maximum_per_allocation() + +.. _InterfaceRtemsResourceMaximumPerAllocation: + +rtems_resource_maximum_per_allocation() +--------------------------------------- + +Gets the maximum number per allocation of a resource number. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_resource_maximum_per_allocation( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number. + +.. rubric:: RETURN VALUES: + +Returns the maximum number per allocation of a resource number. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/config/if/resource-unlimited + +.. raw:: latex + + \clearpage + +.. index:: rtems_resource_unlimited() + +.. _InterfaceRtemsResourceUnlimited: + +rtems_resource_unlimited() +-------------------------- + +Augments the resource number so that it indicates an unlimited resource. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint32_t rtems_resource_unlimited( uint32_t resource ); + +.. rubric:: PARAMETERS: + +``resource`` + This parameter is the resource number to augment. + +.. rubric:: RETURN VALUES: + +Returns the resource number augmented to indicate an unlimited resource. + +.. rubric:: NOTES: + +This directive should be used to configure unlimited objects, see +:ref:`ConfigUnlimitedObjects`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is implemented by a macro and may be called from within C/C++ + constant expressions. In addition, a function implementation of the + directive exists for bindings to other programming languages. + +* The directive will not cause the calling task to be preempted. diff --git a/c-user/config/event-record.rst b/c-user/config/event-record.rst index 31a4fa9..1e5c52a 100644 --- a/c-user/config/event-record.rst +++ b/c-user/config/event-record.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2019, 2022 embedded brains GmbH & Co. KG .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -150,6 +150,47 @@ in a fatal error extension (see :ref:`Terminate`). The zlib compression needs about 512KiB of RAM. This extension can be used to produce crash dumps. +.. Generated from spec:/acfg/if/record-interrupts-enabled + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_RECORD_INTERRUPTS_ENABLED + +.. _CONFIGURE_RECORD_INTERRUPTS_ENABLED: + +CONFIGURE_RECORD_INTERRUPTS_ENABLED +----------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_RECORD_INTERRUPTS_ENABLED`` + +.. 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 + +* and :ref:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` is properly defined, + +then the interrupt event recording is enabled. + +.. rubric:: NOTES: + +The interrupt event recording generates interrupt entry and exit events when +interrupt entries are dispatched. + .. Generated from spec:/acfg/if/record-per-processor-items .. raw:: latex diff --git a/c-user/config/face-technical-standard.rst b/c-user/config/face-technical-standard.rst new file mode 100644 index 0000000..8772773 --- /dev/null +++ b/c-user/config/face-technical-standard.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 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 +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-face + +FACE Technical Standard Related Configuration +============================================= + +This section describes configuration options related to adapting +RTEMS behavior to be aligned with the FACE Technical Standard. +The FACE Technical Standard is a product of the FACE Consortium +which operates under the Open Group. The FACE Consortium was founded +by avionics organizations to improve the portability of cockpit software +across various platforms. It addresses technical and business concerns. + +Most important from an RTEMS perspective, the FACE Technical Standard +defines four POSIX profiles: Security, Safety Base, Safety Extended, and +the General Purpose Profile. Each has an increasingly larger subset of +POSIX APIs. In the Security and Safety profiles, ARINC 653 is required. +It is optional in the General Purpose Profile. + +The RTEMS Project has been tracking alignment with the FACE POSIX profiles +and they are included in the "RTEMS POSIX 1003.1 Compliance Guide." + +.. Generated from spec:/acfg/if/posix-timer-face-behavior + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR + +.. _CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR: + +CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR +------------------------------------ + +.. rubric:: CONSTANT: + +``CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR`` + +.. 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: + +If this configuration option is defined, then POSIX timers may not be created +to use the :term:`CLOCK_REALTIME`. Per POSIX, this is allowed +behavior but per the FACE Technical Standard, it is not. Using POSIX timers +based on CLOCK_REALTIME (e.g., time of day) is unsafe for real-time safety +systems as setting CLOCK_REALTIME will perturb any active timers. + +If this option is not defined, POSIX timers may be created to use the +CLOCK_REALTIME in compliance with the POSIX specification. diff --git a/c-user/config/filesystem.rst b/c-user/config/filesystem.rst index 6e053f2..c565f4c 100644 --- a/c-user/config/filesystem.rst +++ b/c-user/config/filesystem.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, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 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 @@ -919,6 +919,41 @@ based on the configured block size: The value of the configuration option shall be equal to 16, 32, 64, 128, 256, or 512. +.. Generated from spec:/acfg/if/jffs2-delayed-write-task-priority + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY + +.. _CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY: + +CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY +------------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +The default value is 15. + +.. rubric:: DESCRIPTION: + +The value of this configuration option defines the JFFS2 delayed write 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/use-devfs-as-base-filesystem .. raw:: latex diff --git a/c-user/config/general.rst b/c-user/config/general.rst index 0da7530..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 @@ -67,6 +67,55 @@ memory is first dirtied and then zeroed. See also :ref:`CONFIGURE_MALLOC_DIRTY`. +.. Generated from spec:/acfg/if/disable-bsp-settings + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_DISABLE_BSP_SETTINGS + +.. _CONFIGURE_DISABLE_BSP_SETTINGS: + +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: + +In case this configuration option is defined, then the optional BSP provided +settings listed below are disabled. + +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 @@ -129,8 +178,8 @@ 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. +stack space size is calculated by ``<rtems/confdefs.h>`` based on the +values configuration options. .. rubric:: DESCRIPTION: @@ -204,6 +253,42 @@ The following constraints apply to this configuration option: overflow an integer of type `uintptr_t <https://en.cppreference.com/w/c/types/integer>`_. +.. Generated from spec:/acfg/if/init + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_INIT + +.. _CONFIGURE_INIT: + +CONFIGURE_INIT +-------------- + +.. rubric:: CONSTANT: + +``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 @@ -237,13 +322,13 @@ 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. +: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 :c:type:`rtems_extensions_table`. +structures of type :ref:`InterfaceRtemsExtensionsTable`. .. Generated from spec:/acfg/if/interrupt-stack-size @@ -269,8 +354,11 @@ This configuration option is an integer define. .. rubric:: 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`. +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: @@ -450,6 +538,69 @@ The following constraints apply to this configuration option: * 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: + +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: + +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 @@ -866,7 +1017,7 @@ configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`. 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 greater than or equal to one. * The value of the configuration option shall be less than or equal to `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_. @@ -956,7 +1107,7 @@ By allowing users to declare all resources as being unlimited the user can avoid identifying and limiting the resources used. The object maximum of each class can be configured also individually using -the :c:func:`rtems_resource_unlimited` macro. +the :ref:`InterfaceRtemsResourceUnlimited` macro. .. rubric:: CONSTRAINTS: @@ -1039,7 +1190,7 @@ 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. +:ref:`InterfacePrintk` function is used to print the information. .. Generated from spec:/acfg/if/zero-workspace-automatically diff --git a/c-user/config/idle-task.rst b/c-user/config/idle-task.rst index 5cf8364..793fb5c 100644 --- a/c-user/config/idle-task.rst +++ b/c-user/config/idle-task.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -48,8 +48,11 @@ This configuration option is an initializer define. .. rubric:: 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``. +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_IDLE_TASK_BODY` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_IDLE_TASK_BODY`, otherwise the default value is +``_CPU_Thread_Idle_body``. .. rubric:: DESCRIPTION: @@ -64,6 +67,11 @@ exists. IDLE threads can be used to initialize the application, see configuration option :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`. +The BSP may have knowledge of the specific CPU model, system controller +logic, and peripheral buses, so 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 @@ -115,7 +123,7 @@ 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. -The application shall define exactly one of the following configuration +The application shall define at least one of the following configuration options * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, @@ -126,6 +134,9 @@ options otherwise a compile time error in the configuration file will occur. +If no Classic API initialization task and no POSIX API initialization thread +is configured, then no :ref:`GlobalConstruction` is performed. + .. Generated from spec:/acfg/if/idle-task-stack-size .. raw:: latex @@ -149,7 +160,11 @@ This configuration option is an integer define. .. rubric:: DEFAULT VALUE: -The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. +If the :ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option is not defined and +:c:macro:`BSP_IDLE_TASK_STACK_SIZE` is provided by the +:term:`BSP`, then the default value is defined by +:c:macro:`BSP_IDLE_TASK_STACK_SIZE`, otherwise the default value is +defined by the :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` configuration option. .. rubric:: DESCRIPTION: @@ -172,3 +187,74 @@ The following constraints apply to this configuration option: 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/idle-task-storage-size + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_IDLE_TASK_STORAGE_SIZE +.. index:: IDLE task storage size + +.. _CONFIGURE_IDLE_TASK_STORAGE_SIZE: + +CONFIGURE_IDLE_TASK_STORAGE_SIZE +-------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_IDLE_TASK_STORAGE_SIZE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an integer define. + +.. rubric:: DEFAULT VALUE: + +This configuration option has no default value. If it is not specified, then +the task storage area for each :term:`IDLE task` will allocated +from the RTEMS Workspace or through a custom IDLE task stack allocator. + +.. rubric:: DESCRIPTION: + +If this configuration option is specified, then the task storage areas for +the :term:`IDLE tasks <IDLE task>` are statically allocated by +``<rtems/confdefs.h>``. The value of this configuration option defines the +size in bytes of the task storage area of each IDLE task in the system. + +.. rubric:: NOTES: + +By default, the IDLE task storage areas are allocated from the RTEMS +Workspace. Applications which do not want to use a heap allocator can use +this configuration option to use statically allocated memory for the IDLE +task storage areas. The task storage area contains the task stack, the +thread-local storage, and the floating-point context on architectures with a +separate floating-point context. The size of the thread-local storage area +is defined at link time or by the :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` +configuration option. You have to estimate the actual thread-local storage +size if you want to use this configuration option. If the IDLE task stack +size would be less than the value defined by the +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` configuration option, for example because the +thread-local storage size is larger than expected, then the system terminates +with the :ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` fatal source and the +:ref:`INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL <internal_errors>` fatal code during +system initialization. + +The value of this configuration option is passed to +:ref:`InterfaceRTEMSTASKSTORAGESIZE` by ``<rtems/confdefs.h>`` to determine +the actual size of the statically allocated area to take +architecture-specific overheads into account. + +The + +* ``CONFIGURE_IDLE_TASK_STORAGE_SIZE``, and + +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE` + +configuration options are mutually exclusive. + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be greater than or equal to +:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE`. diff --git a/c-user/config/index.rst b/c-user/config/index.rst index b0e21a4..b669ea2 100644 --- a/c-user/config/index.rst +++ b/c-user/config/index.rst @@ -10,6 +10,7 @@ Configuring a System .. toctree:: + introduction intro general device-driver @@ -24,8 +25,9 @@ Configuring a System idle-task scheduler-general scheduler-clustered - bsp-related + face-technical-standard mpci libpci ada + directives obsolete diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst index 4c2f715..eb9c4c1 100644 --- a/c-user/config/intro.rst +++ b/c-user/config/intro.rst @@ -3,49 +3,6 @@ .. Copyright (C) 2012 Gedare Bloom .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -Introduction -============ - -RTEMS must be configured for an application. This configuration encompasses a -variety of information including the length of each clock tick, the maximum -number of each information RTEMS object that can be created, the application -initialization tasks, the task scheduling algorithm to be used, and the device -drivers in the application. - -Although this information is contained in data structures that are used by -RTEMS at system initialization time, the data structures themselves must not be -generated by hand. RTEMS provides a set of macros system which provides a -simple standard mechanism to automate the generation of these structures. - -.. index:: confdefs.h -.. index:: <rtems/confdefs.h> - -The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic -generation of system configuration. It is based on the idea of setting macros -which define configuration parameters of interest to the application and -defaulting or calculating all others. This variety of macros can automatically -produce all of the configuration data required for an RTEMS application. - -.. sidebar: Trivia: - - The term ``confdefs`` is shorthand for a *Configuration Defaults*. - -As a general rule, application developers only specify values for the -configuration parameters of interest to them. They define what resources or -features they require. In most cases, when a parameter is not specified, it -defaults to zero (0) instances, a standards compliant value, or disabled as -appropriate. For example, by default there will be 256 task priority levels but -this can be lowered by the application. This number of priority levels is -required to be compliant with the RTEID/ORKID standards upon which the Classic -API is based. There are similar cases where the default is selected to be -compliant with the POSIX standard. - -For each configuration parameter in the configuration tables, the macro -corresponding to that field is discussed. The RTEMS Maintainers expect that all -systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and -that using this mechanism will avoid internal RTEMS configuration changes -impacting applications. - Default Value Selection Philosophy ================================== @@ -71,9 +28,9 @@ automatically. It assumes that all tasks are floating point and that all will be allocated the minimum stack space. This calculation includes the amount of memory that will be allocated for internal use by RTEMS. The automatic calculation may underestimate the workspace size truly needed by the -application, in which case one can use the ``CONFIGURE_MEMORY_OVERHEAD`` macro -to add a value to the estimate. See :ref:`Specify Memory Overhead` for more -details. +application, in which case one can use the :ref:`CONFIGURE_MEMORY_OVERHEAD` +macro to add a value to the estimate. See :ref:`Specify Memory Overhead` for +more details. The memory area for the RTEMS Workspace is determined by the BSP. In case the RTEMS Workspace is too large for the available memory, then a fatal run-time @@ -83,8 +40,8 @@ The file ``<rtems/confdefs.h>`` will calculate the value of the ``work_space_size`` parameter of the Configuration Table. There are many parameters the application developer can specify to help ``<rtems/confdefs.h>`` in its calculations. Correctly specifying the application requirements via -parameters such as ``CONFIGURE_EXTRA_TASK_STACKS`` and -``CONFIGURE_MAXIMUM_TASKS`` is critical for production software. +parameters such as :ref:`CONFIGURE_EXTRA_TASK_STACKS` and +:ref:`CONFIGURE_MAXIMUM_TASKS` is critical for production software. For each class of objects, the allocation can operate in one of two ways. The default way has an ceiling on the maximum number of object instances which can @@ -176,44 +133,45 @@ milliseconds is as follows: In this example, only a few configuration parameters are specified. The impact of these are as follows: -- The example specified ``CONFIGURE_RTEMS_INIT_TASK_TABLE`` but did not specify - any additional parameters. This results in a configuration of an application - which will begin execution of a single initialization task named ``Init`` - which is non-preemptible and at priority one (1). - -- By specifying ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, this application - is configured to have a clock tick device driver. Without a clock tick device - driver, RTEMS has no way to know that time is passing and will be unable to - support delays and wall time. Further configuration details about time are - provided. Per ``CONFIGURE_MICROSECONDS_PER_TICK`` and - ``CONFIGURE_TICKS_PER_TIMESLICE``, the user specified they wanted a clock +- The example specified :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE` but did not + specify any additional parameters. This results in a configuration of an + application which will begin execution of a single initialization task named + ``Init`` which is non-preemptible and at priority one (1). + +- By specifying :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, this + application is configured to have a clock tick device driver. Without a clock + tick device driver, RTEMS has no way to know that time is passing and will be + unable to support delays and wall time. Further configuration details about + time are provided. Per :ref:`CONFIGURE_MICROSECONDS_PER_TICK` and + :ref:`CONFIGURE_TICKS_PER_TIMESLICE`, the user specified they wanted a clock tick to occur each millisecond, and that the length of a timeslice would be fifty (50) milliseconds. -- By specifying ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, the application - will include a console device driver. Although the console device driver may - support a combination of multiple serial ports and display and keyboard - combinations, it is only required to provide a single device named +- By specifying :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, the + application will include a console device driver. Although the console device + driver may support a combination of multiple serial ports and display and + keyboard combinations, it is only required to provide a single device named ``/dev/console``. This device will be used for Standard Input, Output and - Error I/O Streams. Thus when ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` - is specified, implicitly three (3) file descriptors are reserved for the - Standard I/O Streams and those file descriptors are associated with - ``/dev/console`` during initialization. All console devices are expected to - support the POSIX*termios* interface. - -- The example above specifies via ``CONFIGURE_MAXIMUM_TASKS`` that the + Error I/O Streams. Thus when + :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` is specified, implicitly + three (3) file descriptors are reserved for the Standard I/O Streams and + those file descriptors are associated with ``/dev/console`` during + initialization. All console devices are expected to support the + POSIX*termios* interface. + +- The example above specifies via :ref:`CONFIGURE_MAXIMUM_TASKS` that the application requires a maximum of four (4) simultaneously existing Classic - API tasks. Similarly, by specifying ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``, + API tasks. Similarly, by specifying :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES`, there may be a maximum of only one (1) concurrently existent Classic API message queues. - The most surprising configuration parameter in this example is the use of - ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. Message buffer memory is allocated from - the RTEMS Workspace and must be accounted for. In this example, the single - message queue will have up to twenty (20) messages of type ``struct + :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. Message buffer memory is allocated + from the RTEMS Workspace and must be accounted for. In this example, the + single message queue will have up to twenty (20) messages of type ``struct USER_MESSAGE``. -- The ``CONFIGURE_INIT`` constant must be defined in order to make +- The :ref:`CONFIGURE_INIT` constant must be defined in order to make ``<rtems/confdefs.h>`` instantiate the configuration data structures. This can only be defined in one source file per application that includes ``<rtems/confdefs.h>`` or the symbol table will be instantiated multiple @@ -321,8 +279,6 @@ generally considered a safer embedded systems programming practice to know the system limits rather than experience an out of memory error at an arbitrary and largely unpredictable time in the field. -.. index:: rtems_resource_unlimited - .. _ConfigUnlimitedObjectsClass: Unlimited Objects by Class @@ -330,7 +286,7 @@ Unlimited Objects by Class When the number of objects is not known ahead of time, RTEMS provides an auto-extending mode that can be enabled individually for each object type by -using the macro ``rtems_resource_unlimited``. This takes a value as a +using the macro :ref:`InterfaceRtemsResourceUnlimited`. This takes a value as a parameter, and is used to set the object maximum number field in an API Configuration table. The value is an allocation unit size. When RTEMS is required to grow the object table it is grown by this size. The kernel will @@ -338,18 +294,15 @@ return the object memory back to the RTEMS Workspace when an object is destroyed. The kernel will only return an allocated block of objects to the RTEMS Workspace if at least half the allocation size of free objects remain allocated. RTEMS always keeps one allocation block of objects allocated. Here -is an example of using ``rtems_resource_unlimited``: +is an example of using :c:func:`rtems_resource_unlimited`: .. code-block:: c - #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5) - -.. index:: rtems_resource_is_unlimited -.. index:: rtems_resource_maximum_per_allocation + #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited( 5 ) Object maximum specifications can be evaluated with the -``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation`` -macros. +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation` macros. .. _ConfigUnlimitedObjectsDefault: diff --git a/c-user/config/introduction.rst b/c-user/config/introduction.rst new file mode 100644 index 0000000..8852a24 --- /dev/null +++ b/c-user/config/introduction.rst @@ -0,0 +1,227 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG +.. 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 +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/config/if/group + +.. _ApplicationConfigurationInformationIntroduction: + +Introduction +============ + +.. The following list was generated from: +.. spec:/rtems/config/if/get-build-label +.. spec:/rtems/config/if/get-copyright-notice +.. spec:/rtems/config/if/get-target-hash +.. spec:/rtems/config/if/get-version-string +.. spec:/rtems/config/if/get-do-zero-of-workspace +.. spec:/rtems/config/if/get-idle-task-stack-size +.. spec:/rtems/config/if/get-idle-task +.. spec:/rtems/config/if/get-interrupt-stack-size +.. spec:/rtems/config/if/get-maximum-barriers +.. spec:/rtems/config/if/get-maximum-extensions +.. spec:/rtems/config/if/get-maximum-message-queues +.. spec:/rtems/config/if/get-maximum-partitions +.. spec:/rtems/config/if/get-maximum-periods +.. spec:/rtems/config/if/get-maximum-ports +.. spec:/rtems/config/if/get-maximum-processors +.. spec:/rtems/config/if/get-maximum-regions +.. spec:/rtems/config/if/get-maximum-semaphores +.. spec:/rtems/config/if/get-maximum-tasks +.. spec:/rtems/config/if/get-maximum-timers +.. spec:/rtems/config/if/get-microseconds-per-tick +.. spec:/rtems/config/if/get-milliseconds-per-tick +.. spec:/rtems/config/if/get-nanoseconds-per-tick +.. spec:/rtems/config/if/get-number-of-initial-extensions +.. spec:/rtems/config/if/get-stack-allocate-for-idle-hook +.. spec:/rtems/config/if/get-stack-allocate-hook +.. spec:/rtems/config/if/get-stack-allocate-init-hook +.. spec:/rtems/config/if/get-stack-allocator-avoids-work-space +.. spec:/rtems/config/if/get-stack-free-hook +.. spec:/rtems/config/if/get-stack-space-size +.. spec:/rtems/config/if/get-ticks-per-timeslice +.. spec:/rtems/config/if/get-unified-work-area +.. spec:/rtems/config/if/get-user-extension-table +.. spec:/rtems/config/if/get-user-multiprocessing-table +.. spec:/rtems/config/if/get-work-space-size +.. spec:/rtems/config/if/get-api-configuration +.. spec:/rtems/config/if/resource-is-unlimited +.. spec:/rtems/config/if/resource-maximum-per-allocation +.. spec:/rtems/config/if/resource-unlimited + +The application configuration information group provides an API to get the +configuration of an application. + +RTEMS must be configured for an application. This configuration encompasses a +variety of information including the length of each clock tick, the maximum +number of each information RTEMS object that can be created, the application +initialization tasks, the task scheduling algorithm to be used, and the device +drivers in the application. + +Although this information is contained in data structures that are used by +RTEMS at system initialization time, the data structures themselves must not be +generated by hand. RTEMS provides a set of macros system which provides a +simple standard mechanism to automate the generation of these structures. + +The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic +generation of system configuration. It is based on the idea of setting macros +which define configuration parameters of interest to the application and +defaulting or calculating all others. This variety of macros can automatically +produce all of the configuration data required for an RTEMS application. The +term ``confdefs`` is shorthand for a *Configuration Defaults*. + +As a general rule, application developers only specify values for the +configuration parameters of interest to them. They define what resources or +features they require. In most cases, when a parameter is not specified, it +defaults to zero (0) instances, a standards compliant value, or disabled as +appropriate. For example, by default there will be 256 task priority levels but +this can be lowered by the application. This number of priority levels is +required to be compliant with the RTEID/ORKID standards upon which the Classic +API is based. There are similar cases where the default is selected to be +compliant with the POSIX standard. + +For each configuration parameter in the configuration tables, the macro +corresponding to that field is discussed. The RTEMS Maintainers expect that all +systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and +that using this mechanism will avoid internal RTEMS configuration changes +impacting applications. + +Some application configuration settings and other system parameters can be +queried by the application. The directives provided by the Application +Configuration Information are: + +* :ref:`InterfaceRtemsGetBuildLabel` - Gets the RTEMS build label. + +* :ref:`InterfaceRtemsGetCopyrightNotice` - Gets the RTEMS copyright notice. + +* :ref:`InterfaceRtemsGetTargetHash` - Gets the RTEMS target hash. + +* :ref:`InterfaceRtemsGetVersionString` - Gets the RTEMS version string. + +* :ref:`InterfaceRtemsConfigurationGetDoZeroOfWorkspace` - Indicates if the + RTEMS Workspace is configured to be zeroed during system initialization for + this application. + +* :ref:`InterfaceRtemsConfigurationGetIdleTaskStackSize` - Gets the IDLE task + stack size in bytes of this application. + +* :ref:`InterfaceRtemsConfigurationGetIdleTask` - Gets the IDLE task body of + this application. + +* :ref:`InterfaceRtemsConfigurationGetInterruptStackSize` - Gets the interrupt + stack size in bytes of this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumBarriers` - Gets the resource + number of :ref:`RTEMSAPIClassicBarrier` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumExtensions` - Gets the resource + number of :ref:`RTEMSAPIClassicUserExt` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumMessageQueues` - Gets the resource + number of :ref:`RTEMSAPIClassicMessage` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPartitions` - Gets the resource + number of :ref:`RTEMSAPIClassicPart` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPeriods` - Gets the resource + number of :ref:`RTEMSAPIClassicRatemon` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumPorts` - Gets the resource number + of :ref:`RTEMSAPIClassicDPMem` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumProcessors` - Gets the maximum + number of processors configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumRegions` - Gets the resource + number of :ref:`RTEMSAPIClassicRegion` objects configured for this + application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumSemaphores` - Gets the resource + number of :ref:`RTEMSAPIClassicSem` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumTasks` - Gets the resource number + of :ref:`RTEMSAPIClassicTasks` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMaximumTimers` - Gets the resource number + of :ref:`RTEMSAPIClassicTimer` objects configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMicrosecondsPerTick` - Gets the number of + microseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetMillisecondsPerTick` - Gets the number of + milliseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetNanosecondsPerTick` - Gets the number of + microseconds per clock tick configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetNumberOfInitialExtensions` - Gets the + number of initial extensions configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateForIdleHook` - Gets the task + stack allocator allocate hook used to allocate the stack of each :term:`IDLE + task` configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateHook` - Gets the task stack + allocator allocate hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocateInitHook` - Gets the task + stack allocator initialization hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackAllocatorAvoidsWorkSpace` - + Indicates if the task stack allocator is configured to avoid the RTEMS + Workspace for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackFreeHook` - Gets the task stack + allocator free hook configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetStackSpaceSize` - Gets the configured + size in bytes of the memory space used to allocate thread stacks for this + application. + +* :ref:`InterfaceRtemsConfigurationGetTicksPerTimeslice` - Gets the clock ticks + per timeslice configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetUnifiedWorkArea` - Indicates if the RTEMS + Workspace and C Program Heap are configured to be unified for this + application. + +* :ref:`InterfaceRtemsConfigurationGetUserExtensionTable` - Gets the initial + extensions table configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetUserMultiprocessingTable` - Gets the MPCI + configuration table configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetWorkSpaceSize` - Gets the RTEMS Workspace + size in bytes configured for this application. + +* :ref:`InterfaceRtemsConfigurationGetRtemsApiConfiguration` - Gets the Classic + API Configuration Table of this application. + +* :ref:`InterfaceRtemsResourceIsUnlimited` - Indicates if the resource is + unlimited. + +* :ref:`InterfaceRtemsResourceMaximumPerAllocation` - Gets the maximum number + per allocation of a resource number. + +* :ref:`InterfaceRtemsResourceUnlimited` - Augments the resource number so that + it indicates an unlimited resource. diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst index d40f15c..ab9d568 100644 --- a/c-user/config/mpci.rst +++ b/c-user/config/mpci.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, 2021 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 diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst index 78cb724..f788c08 100644 --- a/c-user/config/posix-api.rst +++ b/c-user/config/posix-api.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, 2021 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 @@ -76,8 +76,8 @@ The following constraints apply to this configuration option: 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-key-value-pairs @@ -134,8 +134,8 @@ The following constraints apply to this configuration option: 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-message-queues @@ -193,8 +193,8 @@ The following constraints apply to this configuration option: <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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-queued-signals @@ -312,8 +312,8 @@ The following constraints apply to this configuration option: <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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-shms @@ -369,8 +369,8 @@ The following constraints apply to this configuration option: <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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` satisfies all other constraints of the configuration option. .. Generated from spec:/acfg/if/max-posix-threads @@ -477,26 +477,22 @@ configuration option enabled. 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 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 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. + 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` + :ref:`InterfaceRtemsResourceUnlimited` the enable unlimited objects for the + object class, if the value passed to :ref:`InterfaceRtemsResourceUnlimited` 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 +* 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 diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst index c038ec8..ee09ba0 100644 --- a/c-user/config/posix-init-thread.rst +++ b/c-user/config/posix-init-thread.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -141,7 +141,7 @@ initialization thread is configured. .. rubric:: NOTES: -The application shall define exactly one of the following configuration +The application shall define at least one of the following configuration options * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`, @@ -151,3 +151,6 @@ options * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION` otherwise a compile time error in the configuration file will occur. + +If no Classic API initialization task is configured, then the POSIX API +initialization thread performs the :ref:`GlobalConstruction`. diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst index 7169a83..d347d6b 100644 --- a/c-user/config/scheduler-general.rst +++ b/c-user/config/scheduler-general.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2022 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 2010 Gedare Bloom .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -407,9 +407,9 @@ scheduler. 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 :ref:`InterfaceRtemsSchedulerIdent`. -Use :c:func:`rtems_build_name` to define the scheduler name. +Use :ref:`InterfaceRtemsBuildName` to define the scheduler name. .. rubric:: CONSTRAINTS: @@ -749,7 +749,7 @@ The following constraints apply to this configuration option: The ``obj_name`` macro parameter shall be the scheduler object name. It is recommended to define the scheduler object name through - :c:func:`rtems_build_name`. + :ref:`InterfaceRtemsBuildName`. * Where the system was build with SMP support enabled, the table shall have one or more entries, otherwise it shall have exactly one entry. @@ -809,5 +809,6 @@ 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. +the configuration macros, please examine +``cpukit/include/rtems/confdefs/scheduler.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 187bff5..c79833f 100644 --- a/c-user/config/task-stack-alloc.rst +++ b/c-user/config/task-stack-alloc.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -136,27 +136,46 @@ This configuration option is an initializer define. .. rubric:: 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>``. +By default, the IDLE task storage area will be allocated from the RTEMS +Workspace. .. 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 +allocate handler used to allocate the task storage area 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. +configuration options. It is assumed that any memory allocated for the task +storage area of an :term:`IDLE task` will not be from the RTEMS +Workspace. + +The IDLE task stack allocator may increase the size of the allocated memory +area to account for the actually allocated memory area. + +The + +* :ref:`CONFIGURE_IDLE_TASK_STORAGE_SIZE`, and + +* ``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` + +configuration options are mutually exclusive. .. 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 )``. +The following constraints apply to this configuration option: + +* The value of the configuration option shall be defined to a valid function + pointer of the type ``void *( *allocate )( uint32_t, size_t * )``. + +* The IDLE task stack allocator shall return a pointer to the allocated memory + area or terminate the system with a fatal error if the allocation request + cannot be satisfied. + +* The IDLE task stack allocator may increase the size of the allocated memory + area. .. Generated from spec:/acfg/if/task-stack-allocator-init |