[PATCH] c-user: Generate task manager documentation

[Sebastian Huber]

Hello Gedare,

thanks a lot for the review.

On 27/04/2021 18:01, Gedare Bloom wrote:

> 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
I fixed this.
>
>
>
>> +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"

What about:

   The type of the entry point argument is an unsigned integer type.  
However,
   the integer type has the property that any valid pointer to ``void`` 
can be
   converted to this type and then converted back to a pointer to 
``void``.  The
   result will compare equal to the original pointer.  The type can 
represent at
   least 32-bits.  Some applications use the entry point argument as an 
index
   into a parameter table to get task-specific parameters.

>
>
>
>> +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.

What about:

The current priority reflects temporary priority adjustments due to locking
protocols, the rate-monotonic period objects on some schedulers such as EDF, and the POSIX sporadic server.

-- 
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/