diff options
Diffstat (limited to 'c-user/rate_monotonic_manager.rst')
| -rw-r--r-- | c-user/rate_monotonic_manager.rst | 578 |
1 files changed, 286 insertions, 292 deletions
diff --git a/c-user/rate_monotonic_manager.rst b/c-user/rate_monotonic_manager.rst index e0fc66b..c2ba1a5 100644 --- a/c-user/rate_monotonic_manager.rst +++ b/c-user/rate_monotonic_manager.rst @@ -639,46 +639,49 @@ This section details the rate monotonic manager's directives. A subsection is dedicated to each of this manager's directives and describes the calling sequence, related constants, usage, and status codes. +.. raw:: latex + + \clearpage + .. _rtems_rate_monotonic_create: RATE_MONOTONIC_CREATE - Create a rate monotonic period ------------------------------------------------------ .. index:: create a period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_create -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_rate_monotonic_create( - rtems_name name, - rtems_id *id - ); + rtems_status_code rtems_rate_monotonic_create( + rtems_name name, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - rate monotonic period created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid period name - * - ``RTEMS_TOO_MANY`` - - too many periods created + * - ``RTEMS_SUCCESSFUL`` + - rate monotonic period created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid period name + * - ``RTEMS_TOO_MANY`` + - too many periods created -**DESCRIPTION:** +DESCRIPTION: + This directive creates a rate monotonic period. The assigned rate + monotonic id is returned in id. This id is used to access the period with + other rate monotonic manager directives. For control and maintenance of + the rate monotonic period, RTEMS allocates a PCB from the local PCB free + pool and initializes it. -This directive creates a rate monotonic period. The assigned rate monotonic id -is returned in id. This id is used to access the period with other rate -monotonic manager directives. For control and maintenance of the rate -monotonic period, RTEMS allocates a PCB from the local PCB free pool and -initializes it. +NOTES: + This directive will not cause the calling task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_rate_monotonic_ident: @@ -686,118 +689,118 @@ RATE_MONOTONIC_IDENT - Get ID of a period ----------------------------------------- .. index:: get ID of a period .. index:: obtain ID of a period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_ident -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_rate_monotonic_ident( - rtems_name name, - rtems_id *id - ); + rtems_status_code rtems_rate_monotonic_ident( + rtems_name name, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period identified successfully - * - ``RTEMS_INVALID_NAME`` - - period name not found + * - ``RTEMS_SUCCESSFUL`` + - period identified successfully + * - ``RTEMS_INVALID_NAME`` + - period name not found -**DESCRIPTION:** +DESCRIPTION: + This directive obtains the period id associated with the period name to be + acquired. If the period name is not unique, then the period id will match + one of the periods with that name. However, this period id is not + guaranteed to correspond to the desired period. The period id is used to + access this period in other rate monotonic manager directives. -This directive obtains the period id associated with the period name to be -acquired. If the period name is not unique, then the period id will match one -of the periods with that name. However, this period id is not guaranteed to -correspond to the desired period. The period id is used to access this period -in other rate monotonic manager directives. +NOTES: + This directive will not cause the running task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_rate_monotonic_cancel: RATE_MONOTONIC_CANCEL - Cancel a period --------------------------------------- .. index:: cancel a period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_cancel -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_rate_monotonic_cancel( - rtems_id id - ); + rtems_status_code rtems_rate_monotonic_cancel( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - period canceled successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` + - rate monotonic period not created by calling task - * - ``RTEMS_SUCCESSFUL`` - - period canceled successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` - - rate monotonic period not created by calling task +DESCRIPTION: -**DESCRIPTION:** + This directive cancels the rate monotonic period id. This period will be + reinitiated by the next invocation of ``rtems_rate_monotonic_period`` + with id. -This directive cancels the rate monotonic period id. This period will be -reinitiated by the next invocation of ``rtems_rate_monotonic_period`` with id. +NOTES: + This directive will not cause the running task to be preempted. -**NOTES:** + The rate monotonic period specified by id must have been created by the + calling task. -This directive will not cause the running task to be preempted. +.. raw:: latex -The rate monotonic period specified by id must have been created by the calling -task. + \clearpage .. _rtems_rate_monotonic_delete: +.. index:: rtems_rate_monotonic_delete RATE_MONOTONIC_DELETE - Delete a rate monotonic period ------------------------------------------------------ .. index:: delete a period -**CALLING SEQUENCE:** +CALLING SEQUENCE: + .. code-block:: c -.. index:: rtems_rate_monotonic_delete + rtems_status_code rtems_rate_monotonic_delete( + rtems_id id + ); -.. code-block:: c +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - rtems_status_code rtems_rate_monotonic_delete( - rtems_id id - ); + * - ``RTEMS_SUCCESSFUL`` + - period deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id -**DIRECTIVE STATUS CODES:** +DESCRIPTION: -.. list-table:: - :class: rtems-table + This directive deletes the rate monotonic period specified by id. If the + period is running, it is automatically canceled. The PCB for the deleted + period is reclaimed by RTEMS. - * - ``RTEMS_SUCCESSFUL`` - - period deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - -**DESCRIPTION:** - -This directive deletes the rate monotonic period specified by id. If the -period is running, it is automatically canceled. The PCB for the deleted -period is reclaimed by RTEMS. +NOTES: + This directive will not cause the running task to be preempted. -**NOTES:** + A rate monotonic period can be deleted by a task other than the task which + created the period. -This directive will not cause the running task to be preempted. +.. raw:: latex -A rate monotonic period can be deleted by a task other than the task which -created the period. + \clearpage .. _rtems_rate_monotonic_period: @@ -806,49 +809,49 @@ RATE_MONOTONIC_PERIOD - Conclude current/Start next period .. index:: conclude current period .. index:: start current period .. index:: period initiation - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_period -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_rate_monotonic_period( - rtems_id id, - rtems_interval length - ); + rtems_status_code rtems_rate_monotonic_period( + rtems_id id, + rtems_interval length + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period initiated successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` - - period not created by calling task - * - ``RTEMS_NOT_DEFINED`` - - period has never been initiated (only possible when period is set to PERIOD_STATUS) - * - ``RTEMS_TIMEOUT`` - - period has expired + * - ``RTEMS_SUCCESSFUL`` + - period initiated successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` + - period not created by calling task + * - ``RTEMS_NOT_DEFINED`` + - period has never been initiated (only possible when period is set to PERIOD_STATUS) + * - ``RTEMS_TIMEOUT`` + - period has expired -**DESCRIPTION:** +DESCRIPTION: + This directive initiates the rate monotonic period id with a length of + period ticks. If id is running, then the calling task will block for the + remainder of the period before reinitiating the period with the specified + period. If id was not running (either expired or never initiated), the + period is immediately initiated and the directive returns immediately. -This directive initiates the rate monotonic period id with a length of period -ticks. If id is running, then the calling task will block for the remainder of -the period before reinitiating the period with the specified period. If id was -not running (either expired or never initiated), the period is immediately -initiated and the directive returns immediately. + If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current + state of id will be returned. The directive status indicates the current + state of the period. This does not alter the state or period of the + period. -If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current state of -id will be returned. The directive status indicates the current state of the -period. This does not alter the state or period of the period. +NOTES: + This directive will not cause the running task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_rate_monotonic_get_status: @@ -856,63 +859,62 @@ RATE_MONOTONIC_GET_STATUS - Obtain status from a period ------------------------------------------------------- .. index:: get status of period .. index:: obtain status of period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_get_status -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_rate_monotonic_get_status( - rtems_id id, - rtems_rate_monotonic_period_status *status - ); + rtems_status_code rtems_rate_monotonic_get_status( + rtems_id id, + rtems_rate_monotonic_period_status *status + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - period initiated successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + * - ``RTEMS_INVALID_ADDRESS`` + - invalid address of status - * - ``RTEMS_SUCCESSFUL`` - - period initiated successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of status +*DESCRIPTION: + This directive returns status information associated with the rate + monotonic period id in the following data structure: -**DESCRIPTION:** + .. index:: rtems_rate_monotonic_period_status -This directive returns status information associated with the rate monotonic -period id in the following data structure: + .. code-block:: c -.. index:: rtems_rate_monotonic_period_status + typedef struct { + rtems_id owner; + rtems_rate_monotonic_period_states state; + rtems_rate_monotonic_period_time_t since_last_period; + rtems_thread_cpu_usage_t executed_since_last_period; + } rtems_rate_monotonic_period_status; -.. code-block:: c + .. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it. - typedef struct { - rtems_id owner; - rtems_rate_monotonic_period_states state; - rtems_rate_monotonic_period_time_t since_last_period; - rtems_thread_cpu_usage_t executed_since_last_period; - } rtems_rate_monotonic_period_status; - -.. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it. - -A configure time option can be used to select whether the time information is -given in ticks or seconds and nanoseconds. The default is seconds and -nanoseconds. If the period's state is ``RATE_MONOTONIC_INACTIVE``, both time -values will be set to 0. Otherwise, both time values will contain time -information since the last invocation of the ``rtems_rate_monotonic_period`` -directive. More specifically, the ticks_since_last_period value contains the -elapsed time which has occurred since the last invocation of the -``rtems_rate_monotonic_period`` directive and the -``ticks_executed_since_last_period`` contains how much processor time the -owning task has consumed since the invocation of the -``rtems_rate_monotonic_period`` directive. + A configure time option can be used to select whether the time information + is given in ticks or seconds and nanoseconds. The default is seconds and + nanoseconds. If the period's state is ``RATE_MONOTONIC_INACTIVE``, both + time values will be set to 0. Otherwise, both time values will contain + time information since the last invocation of the + ``rtems_rate_monotonic_period`` directive. More specifically, the + ticks_since_last_period value contains the elapsed time which has occurred + since the last invocation of the ``rtems_rate_monotonic_period`` directive + and the ``ticks_executed_since_last_period`` contains how much processor + time the owning task has consumed since the invocation of the + ``rtems_rate_monotonic_period`` directive. -**NOTES:** +NOTES: + This directive will not cause the running task to be preempted. -This directive will not cause the running task to be preempted. +.. raw:: latex + + \clearpage .. _rtems_rate_monotonic_get_statistics: @@ -920,131 +922,128 @@ RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period --------------------------------------------------------------- .. index:: get statistics of period .. index:: obtain statistics of period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_get_statistics -.. code-block:: c - - rtems_status_code rtems_rate_monotonic_get_statistics( - rtems_id id, - rtems_rate_monotonic_period_statistics *statistics - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - period initiated successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of statistics - -**DESCRIPTION:** - -This directive returns statistics information associated with the rate -monotonic period id in the following data structure: - -.. index:: rtems_rate_monotonic_period_statistics - -.. code-block:: c - - typedef struct { - uint32_t count; - uint32_t missed_count; - #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS - struct timespec min_cpu_time; - struct timespec max_cpu_time; - struct timespec total_cpu_time; - #else - uint32_t min_cpu_time; - uint32_t max_cpu_time; - uint32_t total_cpu_time; - #endif - #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS - struct timespec min_wall_time; - struct timespec max_wall_time; - struct timespec total_wall_time; - #else - uint32_t min_wall_time; - uint32_t max_wall_time; - uint32_t total_wall_time; - #endif - } rtems_rate_monotonic_period_statistics; - -This directive returns the current statistics information for the period -instance assocaited with ``id``. The information returned is indicated by the -structure above. - -**NOTES:** - -This directive will not cause the running task to be preempted. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_rate_monotonic_get_statistics( + rtems_id id, + rtems_rate_monotonic_period_statistics *statistics + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - period initiated successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id + * - ``RTEMS_INVALID_ADDRESS`` + - invalid address of statistics + +DESCRIPTION: + This directive returns statistics information associated with the rate + monotonic period id in the following data structure: + + .. index:: rtems_rate_monotonic_period_statistics + + .. code-block:: c + + typedef struct { + uint32_t count; + uint32_t missed_count; + #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS + struct timespec min_cpu_time; + struct timespec max_cpu_time; + struct timespec total_cpu_time; + #else + uint32_t min_cpu_time; + uint32_t max_cpu_time; + uint32_t total_cpu_time; + #endif + #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS + struct timespec min_wall_time; + struct timespec max_wall_time; + struct timespec total_wall_time; + #else + uint32_t min_wall_time; + uint32_t max_wall_time; + uint32_t total_wall_time; + #endif + } rtems_rate_monotonic_period_statistics; + + This directive returns the current statistics information for the period + instance assocaited with ``id``. The information returned is indicated by + the structure above. + +NOTES: + This directive will not cause the running task to be preempted. + +.. raw:: latex + + \clearpage .. _rtems_rate_monotonic_reset_statistics: RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period --------------------------------------------------------------- .. index:: reset statistics of period - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_reset_statistics -.. code-block:: c - - rtems_status_code rtems_rate_monotonic_reset_statistics( - rtems_id id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_rate_monotonic_reset_statistics( + rtems_id id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - period initiated successfully - * - ``RTEMS_INVALID_ID`` - - invalid rate monotonic period id + * - ``RTEMS_SUCCESSFUL`` + - period initiated successfully + * - ``RTEMS_INVALID_ID`` + - invalid rate monotonic period id -**DESCRIPTION:** +DESCRIPTION: + This directive resets the statistics information associated with this rate + monotonic period instance. -This directive resets the statistics information associated with this rate -monotonic period instance. +NOTES: + This directive will not cause the running task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_rate_monotonic_reset_all_statistics: RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods ---------------------------------------------------------------------- .. index:: reset statistics of all periods - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_reset_all_statistics -.. code-block:: c - - void rtems_rate_monotonic_reset_all_statistics(void); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + void rtems_rate_monotonic_reset_all_statistics(void); -NONE +DIRECTIVE STATUS CODES: + NONE -**DESCRIPTION:** +DESCRIPTION: + This directive resets the statistics information associated with all rate + monotonic period instances. -This directive resets the statistics information associated with all rate -monotonic period instances. +NOTES: + This directive will not cause the running task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_rate_monotonic_report_statistics: @@ -1052,37 +1051,32 @@ RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report ----------------------------------------------------------------- .. index:: print period statistics report .. index:: period statistics report - -**CALLING SEQUENCE:** - .. index:: rtems_rate_monotonic_report_statistics -.. code-block:: c - - void rtems_rate_monotonic_report_statistics(void); - -**DIRECTIVE STATUS CODES:** +CALLING SEQUENCE: + .. code-block:: c -NONE + void rtems_rate_monotonic_report_statistics(void); -**DESCRIPTION:** +DIRECTIVE STATUS CODES: + NONE -This directive prints a report on all active periods which have executed at -least one period. The following is an example of the output generated by this -directive. +DESCRIPTION: + This directive prints a report on all active periods which have executed at + least one period. The following is an example of the output generated by + this directive. -.. index:: rtems_rate_monotonic_period_statistics - -.. code-block:: c + .. index:: rtems_rate_monotonic_period_statistics - ID OWNER PERIODS MISSED CPU TIME WALL TIME - MIN/MAX/AVG MIN/MAX/AVG - 0x42010001 TA1 502 0 0/1/0.99 0/0/0.00 - 0x42010002 TA2 502 0 0/1/0.99 0/0/0.00 - 0x42010003 TA3 501 0 0/1/0.99 0/0/0.00 - 0x42010004 TA4 501 0 0/1/0.99 0/0/0.00 - 0x42010005 TA5 10 0 0/1/0.90 0/0/0.00 + .. code-block:: c -**NOTES:** + ID OWNER PERIODS MISSED CPU TIME WALL TIME + MIN/MAX/AVG MIN/MAX/AVG + 0x42010001 TA1 502 0 0/1/0.99 0/0/0.00 + 0x42010002 TA2 502 0 0/1/0.99 0/0/0.00 + 0x42010003 TA3 501 0 0/1/0.99 0/0/0.00 + 0x42010004 TA4 501 0 0/1/0.99 0/0/0.00 + 0x42010005 TA5 10 0 0/1/0.90 0/0/0.00 -This directive will not cause the running task to be preempted. +NOTES: + This directive will not cause the running task to be preempted. |