From 7bad8940ad05ea1e3b41745012a0dc5391275477 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 27 Mar 2020 12:53:09 +0100 Subject: c-user: Use new template for integer config opts Try to bring all descriptions up to date. Add cross-references to several options. Clarify configuration value constraints. Use this template also for initializer type options. Close #3901. --- c-user/config/classic-init-task.rst | 134 +++++++++++++++++++----------------- 1 file changed, 71 insertions(+), 63 deletions(-) (limited to 'c-user/config/classic-init-task.rst') diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst index 8addf9f..ca300e7 100644 --- a/c-user/config/classic-init-task.rst +++ b/c-user/config/classic-init-task.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Classic API Initialization Task Configuration @@ -18,18 +19,19 @@ CONFIGURE_INIT_TASK_ARGUMENTS CONSTANT: ``CONFIGURE_INIT_TASK_ARGUMENTS`` -DATA TYPE: - RTEMS Task Argument (``rtems_task_argument``). - -RANGE: - Complete range of the type. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is 0. +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid integer of type + ``rtems_task_argument``. + DESCRIPTION: - ``CONFIGURE_INIT_TASK_ARGUMENTS`` is the task argument of the single - initialization task defined by the Classic API Initialization Tasks Table. + The value of this configuration option defines task argument of the Classic + API initialization task. NOTES: None. @@ -44,18 +46,18 @@ CONFIGURE_INIT_TASK_ATTRIBUTES CONSTANT: ``CONFIGURE_INIT_TASK_ATTRIBUTES`` -DATA TYPE: - RTEMS Attributes (``rtems_attribute``). - -RANGE: - Valid task attribute sets. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is ``RTEMS_DEFAULT_ATTRIBUTES``. +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid task attribute set. + DESCRIPTION: - ``CONFIGURE_INIT_TASK_ATTRIBUTES`` is the task attributes of the single - initialization task defined by the Classic API Initialization Tasks Table. + The value of this configuration option defines the task attributes of the + Classic API initialization task. NOTES: None. @@ -70,23 +72,23 @@ 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 shall 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 application shall provide the function referenced by this configuration + option. .. index:: CONFIGURE_INIT_TASK_INITIAL_MODES @@ -98,19 +100,19 @@ CONFIGURE_INIT_TASK_INITIAL_MODES CONSTANT: ``CONFIGURE_INIT_TASK_INITIAL_MODES`` -DATA TYPE: - RTEMS Mode (``rtems_mode``). - -RANGE: - Valid task mode sets. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is ``RTEMS_NO_PREEMPT``. + In SMP configurations, the default value is ``RTEMS_DEFAULT_MODES``, + otherwise the default value is ``RTEMS_NO_PREEMPT``. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid task mode set. DESCRIPTION: - ``CONFIGURE_INIT_TASK_INITIAL_MODES`` is the initial execution mode of the - single initialization task defined by the Classic API Initialization Tasks - Table. + The value of this configuration option defines the initial execution mode of + the Classic API initialization task. NOTES: None. @@ -125,21 +127,22 @@ CONFIGURE_INIT_TASK_NAME CONSTANT: ``CONFIGURE_INIT_TASK_NAME`` -DATA TYPE: - RTEMS Name (``rtems_name``). - -RANGE: - Any value. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: The default value is ``rtems_build_name( 'U', 'I', '1', ' ' )``. +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid integer of type + ``rtems_name``. + DESCRIPTION: - ``CONFIGURE_INIT_TASK_NAME`` is the name of the single initialization task - defined by the Classic API Initialization Tasks Table. + The value of this configuration option defines the name of the Classic API + initialization task. NOTES: - None. + Use :c:func:`rtems_build_name` to define the task name. .. index:: CONFIGURE_INIT_TASK_PRIORITY @@ -151,18 +154,19 @@ CONFIGURE_INIT_TASK_PRIORITY CONSTANT: ``CONFIGURE_INIT_TASK_PRIORITY`` -DATA TYPE: - RTEMS Task Priority (``rtems_task_priority``). - -RANGE: - One (1) to the maximum user priority value of the scheduler. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is 1, which is the highest priority in the Classic API. + The default value is 1. + +VALUE CONSTRAINTS: + The value of this configuration option shall be a valid Classic API task + priority. The set of valid task priorities is scheduler-specific. DESCRIPTION: - ``CONFIGURE_INIT_TASK_PRIORITY`` is the initial priority of the single - initialization task defined by the Classic API Initialization Tasks Table. + The value of this configuration option defines the initial priority of the + Classic API initialization task. NOTES: None. @@ -177,24 +181,28 @@ CONFIGURE_INIT_TASK_STACK_SIZE CONSTANT: ``CONFIGURE_INIT_TASK_STACK_SIZE`` -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Zero or positive. +OPTION TYPE: + This configuration option is an integer define. DEFAULT VALUE: - The default value is RTEMS_MINIMUM_STACK_SIZE. + The default value is :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + +VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`. + + * It shall be small enough so that the task + stack space calculation carried out by ```` does not + overflow an integer of type ``uintptr_t``. DESCRIPTION: - ``CONFIGURE_INIT_TASK_STACK_SIZE`` is the stack size of the single - initialization task defined by the Classic API Initialization Tasks Table. + The value of this configuration option defines the task stack size of the + Classic API initialization task. NOTES: - If the stack size specified is greater than the configured minimum, it must - be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``. See :ref:`Reserve - Task/Thread Stack Memory Above Minimum` for more information about - ``CONFIGURE_EXTRA_TASK_STACKS``. + None. .. index:: CONFIGURE_RTEMS_INIT_TASKS_TABLE @@ -218,10 +226,10 @@ DESCRIPTION: initialization task is configured. NOTES: - The application must define exactly one of the following configuration + The application shall 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 -- cgit v1.2.3