Changeset 2730599c in rtems


Ignore:
Timestamp:
Jan 27, 2021, 5:10:15 AM (12 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
f9dc44a
Parents:
026eb3db
git-author:
Sebastian Huber <sebastian.huber@…> (01/27/21 05:10:15)
git-committer:
Sebastian Huber <sebastian.huber@…> (02/17/21 17:55:24)
Message:

rtems: Clarify event manager documentation

Unify the wording across similar directives of other managers. Add
"CONSTRAINTS" section.

Update #3993.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • cpukit/include/rtems/rtems/event.h

    r026eb3db r2730599c  
    1010
    1111/*
    12  * Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de)
     12 * Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
    1313 * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
    1414 *
     
    480480 * directive except that it operates with a different set of events for each
    481481 * task.
     482 *
     483 * @par Constraints
     484 * @parblock
     485 * The following constraints apply to this directive:
     486 *
     487 * * The directive may be called from within device driver initialization
     488 *   context.
     489 *
     490 * * The directive may be called from within task context.
     491 *
     492 * * The timeout functionality of the directive requires a clock tick.
     493 * @endparblock
    482494 */
    483495rtems_status_code rtems_event_system_receive(
     
    496508 *
    497509 * @param event_in is the event set to send.
     510 *
     511 * @par Constraints
     512 * @parblock
     513 * The following constraints apply to this directive:
     514 *
     515 * * The directive may be called from within interrupt context.
     516 *
     517 * * The directive may be called from within device driver initialization
     518 *   context.
     519 *
     520 * * The directive may be called from within task context.
     521 *
     522 * * The directive may unblock another task which may preempt the calling task.
     523 * @endparblock
    498524 */
    499525rtems_status_code rtems_event_system_send(
     
    530556/**
    531557 * @brief Clears the transient event.
     558 *
     559 * @par Constraints
     560 * @parblock
     561 * The following constraints apply to this directive:
     562 *
     563 * * The directive may be called from within device driver initialization
     564 *   context.
     565 *
     566 * * The directive may be called from within task context.
     567 *
     568 * * The directive will not cause the calling task to be preempted.
     569 * @endparblock
    532570 */
    533571static inline void rtems_event_transient_clear( void )
     
    551589 *
    552590 * @param ticks is the optional timeout in clock ticks.
     591 *
     592 * @par Constraints
     593 * @parblock
     594 * The following constraints apply to this directive:
     595 *
     596 * * The directive may be called from within device driver initialization
     597 *   context.
     598 *
     599 * * The directive may be called from within task context.
     600 *
     601 * * The timeout functionality of the directive requires a clock tick.
     602 * @endparblock
    553603 */
    554604static inline rtems_status_code rtems_event_transient_receive(
     
    573623 *
    574624 * @param id is the identifier of the task to receive the transient event.
     625 *
     626 * @par Constraints
     627 * @parblock
     628 * The following constraints apply to this directive:
     629 *
     630 * * The directive may be called from within interrupt context.
     631 *
     632 * * The directive may be called from within device driver initialization
     633 *   context.
     634 *
     635 * * The directive may be called from within task context.
     636 *
     637 * * The directive may unblock another task which may preempt the calling task.
     638 * @endparblock
    575639 */
    576640static inline rtems_status_code rtems_event_transient_send( rtems_id id )
     
    632696 * to the appropriate task.
    633697 * @endparblock
     698 *
     699 * @par Constraints
     700 * @parblock
     701 * The following constraints apply to this directive:
     702 *
     703 * * The directive may be called from within interrupt context.
     704 *
     705 * * The directive may be called from within device driver initialization
     706 *   context.
     707 *
     708 * * The directive may be called from within task context.
     709 *
     710 * * The directive may unblock another task which may preempt the calling task.
     711 * @endparblock
    634712 */
    635713rtems_status_code rtems_event_send( rtems_id id, rtems_event_set event_in );
     
    662740 * To **get the pending events** use the constant #RTEMS_PENDING_EVENTS for the
    663741 * ``event_in`` parameter.  The pending events are returned to the calling task
    664  * but the event set of the task is left unaltered.  The ``option_set`` and
    665  * ``ticks`` parameters are ignored in this case.  The directive returns
     742 * but the event set of the calling task is left unaltered.  The ``option_set``
     743 * and ``ticks`` parameters are ignored in this case.  The directive returns
    666744 * immediately and does not block.
    667745 *
    668746 * To **receive events** you have to define an input event condition and some
    669  * options.  The **option set** specified in ``option_set`` defines
    670  *
    671  * * if the task will wait or poll for the events, and
    672  *
    673  * * if the task wants to receive all or any of the input events.
    674  *
    675  * The option set is built through a *bitwise or* of the option constants
    676  * described below.
    677  *
    678  * The task can **wait** or **poll** for the events.
     747 * options.
     748 *
     749 * The **option set** specified in ``option_set`` is built through a *bitwise
     750 * or* of the option constants described below.  Not all combinations of
     751 * options are allowed.  Some options are mutually exclusive.  If mutually
     752 * exclusive options are combined, the behaviour is undefined.  Options not
     753 * mentioned below are not evaluated by this directive and have no effect.
     754 * Default options can be selected by using the #RTEMS_DEFAULT_OPTIONS
     755 * constant.  The option set defines
     756 *
     757 * * if the calling task will wait or poll for the events, and
     758 *
     759 * * if the calling task wants to receive all or any of the input events.
     760 *
     761 * The calling task can **wait** or **poll** for the events.
    679762 *
    680763 * * **Waiting** for events is the default and can be emphasized through the
    681764 *   use of the #RTEMS_WAIT option.  The ``ticks`` parameter defines how long
    682  *   the task is willing to wait.  Use #RTEMS_NO_TIMEOUT to wait potentially
    683  *   forever, otherwise set a timeout interval in clock ticks.
     765 *   the calling task is willing to wait.  Use #RTEMS_NO_TIMEOUT to wait
     766 *   potentially forever, otherwise set a timeout interval in clock ticks.
    684767 *
    685768 * * Not waiting for events (**polling**) is selected by the #RTEMS_NO_WAIT
     
    687770 *   ignored.
    688771 *
    689  * The task can receive **all** or **any** of the input events specified in
    690  * ``event_in``.
     772 * The calling task can receive **all** or **any** of the input events
     773 * specified in ``event_in``.
    691774 *
    692775 * * Receiving **all** input events is the default and can be emphasized
     
    708791 * @par Notes
    709792 * @parblock
    710  * This directive shall be called by a task.  Calling this directive from
    711  * interrupt context is undefined behaviour.
    712  *
    713793 * This directive only affects the events specified in ``event_in``. Any
    714794 * pending events that do not correspond to any of the events specified in
     
    726806 * ::RTEMS_UNSATISFIED status code will be returned.
    727807 * @endparblock
     808 *
     809 * @par Constraints
     810 * @parblock
     811 * The following constraints apply to this directive:
     812 *
     813 * * The directive may be called from within device driver initialization
     814 *   context.
     815 *
     816 * * The directive may be called from within task context.
     817 *
     818 * * The timeout functionality of the directive requires a clock tick.
     819 * @endparblock
    728820 */
    729821rtems_status_code rtems_event_receive(
Note: See TracChangeset for help on using the changeset viewer.