[PATCH] c-user: Add application config info directives
Sebastian Huber
sebastian.huber at embedded-brains.de
Fri Sep 9 14:33:33 UTC 2022
Close #4267.
Close #4269.
---
c-user/config/directives.rst | 1197 ++++++++++++++++++++++++++++++++
c-user/config/index.rst | 2 +
c-user/config/intro.rst | 43 --
c-user/config/introduction.rst | 221 ++++++
4 files changed, 1420 insertions(+), 43 deletions(-)
create mode 100644 c-user/config/directives.rst
create mode 100644 c-user/config/introduction.rst
diff --git a/c-user/config/directives.rst b/c-user/config/directives.rst
new file mode 100644
index 0000000..7a73d77
--- /dev/null
+++ b/c-user/config/directives.rst
@@ -0,0 +1,1197 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. 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.
+
+.. rubric:: RETURN VALUES:
+
+Returns the 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 the pointer to the RTEMS copyright notice.
+
+.. 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.
+
+.. rubric:: RETURN VALUES:
+
+Returns the 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 the pointer to the RTEMS version string.
+
+.. 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
+
+ #define rtems_configuration_get_do_zero_of_workspace()
+
+.. rubric:: RETURN VALUES:
+
+Returns true, if the RTEMS Workspace is configured to be zeroed during system
+initialization for this application, otherwise false.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY`.
+
+.. 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
+
+ #define rtems_configuration_get_idle_task_stack_size()
+
+.. rubric:: RETURN VALUES:
+
+Returns the IDLE task stack size in bytes of this application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE`.
+
+.. 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 entry of this application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_configuration_get_idle_task()
+
+.. rubric:: RETURN VALUES:
+
+Returns the IDLE task entry of this application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_IDLE_TASK_BODY`.
+
+.. 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
+
+ #define rtems_configuration_get_interrupt_stack_size()
+
+.. rubric:: RETURN VALUES:
+
+Returns the interrupt stack size in bytes of this application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`.
+
+.. 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 maximum number of Classic API Barriers configured for this
+application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_configuration_get_maximum_barriers( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number of Classic API Barriers configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MAXIMUM_BARRIERS`.
+
+.. 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 maximum number of Classic API User Extensions configured for this
+application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_configuration_get_maximum_extensions( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number of Classic API User Extensions configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MAXIMUM_USER_EXTENSIONS`.
+
+.. 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 maximum number of Classic API Message Queues configured for this
+application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_configuration_get_maximum_message_queues( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number of Classic API Message Queues configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES`.
+
+.. 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 maximum number of Classic API Partitions configured for this
+application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_configuration_get_maximum_partitions( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number of Classic API Partitions configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MAXIMUM_PARTITIONS`.
+
+.. 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 maximum number of Classic API Rate Monotonic Periods configured for
+this application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_configuration_get_maximum_periods( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number of Classic API Rate Monotonic Periods configured for
+this application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MAXIMUM_PERIODS`.
+
+.. 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 maximum number of Classic API Dual-Ported Memories configured for this
+application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_configuration_get_maximum_ports( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number of Classic API Dual-Ported Memories configured for
+this application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MAXIMUM_PORTS`.
+
+.. 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
+
+ #define rtems_configuration_get_maximum_processors()
+
+.. 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.
+
+.. 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 maximum number of Classic API Regions configured for this application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_configuration_get_maximum_regions( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number of Classic API Regions configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MAXIMUM_REGIONS`.
+
+.. 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 maximum number of Classic API Semaphores configured for this
+application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_configuration_get_maximum_semaphores( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number of Classic API Semaphores configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MAXIMUM_SEMAPHORES`.
+
+.. 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 maximum number of Classic API Tasks configured for this application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_configuration_get_maximum_tasks( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number of Classic API Tasks configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MAXIMUM_TASKS`.
+
+.. 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 maximum number of Classic API Timers configured for this application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uint32_t rtems_configuration_get_maximum_timers( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number of Classic API Timers configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MAXIMUM_TIMERS`.
+
+.. 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
+
+ #define rtems_configuration_get_microseconds_per_tick()
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of microseconds per clock tick configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MICROSECONDS_PER_TICK`.
+
+.. 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
+
+ #define rtems_configuration_get_milliseconds_per_tick()
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of milliseconds per clock tick configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MICROSECONDS_PER_TICK`.
+
+.. 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
+
+ #define rtems_configuration_get_nanoseconds_per_tick()
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of microseconds per clock tick configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_MICROSECONDS_PER_TICK`.
+
+.. 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
+
+ #define rtems_configuration_get_number_of_initial_extensions()
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of initial extensions configured for this application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_INITIAL_EXTENSIONS`.
+
+.. 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 thread stack allocator allocate hook used to allocate the stack of
+each :term:`IDLE task` configured for this application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_configuration_get_stack_allocate_for_idle_hook()
+
+.. rubric:: RETURN VALUES:
+
+Returns the thread stack allocator allocate hook used to allocate the stack of
+each :term:`IDLE task` configured for this application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`.
+
+.. 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 thread stack allocator allocate hook configured for this application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_configuration_get_stack_allocate_hook()
+
+.. rubric:: RETURN VALUES:
+
+Returns the thread stack allocator allocate hook configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`.
+
+.. 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 thread stack allocator initialization hook configured for this
+application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_configuration_get_stack_allocate_init_hook()
+
+.. rubric:: RETURN VALUES:
+
+Returns the thread stack allocator initialization hook configured for this
+application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT`.
+
+.. 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 thread stack allocator is configured to avoid the RTEMS
+Workspace for this application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_configuration_get_stack_allocator_avoids_work_space()
+
+.. rubric:: RETURN VALUES:
+
+Returns true, if the thread stack allocator is configured to avoid the RTEMS
+Workspace for this application, otherwise false.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE`.
+
+.. 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 thread stack allocator free hook configured for this application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ #define rtems_configuration_get_stack_free_hook()
+
+.. rubric:: RETURN VALUES:
+
+Returns the thread stack allocator free hook configured for this application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR`.
+
+.. 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 thread stack space size in bytes of configured for this application.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ uintptr_t rtems_configuration_get_stack_space_size( void );
+
+.. rubric:: RETURN VALUES:
+
+Returns the thread stack space size in bytes of configured for this
+application.
+
+.. 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
+
+ #define rtems_configuration_get_ticks_per_timeslice()
+
+.. rubric:: RETURN VALUES:
+
+Returns the clock ticks per timeslice configured for this application.
+
+.. rubric:: NOTES:
+
+See :ref:`CONFIGURE_TICKS_PER_TIMESLICE`.
+
+.. 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
+
+ #define rtems_configuration_get_unified_work_area()
+
+.. 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:
+
+See :ref:`CONFIGURE_UNIFIED_WORK_AREAS`.
+
+.. 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
+
+ #define rtems_configuration_get_user_extension_table()
+
+.. rubric:: RETURN VALUES:
+
+Returns the pointer to the initial extensions table configured for this
+application.
+
+.. 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
+
+ #define rtems_configuration_get_user_multiprocessing_table()
+
+.. rubric:: RETURN VALUES:
+
+Returns the pointer to the MPCI configuration table configured for this
+application.
+
+.. 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
+
+ #define rtems_configuration_get_work_space_size()
+
+.. rubric:: RETURN VALUES:
+
+Returns the RTEMS Workspace size in bytes configured for this application.
+
+.. 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 the pointer to the Classic API Configuration Table of this application.
+
+.. 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
+
+ #define rtems_resource_is_unlimited( resource )
+
+.. rubric:: PARAMETERS:
+
+``resource``
+ This parameter is the resource number.
+
+.. rubric:: RETURN VALUES:
+
+Returns true, if the resource is unlimited, otherwise false.
+
+.. rubric:: NOTES:
+
+This function is implemented as a macro and can be used to define compile time
+constants.
+
+.. 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
+
+ #define rtems_resource_maximum_per_allocation( resource )
+
+.. rubric:: PARAMETERS:
+
+``resource``
+ This parameter is the resource number.
+
+.. rubric:: RETURN VALUES:
+
+Returns the maximum number per allocation of a resource number.
+
+.. rubric:: NOTES:
+
+This function is implemented as a macro and can be used to define compile time
+constants.
+
+.. 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
+
+ #define rtems_resource_unlimited( 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 function is implemented as a macro and can be used to define compile time
+constants.
diff --git a/c-user/config/index.rst b/c-user/config/index.rst
index fd877b5..498387e 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
@@ -29,4 +30,5 @@ Configuring a System
mpci
libpci
ada
+ directives
obsolete
diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst
index 4c2f715..04ec996 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
==================================
diff --git a/c-user/config/introduction.rst b/c-user/config/introduction.rst
new file mode 100644
index 0000000..d06662a
--- /dev/null
+++ b/c-user/config/introduction.rst
@@ -0,0 +1,221 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. 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 entry of
+ this application.
+
+* :ref:`InterfaceRtemsConfigurationGetInterruptStackSize` - Gets the interrupt
+ stack size in bytes of this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumBarriers` - Gets the maximum
+ number of Classic API Barriers configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumExtensions` - Gets the maximum
+ number of Classic API User Extensions configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumMessageQueues` - Gets the maximum
+ number of Classic API Message Queues configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumPartitions` - Gets the maximum
+ number of Classic API Partitions configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumPeriods` - Gets the maximum number
+ of Classic API Rate Monotonic Periods configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumPorts` - Gets the maximum number
+ of Classic API Dual-Ported Memories configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumProcessors` - Gets the maximum
+ number of processors configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumRegions` - Gets the maximum number
+ of Classic API Regions configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumSemaphores` - Gets the maximum
+ number of Classic API Semaphores configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumTasks` - Gets the maximum number
+ of Classic API Tasks configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetMaximumTimers` - Gets the maximum number
+ of Classic API Timers 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
+ thread stack allocator allocate hook used to allocate the stack of each
+ :term:`IDLE task` configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetStackAllocateHook` - Gets the thread
+ stack allocator allocate hook configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetStackAllocateInitHook` - Gets the thread
+ stack allocator initialization hook configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetStackAllocatorAvoidsWorkSpace` -
+ Indicates if the thread stack allocator is configured to avoid the RTEMS
+ Workspace for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetStackFreeHook` - Gets the thread stack
+ allocator free hook configured for this application.
+
+* :ref:`InterfaceRtemsConfigurationGetStackSpaceSize` - Gets the thread stack
+ space size in bytes of configured 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.
--
2.35.3
More information about the devel
mailing list