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

[Gedare Bloom]

looks good

On Sat, Jul 22, 2023 at 4:54 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> ---
>  c-user/glossary.rst                  | 13 +++++++++++++
>  c-user/initialization/operations.rst | 25 +++++++++++++++----------
>  c-user/rtems_data_types.rst          |  2 +-
>  c-user/task/directives.rst           |  6 +++---
>  4 files changed, 32 insertions(+), 14 deletions(-)
>
> 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