[PATCH 4/8] c-user: Add user extensions glossary terms

[Gedare Bloom]

On Wed, Apr 21, 2021 at 7:50 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> ---
>  c-user/glossary.rst                   | 40 +++++++++++++++++++++++++--
>  c-user/user-extensions/background.rst | 13 +++------
>  2 files changed, 42 insertions(+), 11 deletions(-)
>
> diff --git a/c-user/glossary.rst b/c-user/glossary.rst
> index 71a0242..dc765ec 100644
> --- a/c-user/glossary.rst
> +++ b/c-user/glossary.rst
> @@ -233,6 +233,12 @@ Glossary
>          A term used to describe memory which can be accessed at two different
>          addresses.
>
> +    dynamic extension sets
> +        The dynamic extension sets are a list of :term:`user extensions`.  The list
> +        is defined by the system services used by the application and directive calls
> +        such as :c:func:`rtems_extension_create`.  See also
> +        :term:`initial extension sets`.
> +
>      EARS
>          This term is an acronym for Easy Approach to Requirements Syntax.
>
> @@ -286,6 +292,26 @@ Glossary
>          An object known by all nodes in a multiprocessor system.  An object
>          created with the GLOBAL attribute will be exported.
>
> +    extension forward order
> +        The :term:`user extensions` may be invoked in extension forward order.  In
> +        forward order, an user extension of the :term:`initial extension sets` is
> +        invoked before an user extension of the :term:`dynamic extension sets`.  In
s/an user extension/user extensions

in both these sentences, it is all initial extension set are invoked
before all dynamic extension sets, clarify by using the plural form.

> +        the initial extension sets the order is defined by the table index.  The user
> +        extension with the lowest table index is invoked first.  In the dynamic
> +        extension sets the order is defined by the registration order.  The first
> +        registered user extension is invoked first.  See also
> +        :term:`extension reverse order`.
> +
> +    extension reverse order
> +        The :term:`user extensions` may be invoked in extension reverse order.  In
> +        reverse order, an user extension of the :term:`dynamic extension sets` is
> +        invoked before an user extension of the :term:`initial extension sets`.  In
ditto

> +        the initial extension sets the order is defined by the table index.  The user
> +        extension with the highest table index is invoked first.  In the dynamic

Maybe swap the order of description to put dynamic first, since they
would be invoked first in this reverse order.

> +        extension sets the order is defined by the registration order.  The last
> +        registered user extension is invoked first.  See also
> +        :term:`extension forward order`.
> +
>      external address
>          The address used to access dual-ported memory by all the nodes in a
>          system which do not own the memory.
> @@ -371,6 +397,13 @@ Glossary
>          An ineligible scheduler of a :term:`task` is a :term:`scheduler` which is
>          not an :term:`eligible scheduler`.
>
> +    initial extension sets
> +        The initial extension sets are a table of :term:`user extensions`.  The table
> +        is defined by the application configuration for example through the
> +        :ref:`CONFIGURE_INITIAL_EXTENSIONS` application configuration option.  The
> +        initial extension sets cannot be altered during runtime through directive
> +        calls.  See also :term:`dynamic extension sets`.
> +
>      interface
>          A specification of the methodology used to connect multiple independent
>          subsystems.
> @@ -991,8 +1024,11 @@ Glossary
>          A table which contains the entry points for each user extensions.
>
>      user extensions
> -        Software routines provided by the application to enhance the
> -        functionality of RTEMS.
> +        User extensions are software routines provided by the application to enhance
> +        the functionality of RTEMS.  An active user extension is either in the
> +        :term:`initial extension sets` or the :term:`dynamic extension sets`.  User
> +        extensions are invoked in :term:`extension forward order` or
> +        :term:`extension reverse order`.
>
>      User Initialization Tasks Table
>          A table which contains the information needed to create and start each of
> diff --git a/c-user/user-extensions/background.rst b/c-user/user-extensions/background.rst
> index 2dc2577..5aa747b 100644
> --- a/c-user/user-extensions/background.rst
> +++ b/c-user/user-extensions/background.rst
> @@ -109,15 +109,10 @@ and release the extension buffers.
>  Order of Invocation
>  -------------------
>
> -The user extensions are invoked in either `forward` or `reverse` order.  In
> -forward order, the user extensions of initial extension sets are invoked before
> -the user extensions of the dynamic extension sets.  The forward order of
> -initial extension sets is defined by the initial extension sets table index.
> -The forward order of dynamic extension sets is defined by the order in which
> -the dynamic extension sets were created.  The reverse order is defined
> -accordingly.  By invoking the user extensions in this order, extensions can be
> -built upon one another.  At the following system events, the user extensions
> -are invoked in `forward` order
> +The user extensions are invoked in either :term:`extension forward order` or
> +:term:`extension reverse order`.  By invoking the user extensions in these
> +orders, extensions can be built upon one another.  At the following system
> +events, the user extensions are invoked in `forward` order
>
>  - thread creation,
>
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel