[PATCH] c-user: Generate task manager documentation

[Gedare Bloom]

On Tue, Apr 27, 2021 at 3:31 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> The documentation is a consolidation of the comments in Doxygen markup
> and the documentation sources in Sphinx markup.  The documentation was
> transfered to interface specification items.  The documentation source
> files were generated from the items by a script.
>
> Update #3993.
> ---
> Here is the updated document for review:
>
> https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
>
[...]
> +.. Generated from spec:/rtems/task/if/construct
> +
> +.. raw:: latex
> +
> +    \clearpage
> +
> +.. index:: rtems_task_construct()
> +
> +.. _InterfaceRtemsTaskConstruct:
> +
> +rtems_task_construct()
> +----------------------
> +
> +Constructs a task from the specified the task configuration.

delete second the. I think this will fix the same error in introduction.rst



> +rtems_task_restart()
> +--------------------
> +
> +Restarts the task.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_task_restart(
> +      rtems_id            id,
> +      rtems_task_argument argument
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> +    This parameter is the task identifier.  The constant :c:macro:`RTEMS_SELF`
> +    may be used to specify the calling task.
> +
> +``argument``
> +    This parameter is the task entry point argument.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive resets the task specified by ``id`` to begin execution at its
> +original entry point.  The task's priority and execution mode are set to the
> +original creation values.  If the task is currently blocked, RTEMS
> +automatically makes the task ready.  A task can be restarted from any state,
> +except the dormant state.  The task's entry point argument is contained in
> +``argument``.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no task associated with the identifier specified by ``id``.
> +
> +:c:macro:`RTEMS_INCORRECT_STATE`
> +    The task never started.
> +
> +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
> +    The task resided on a remote node.
> +
> +.. rubric:: NOTES:
> +
> +The task entry point argument may be a single value or an index into an array
I know this documentation already existed, but in review, it is a
little strangely worded. Since the type can be cast as a pointer, it
can point to anything. Perhaps change "may be" to "is usually"



> +rtems_task_get_priority()
> +-------------------------
> +
> +Gets the current priority of the task with respect to the scheduler.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> +    rtems_status_code rtems_task_get_priority(
> +      rtems_id             task_id,
> +      rtems_id             scheduler_id,
> +      rtems_task_priority *priority
> +    );
> +
> +.. rubric:: PARAMETERS:
> +
> +``task_id``
> +    This parameter is the task identifier.  The constant :c:macro:`RTEMS_SELF`
> +    may be used to specify the calling task.
> +
> +``scheduler_id``
> +    This parameter is the scheduler identifier.
> +
> +``priority``
> +    This parameter is the pointer to an :c:type:`rtems_task_priority` variable.
> +    When the directive call is successful, the current priority of the task
> +    with respect to the specified scheduler will be stored in this variable.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive returns the current priority in ``priority`` of the task
> +specified by ``task_id`` with respect to the scheduler specified by
> +``scheduler_id``.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> +    The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> +    The ``priority`` parameter was `NULL
> +    <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no task associated with the identifier specified by ``task_id``.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> +    There was no scheduler associated with the identifier specified by
> +    ``scheduler_id``.
> +
> +:c:macro:`RTEMS_NOT_DEFINED`
> +    The task had no priority with respect to the scheduler.
> +
> +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
> +    The task resided on a remote node.
> +
> +.. rubric:: NOTES:
> +
> +The current priority reflects temporary priority adjustments due to locking
> +protocols, the rate-monotonic period objects on some schedulers, and other
> +mechanisms.

It would be nice to complete "other mechanisms" if possible.