[PATCH] c-user: New template for initializer config opts
Sebastian Huber
sebastian.huber at embedded-brains.de
Mon Mar 30 09:28:17 UTC 2020
Try to bring all descriptions up to date. Add cross-references to
several options. Clarify configuration value constraints.
Close #3901.
---
c-user/config/bsp-related.rst | 87 ++++++++++++++++++++++---------------
c-user/config/classic-init-task.rst | 21 +++++----
c-user/config/device-driver.rst | 56 ++++++++++++------------
c-user/config/general.rst | 22 +++++-----
c-user/config/idle-task.rst | 25 ++++++-----
c-user/config/mpci.rst | 17 ++++----
c-user/config/posix-init-thread.rst | 21 +++++----
c-user/config/task-stack-alloc.rst | 67 ++++++++++++++--------------
8 files changed, 171 insertions(+), 145 deletions(-)
diff --git a/c-user/config/bsp-related.rst b/c-user/config/bsp-related.rst
index 12d437f..88f2c26 100644
--- a/c-user/config/bsp-related.rst
+++ b/c-user/config/bsp-related.rst
@@ -20,24 +20,30 @@ BSP_IDLE_TASK_BODY
CONSTANT:
``BSP_IDLE_TASK_BODY``
-DATA TYPE:
- Function pointer.
-
-RANGE:
- Undefined or valid function pointer.
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
- This option is BSP specific.
+ The default value is BSP-specific.
+
+VALUE CONSTRAINTS:
+ The value of this configuration option must be defined to a valid function
+ pointer of the type ``void *( *idle_body )( uintptr_t )``.
DESCRIPTION:
- If ``BSP_IDLE_TASK_BODY`` is defined by the BSP and
- ``CONFIGURE_IDLE_TASK_BODY`` is not defined by the application, then this
- BSP specific idle task body will be used.
+ 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`.
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
+ peripheral buses, a BSP-specific IDLE task may be capable of turning
+ components off to save power during extended periods of no task activity.
.. index:: BSP_IDLE_TASK_STACK_SIZE
@@ -89,22 +95,29 @@ BSP_INITIAL_EXTENSION
CONSTANT:
``BSP_INITIAL_EXTENSION``
-DATA TYPE:
- List of user extension initializers (``rtems_extensions_table``).
-
-RANGE:
- Undefined or a list of user extension initializers.
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
- This option is BSP specific.
+ The default value is BSP-specific.
+
+VALUE CONSTRAINTS:
+ The value of this configuration option must be a list of initializers for
+ structures of type :c:type:`rtems_extensions_table`.
DESCRIPTION:
- If ``BSP_INITIAL_EXTENSION`` is defined by the BSP, then this BSP specific
- initial extension will be placed as the last entry in the initial extension
- table.
+ 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.
NOTES:
- None.
+ The value of this configuration option is placed after the entries of all
+ other initial user extensions.
.. index:: BSP_INTERRUPT_STACK_SIZE
@@ -156,26 +169,30 @@ CONFIGURE_BSP_PREREQUISITE_DRIVERS
CONSTANT:
``CONFIGURE_BSP_PREREQUISITE_DRIVERS``
-DATA TYPE:
- List of device driver initializers (``rtems_driver_address_table``).
-
-RANGE:
- Undefined or array of device drivers.
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
- This option is BSP specific.
+ The default value is BSP-specific.
+
+VALUE CONSTRAINTS:
+ The value of this configuration option must be a list of initializers for
+ structures of type :c:type:`rtems_extensions_table`.
DESCRIPTION:
- ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is defined if the BSP has device
- drivers it needs to include in the Device Driver Table. This should be
- defined to the set of device driver entries that will be placed in the
- table at the *FRONT* of the Device Driver Table and initialized before any
- other drivers *INCLUDING* any application prerequisite drivers.
+ 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.
NOTES:
- ``CONFIGURE_BSP_PREREQUISITE_DRIVERS`` is typically used by BSPs to
- configure common infrastructure such as bus controllers or probe for
- devices.
+ The value of this configuration option is placed before the entries of all
+ other initial user extensions (including
+ :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`).
.. index:: CONFIGURE_DISABLE_BSP_SETTINGS
diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst
index 8f699ee..9987293 100644
--- a/c-user/config/classic-init-task.rst
+++ b/c-user/config/classic-init-task.rst
@@ -71,23 +71,22 @@ CONFIGURE_INIT_TASK_ENTRY_POINT
CONSTANT:
``CONFIGURE_INIT_TASK_ENTRY_POINT``
-DATA TYPE:
- Task entry function pointer (``rtems_task_entry``).
-
-RANGE:
- Valid task entry function pointer.
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
The default value is ``Init``.
+VALUE CONSTRAINTS:
+ The value of this configuration option must be defined to a valid function
+ pointer of the type ``void ( *entry_point )( rtems_task_argument )``.
+
DESCRIPTION:
- ``CONFIGURE_INIT_TASK_ENTRY_POINT`` is the entry point (a.k.a. function
- name) of the single initialization task defined by the Classic API
- Initialization Tasks Table.
+ The value of this configuration option initializes the entry point of the
+ Classic API initialization task.
NOTES:
- The user must implement the function ``Init`` or the function name provided
- in this configuration parameter.
+ The user must implement the function referenced by this configuration option.
.. index:: CONFIGURE_INIT_TASK_INITIAL_MODES
@@ -228,7 +227,7 @@ NOTES:
The application must define exactly one of the following configuration
options
- * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`,
+ * `CONFIGURE_RTEMS_INIT_TASKS_TABLE`,
* :ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, or
diff --git a/c-user/config/device-driver.rst b/c-user/config/device-driver.rst
index 367573e..c229c99 100644
--- a/c-user/config/device-driver.rst
+++ b/c-user/config/device-driver.rst
@@ -54,23 +54,26 @@ CONFIGURE_APPLICATION_EXTRA_DRIVERS
CONSTANT:
``CONFIGURE_APPLICATION_EXTRA_DRIVERS``
-DATA TYPE:
- device driver entry structures
-
-RANGE:
- Undefined or set of device driver entry structures
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
- This is not defined by default.
+ The default value is the empty list.
+
+VALUE CONSTRAINTS:
+ The value of this configuration option must be a list of initializers for
+ structures of type :c:type:`rtems_driver_address_table`.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` is defined if the application has
- device drivers it needs to include in the Device Driver Table. This should
- be defined to the set of device driver entries that will be placed in the
- table at the *END* of the Device Driver Table.
+ The value of this configuration option is used to initialize the Device
+ Driver Table.
NOTES:
- None.
+ The value of this configuration option is placed after the entries of other
+ device driver configuration options.
+
+ See :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` for an alternative
+ placement of application device driver initializers.
.. index:: CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
@@ -445,28 +448,27 @@ CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
CONSTANT:
``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS``
-DATA TYPE:
- device driver entry structures
-
-RANGE:
- Undefined or set of device driver entry structures
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
- This is not defined by default.
+ The default value is the empty list.
+
+VALUE CONSTRAINTS:
+ The value of this configuration option must be a list of initializers for
+ structures of type :c:type:`rtems_driver_address_table`.
DESCRIPTION:
- ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` is defined if the
- application has device drivers it needs to include in the Device Driver
- Table. This should be defined to the set of device driver entries that
- will be placed in the table at the *FRONT* of the Device Driver Table and
- initialized before any other drivers *EXCEPT* any BSP prerequisite drivers.
+ The value of this configuration option is used to initialize the Device
+ Driver Table.
NOTES:
- In some cases, it is used by System On Chip BSPs to support peripheral
- buses beyond those normally found on the System On Chip. For example, this
- is used by one RTEMS system which has implemented a SPARC/ERC32 based board
- with VMEBus. The VMEBus Controller initialization is performed by a device
- driver configured via this configuration parameter.
+ The value of this configuration option is placed after the entries defined by
+ :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver
+ configuration options.
+
+ See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement
+ of application device driver initializers.
.. index:: CONFIGURE_MAXIMUM_DRIVERS
diff --git a/c-user/config/general.rst b/c-user/config/general.rst
index 17ef1c8..b94bddf 100644
--- a/c-user/config/general.rst
+++ b/c-user/config/general.rst
@@ -83,22 +83,24 @@ CONFIGURE_INITIAL_EXTENSIONS
CONSTANT:
``CONFIGURE_INITIAL_EXTENSIONS``
-DATA TYPE:
- List of user extension initializers (``rtems_extensions_table``).
-
-RANGE:
- Undefined or a list of one or more user extensions.
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
- This is not defined by default.
+ The default value is the empty list.
+
+VALUE CONSTRAINTS:
+ The value of this configuration option must be a list of initializers for
+ structures of type :c:type:`rtems_extensions_table`.
DESCRIPTION:
- If ``CONFIGURE_INITIAL_EXTENSIONS`` is defined by the application, then
- this application specific set of initial extensions will be placed in the
- initial extension table.
+ The value of this configuration option is used to initialize the table of
+ initial user extensions.
NOTES:
- None.
+ 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.
.. index:: CONFIGURE_INTERRUPT_STACK_SIZE
.. index:: interrupt stack size
diff --git a/c-user/config/idle-task.rst b/c-user/config/idle-task.rst
index b2a8767..ff2168c 100644
--- a/c-user/config/idle-task.rst
+++ b/c-user/config/idle-task.rst
@@ -17,22 +17,27 @@ CONFIGURE_IDLE_TASK_BODY
CONSTANT:
``CONFIGURE_IDLE_TASK_BODY``
-DATA TYPE:
- Function pointer.
-
-RANGE:
- Undefined or valid function pointer.
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
- This is not defined by default.
+ If :ref:`BSP_IDLE_TASK_BODY` is defined, then this will be the default value,
+ otherwise the default value is ``_CPU_Thread_Idle_body``.
+
+VALUE CONSTRAINTS:
+ The value of this configuration option must be defined to a valid function
+ pointer of the type ``void *( *idle_body )( uintptr_t )``.
DESCRIPTION:
- ``CONFIGURE_IDLE_TASK_BODY`` is set to the function name corresponding to
- the application specific IDLE thread body. If not specified, the BSP or
- RTEMS default IDLE thread body will be used.
+ The value of this configuration option initializes the IDLE thread body.
NOTES:
- None.
+ IDLE threads must not block. A blocking IDLE thread results in undefined
+ system behaviour because the scheduler assume that at least one ready thread
+ exists.
+
+ IDLE threads can be used to initialize the application, see configuration
+ option :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`.
.. index:: CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION
diff --git a/c-user/config/mpci.rst b/c-user/config/mpci.rst
index 7981fbc..ee0aff0 100644
--- a/c-user/config/mpci.rst
+++ b/c-user/config/mpci.rst
@@ -134,18 +134,19 @@ CONFIGURE_MP_MPCI_TABLE_POINTER
CONSTANT:
``CONFIGURE_MP_MPCI_TABLE_POINTER``
-DATA TYPE:
- pointer to ``rtems_mpci_table``
-
-RANGE:
- undefined or valid pointer
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
- This is not defined by default.
+ The default value is ``&MPCI_table``.
+
+VALUE CONSTRAINTS:
+ The value of this configuration option must be a pointer to
+ :c:type:`rtems_mpci_table`.
DESCRIPTION:
- ``CONFIGURE_MP_MPCI_TABLE_POINTER`` is the pointer to the MPCI
- Configuration Table. The default value of this field is``&MPCI_table``.
+ The value of this configuration option initializes the MPCI Configuration
+ Table.
NOTES:
RTEMS provides a Shared Memory MPCI Device Driver which can be used on any
diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst
index 6f47df4..5614342 100644
--- a/c-user/config/posix-init-thread.rst
+++ b/c-user/config/posix-init-thread.rst
@@ -18,23 +18,22 @@ CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT
CONSTANT:
``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT``
-DATA TYPE:
- POSIX thread function pointer (``void *(*entry_point)(void *)``).
-
-RANGE:
- Undefined or a valid POSIX thread function pointer.
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
The default value is ``POSIX_Init``.
+VALUE CONSTRAINTS:
+ The value of this configuration option must be defined to a valid function
+ pointer of the type ``void *( *entry_point )( void * )``.
+
DESCRIPTION:
- ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` is the entry point
- (a.k.a. function name) of the single initialization thread defined by the
- POSIX API Initialization Threads Table.
+ The value of this configuration option initializes the entry point of the
+ POSIX API initialization thread.
NOTES:
- The user must implement the function ``POSIX_Init`` or the function name
- provided in this configuration parameter.
+ The user must implement the function referenced by this configuration option.
.. index:: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE
@@ -64,7 +63,7 @@ VALUE CONSTRAINTS:
DESCRIPTION:
The value of this configuration option defines the thread stack size of the
- POSIX API initialization threads.
+ POSIX API initialization thread.
NOTES:
None.
diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst
index e031595..e1c48a5 100644
--- a/c-user/config/task-stack-alloc.rst
+++ b/c-user/config/task-stack-alloc.rst
@@ -22,28 +22,29 @@ CONFIGURE_TASK_STACK_ALLOCATOR
CONSTANT:
``CONFIGURE_TASK_STACK_ALLOCATOR``
-DATA TYPE:
- Function pointer.
-
-RANGE:
- Undefined or valid function pointer.
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
The default value is ``_Workspace_Allocate``, which indicates that task
stacks will be allocated from the RTEMS Workspace.
+VALUE CONSTRAINTS:
+ The value of this configuration option must be defined to a valid function
+ pointer of the type ``void *( *allocate )( size_t )``.
+
DESCRIPTION:
- ``CONFIGURE_TASK_STACK_ALLOCATOR`` may point to a user provided routine to
- allocate task stacks.
+ The value of this configuration option initializes the stack allocator
+ allocate handler.
NOTES:
A correctly configured system must configure the following to be consistent:
- - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
+ - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT`
- - ``CONFIGURE_TASK_STACK_ALLOCATOR``
+ - `CONFIGURE_TASK_STACK_ALLOCATOR`
- - ``CONFIGURE_TASK_STACK_DEALLOCATOR``
+ - :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR`
.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT
@@ -55,29 +56,28 @@ CONFIGURE_TASK_STACK_ALLOCATOR_INIT
CONSTANT:
``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
-DATA TYPE:
- Function pointer.
-
-RANGE:
- Undefined, NULL or valid function pointer.
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
- The default value is NULL, which indicates that task stacks will be
- allocated from the RTEMS Workspace.
+ The default value is ``NULL``.
+
+VALUE CONSTRAINTS:
+ The value of this configuration option must be defined to a valid function
+ pointer of the type ``void ( *initialize )( size_t )`` or to ``NULL``.
DESCRIPTION:
- ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` configures the initialization
- method for an application or BSP specific task stack allocation
- implementation.
+ The value of this configuration option initializes the stack allocator
+ initialization handler.
NOTES:
A correctly configured system must configure the following to be consistent:
- - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
+ - `CONFIGURE_TASK_STACK_ALLOCATOR_INIT`
- - ``CONFIGURE_TASK_STACK_ALLOCATOR``
+ - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`
- - ``CONFIGURE_TASK_STACK_DEALLOCATOR``
+ - :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR`
.. index:: CONFIGURE_TASK_STACK_DEALLOCATOR
.. index:: task stack deallocator
@@ -90,25 +90,26 @@ CONFIGURE_TASK_STACK_DEALLOCATOR
CONSTANT:
``CONFIGURE_TASK_STACK_DEALLOCATOR``
-DATA TYPE:
- Function pointer.
-
-RANGE:
- Undefined or valid function pointer.
+OPTION TYPE:
+ This configuration option is an initializer define.
DEFAULT VALUE:
The default value is ``_Workspace_Free``, which indicates that task stacks
will be allocated from the RTEMS Workspace.
+VALUE CONSTRAINTS:
+ The value of this configuration option must be defined to a valid function
+ pointer of the type ``void ( *deallocate )( void * )``.
+
DESCRIPTION:
- ``CONFIGURE_TASK_STACK_DEALLOCATOR`` may point to a user provided routine
- to free task stacks.
+ The value of this configuration option initializes the stack allocator
+ deallocate handler.
NOTES:
A correctly configured system must configure the following to be consistent:
- - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
+ - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT`
- - ``CONFIGURE_TASK_STACK_ALLOCATOR``
+ - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`
- - ``CONFIGURE_TASK_STACK_DEALLOCATOR``
+ - `CONFIGURE_TASK_STACK_DEALLOCATOR`
--
2.16.4
More information about the devel
mailing list