[PATCH] c-user: Generate task manager documentation

Tue Apr 27 19:00:46 UTC 2021

your suggestions look good

On Tue, Apr 27, 2021 at 11:52 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> 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/
>