[PATCH v2] c-user: Link task entry and global construction

Tue Jul 25 02:30:05 UTC 2023

OK. Next time if you can just comment on the v1 that there's a v2. thanks

On Sun, Jul 23, 2023 at 11:51 PM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> ---
> v2: Mention global construction in application configuration options.
>
>  c-user/config/classic-init-task.rst  |  5 ++++-
>  c-user/config/idle-task.rst          |  5 ++++-
>  c-user/config/posix-init-thread.rst  |  5 ++++-
>  c-user/glossary.rst                  | 13 +++++++++++++
>  c-user/initialization/operations.rst | 25 +++++++++++++++----------
>  c-user/rtems_data_types.rst          |  2 +-
>  c-user/task/directives.rst           |  6 +++---
>  7 files changed, 44 insertions(+), 17 deletions(-)
>
> diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst
> index 43ab95c..2f1baad 100644
> --- a/c-user/config/classic-init-task.rst
> +++ b/c-user/config/classic-init-task.rst
> @@ -405,7 +405,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``,
> @@ -415,3 +415,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/idle-task.rst b/c-user/config/idle-task.rst
> index e98ad83..793fb5c 100644
> --- a/c-user/config/idle-task.rst
> +++ b/c-user/config/idle-task.rst
> @@ -123,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`,
> @@ -134,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
> diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst
> index 8a8b9b5..d4439a6 100644
> --- a/c-user/config/posix-init-thread.rst
> +++ b/c-user/config/posix-init-thread.rst
> @@ -151,7 +151,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`,
> @@ -162,6 +162,9 @@ options
>
>  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`.
> +
>  .. rubric:: CONSTRAINTS:
>
>  The configuration option is not included in the pre-qualified feature set of
> diff --git a/c-user/glossary.rst b/c-user/glossary.rst
> index 0962f44..8d86691 100644
> --- a/c-user/glossary.rst
> +++ b/c-user/glossary.rst
> @@ -476,6 +476,10 @@ Glossary
>          An object that has been created with the GLOBAL attribute and exported to
>          all nodes in a multiprocessor system.
>
> +    global construction
> +        In the global construction, the C++ global constructors and constructor
> +        functions are invoked.  See :ref:`GlobalConstruction`.
> +
>      GNAT
>          *GNAT* is the :term:`GNU` compiler for Ada, integrated into the
>          :term:`GCC`.
> @@ -1379,6 +1383,15 @@ Glossary
>          A data structure associated with each task used by RTEMS to manage that
>          task.
>
> +    task entry
> +        The task entry is invoked to execute the task's job.  Before the task entry
> +        is invoked, the thread begin :term:`user extensions` run in the context of
> +        the task.  After the return of the task entry, the thread exitted user
> +        extensions run in the context of the task.  The first user initialization
> +        task performs the :term:`global construction` after running the thread begin
> +        extensions and before the task entry is invoked.  See also
> +        :ref:`InterfaceRtemsTaskStart`.
> +
>      task migration
>          Task migration happens in case a task stops execution on one processor
>          and resumes execution on another processor.
> diff --git a/c-user/initialization/operations.rst b/c-user/initialization/operations.rst
> index db5c94b..e7d310c 100644
> --- a/c-user/initialization/operations.rst
> +++ b/c-user/initialization/operations.rst
> @@ -285,19 +285,24 @@ Many of RTEMS actions during initialization are based upon the contents of the
>  Configuration Table.  For more information regarding the format and contents of
>  this table, please refer to the chapter :ref:`Configuring a System`.
>
> +.. index:: global construction
> +
> +.. _GlobalConstruction:
> +
>  Global Construction
>  -------------------
>
> -The global construction is carried out by the first Classic API initialization
> -task (first is defined by index zero in the Classic API initialization task
> -configuration table).  If no Classic API initialization task exists, then it is
> -carried out by the first POSIX API initialization thread.  If no initialization
> -task or thread exists, then no global construction is performed, see for
> -example :ref:`Specify Idle Task Performs Application Initialization`.  The
> -Classic API task or POSIX API thread which carries out global construction is
> -called the main thread.
> -
> -Global construction runs before the entry function of the main thread.  The
> +The :term:`global construction` is carried out by the Classic API
> +initialization task.  If no Classic API initialization task exists, then it is
> +carried out by the POSIX API initialization thread.  If no initialization task
> +or thread exists, then no global construction is performed.  The Classic API
> +task or POSIX API thread which carries out global construction is called the
> +main thread.  For configuration options related to initialization tasks, see
> +:ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`,
> +:ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, and
> +:ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`.
> +
> +Global construction runs before the :term:`task entry` of the main thread.  The
>  configuration of the main thread must take the global construction into
>  account.  In particular, the main thread stack size, priority, attributes and
>  initial modes must be set accordingly.  Thread-local objects and POSIX key
> diff --git a/c-user/rtems_data_types.rst b/c-user/rtems_data_types.rst
> index a311509..8e4274b 100644
> --- a/c-user/rtems_data_types.rst
> +++ b/c-user/rtems_data_types.rst
> @@ -1523,7 +1523,7 @@ extension set.
>  rtems_task_entry
>  ----------------
>
> -This type defines the entry point of an RTEMS task.
> +This type defines the :term:`task entry` point of an RTEMS task.
>
>  .. Generated from spec:/rtems/userext/if/task-exitted
>
> diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst
> index f4b65f5..d976905 100644
> --- a/c-user/task/directives.rst
> +++ b/c-user/task/directives.rst
> @@ -624,9 +624,9 @@ Starts the task.
>  .. rubric:: DESCRIPTION:
>
>  This directive readies the task, specified by ``id``, for execution based on
> -the priority and execution mode specified when the task was created.  The entry
> -point of the task is given in ``entry_point``. The task's entry point argument
> -is contained in ``argument``.
> +the priority and execution mode specified when the task was created.  The
> +:term:`task entry` point of the task is given in ``entry_point``.  The task's
> +entry point argument is contained in ``argument``.
>
>  .. rubric:: RETURN VALUES:
>
> --
> 2.35.3
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel