diff options
| -rw-r--r-- | c_user/clock_manager.rst | 576 | ||||
| -rw-r--r-- | c_user/initialization.rst | 272 | ||||
| -rw-r--r-- | c_user/interrupt_manager.rst | 414 | ||||
| -rw-r--r-- | c_user/key_concepts.rst | 369 | ||||
| -rw-r--r-- | c_user/overview.rst | 560 | ||||
| -rw-r--r-- | c_user/preface.rst | 305 | ||||
| -rw-r--r-- | c_user/rate_monotonic_manager.rst | 1144 | ||||
| -rw-r--r-- | c_user/rtems_data_types.rst | 487 | ||||
| -rw-r--r-- | c_user/rtemsarc.png | bin | 0 -> 5698 bytes | |||
| -rw-r--r-- | c_user/rtemspie.png | bin | 0 -> 31984 bytes | |||
| -rw-r--r-- | c_user/scheduling_concepts.rst | 692 | ||||
| -rw-r--r-- | c_user/states.png | bin | 0 -> 22036 bytes | |||
| -rw-r--r-- | c_user/task_manager.rst | 1590 | ||||
| -rw-r--r-- | c_user/timer_manager.rst | 575 |
14 files changed, 3539 insertions, 3445 deletions
diff --git a/c_user/clock_manager.rst b/c_user/clock_manager.rst index 5ea889f..40d984f 100644 --- a/c_user/clock_manager.rst +++ b/c_user/clock_manager.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Clock Manager ############# @@ -10,37 +14,37 @@ The clock manager provides support for time of day and other time related capabilities. The directives provided by the clock manager are: -- ``rtems_clock_set`` - Set date and time +- rtems_clock_set_ - Set date and time -- ``rtems_clock_get`` - Get date and time information +- rtems_clock_get_ - Get date and time information -- ``rtems_clock_get_tod`` - Get date and time in TOD format +- rtems_clock_get_tod_ - Get date and time in TOD format -- ``rtems_clock_get_tod_timeval`` - Get date and time in timeval format +- rtems_clock_get_tod_timeval_ - Get date and time in timeval format -- ``rtems_clock_get_seconds_since_epoch`` - Get seconds since epoch +- rtems_clock_get_seconds_since_epoch_ - Get seconds since epoch -- ``rtems_clock_get_ticks_per_second`` - Get ticks per second +- rtems_clock_get_ticks_per_second_ - Get ticks per second -- ``rtems_clock_get_ticks_since_boot`` - Get current ticks counter value +- rtems_clock_get_ticks_since_boot_ - Get current ticks counter value -- ``rtems_clock_tick_later`` - Get tick value in the future +- rtems_clock_tick_later_ - Get tick value in the future -- ``rtems_clock_tick_later_usec`` - Get tick value in the future in microseconds +- rtems_clock_tick_later_usec_ - Get tick value in the future in microseconds -- ``rtems_clock_tick_before`` - Is tick value is before a point in time +- rtems_clock_tick_before_ - Is tick value is before a point in time -- ``rtems_clock_get_uptime`` - Get time since boot +- rtems_clock_get_uptime_ - Get time since boot -- ``rtems_clock_get_uptime_timeval`` - Get time since boot in timeval format +- rtems_clock_get_uptime_timeval_ - Get time since boot in timeval format -- ``rtems_clock_get_uptime_seconds`` - Get seconds since boot +- rtems_clock_get_uptime_seconds_ - Get seconds since boot -- ``rtems_clock_get_uptime_nanoseconds`` - Get nanoseconds since boot +- rtems_clock_get_uptime_nanoseconds_ - Get nanoseconds since boot -- ``rtems_clock_set_nanoseconds_extension`` - Install the nanoseconds since last tick handler +- rtems_clock_set_nanoseconds_extension_ - Install the nanoseconds since last tick handler -- ``rtems_clock_tick`` - Announce a clock tick +- rtems_clock_tick_ - Announce a clock tick Background ========== @@ -48,93 +52,89 @@ Background Required Support ---------------- -For the features provided by the clock manager to be -utilized, periodic timer interrupts are required. Therefore, a -real-time clock or hardware timer is necessary to create the -timer interrupts. The ``rtems_clock_tick`` -directive is normally called -by the timer ISR to announce to RTEMS that a system clock tick -has occurred. Elapsed time is measured in ticks. A tick is -defined to be an integral number of microseconds which is -specified by the user in the Configuration Table. +For the features provided by the clock manager to be utilized, periodic timer +interrupts are required. Therefore, a real-time clock or hardware timer is +necessary to create the timer interrupts. The ``rtems_clock_tick`` directive +is normally called by the timer ISR to announce to RTEMS that a system clock +tick has occurred. Elapsed time is measured in ticks. A tick is defined to be +an integral number of microseconds which is specified by the user in the +Configuration Table. Time and Date Data Structures ----------------------------- -The clock facilities of the clock manager operate -upon calendar time. These directives utilize the following date -and time structure for the native time and date format: +The clock facilities of the clock manager operate upon calendar time. These +directives utilize the following date and time structure for the native time +and date format: + .. index:: rtems_time_of_day .. code:: c struct rtems_tod_control { - uint32_t year; /* greater than 1987 \*/ - uint32_t month; /* 1 - 12 \*/ - uint32_t day; /* 1 - 31 \*/ - uint32_t hour; /* 0 - 23 \*/ - uint32_t minute; /* 0 - 59 \*/ - uint32_t second; /* 0 - 59 \*/ - uint32_t ticks; /* elapsed between seconds \*/ + uint32_t year; /* greater than 1987 */ + uint32_t month; /* 1 - 12 */ + uint32_t day; /* 1 - 31 */ + uint32_t hour; /* 0 - 23 */ + uint32_t minute; /* 0 - 59 */ + uint32_t second; /* 0 - 59 */ + uint32_t ticks; /* elapsed between seconds */ }; typedef struct rtems_tod_control rtems_time_of_day; -The native date and time format is the only format -supported when setting the system date and time using the``rtems_clock_set`` directive. Some applications -expect to operate on a "UNIX-style" date and time data structure. The``rtems_clock_get_tod_timeval`` always returns -the date and time in ``struct timeval`` format. The``rtems_clock_get`` directive can optionally return -the current date and time in this format. +The native date and time format is the only format supported when setting the +system date and time using the ``rtems_clock_set`` directive. Some +applications expect to operate on a *UNIX-style* date and time data structure. +The ``rtems_clock_get_tod_timeval`` always returns the date and time in +``struct timeval`` format. The ``rtems_clock_get`` directive can optionally +return the current date and time in this format. -The ``struct timeval`` data structure has two fields: ``tv_sec`` -and ``tv_usec`` which are seconds and microseconds, respectively. -The ``tv_sec`` field in this data structure is the number of seconds -since the POSIX epoch of January 1, 1970 but will never be prior to -the RTEMS epoch of January 1, 1988. +The ``struct timeval`` data structure has two fields: ``tv_sec`` and +``tv_usec`` which are seconds and microseconds, respectively. The ``tv_sec`` +field in this data structure is the number of seconds since the POSIX epoch of +*January 1, 1970* but will never be prior to the RTEMS epoch of *January 1, +1988*. Clock Tick and Timeslicing -------------------------- .. index:: timeslicing -Timeslicing is a task scheduling discipline in which -tasks of equal priority are executed for a specific period of -time before control of the CPU is passed to another task. It is -also sometimes referred to as the automatic round-robin -scheduling algorithm. The length of time allocated to each task -is known as the quantum or timeslice. - -The system's timeslice is defined as an integral -number of ticks, and is specified in the Configuration Table. -The timeslice is defined for the entire system of tasks, but -timeslicing is enabled and disabled on a per task basis. - -The ``rtems_clock_tick`` -directive implements timeslicing by -decrementing the running task's time-remaining counter when both -timeslicing and preemption are enabled. If the task's timeslice -has expired, then that task will be preempted if there exists a -ready task of equal priority. +Timeslicing is a task scheduling discipline in which tasks of equal priority +are executed for a specific period of time before control of the CPU is passed +to another task. It is also sometimes referred to as the automatic round-robin +scheduling algorithm. The length of time allocated to each task is known as +the quantum or timeslice. + +The system's timeslice is defined as an integral number of ticks, and is +specified in the Configuration Table. The timeslice is defined for the entire +system of tasks, but timeslicing is enabled and disabled on a per task basis. + +The ``rtems_clock_tick`` directive implements timeslicing by decrementing the +running task's time-remaining counter when both timeslicing and preemption are +enabled. If the task's timeslice has expired, then that task will be preempted +if there exists a ready task of equal priority. Delays ------ .. index:: delays -A sleep timer allows a task to delay for a given -interval or up until a given time, and then wake and continue -execution. This type of timer is created automatically by the``rtems_task_wake_after`` -and ``rtems_task_wake_when`` directives and, as a result, -does not have an RTEMS ID. Once activated, a sleep timer cannot -be explicitly deleted. Each task may activate one and only one -sleep timer at a time. +A sleep timer allows a task to delay for a given interval or up until a given +time, and then wake and continue execution. This type of timer is created +automatically by the ``rtems_task_wake_after`` and ``rtems_task_wake_when`` +directives and, as a result, does not have an RTEMS ID. Once activated, a +sleep timer cannot be explicitly deleted. Each task may activate one and only +one sleep timer at a time. Timeouts -------- .. index:: timeouts -Timeouts are a special type of timer automatically -created when the timeout option is used on the``rtems_message_queue_receive``,``rtems_event_receive``,``rtems_semaphore_obtain`` and``rtems_region_get_segment`` directives. -Each task may have one and only one timeout active at a time. -When a timeout expires, it unblocks the task with a timeout status code. +Timeouts are a special type of timer automatically created when the timeout +option is used on the ``rtems_message_queue_receive``, ``rtems_event_receive``, +``rtems_semaphore_obtain`` and ``rtems_region_get_segment`` directives. Each +task may have one and only one timeout active at a time. When a timeout +expires, it unblocks the task with a timeout status code. Operations ========== @@ -142,71 +142,67 @@ Operations Announcing a Tick ----------------- -RTEMS provides the ``rtems_clock_tick`` directive which is -called from the user's real-time clock ISR to inform RTEMS that -a tick has elapsed. The tick frequency value, defined in -microseconds, is a configuration parameter found in the -Configuration Table. RTEMS divides one million microseconds -(one second) by the number of microseconds per tick to determine -the number of calls to the``rtems_clock_tick`` directive per second. The -frequency of ``rtems_clock_tick`` -calls determines the resolution -(granularity) for all time dependent RTEMS actions. For -example, calling ``rtems_clock_tick`` -ten times per second yields a higher -resolution than calling ``rtems_clock_tick`` -two times per second. The ``rtems_clock_tick`` -directive is responsible for maintaining both -calendar time and the dynamic set of timers. +RTEMS provides the ``rtems_clock_tick`` directive which is called from the +user's real-time clock ISR to inform RTEMS that a tick has elapsed. The tick +frequency value, defined in microseconds, is a configuration parameter found in +the Configuration Table. RTEMS divides one million microseconds (one second) +by the number of microseconds per tick to determine the number of calls to +the``rtems_clock_tick`` directive per second. The frequency of +``rtems_clock_tick`` calls determines the resolution (granularity) for all time +dependent RTEMS actions. For example, calling ``rtems_clock_tick`` ten times +per second yields a higher resolution than calling ``rtems_clock_tick`` two +times per second. The ``rtems_clock_tick`` directive is responsible for +maintaining both calendar time and the dynamic set of timers. Setting the Time ---------------- -The ``rtems_clock_set`` directive allows a task or an ISR to -set the date and time maintained by RTEMS. If setting the date -and time causes any outstanding timers to pass their deadline, -then the expired timers will be fired during the invocation of -the ``rtems_clock_set`` directive. +The ``rtems_clock_set`` directive allows a task or an ISR to set the date and +time maintained by RTEMS. If setting the date and time causes any outstanding +timers to pass their deadline, then the expired timers will be fired during the +invocation of the ``rtems_clock_set`` directive. Obtaining the Time ------------------ -The ``rtems_clock_get`` directive allows a task or an ISR to -obtain the current date and time or date and time related -information. The current date and time can be returned in -either native or UNIX-style format. Additionally, the -application can obtain date and time related information such as -the number of seconds since the RTEMS epoch, the number of ticks -since the executive was initialized, and the number of ticks per -second. The information returned by the``rtems_clock_get`` directive is -dependent on the option selected by the caller. This -is specified using one of the following constants -associated with the enumerated type``rtems_clock_get_options``:.. index:: rtems_clock_get_options +The ``rtems_clock_get`` directive allows a task or an ISR to obtain the current +date and time or date and time related information. The current date and time +can be returned in either native or *UNIX-style* format. Additionally, the +application can obtain date and time related information such as the number of +seconds since the RTEMS epoch, the number of ticks since the executive was +initialized, and the number of ticks per second. The information returned by +the``rtems_clock_get`` directive is dependent on the option selected by the +caller. This is specified using one of the following constants associated with +the enumerated type ``rtems_clock_get_options``: + +.. index:: rtems_clock_get_options -- ``RTEMS_CLOCK_GET_TOD`` - obtain native style date and time +``RTEMS_CLOCK_GET_TOD`` + obtain native style date and time -- ``RTEMS_CLOCK_GET_TIME_VALUE`` - obtain UNIX-style - date and time +``RTEMS_CLOCK_GET_TIME_VALUE`` + obtain *UNIX-style* date and time -- ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` - obtain number of ticks - since RTEMS was initialized +``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` + obtain number of ticks since RTEMS was initialized -- ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` - obtain number - of seconds since RTEMS epoch +``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` + obtain number of seconds since RTEMS epoch -- ``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` - obtain number of clock - ticks per second +``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` + obtain number of clock ticks per second -Calendar time operations will return an error code if -invoked before the date and time have been set. +Calendar time operations will return an error code if invoked before the date +and time have been set. Directives ========== -This section details the clock 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. +This section details the clock 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. + +.. _rtems_clock_set: CLOCK_SET - Set date and time ----------------------------- @@ -220,42 +216,51 @@ CLOCK_SET - Set date and time .. code:: c rtems_status_code rtems_clock_set( - rtems_time_of_day \*time_buffer + rtems_time_of_day *time_buffer ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - date and time set successfully -``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL -``RTEMS_INVALID_CLOCK`` - invalid time of day +``RTEMS_SUCCESSFUL`` + date and time set successfully + +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL + +``RTEMS_INVALID_CLOCK`` + invalid time of day **DESCRIPTION:** -This directive sets the system date and time. The -date, time, and ticks in the time_buffer structure are all -range-checked, and an error is returned if any one is out of its -valid range. +This directive sets the system date and time. The date, time, and ticks in the +time_buffer structure are all range-checked, and an error is returned if any +one is out of its valid range. **NOTES:** Years before 1988 are invalid. -The system date and time are based on the configured -tick rate (number of microseconds in a tick). +The system date and time are based on the configured tick rate (number of +microseconds in a tick). + +Setting the time forward may cause a higher priority task, blocked waiting on a +specific time, to be made ready. In this case, the calling task will be +preempted after the next clock tick. -Setting the time forward may cause a higher priority -task, blocked waiting on a specific time, to be made ready. In -this case, the calling task will be preempted after the next -clock tick. +Re-initializing RTEMS causes the system date and time to be reset to an +uninitialized state. Another call to ``rtems_clock_set`` is required to +re-initialize the system date and time to application specific specifications. -Re-initializing RTEMS causes the system date and time -to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize -the system date and time to application specific specifications. +.. _rtems_clock_get: CLOCK_GET - Get date and time information ----------------------------------------- .. index:: obtain the time of day +.. warning:: + + This directive is deprecated and will be removed. + **CALLING SEQUENCE:** .. index:: rtems_clock_get @@ -263,49 +268,62 @@ CLOCK_GET - Get date and time information .. code:: c rtems_status_code rtems_clock_get( - rtems_clock_get_options option, - void \*time_buffer + rtems_clock_get_options option, + void *time_buffer ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - current time obtained successfully -``RTEMS_NOT_DEFINED`` - system date and time is not set -``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL +``RTEMS_SUCCESSFUL`` + current time obtained successfully -**DESCRIPTION:** +``RTEMS_NOT_DEFINED`` + system date and time is not set -This directive is deprecated. +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL -This directive obtains the system date and time. If -the caller is attempting to obtain the date and time (i.e. -option is set to either ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``,``RTEMS_CLOCK_GET_TOD``, or``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time -has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned. -The caller can always obtain the number of ticks per second (option is``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number of -ticks since the executive was initialized option is``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``). - -The ``option`` argument may taken on any value of the enumerated -type ``rtems_clock_get_options``. The data type expected for``time_buffer`` is based on the value of ``option`` as -indicated below:.. index:: rtems_clock_get_options - -- ``RTEMS_CLOCK_GET_TOD`` - (rtems_time_of_day \*) - -- ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` - (rtems_interval \*) - -- ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` - (rtems_interval \*) - -- ``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` - (rtems_interval \*) +**DESCRIPTION:** -- ``RTEMS_CLOCK_GET_TIME_VALUE`` - (struct timeval \*) +This directive obtains the system date and time. If the caller is attempting +to obtain the date and time (i.e. option is set to either +``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``, ``RTEMS_CLOCK_GET_TOD``, or +``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time has not been set with a +previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status +code is returned. The caller can always obtain the number of ticks per second +(option is ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number of ticks since +the executive was initialized option is ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``). + +The ``option`` argument may taken on any value of the enumerated type +``rtems_clock_get_options``. The data type expected for``time_buffer`` is +based on the value of ``option`` as indicated below: + +.. index:: rtems_clock_get_options + ++-----------------------------------------+---------------------------+ +| Option | Return type | ++=========================================+===========================+ +| ``RTEMS_CLOCK_GET_TOD`` | ``(rtems_time_of_day *)`` | ++-----------------------------------------+---------------------------+ +| ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` | ``(rtems_interval *)`` | ++-----------------------------------------+---------------------------+ +| ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` | ``(rtems_interval *)`` | ++-----------------------------------------+---------------------------+ +|``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` | ``(rtems_interval *)`` | ++-----------------------------------------+---------------------------+ +| ``RTEMS_CLOCK_GET_TIME_VALUE`` | ``(struct timeval *)`` | ++-----------------------------------------+---------------------------+ **NOTES:** This directive is callable from an ISR. -This directive will not cause the running task to be -preempted. Re-initializing RTEMS causes the system date and -time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the -system date and time to application specific specifications. +This directive will not cause the running task to be preempted. +Re-initializing RTEMS causes the system date and time to be reset to an +uninitialized state. Another call to ``rtems_clock_set`` is required to +re-initialize the system date and time to application specific specifications. + +.. _rtems_clock_get_tod: CLOCK_GET_TOD - Get date and time in TOD format ----------------------------------------------- @@ -318,28 +336,36 @@ CLOCK_GET_TOD - Get date and time in TOD format .. code:: c rtems_status_code rtems_clock_get_tod( - rtems_time_of_day \*time_buffer + rtems_time_of_day *time_buffer ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - current time obtained successfully -``RTEMS_NOT_DEFINED`` - system date and time is not set -``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL +``RTEMS_SUCCESSFUL`` + current time obtained successfully + +``RTEMS_NOT_DEFINED`` + system date and time is not set + +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL **DESCRIPTION:** -This directive obtains the system date and time. If the date and time -has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned. +This directive obtains the system date and time. If the date and time has not +been set with a previous call to ``rtems_clock_set``, then the +``RTEMS_NOT_DEFINED`` status code is returned. **NOTES:** This directive is callable from an ISR. -This directive will not cause the running task to be -preempted. Re-initializing RTEMS causes the system date and -time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the -system date and time to application specific specifications. +This directive will not cause the running task to be preempted. +Re-initializing RTEMS causes the system date and time to be reset to an +uninitialized state. Another call to ``rtems_clock_set`` is required to +re-initialize the system date and time to application specific specifications. + +.. _rtems_clock_get_tod_timeval: CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format ----------------------------------------------------------- @@ -351,29 +377,37 @@ CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format .. code:: c - rtems_status_code rtems_clock_get_tod( - struct timeval \*time + rtems_status_code rtems_clock_get_tod_interval( + struct timeval *time ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - current time obtained successfully -``RTEMS_NOT_DEFINED`` - system date and time is not set -``RTEMS_INVALID_ADDRESS`` - ``time`` is NULL +``RTEMS_SUCCESSFUL`` + current time obtained successfully + +``RTEMS_NOT_DEFINED`` + system date and time is not set + +``RTEMS_INVALID_ADDRESS`` + ``time`` is NULL **DESCRIPTION:** -This directive obtains the system date and time in POSIX``struct timeval`` format. If the date and time -has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned. +This directive obtains the system date and time in POSIX ``struct timeval`` +format. If the date and time has not been set with a previous call to +``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status code is returned. **NOTES:** This directive is callable from an ISR. -This directive will not cause the running task to be -preempted. Re-initializing RTEMS causes the system date and -time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the -system date and time to application specific specifications. +This directive will not cause the running task to be preempted. +Re-initializing RTEMS causes the system date and time to be reset to an +uninitialized state. Another call to ``rtems_clock_set`` is required to +re-initialize the system date and time to application specific specifications. + +.. _rtems_clock_get_seconds_since_epoch: CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch ------------------------------------------------------- @@ -386,29 +420,37 @@ CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch .. code:: c rtems_status_code rtems_clock_get_seconds_since_epoch( - rtems_interval \*the_interval + rtems_interval *the_interval ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - current time obtained successfully -``RTEMS_NOT_DEFINED`` - system date and time is not set -``RTEMS_INVALID_ADDRESS`` - ``the_interval`` is NULL +``RTEMS_SUCCESSFUL`` + current time obtained successfully + +``RTEMS_NOT_DEFINED`` + system date and time is not set + +``RTEMS_INVALID_ADDRESS`` + ``the_interval`` is NULL **DESCRIPTION:** -This directive returns the number of seconds since the RTEMS -epoch and the current system date and time. If the date and time -has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned. +This directive returns the number of seconds since the RTEMS epoch and the +current system date and time. If the date and time has not been set with a +previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status +code is returned. **NOTES:** This directive is callable from an ISR. -This directive will not cause the running task to be -preempted. Re-initializing RTEMS causes the system date and -time to be reset to an uninitialized state. Another call to``rtems_clock_set`` is required to re-initialize the -system date and time to application specific specifications. +This directive will not cause the running task to be preempted. +Re-initializing RTEMS causes the system date and time to be reset to an +uninitialized state. Another call to ``rtems_clock_set`` is required to +re-initialize the system date and time to application specific specifications. + +.. _rtems_clock_get_ticks_per_second: CLOCK_GET_TICKS_PER_SECOND - Get ticks per second ------------------------------------------------- @@ -428,9 +470,8 @@ NONE **DESCRIPTION:** -This directive returns the number of clock ticks per second. This -is strictly based upon the microseconds per clock tick that the -application has configured. +This directive returns the number of clock ticks per second. This is strictly +based upon the microseconds per clock tick that the application has configured. **NOTES:** @@ -438,6 +479,8 @@ This directive is callable from an ISR. This directive will not cause the running task to be preempted. +.. _rtems_clock_get_ticks_since_boot: + CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value ------------------------------------------------------------ .. index:: obtain ticks since boot @@ -459,8 +502,9 @@ NONE This directive returns the current tick counter value. With a 1ms clock tick, this counter overflows after 50 days since boot. This is the historical -measure of uptime in an RTEMS system. The newer service``rtems_clock_get_uptime`` is another and potentially more -accurate way of obtaining similar information. +measure of uptime in an RTEMS system. The newer service +``rtems_clock_get_uptime`` is another and potentially more accurate way of +obtaining similar information. **NOTES:** @@ -468,6 +512,8 @@ This directive is callable from an ISR. This directive will not cause the running task to be preempted. +.. _rtems_clock_tick_later: + CLOCK_TICK_LATER - Get tick value in the future ----------------------------------------------- @@ -478,7 +524,7 @@ CLOCK_TICK_LATER - Get tick value in the future .. code:: c rtems_interval rtems_clock_tick_later( - rtems_interval delta + rtems_interval delta ); **DESCRIPTION:** @@ -491,6 +537,8 @@ This directive is callable from an ISR. This directive will not cause the running task to be preempted. +.. _rtems_clock_tick_later_usec: + CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds -------------------------------------------------------------------- @@ -501,7 +549,7 @@ CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds .. code:: c rtems_interval rtems_clock_tick_later_usec( - rtems_interval delta_in_usec + rtems_interval delta_in_usec ); **DESCRIPTION:** @@ -514,6 +562,8 @@ This directive is callable from an ISR. This directive will not cause the running task to be preempted. +.. _rtems_clock_tick_before: + CLOCK_TICK_BEFORE - Is tick value is before a point in time ----------------------------------------------------------- @@ -524,7 +574,7 @@ CLOCK_TICK_BEFORE - Is tick value is before a point in time .. code:: c rtems_interval rtems_clock_tick_before( - rtems_interval tick + rtems_interval tick ); **DESCRIPTION:** @@ -544,15 +594,17 @@ This directive will not cause the running task to be preempted. status busy( void ) { - rtems_interval timeout = rtems_clock_tick_later_usec( 10000 ); - do { - if ( ok() ) { - return success; - } - } while ( rtems_clock_tick_before( timeout ) ); - return timeout; + rtems_interval timeout = rtems_clock_tick_later_usec( 10000 ); + do { + if ( ok() ) { + return success; + } + } while ( rtems_clock_tick_before( timeout ) ); + return timeout; } +.. _rtems_clock_get_uptime: + CLOCK_GET_UPTIME - Get the time since boot ------------------------------------------ .. index:: clock get uptime @@ -565,28 +617,32 @@ CLOCK_GET_UPTIME - Get the time since boot .. code:: c rtems_status_code rtems_clock_get_uptime( - struct timespec \*uptime + struct timespec *uptime ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - clock tick processed successfully -``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL +``RTEMS_SUCCESSFUL`` + clock tick processed successfully + +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL **DESCRIPTION:** -This directive returns the seconds and nanoseconds since the -system was booted. If the BSP supports nanosecond clock -accuracy, the time reported will probably be different on every -call. +This directive returns the seconds and nanoseconds since the system was booted. +If the BSP supports nanosecond clock accuracy, the time reported will probably +be different on every call. **NOTES:** This directive may be called from an ISR. +.. _rtems_clock_get_uptime_timeval: + CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format -------------------------------------------------------------------- -.. index:: clock get uptime +.. index:: clock get uptime interval .. index:: uptime **CALLING SEQUENCE:** @@ -596,7 +652,7 @@ CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format .. code:: c void rtems_clock_get_uptime_timeval( - struct timeval \*uptime + struct timeval *uptime ); **DIRECTIVE STATUS CODES:** @@ -605,18 +661,19 @@ NONE **DESCRIPTION:** -This directive returns the seconds and microseconds since the -system was booted. If the BSP supports nanosecond clock -accuracy, the time reported will probably be different on every -call. +This directive returns the seconds and microseconds since the system was +booted. If the BSP supports nanosecond clock accuracy, the time reported will +probably be different on every call. **NOTES:** This directive may be called from an ISR. +.. _rtems_clock_get_uptime_seconds: + CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot ----------------------------------------------------- -.. index:: clock get uptime +.. index:: clock get uptime seconds .. index:: uptime **CALLING SEQUENCE:** @@ -639,6 +696,8 @@ This directive returns the seconds since the system was booted. This directive may be called from an ISR. +.. _rtems_clock_get_uptime_nanoseconds: + CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot ------------------------------------------------------------- .. index:: clock get nanoseconds uptime @@ -664,6 +723,8 @@ This directive returns the nanoseconds since the system was booted. This directive may be called from an ISR. +.. _rtems_clock_set_nanoseconds_extension: + CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler --------------------------------------------------------------------------------- .. index:: clock set nanoseconds extension @@ -677,32 +738,37 @@ CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handle .. code:: c rtems_status_code rtems_clock_set_nanoseconds_extension( - rtems_nanoseconds_extension_routine routine + rtems_nanoseconds_extension_routine routine ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - clock tick processed successfully -``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL +``RTEMS_SUCCESSFUL`` + clock tick processed successfully + +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL **DESCRIPTION:** -This directive is used by the Clock device driver to install the``routine`` which will be invoked by the internal RTEMS method used to -obtain a highly accurate time of day. It is usually called during -the initialization of the driver. +This directive is used by the Clock device driver to install the ``routine`` +which will be invoked by the internal RTEMS method used to obtain a highly +accurate time of day. It is usually called during the initialization of the +driver. -When the ``routine`` is invoked, it will determine the number of -nanoseconds which have elapsed since the last invocation of -the ``rtems_clock_tick`` directive. It should do -this as quickly as possible with as little impact as possible -on the device used as a clock source. +When the ``routine`` is invoked, it will determine the number of nanoseconds +which have elapsed since the last invocation of the ``rtems_clock_tick`` +directive. It should do this as quickly as possible with as little impact as +possible on the device used as a clock source. **NOTES:** This directive may be called from an ISR. -This directive is called as part of every service to obtain the -current date and time as well as timestamps. +This directive is called as part of every service to obtain the current date +and time as well as timestamps. + +.. _rtems_clock_tick: CLOCK_TICK - Announce a clock tick ---------------------------------- @@ -718,29 +784,21 @@ CLOCK_TICK - Announce a clock tick **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - clock tick processed successfully +``RTEMS_SUCCESSFUL`` + clock tick processed successfully **DESCRIPTION:** -This directive announces to RTEMS that a system clock -tick has occurred. The directive is usually called from the -timer interrupt ISR of the local processor. This directive -maintains the system date and time, decrements timers for -delayed tasks, timeouts, rate monotonic periods, and implements +This directive announces to RTEMS that a system clock tick has occurred. The +directive is usually called from the timer interrupt ISR of the local +processor. This directive maintains the system date and time, decrements +timers for delayed tasks, timeouts, rate monotonic periods, and implements timeslicing. **NOTES:** This directive is typically called from an ISR. -The ``microseconds_per_tick`` and ``ticks_per_timeslice`` -parameters in the Configuration Table contain the number of -microseconds per tick and number of ticks per timeslice, -respectively. - -.. COMMENT: COPYRIGHT (c) 1988-2008. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - +The ``microseconds_per_tick`` and ``ticks_per_timeslice`` parameters in the +Configuration Table contain the number of microseconds per tick and number of +ticks per timeslice, respectively. diff --git a/c_user/initialization.rst b/c_user/initialization.rst index e2a823b..95c6e59 100644 --- a/c_user/initialization.rst +++ b/c_user/initialization.rst @@ -1,16 +1,19 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Initialization Manager ###################### Introduction ============ -The Initialization Manager is responsible for -initiating and shutting down RTEMS. Initiating RTEMS involves -creating and starting all configured initialization tasks, and -for invoking the initialization routine for each user-supplied -device driver. In a multiprocessor configuration, this manager -also initializes the interprocessor communications layer. The -directives provided by the Initialization Manager are: +The Initialization Manager is responsible for initiating and shutting down +RTEMS. Initiating RTEMS involves creating and starting all configured +initialization tasks, and for invoking the initialization routine for each +user-supplied device driver. In a multiprocessor configuration, this manager +also initializes the interprocessor communications layer. The directives +provided by the Initialization Manager are: - ``rtems_initialize_executive`` - Initialize RTEMS @@ -23,97 +26,85 @@ Initialization Tasks -------------------- .. index:: initialization tasks -Initialization task(s) are the mechanism by which -RTEMS transfers initial control to the user's application. -Initialization tasks differ from other application tasks in that -they are defined in the User Initialization Tasks Table and -automatically created and started by RTEMS as part of its -initialization sequence. Since the initialization tasks are -scheduled using the same algorithm as all other RTEMS tasks, -they must be configured at a priority and mode which will ensure -that they will complete execution before other application tasks -execute. Although there is no upper limit on the number of -initialization tasks, an application is required to define at -least one. - -A typical initialization task will create and start -the static set of application tasks. It may also create any -other objects used by the application. Initialization tasks -which only perform initialization should delete themselves upon -completion to free resources for other tasks. Initialization -tasks may transform themselves into a "normal" application task. -This transformation typically involves changing priority and -execution mode. RTEMS does not automatically delete the -initialization tasks. +Initialization task(s) are the mechanism by which RTEMS transfers initial +control to the user's application. Initialization tasks differ from other +application tasks in that they are defined in the User Initialization Tasks +Table and automatically created and started by RTEMS as part of its +initialization sequence. Since the initialization tasks are scheduled using +the same algorithm as all other RTEMS tasks, they must be configured at a +priority and mode which will ensure that they will complete execution before +other application tasks execute. Although there is no upper limit on the +number of initialization tasks, an application is required to define at least +one. + +A typical initialization task will create and start the static set of +application tasks. It may also create any other objects used by the +application. Initialization tasks which only perform initialization should +delete themselves upon completion to free resources for other tasks. +Initialization tasks may transform themselves into a "normal" application task. +This transformation typically involves changing priority and execution mode. +RTEMS does not automatically delete the initialization tasks. System Initialization --------------------- -System Initialization begins with board reset and continues -through RTEMS initialization, initialization of all device -drivers, and eventually a context switch to the first user -task. Remember, that interrupts are disabled during -initialization and the *initialization context* is not -a task in any sense and the user should be very careful -during initialization. - -The BSP must ensure that the there is enough stack -space reserved for the initialization context to -successfully execute the initialization routines for -all device drivers and, in multiprocessor configurations, the -Multiprocessor Communications Interface Layer initialization -routine. +System Initialization begins with board reset and continues through RTEMS +initialization, initialization of all device drivers, and eventually a context +switch to the first user task. Remember, that interrupts are disabled during +initialization and the *initialization context* is not a task in any sense and +the user should be very careful during initialization. + +The BSP must ensure that the there is enough stack space reserved for the +initialization context to successfully execute the initialization routines for +all device drivers and, in multiprocessor configurations, the Multiprocessor +Communications Interface Layer initialization routine. The Idle Task ------------- -The Idle Task is the lowest priority task in a system -and executes only when no other task is ready to execute. This -default implementation of this task consists of an infinite -loop. RTEMS allows the Idle Task body to be replaced by a CPU -specific implementation, a BSP specific implementation or an -application specific implementation. +The Idle Task is the lowest priority task in a system and executes only when no +other task is ready to execute. This default implementation of this task +consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by +a CPU specific implementation, a BSP specific implementation or an application +specific implementation. -The Idle Task is preemptible and *WILL* be preempted when -any other task is made ready to execute. This characteristic is -critical to the overall behavior of any application. +The Idle Task is preemptible and *WILL* be preempted when any other task is +made ready to execute. This characteristic is critical to the overall behavior +of any application. Initialization Manager Failure ------------------------------ -The ``rtems_fatal_error_occurred`` directive will -be invoked from ``rtems_initialize_executive`` -for any of the following reasons: +The ``rtems_fatal_error_occurred`` directive will be invoked from +``rtems_initialize_executive`` for any of the following reasons: -- If either the Configuration Table or the CPU Dependent - Information Table is not provided. +- If either the Configuration Table or the CPU Dependent Information Table is + not provided. -- If the starting address of the RTEMS RAM Workspace, - supplied by the application in the Configuration Table, is NULL - or is not aligned on a four-byte boundary. +- If the starting address of the RTEMS RAM Workspace, supplied by the + application in the Configuration Table, is NULL or is not aligned on a + four-byte boundary. -- If the size of the RTEMS RAM Workspace is not large - enough to initialize and configure the system. +- If the size of the RTEMS RAM Workspace is not large enough to initialize and + configure the system. - If the interrupt stack size specified is too small. -- If multiprocessing is configured and the node entry in - the Multiprocessor Configuration Table is not between one and - the maximum_nodes entry. +- If multiprocessing is configured and the node entry in the Multiprocessor + Configuration Table is not between one and the maximum_nodes entry. -- If a multiprocessor system is being configured and no - Multiprocessor Communications Interface is specified. +- If a multiprocessor system is being configured and no Multiprocessor + Communications Interface is specified. -- If no user initialization tasks are configured. At - least one initialization task must be configured to allow RTEMS - to pass control to the application at the end of the executive - initialization sequence. +- If no user initialization tasks are configured. At least one initialization + task must be configured to allow RTEMS to pass control to the application at + the end of the executive initialization sequence. -- If any of the user initialization tasks cannot be - created or started successfully. +- If any of the user initialization tasks cannot be created or started + successfully. -A discussion of RTEMS actions when a fatal error occurs -may be found `Announcing a Fatal Error`_. +A discussion of RTEMS actions when a fatal error occurs may be found +`Announcing a Fatal Error`_. Operations ========== @@ -121,10 +112,10 @@ Operations Initializing RTEMS ------------------ -The Initialization Manager ``rtems_initialize_executive`` -directives is called by the ``boot_card`` routine. The ``boot_card`` -routine is invoked by the Board Support Package once a basic C run-time -environment is set up. This consists of +The Initialization Manager ``rtems_initialize_executive`` directives is called +by the ``boot_card`` routine. The ``boot_card`` routine is invoked by the +Board Support Package once a basic C run-time environment is set up. This +consists of - a valid and accessible text section, read-only data, read-write data and zero-initialized data, @@ -136,85 +127,83 @@ environment is set up. This consists of - disabled interrupts. -The ``rtems_initialize_executive`` directive uses a system -initialization linker set to initialize only those parts of the overall RTEMS -feature set that is necessary for a particular application. See `Linker Sets`_. -Each RTEMS feature used the application may optionally register an -initialization handler. The system initialization API is available via``#included <rtems/sysinit.h>``. +The ``rtems_initialize_executive`` directive uses a system initialization +linker set to initialize only those parts of the overall RTEMS feature set that +is necessary for a particular application. See `Linker Sets`_. Each RTEMS +feature used the application may optionally register an initialization handler. +The system initialization API is available via``#included <rtems/sysinit.h>``. A list of all initialization steps follows. Some steps are optional depending on the requested feature set of the application. The initialization steps are execute in the order presented here. -:dfn:`RTEMS_SYSINIT_BSP_WORK_AREAS` +`RTEMS_SYSINIT_BSP_WORK_AREAS` The work areas consisting of C Program Heap and the RTEMS Workspace are initialized by the Board Support Package. This step is mandatory. -:dfn:`RTEMS_SYSINIT_BSP_START` - Basic initialization step provided by the Board Support Package. This step is - mandatory. - -:dfn:`RTEMS_SYSINIT_DATA_STRUCTURES` - This directive is called when the Board Support Package has completed its basic - initialization and allows RTEMS to initialize the application environment based - upon the information in the Configuration Table, User Initialization Tasks - Table, Device Driver Table, User Extension Table, Multiprocessor Configuration - Table, and the Multiprocessor Communications Interface (MPCI) Table. - -:dfn:`RTEMS_SYSINIT_BSP_LIBC` - Depending on the application configuration the IO library and root filesystem - is initialized. This step is mandatory. - -:dfn:`RTEMS_SYSINIT_BEFORE_DRIVERS` - This directive performs initialization that must occur between basis RTEMS data - structure initialization and device driver initialization. In particular, in a - multiprocessor configuration, this directive will create the MPCI Server Task. - -:dfn:`RTEMS_SYSINIT_BSP_PRE_DRIVERS` +`RTEMS_SYSINIT_BSP_START` + Basic initialization step provided by the Board Support Package. This step + is mandatory. + +`RTEMS_SYSINIT_DATA_STRUCTURES` + This directive is called when the Board Support Package has completed its + basic initialization and allows RTEMS to initialize the application + environment based upon the information in the Configuration Table, User + Initialization Tasks Table, Device Driver Table, User Extension Table, + Multiprocessor Configuration Table, and the Multiprocessor Communications + Interface (MPCI) Table. + +`RTEMS_SYSINIT_BSP_LIBC` + Depending on the application configuration the IO library and root + filesystem is initialized. This step is mandatory. + +`RTEMS_SYSINIT_BEFORE_DRIVERS` + This directive performs initialization that must occur between basis RTEMS + data structure initialization and device driver initialization. In + particular, in a multiprocessor configuration, this directive will create + the MPCI Server Task. + +`RTEMS_SYSINIT_BSP_PRE_DRIVERS` Initialization step performed right before device drivers are initialized provided by the Board Support Package. This step is mandatory. -:dfn:`RTEMS_SYSINIT_DEVICE_DRIVERS` - This step initializes all statically configured device drivers and performs all - RTEMS initialization which requires device drivers to be initialized. This - step is mandatory. - In a multiprocessor configuration, this service will initialize the - Multiprocessor Communications Interface (MPCI) and synchronize with the other - nodes in the system. +`RTEMS_SYSINIT_DEVICE_DRIVERS` + This step initializes all statically configured device drivers and performs + all RTEMS initialization which requires device drivers to be initialized. + This step is mandatory. In a multiprocessor configuration, this service + will initialize the Multiprocessor Communications Interface (MPCI) and + synchronize with the other nodes in the system. -:dfn:`RTEMS_SYSINIT_BSP_POST_DRIVERS` +`RTEMS_SYSINIT_BSP_POST_DRIVERS` Initialization step performed right after device drivers are initialized provided by the Board Support Package. This step is mandatory. -The final action of the ``rtems_initialize_executive`` directive -is to start multitasking. RTEMS does not return to the initialization context -and the initialization stack may be re-used for interrupt processing. +The final action of the ``rtems_initialize_executive`` directive is to start +multitasking. RTEMS does not return to the initialization context and the +initialization stack may be re-used for interrupt processing. -Many of RTEMS actions during initialization are based upon -the contents of the Configuration Table. For more information -regarding the format and contents of this table, please refer -to the chapter `Configuring a System`_. +Many of RTEMS actions during initialization are based upon the contents of the +Configuration Table. For more information regarding the format and contents of +this table, please refer to the chapter `Configuring a System`_. -The final action in the initialization sequence is the -initiation of multitasking. When the scheduler and dispatcher -are enabled, the highest priority, ready task will be dispatched -to run. Control will not be returned to the Board Support -Package after multitasking is enabled. The initialization stack may be re-used -for interrupt processing. +The final action in the initialization sequence is the initiation of +multitasking. When the scheduler and dispatcher are enabled, the highest +priority, ready task will be dispatched to run. Control will not be returned +to the Board Support Package after multitasking is enabled. The initialization +stack may be re-used for interrupt processing. Shutting Down RTEMS ------------------- -The ``rtems_shutdown_executive`` directive is invoked by the -application to end multitasking and terminate the system. +The ``rtems_shutdown_executive`` directive is invoked by the application to end +multitasking and terminate the system. Directives ========== -This section details the Initialization 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. +This section details the Initialization 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. INITIALIZE_EXECUTIVE - Initialize RTEMS --------------------------------------- @@ -256,7 +245,7 @@ SHUTDOWN_EXECUTIVE - Shutdown RTEMS .. code:: c void rtems_shutdown_executive( - uint32_t result + uint32_t result ); **DIRECTIVE STATUS CODES:** @@ -266,19 +255,12 @@ NONE **DESCRIPTION:** This directive is called when the application wishes to shutdown RTEMS. The -system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and -the specified ``result`` code. +system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and the +specified ``result`` code. **NOTES:** -This directive *must* be the last RTEMS directive -invoked by an application and it *does not return* to the caller. +This directive *must* be the last RTEMS directive invoked by an application and +it *does not return* to the caller. This directive may be called any time. - -.. COMMENT: COPYRIGHT (c) 1988-2014. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - diff --git a/c_user/interrupt_manager.rst b/c_user/interrupt_manager.rst index 52f4339..7f42bd2 100644 --- a/c_user/interrupt_manager.rst +++ b/c_user/interrupt_manager.rst @@ -1,41 +1,43 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Interrupt Manager ################# Introduction ============ -Any real-time executive must provide a mechanism for -quick response to externally generated interrupts to satisfy the -critical time constraints of the application. The interrupt -manager provides this mechanism for RTEMS. This manager permits -quick interrupt response times by providing the critical ability -to alter task execution which allows a task to be preempted upon -exit from an ISR. The interrupt manager includes the following -directive: +Any real-time executive must provide a mechanism for quick response to +externally generated interrupts to satisfy the critical time constraints of the +application. The interrupt manager provides this mechanism for RTEMS. This +manager permits quick interrupt response times by providing the critical +ability to alter task execution which allows a task to be preempted upon exit +from an ISR. The interrupt manager includes the following directive: -- ``rtems_interrupt_catch`` - Establish an ISR +- rtems_interrupt_catch_ - Establish an ISR -- ``rtems_interrupt_disable`` - Disable Interrupts +- rtems_interrupt_disable_ - Disable Interrupts -- ``rtems_interrupt_enable`` - Enable Interrupts +- rtems_interrupt_enable_ - Enable Interrupts -- ``rtems_interrupt_flash`` - Flash Interrupt +- rtems_interrupt_flash_ - Flash Interrupt -- ``rtems_interrupt_local_disable`` - Disable Interrupts on Current Processor +- rtems_interrupt_local_disable_ - Disable Interrupts on Current Processor -- ``rtems_interrupt_local_enable`` - Enable Interrupts on Current Processor +- rtems_interrupt_local_enable_ - Enable Interrupts on Current Processor -- ``rtems_interrupt_lock_initialize`` - Initialize an ISR Lock +- rtems_interrupt_lock_initialize_ - Initialize an ISR Lock -- ``rtems_interrupt_lock_acquire`` - Acquire an ISR Lock +- rtems_interrupt_lock_acquire_ - Acquire an ISR Lock -- ``rtems_interrupt_lock_release`` - Release an ISR Lock +- rtems_interrupt_lock_release_ - Release an ISR Lock -- ``rtems_interrupt_lock_acquire_isr`` - Acquire an ISR Lock from ISR +- rtems_interrupt_lock_acquire_isr_ - Acquire an ISR Lock from ISR -- ``rtems_interrupt_lock_release_isr`` - Release an ISR Lock from ISR +- rtems_interrupt_lock_release_isr_ - Release an ISR Lock from ISR -- ``rtems_interrupt_is_in_progress`` - Is an ISR in Progress +- rtems_interrupt_is_in_progress_ - Is an ISR in Progress Background ========== @@ -44,108 +46,98 @@ Processing an Interrupt ----------------------- .. index:: interrupt processing -The interrupt manager allows the application to -connect a function to a hardware interrupt vector. When an -interrupt occurs, the processor will automatically vector to -RTEMS. RTEMS saves and restores all registers which are not -preserved by the normal C calling convention -for the target -processor and invokes the user's ISR. The user's ISR is -responsible for processing the interrupt, clearing the interrupt -if necessary, and device specific manipulation... index:: rtems_vector_number - -The ``rtems_interrupt_catch`` -directive connects a procedure to -an interrupt vector. The vector number is managed using -the ``rtems_vector_number`` data type. - -The interrupt service routine is assumed -to abide by these conventions and have a prototype similar to -the following:.. index:: rtems_isr +The interrupt manager allows the application to connect a function to a +hardware interrupt vector. When an interrupt occurs, the processor will +automatically vector to RTEMS. RTEMS saves and restores all registers which +are not preserved by the normal C calling convention for the target processor +and invokes the user's ISR. The user's ISR is responsible for processing the +interrupt, clearing the interrupt if necessary, and device specific +manipulation. + +.. index:: rtems_vector_number + +The ``rtems_interrupt_catch`` directive connects a procedure to an interrupt +vector. The vector number is managed using the ``rtems_vector_number`` data +type. + +The interrupt service routine is assumed to abide by these conventions and have +a prototype similar to the following: + +.. index:: rtems_isr .. code:: c rtems_isr user_isr( - rtems_vector_number vector + rtems_vector_number vector ); -The vector number argument is provided by RTEMS to -allow the application to identify the interrupt source. This -could be used to allow a single routine to service interrupts -from multiple instances of the same device. For example, a -single routine could service interrupts from multiple serial -ports and use the vector number to identify which port requires -servicing. - -To minimize the masking of lower or equal priority -level interrupts, the ISR should perform the minimum actions -required to service the interrupt. Other non-essential actions -should be handled by application tasks. Once the user's ISR has -completed, it returns control to the RTEMS interrupt manager -which will perform task dispatching and restore the registers -saved before the ISR was invoked. - -The RTEMS interrupt manager guarantees that proper -task scheduling and dispatching are performed at the conclusion -of an ISR. A system call made by the ISR may have readied a -task of higher priority than the interrupted task. Therefore, -when the ISR completes, the postponed dispatch processing must -be performed. No dispatch processing is performed as part of -directives which have been invoked by an ISR. - -Applications must adhere to the following rule if -proper task scheduling and dispatching is to be performed: - -- ** *The interrupt manager must be used for all ISRs which - may be interrupted by the highest priority ISR which invokes an - RTEMS directive.* - -Consider a processor which allows a numerically low -interrupt level to interrupt a numerically greater interrupt -level. In this example, if an RTEMS directive is used in a -level 4 ISR, then all ISRs which execute at levels 0 through 4 -must use the interrupt manager. - -Interrupts are nested whenever an interrupt occurs -during the execution of another ISR. RTEMS supports efficient -interrupt nesting by allowing the nested ISRs to terminate -without performing any dispatch processing. Only when the +The vector number argument is provided by RTEMS to allow the application to +identify the interrupt source. This could be used to allow a single routine to +service interrupts from multiple instances of the same device. For example, a +single routine could service interrupts from multiple serial ports and use the +vector number to identify which port requires servicing. + +To minimize the masking of lower or equal priority level interrupts, the ISR +should perform the minimum actions required to service the interrupt. Other +non-essential actions should be handled by application tasks. Once the user's +ISR has completed, it returns control to the RTEMS interrupt manager which will +perform task dispatching and restore the registers saved before the ISR was +invoked. + +The RTEMS interrupt manager guarantees that proper task scheduling and +dispatching are performed at the conclusion of an ISR. A system call made by +the ISR may have readied a task of higher priority than the interrupted task. +Therefore, when the ISR completes, the postponed dispatch processing must be +performed. No dispatch processing is performed as part of directives which +have been invoked by an ISR. + +Applications must adhere to the following rule if proper task scheduling and +dispatching is to be performed: + +.. note:: + + The interrupt manager must be used for all ISRs which may be interrupted by + the highest priority ISR which invokes an RTEMS directive. + +Consider a processor which allows a numerically low interrupt level to +interrupt a numerically greater interrupt level. In this example, if an RTEMS +directive is used in a level 4 ISR, then all ISRs which execute at levels 0 +through 4 must use the interrupt manager. + +Interrupts are nested whenever an interrupt occurs during the execution of +another ISR. RTEMS supports efficient interrupt nesting by allowing the nested +ISRs to terminate without performing any dispatch processing. Only when the outermost ISR terminates will the postponed dispatching occur. RTEMS Interrupt Levels ---------------------- .. index:: interrupt levels -Many processors support multiple interrupt levels or -priorities. The exact number of interrupt levels is processor -dependent. RTEMS internally supports 256 interrupt levels which -are mapped to the processor's interrupt levels. For specific -information on the mapping between RTEMS and the target -processor's interrupt levels, refer to the Interrupt Processing -chapter of the Applications Supplement document for a specific -target processor. +Many processors support multiple interrupt levels or priorities. The exact +number of interrupt levels is processor dependent. RTEMS internally supports +256 interrupt levels which are mapped to the processor's interrupt levels. For +specific information on the mapping between RTEMS and the target processor's +interrupt levels, refer to the Interrupt Processing chapter of the Applications +Supplement document for a specific target processor. Disabling of Interrupts by RTEMS -------------------------------- .. index:: disabling interrupts -During the execution of directive calls, critical -sections of code may be executed. When these sections are -encountered, RTEMS disables all maskable interrupts before the -execution of the section and restores them to the previous level -upon completion of the section. RTEMS has been optimized to -ensure that interrupts are disabled for a minimum length of -time. The maximum length of time interrupts are disabled by -RTEMS is processor dependent and is detailed in the Timing -Specification chapter of the Applications Supplement document -for a specific target processor. - -Non-maskable interrupts (NMI) cannot be disabled, and -ISRs which execute at this level MUST NEVER issue RTEMS system -calls. If a directive is invoked, unpredictable results may -occur due to the inability of RTEMS to protect its critical -sections. However, ISRs that make no system calls may safely -execute as non-maskable interrupts. +During the execution of directive calls, critical sections of code may be +executed. When these sections are encountered, RTEMS disables all maskable +interrupts before the execution of the section and restores them to the +previous level upon completion of the section. RTEMS has been optimized to +ensure that interrupts are disabled for a minimum length of time. The maximum +length of time interrupts are disabled by RTEMS is processor dependent and is +detailed in the Timing Specification chapter of the Applications Supplement +document for a specific target processor. + +Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at +this level MUST NEVER issue RTEMS system calls. If a directive is invoked, +unpredictable results may occur due to the inability of RTEMS to protect its +critical sections. However, ISRs that make no system calls may safely execute +as non-maskable interrupts. Operations ========== @@ -153,32 +145,28 @@ Operations Establishing an ISR ------------------- -The ``rtems_interrupt_catch`` -directive establishes an ISR for -the system. The address of the ISR and its associated CPU -vector number are specified to this directive. This directive -installs the RTEMS interrupt wrapper in the processor's -Interrupt Vector Table and the address of the user's ISR in the -RTEMS' Vector Table. This directive returns the previous -contents of the specified vector in the RTEMS' Vector Table. +The ``rtems_interrupt_catch`` directive establishes an ISR for the system. The +address of the ISR and its associated CPU vector number are specified to this +directive. This directive installs the RTEMS interrupt wrapper in the +processor's Interrupt Vector Table and the address of the user's ISR in the +RTEMS' Vector Table. This directive returns the previous contents of the +specified vector in the RTEMS' Vector Table. Directives Allowed from an ISR ------------------------------ -Using the interrupt manager ensures that RTEMS knows -when a directive is being called from an ISR. The ISR may then -use system calls to synchronize itself with an application task. -The synchronization may involve messages, events or signals -being passed by the ISR to the desired task. Directives invoked -by an ISR must operate only on objects which reside on the local -node. The following is a list of RTEMS system calls that may be -made from an ISR: +Using the interrupt manager ensures that RTEMS knows when a directive is being +called from an ISR. The ISR may then use system calls to synchronize itself +with an application task. The synchronization may involve messages, events or +signals being passed by the ISR to the desired task. Directives invoked by an +ISR must operate only on objects which reside on the local node. The following +is a list of RTEMS system calls that may be made from an ISR: - Task Management - Although it is acceptable to operate on the RTEMS_SELF task (e.g. - the currently executing task), while in an ISR, this will refer - to the interrupted task. Most of the time, it is an application - implementation error to use RTEMS_SELF from an ISR. + Although it is acceptable to operate on the RTEMS_SELF task (e.g. the + currently executing task), while in an ISR, this will refer to the + interrupted task. Most of the time, it is an application implementation + error to use RTEMS_SELF from an ISR. - rtems_task_suspend - rtems_task_resume @@ -253,10 +241,11 @@ made from an ISR: Directives ========== -This section details the interrupt 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. +This section details the interrupt 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. + +.. _rtems_interrupt_catch: INTERRUPT_CATCH - Establish an ISR ---------------------------------- @@ -270,31 +259,38 @@ INTERRUPT_CATCH - Establish an ISR .. code:: c rtems_status_code rtems_interrupt_catch( - rtems_isr_entry new_isr_handler, - rtems_vector_number vector, - rtems_isr_entry \*old_isr_handler + rtems_isr_entry new_isr_handler, + rtems_vector_number vector, + rtems_isr_entry *old_isr_handler ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - ISR established successfully -``RTEMS_INVALID_NUMBER`` - illegal vector number -``RTEMS_INVALID_ADDRESS`` - illegal ISR entry point or invalid ``old_isr_handler`` +``RTEMS_SUCCESSFUL`` + ISR established successfully + +``RTEMS_INVALID_NUMBER`` + illegal vector number + +``RTEMS_INVALID_ADDRESS`` + illegal ISR entry point or invalid ``old_isr_handler`` **DESCRIPTION:** -This directive establishes an interrupt service -routine (ISR) for the specified interrupt vector number. The``new_isr_handler`` parameter specifies the entry point of the ISR. -The entry point of the previous ISR for the specified vector is -returned in ``old_isr_handler``. +This directive establishes an interrupt service routine (ISR) for the specified +interrupt vector number. The ``new_isr_handler`` parameter specifies the entry +point of the ISR. The entry point of the previous ISR for the specified vector +is returned in ``old_isr_handler``. -To release an interrupt vector, pass the old handler's address obtained -when the vector was first capture. +To release an interrupt vector, pass the old handler's address obtained when +the vector was first capture. **NOTES:** This directive will not cause the calling task to be preempted. +.. _rtems_interrupt_disable: + INTERRUPT_DISABLE - Disable Interrupts -------------------------------------- .. index:: disable interrupts @@ -306,9 +302,8 @@ INTERRUPT_DISABLE - Disable Interrupts .. code:: c void rtems_interrupt_disable( - rtems_interrupt_level level + rtems_interrupt_level level ); - /* this is implemented as a macro and sets level as a side-effect \*/ **DIRECTIVE STATUS CODES:** @@ -316,20 +311,23 @@ NONE **DESCRIPTION:** -This directive disables all maskable interrupts and returns -the previous ``level``. A later invocation of the``rtems_interrupt_enable`` directive should be used to -restore the interrupt level. +.. sidebar:: *Macro* + + This directive is implemented as a macro which modifies the ``level`` + parameter. + +This directive disables all maskable interrupts and returns the previous +``level``. A later invocation of the ``rtems_interrupt_enable`` directive +should be used to restore the interrupt level. **NOTES:** This directive will not cause the calling task to be preempted. -*This directive is implemented as a macro which modifies the ``level`` -parameter.* - This directive is only available on uni-processor configurations. The -directive ``rtems_interrupt_local_disable`` is available on all -configurations. +directive ``rtems_interrupt_local_disable`` is available on all configurations. + +.. _rtems_interrupt_enable: INTERRUPT_ENABLE - Enable Interrupts ------------------------------------ @@ -342,7 +340,7 @@ INTERRUPT_ENABLE - Enable Interrupts .. code:: c void rtems_interrupt_enable( - rtems_interrupt_level level + rtems_interrupt_level level ); **DIRECTIVE STATUS CODES:** @@ -351,19 +349,20 @@ NONE **DESCRIPTION:** -This directive enables maskable interrupts to the ``level`` -which was returned by a previous call to``rtems_interrupt_disable``. -Immediately prior to invoking this directive, maskable interrupts should -be disabled by a call to ``rtems_interrupt_disable`` -and will be enabled when this directive returns to the caller. +This directive enables maskable interrupts to the ``level`` which was returned +by a previous call to ``rtems_interrupt_disable``. Immediately prior to +invoking this directive, maskable interrupts should be disabled by a call to +``rtems_interrupt_disable`` and will be enabled when this directive returns to +the caller. **NOTES:** This directive will not cause the calling task to be preempted. This directive is only available on uni-processor configurations. The -directive ``rtems_interrupt_local_enable`` is available on all -configurations. +directive ``rtems_interrupt_local_enable`` is available on all configurations. + +.. _rtems_interrupt_flash: INTERRUPT_FLASH - Flash Interrupts ---------------------------------- @@ -376,7 +375,7 @@ INTERRUPT_FLASH - Flash Interrupts .. code:: c void rtems_interrupt_flash( - rtems_interrupt_level level + rtems_interrupt_level level ); **DIRECTIVE STATUS CODES:** @@ -385,19 +384,21 @@ NONE **DESCRIPTION:** -This directive temporarily enables maskable interrupts to the ``level`` -which was returned by a previous call to``rtems_interrupt_disable``. -Immediately prior to invoking this directive, maskable interrupts should -be disabled by a call to ``rtems_interrupt_disable`` -and will be redisabled when this directive returns to the caller. +This directive temporarily enables maskable interrupts to the ``level`` which +was returned by a previous call to ``rtems_interrupt_disable``. Immediately +prior to invoking this directive, maskable interrupts should be disabled by a +call to ``rtems_interrupt_disable`` and will be redisabled when this directive +returns to the caller. **NOTES:** This directive will not cause the calling task to be preempted. This directive is only available on uni-processor configurations. The -directives ``rtems_interrupt_local_disable`` and``rtems_interrupt_local_enable`` is available on all -configurations. +directives ``rtems_interrupt_local_disable`` +and``rtems_interrupt_local_enable`` is available on all configurations. + +.. _rtems_interrupt_local_disable: INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor ----------------------------------------------------------------- @@ -410,9 +411,8 @@ INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor .. code:: c void rtems_interrupt_local_disable( - rtems_interrupt_level level + rtems_interrupt_level level ); - /* this is implemented as a macro and sets level as a side-effect \*/ **DIRECTIVE STATUS CODES:** @@ -420,20 +420,24 @@ NONE **DESCRIPTION:** -This directive disables all maskable interrupts and returns -the previous ``level``. A later invocation of the``rtems_interrupt_local_enable`` directive should be used to -restore the interrupt level. +.. sidebar:: *Macro* + + This directive is implemented as a macro which modifies the ``level`` + parameter. + +This directive disables all maskable interrupts and returns the previous +``level``. A later invocation of the ``rtems_interrupt_local_enable`` directive +should be used to restore the interrupt level. **NOTES:** This directive will not cause the calling task to be preempted. -*This directive is implemented as a macro which modifies the ``level`` -parameter.* - On SMP configurations this will not ensure system wide mutual exclusion. Use interrupt locks instead. +.. _rtems_interrupt_local_enable: + INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor --------------------------------------------------------------- .. index:: enable interrupts @@ -445,7 +449,7 @@ INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor .. code:: c void rtems_interrupt_local_enable( - rtems_interrupt_level level + rtems_interrupt_level level ); **DIRECTIVE STATUS CODES:** @@ -454,16 +458,18 @@ NONE **DESCRIPTION:** -This directive enables maskable interrupts to the ``level`` -which was returned by a previous call to``rtems_interrupt_local_disable``. -Immediately prior to invoking this directive, maskable interrupts should -be disabled by a call to ``rtems_interrupt_local_disable`` -and will be enabled when this directive returns to the caller. +This directive enables maskable interrupts to the ``level`` which was returned +by a previous call to ``rtems_interrupt_local_disable``. Immediately prior to +invoking this directive, maskable interrupts should be disabled by a call to +``rtems_interrupt_local_disable`` and will be enabled when this directive +returns to the caller. **NOTES:** This directive will not cause the calling task to be preempted. +.. _rtems_interrupt_lock_initialize: + INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock -------------------------------------------------- @@ -474,7 +480,7 @@ INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock .. code:: c void rtems_interrupt_lock_initialize( - rtems_interrupt_lock \*lock + rtems_interrupt_lock *lock ); **DIRECTIVE STATUS CODES:** @@ -489,6 +495,8 @@ Initializes an interrupt lock. Concurrent initialization leads to unpredictable results. +.. _rtems_interrupt_lock_acquire: + INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock -------------------------------------------- @@ -499,8 +507,8 @@ INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock .. code:: c void rtems_interrupt_lock_acquire( - rtems_interrupt_lock \*lock, - rtems_interrupt_level level + rtems_interrupt_lock *lock, + rtems_interrupt_level level ); **DIRECTIVE STATUS CODES:** @@ -517,6 +525,8 @@ SMP lock. This directive will not cause the calling thread to be preempted. This directive can be used in thread and interrupt context. +.. _rtems_interrupt_lock_release: + INTERRUPT_LOCK_RELEASE - Release an ISR Lock -------------------------------------------- @@ -527,8 +537,8 @@ INTERRUPT_LOCK_RELEASE - Release an ISR Lock .. code:: c void rtems_interrupt_lock_release( - rtems_interrupt_lock \*lock, - rtems_interrupt_level level + rtems_interrupt_lock *lock, + rtems_interrupt_level level ); **DIRECTIVE STATUS CODES:** @@ -545,6 +555,8 @@ releases a SMP lock. This directive will not cause the calling thread to be preempted. This directive can be used in thread and interrupt context. +.. _rtems_interrupt_lock_acquire_isr: + INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR --------------------------------------------------------- @@ -555,8 +567,8 @@ INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR .. code:: c void rtems_interrupt_lock_acquire_isr( - rtems_interrupt_lock \*lock, - rtems_interrupt_level level + rtems_interrupt_lock *lock, + rtems_interrupt_level level ); **DIRECTIVE STATUS CODES:** @@ -577,6 +589,8 @@ protected by this lock, then the result is unpredictable. This directive should be called from the corresponding interrupt service routine. +.. _rtems_interrupt_lock_release_isr: + INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR --------------------------------------------------------- @@ -587,8 +601,8 @@ INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR .. code:: c void rtems_interrupt_lock_release_isr( - rtems_interrupt_lock \*lock, - rtems_interrupt_level level + rtems_interrupt_lock *lock, + rtems_interrupt_level level ); **DIRECTIVE STATUS CODES:** @@ -605,6 +619,8 @@ directive releases a SMP lock. This directive should be called from the corresponding interrupt service routine. +.. _rtems_interrupt_is_in_progress: + INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress ------------------------------------------------ .. index:: is interrupt in progress @@ -615,7 +631,7 @@ INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress .. code:: c - bool rtems_interrupt_is_in_progress( void ); + bool rtems_interrupt_is_in_progress(void); **DIRECTIVE STATUS CODES:** @@ -623,19 +639,11 @@ NONE **DESCRIPTION:** -This directive returns ``TRUE`` if the processor is currently -servicing an interrupt and ``FALSE`` otherwise. A return value -of ``TRUE`` indicates that the caller is an interrupt service -routine, *NOT* a task. The directives available to an interrupt -service routine are restricted. +This directive returns ``TRUE`` if the processor is currently servicing an +interrupt and ``FALSE`` otherwise. A return value of ``TRUE`` indicates that +the caller is an interrupt service routine, *NOT* a task. The directives +available to an interrupt service routine are restricted. **NOTES:** This directive will not cause the calling task to be preempted. - -.. COMMENT: COPYRIGHT (c) 1988-2008 - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - diff --git a/c_user/key_concepts.rst b/c_user/key_concepts.rst index 9f4c5ea..0e15af8 100644 --- a/c_user/key_concepts.rst +++ b/c_user/key_concepts.rst @@ -1,106 +1,108 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Key Concepts ############ Introduction ============ -The facilities provided by RTEMS are built upon a -foundation of very powerful concepts. These concepts must be -understood before the application developer can efficiently -utilize RTEMS. The purpose of this chapter is to familiarize +The facilities provided by RTEMS are built upon a foundation of very powerful +concepts. These concepts must be understood before the application developer +can efficiently utilize RTEMS. The purpose of this chapter is to familiarize one with these concepts. +.. _objects: + Objects ======= .. index:: objects -RTEMS provides directives which can be used to -dynamically create, delete, and manipulate a set of predefined -object types. These types include tasks, message queues, -semaphores, memory regions, memory partitions, timers, ports, -and rate monotonic periods. The object-oriented nature of RTEMS -encourages the creation of modular applications built upon -re-usable "building block" routines. - -All objects are created on the local node as required -by the application and have an RTEMS assigned ID. All objects -have a user-assigned name. Although a relationship exists -between an object's name and its RTEMS assigned ID, the name and -ID are not identical. Object names are completely arbitrary and -selected by the user as a meaningful "tag" which may commonly -reflect the object's use in the application. Conversely, object -IDs are designed to facilitate efficient object manipulation by -the executive. +RTEMS provides directives which can be used to dynamically create, delete, and +manipulate a set of predefined object types. These types include tasks, +message queues, semaphores, memory regions, memory partitions, timers, ports, +and rate monotonic periods. The object-oriented nature of RTEMS encourages the +creation of modular applications built upon re-usable "building block" +routines. + +All objects are created on the local node as required by the application and +have an RTEMS assigned ID. All objects have a user-assigned name. Although a +relationship exists between an object's name and its RTEMS assigned ID, the +name and ID are not identical. Object names are completely arbitrary and +selected by the user as a meaningful "tag" which may commonly reflect the +object's use in the application. Conversely, object IDs are designed to +facilitate efficient object manipulation by the executive. Object Names ------------ .. index:: object name .. index:: rtems_object_name -An object name is an unsigned thirty-two bit entity -associated with the object by the user. The data type``rtems_name`` is used to store object names... index:: rtems_build_name +An object name is an unsigned thirty-two bit entity associated with the object +by the user. The data type ``rtems_name`` is used to store object +names... index:: rtems_build_name + +Although not required by RTEMS, object names are often composed of four ASCII +characters which help identify that object. For example, a task which causes a +light to blink might be called "LITE". The ``rtems_build_name`` routine is +provided to build an object name from four ASCII characters. The following +example illustrates this: .. code:: c -Although not required by RTEMS, object names are often -composed of four ASCII characters which help identify that object. -For example, a task which causes a light to blink might be -called "LITE". The ``rtems_build_name`` routine -is provided to build an object name from four ASCII characters. -The following example illustrates this: .. code:: c rtems_object_name my_name; my_name = rtems_build_name( 'L', 'I', 'T', 'E' ); -However, it is not required that the application use ASCII -characters to build object names. For example, if an -application requires one-hundred tasks, it would be difficult to -assign meaningful ASCII names to each task. A more convenient -approach would be to name them the binary values one through +However, it is not required that the application use ASCII characters to build +object names. For example, if an application requires one-hundred tasks, it +would be difficult to assign meaningful ASCII names to each task. A more +convenient approach would be to name them the binary values one through one-hundred, respectively... index:: rtems_object_get_name -RTEMS provides a helper routine, ``rtems_object_get_name``, -which can be used to obtain the name of any RTEMS object using just -its ID. This routine attempts to convert the name into a printable string. +RTEMS provides a helper routine, ``rtems_object_get_name``, which can be used +to obtain the name of any RTEMS object using just its ID. This routine +attempts to convert the name into a printable string. + +The following example illustrates the use of this method to print an object +name: -The following example illustrates the use of this method to print -an object name: .. code:: c #include <rtems.h> #include <rtems/bspIo.h> void print_name(rtems_id id) { - char buffer[10]; /* name assumed to be 10 characters or less \*/ - char \*result; - result = rtems_object_get_name( id, sizeof(buffer), buffer ); - printk( "ID=0x%08x name=%s\\n", id, ((result) ? result : "no name") ); + char buffer[10]; /* name assumed to be 10 characters or less */ + char *result; + result = rtems_object_get_name( id, sizeof(buffer), buffer ); + printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") ); } Object IDs ---------- - .. index:: object ID .. index:: object ID composition .. index:: rtems_id -An object ID is a unique unsigned integer value which uniquely identifies -an object instance. Object IDs are passed as arguments to many directives -in RTEMS and RTEMS translates the ID to an internal object pointer. The -efficient manipulation of object IDs is critical to the performance -of RTEMS services. Because of this, there are two object Id formats -defined. Each target architecture specifies which format it will use. -There is a thirty-two bit format which is used for most of the supported -architectures and supports multiprocessor configurations. There is also -a simpler sixteen bit format which is appropriate for smaller target -architectures and does not support multiprocessor configurations. +An object ID is a unique unsigned integer value which uniquely identifies an +object instance. Object IDs are passed as arguments to many directives in +RTEMS and RTEMS translates the ID to an internal object pointer. The efficient +manipulation of object IDs is critical to the performance of RTEMS services. +Because of this, there are two object Id formats defined. Each target +architecture specifies which format it will use. There is a thirty-two bit +format which is used for most of the supported architectures and supports +multiprocessor configurations. There is also a simpler sixteen bit format +which is appropriate for smaller target architectures and does not support +multiprocessor configurations. Thirty-Two Object ID Format ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The thirty-two bit format for an object ID is composed of four parts: API, -object class, node, and index. The data type ``rtems_id`` -is used to store object IDs. +object class, node, and index. The data type ``rtems_id`` is used to store +object IDs. .. code:: c @@ -111,21 +113,19 @@ is used to store object IDs. | | | | | +---------+-------+--------------+-------------------------------+ -The most significant five bits are the object class. The next -three bits indicate the API to which the object class belongs. -The next eight bits (16-23) are the number of the node on which -this object was created. The node number is always one (1) in a single -processor system. The least significant sixteen bits form an -identifier within a particular object type. This identifier, -called the object index, ranges in value from 1 to the maximum +The most significant five bits are the object class. The next three bits +indicate the API to which the object class belongs. The next eight bits +(16-23) are the number of the node on which this object was created. The node +number is always one (1) in a single processor system. The least significant +sixteen bits form an identifier within a particular object type. This +identifier, called the object index, ranges in value from 1 to the maximum number of objects configured for this object type. Sixteen Bit Object ID Format ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The sixteen bit format for an object ID is composed of three parts: API, -object class, and index. The data type ``rtems_id`` -is used to store object IDs. +The sixteen bit format for an object ID is composed of three parts: API, object +class, and index. The data type ``rtems_id`` is used to store object IDs. .. code:: c @@ -137,39 +137,35 @@ is used to store object IDs. +---------+-------+--------------+ The sixteen-bit format is designed to be as similar as possible to the -thrity-two bit format. The differences are limited to the eliminatation -of the node field and reduction of the index field from sixteen-bits -to 8-bits. Thus the sixteen bit format only supports up to 255 object -instances per API/Class combination and single processor systems. -As this format is typically utilized by sixteen-bit processors with -limited address space, this is more than enough object instances. +thrity-two bit format. The differences are limited to the eliminatation of the +node field and reduction of the index field from sixteen-bits to 8-bits. Thus +the sixteen bit format only supports up to 255 object instances per API/Class +combination and single processor systems. As this format is typically utilized +by sixteen-bit processors with limited address space, this is more than enough +object instances. Object ID Description --------------------- -The components of an object ID make it possible -to quickly locate any object in even the most complicated -multiprocessor system. Object ID's are associated with an -object by RTEMS when the object is created and the corresponding -ID is returned by the appropriate object create directive. The -object ID is required as input to all directives involving -objects, except those which create an object or obtain the ID of -an object. - -The object identification directives can be used to -dynamically obtain a particular object's ID given its name. -This mapping is accomplished by searching the name table -associated with this object type. If the name is non-unique, -then the ID associated with the first occurrence of the name -will be returned to the application. Since object IDs are -returned when the object is created, the object identification -directives are not necessary in a properly designed single -processor application. - -In addition, services are provided to portably examine the -subcomponents of an RTEMS ID. These services are -described in detail later in this manual but are prototyped -as follows:.. index:: obtaining class from object ID +The components of an object ID make it possible to quickly locate any object in +even the most complicated multiprocessor system. Object ID's are associated +with an object by RTEMS when the object is created and the corresponding ID is +returned by the appropriate object create directive. The object ID is required +as input to all directives involving objects, except those which create an +object or obtain the ID of an object. + +The object identification directives can be used to dynamically obtain a +particular object's ID given its name. This mapping is accomplished by +searching the name table associated with this object type. If the name is +non-unique, then the ID associated with the first occurrence of the name will +be returned to the application. Since object IDs are returned when the object +is created, the object identification directives are not necessary in a +properly designed single processor application. + +In addition, services are provided to portably examine the subcomponents of an +RTEMS ID. These services are described in detail later in this manual but are +prototyped as follows:.. index:: obtaining class from object ID + .. index:: obtaining node from object ID .. index:: obtaining index from object ID .. index:: get class from object ID @@ -187,26 +183,24 @@ as follows:.. index:: obtaining class from object ID uint32_t rtems_object_id_get_node( rtems_id ); uint32_t rtems_object_id_get_index( rtems_id ); -An object control block is a data structure defined -by RTEMS which contains the information necessary to manage a -particular object type. For efficiency reasons, the format of -each object type's control block is different. However, many of -the fields are similar in function. The number of each type of -control block is application dependent and determined by the -values specified in the user's Configuration Table. An object -control block is allocated at object create time and freed when -the object is deleted. With the exception of user extension -routines, object control blocks are not directly manipulated by -user applications. +An object control block is a data structure defined by RTEMS which contains the +information necessary to manage a particular object type. For efficiency +reasons, the format of each object type's control block is different. However, +many of the fields are similar in function. The number of each type of control +block is application dependent and determined by the values specified in the +user's Configuration Table. An object control block is allocated at object +create time and freed when the object is deleted. With the exception of user +extension routines, object control blocks are not directly manipulated by user +applications. Communication and Synchronization ================================= .. index:: communication and synchronization -In real-time multitasking applications, the ability -for cooperating execution threads to communicate and synchronize -with each other is imperative. A real-time executive should -provide an application with the following capabilities: +In real-time multitasking applications, the ability for cooperating execution +threads to communicate and synchronize with each other is imperative. A +real-time executive should provide an application with the following +capabilities: - Data transfer between cooperating tasks @@ -216,15 +210,13 @@ provide an application with the following capabilities: - Synchronization of tasks and ISRs -Most RTEMS managers can be used to provide some form -of communication and/or synchronization. However, managers -dedicated specifically to communication and synchronization -provide well established mechanisms which directly map to the -application's varying needs. This level of flexibility allows -the application designer to match the features of a particular -manager with the complexity of communication and synchronization -required. The following managers were specifically designed for -communication and synchronization: +Most RTEMS managers can be used to provide some form of communication and/or +synchronization. However, managers dedicated specifically to communication and +synchronization provide well established mechanisms which directly map to the +application's varying needs. This level of flexibility allows the application +designer to match the features of a particular manager with the complexity of +communication and synchronization required. The following managers were +specifically designed for communication and synchronization: - Semaphore @@ -234,83 +226,69 @@ communication and synchronization: - Signal -The semaphore manager supports mutual exclusion -involving the synchronization of access to one or more shared -user resources. Binary semaphores may utilize the optional -priority inheritance algorithm to avoid the problem of priority +The semaphore manager supports mutual exclusion involving the synchronization +of access to one or more shared user resources. Binary semaphores may utilize +the optional priority inheritance algorithm to avoid the problem of priority inversion. The message manager supports both communication and -synchronization, while the event manager primarily provides a -high performance synchronization mechanism. The signal manager -supports only asynchronous communication and is typically used -for exception handling. +synchronization, while the event manager primarily provides a high performance +synchronization mechanism. The signal manager supports only asynchronous +communication and is typically used for exception handling. Time ==== .. index:: time -The development of responsive real-time applications -requires an understanding of how RTEMS maintains and supports -time-related operations. The basic unit of time in RTEMS is -known as a tick. The frequency of clock ticks is completely -application dependent and determines the granularity and -accuracy of all interval and calendar time operations... index:: rtems_interval - -By tracking time in units of ticks, RTEMS is capable -of supporting interval timing functions such as task delays, -timeouts, timeslicing, the delayed execution of timer service -routines, and the rate monotonic scheduling of tasks. An -interval is defined as a number of ticks relative to the current -time. For example, when a task delays for an interval of ten -ticks, it is implied that the task will not execute until ten -clock ticks have occurred. -All intervals are specified using data type``rtems_interval``. - -A characteristic of interval timing is that the -actual interval period may be a fraction of a tick less than the -interval requested. This occurs because the time at which the -delay timer is set up occurs at some time between two clock -ticks. Therefore, the first countdown tick occurs in less than -the complete time interval for a tick. This can be a problem if -the clock granularity is large. - -The rate monotonic scheduling algorithm is a hard -real-time scheduling methodology. This methodology provides -rules which allows one to guarantee that a set of independent -periodic tasks will always meet their deadlines - even under -transient overload conditions. The rate monotonic manager -provides directives built upon the Clock Manager's interval -timer support routines. - -Interval timing is not sufficient for the many -applications which require that time be kept in wall time or -true calendar form. Consequently, RTEMS maintains the current -date and time. This allows selected time operations to be -scheduled at an actual calendar date and time. For example, a -task could request to delay until midnight on New Year's Eve -before lowering the ball at Times Square. -The data type ``rtems_time_of_day`` is used to specify -calendar time in RTEMS services. -See `Time and Date Data Structures`_ +The development of responsive real-time applications requires an understanding +of how RTEMS maintains and supports time-related operations. The basic unit of +time in RTEMS is known as a tick. The frequency of clock ticks is completely +application dependent and determines the granularity and accuracy of all +interval and calendar time operations... index:: rtems_interval + +By tracking time in units of ticks, RTEMS is capable of supporting interval +timing functions such as task delays, timeouts, timeslicing, the delayed +execution of timer service routines, and the rate monotonic scheduling of +tasks. An interval is defined as a number of ticks relative to the current +time. For example, when a task delays for an interval of ten ticks, it is +implied that the task will not execute until ten clock ticks have occurred. +All intervals are specified using data type ``rtems_interval``. + +A characteristic of interval timing is that the actual interval period may be a +fraction of a tick less than the interval requested. This occurs because the +time at which the delay timer is set up occurs at some time between two clock +ticks. Therefore, the first countdown tick occurs in less than the complete +time interval for a tick. This can be a problem if the clock granularity is +large. + +The rate monotonic scheduling algorithm is a hard real-time scheduling +methodology. This methodology provides rules which allows one to guarantee +that a set of independent periodic tasks will always meet their deadlines - +even under transient overload conditions. The rate monotonic manager provides +directives built upon the Clock Manager's interval timer support routines. + +Interval timing is not sufficient for the many applications which require that +time be kept in wall time or true calendar form. Consequently, RTEMS maintains +the current date and time. This allows selected time operations to be +scheduled at an actual calendar date and time. For example, a task could +request to delay until midnight on New Year's Eve before lowering the ball at +Times Square. The data type ``rtems_time_of_day`` is used to specify calendar +time in RTEMS services. See `Time and Date Data Structures`_ ... index:: rtems_time_of_day -Obviously, the directives which use intervals or wall -time cannot operate without some external mechanism which -provides a periodic clock tick. This clock tick is typically -provided by a real time clock or counter/timer device. +Obviously, the directives which use intervals or wall time cannot operate +without some external mechanism which provides a periodic clock tick. This +clock tick is typically provided by a real time clock or counter/timer device. Memory Management ================= .. index:: memory management -RTEMS memory management facilities can be grouped -into two classes: dynamic memory allocation and address -translation. Dynamic memory allocation is required by -applications whose memory requirements vary through the -application's course of execution. Address translation is -needed by applications which share memory with another CPU or an -intelligent Input/Output processor. The following RTEMS -managers provide facilities to manage memory: +RTEMS memory management facilities can be grouped into two classes: dynamic +memory allocation and address translation. Dynamic memory allocation is +required by applications whose memory requirements vary through the +application's course of execution. Address translation is needed by +applications which share memory with another CPU or an intelligent Input/Output +processor. The following RTEMS managers provide facilities to manage memory: - Region @@ -318,21 +296,12 @@ managers provide facilities to manage memory: - Dual Ported Memory -RTEMS memory management features allow an application -to create simple memory pools of fixed size buffers and/or more -complex memory pools of variable size segments. The partition -manager provides directives to manage and maintain pools of -fixed size entities such as resource control blocks. -Alternatively, the region manager provides a more general -purpose memory allocation scheme that supports variable size -blocks of memory which are dynamically obtained and freed by the -application. The dual-ported memory manager provides executive -support for address translation between internal and external -dual-ported RAM address space. - -.. COMMENT: COPYRIGHT (c) 1988-2002. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - +RTEMS memory management features allow an application to create simple memory +pools of fixed size buffers and/or more complex memory pools of variable size +segments. The partition manager provides directives to manage and maintain +pools of fixed size entities such as resource control blocks. Alternatively, +the region manager provides a more general purpose memory allocation scheme +that supports variable size blocks of memory which are dynamically obtained and +freed by the application. The dual-ported memory manager provides executive +support for address translation between internal and external dual-ported RAM +address space. diff --git a/c_user/overview.rst b/c_user/overview.rst index 80ad8da..a4f203f 100644 --- a/c_user/overview.rst +++ b/c_user/overview.rst @@ -1,13 +1,16 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Overview ######## Introduction ============ -RTEMS, Real-Time Executive for Multiprocessor Systems, is a -real-time executive (kernel) which provides a high performance -environment for embedded military applications including the -following features: +RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time executive +(kernel) which provides a high performance environment for embedded military +applications including the following features: - multitasking capabilities @@ -27,164 +30,153 @@ following features: - high level of user configurability -This manual describes the usage of RTEMS for -applications written in the C programming language. Those -implementation details that are processor dependent are provided -in the Applications Supplement documents. A supplement -document which addresses specific architectural issues that -affect RTEMS is provided for each processor type that is -supported. +This manual describes the usage of RTEMS for applications written in the C +programming language. Those implementation details that are processor +dependent are provided in the Applications Supplement documents. A supplement +document which addresses specific architectural issues that affect RTEMS is +provided for each processor type that is supported. Real-time Application Systems ============================= -Real-time application systems are a special class of -computer applications. They have a complex set of -characteristics that distinguish them from other software -problems. Generally, they must adhere to more rigorous -requirements. The correctness of the system depends not only on -the results of computations, but also on the time at which the -results are produced. The most important and complex -characteristic of real-time application systems is that they -must receive and respond to a set of external stimuli within -rigid and critical time constraints referred to as deadlines. -Systems can be buried by an avalanche of interdependent, -asynchronous or cyclical event streams. - -Deadlines can be further characterized as either hard -or soft based upon the value of the results when produced after -the deadline has passed. A deadline is hard if the results have -no value or if their use will result in a catastrophic event. -In contrast, results which are produced after a soft deadline -may have some value. - -Another distinguishing requirement of real-time -application systems is the ability to coordinate or manage a -large number of concurrent activities. Since software is a -synchronous entity, this presents special problems. One -instruction follows another in a repeating synchronous cycle. -Even though mechanisms have been developed to allow for the -processing of external asynchronous events, the software design -efforts required to process and manage these events and tasks -are growing more complicated. - -The design process is complicated further by -spreading this activity over a set of processors instead of a -single processor. The challenges associated with designing and -building real-time application systems become very complex when -multiple processors are involved. New requirements such as -interprocessor communication channels and global resources that -must be shared between competing processors are introduced. The -ramifications of multiple processors complicate each and every -characteristic of a real-time system. +Real-time application systems are a special class of computer applications. +They have a complex set of characteristics that distinguish them from other +software problems. Generally, they must adhere to more rigorous requirements. +The correctness of the system depends not only on the results of computations, +but also on the time at which the results are produced. The most important and +complex characteristic of real-time application systems is that they must +receive and respond to a set of external stimuli within rigid and critical time +constraints referred to as deadlines. Systems can be buried by an avalanche of +interdependent, asynchronous or cyclical event streams. + +Deadlines can be further characterized as either hard or soft based upon the +value of the results when produced after the deadline has passed. A deadline +is hard if the results have no value or if their use will result in a +catastrophic event. In contrast, results which are produced after a soft +deadline may have some value. + +Another distinguishing requirement of real-time application systems is the +ability to coordinate or manage a large number of concurrent activities. Since +software is a synchronous entity, this presents special problems. One +instruction follows another in a repeating synchronous cycle. Even though +mechanisms have been developed to allow for the processing of external +asynchronous events, the software design efforts required to process and manage +these events and tasks are growing more complicated. + +The design process is complicated further by spreading this activity over a set +of processors instead of a single processor. The challenges associated with +designing and building real-time application systems become very complex when +multiple processors are involved. New requirements such as interprocessor +communication channels and global resources that must be shared between +competing processors are introduced. The ramifications of multiple processors +complicate each and every characteristic of a real-time system. Real-time Executive =================== -Fortunately, real-time operating systems or real-time -executives serve as a cornerstone on which to build the -application system. A real-time multitasking executive allows -an application to be cast into a set of logical, autonomous -processes or tasks which become quite manageable. Each task is -internally synchronous, but different tasks execute -independently, resulting in an asynchronous processing stream. -Tasks can be dynamically paused for many reasons resulting in a -different task being allowed to execute for a period of time. -The executive also provides an interface to other system -components such as interrupt handlers and device drivers. -System components may request the executive to allocate and -coordinate resources, and to wait for and trigger synchronizing -conditions. The executive system calls effectively extend the -CPU instruction set to support efficient multitasking. By -causing tasks to travel through well-defined state transitions, -system calls permit an application to demand-switch between -tasks in response to real-time events. - -By proper grouping of responses to stimuli into -separate tasks, a system can now asynchronously switch between -independent streams of execution, directly responding to -external stimuli as they occur. This allows the system design -to meet critical performance specifications which are typically -measured by guaranteed response time and transaction throughput. -The multiprocessor extensions of RTEMS provide the features -necessary to manage the extra requirements introduced by a -system distributed across several processors. It removes the -physical barriers of processor boundaries from the world of the -system designer, enabling more critical aspects of the system to -receive the required attention. Such a system, based on an -efficient real-time, multiprocessor executive, is a more -realistic model of the outside world or environment for which it -is designed. As a result, the system will always be more -logical, efficient, and reliable. - -By using the directives provided by RTEMS, the -real-time applications developer is freed from the problem of -controlling and synchronizing multiple tasks and processors. In -addition, one need not develop, test, debug, and document -routines to manage memory, pass messages, or provide mutual -exclusion. The developer is then able to concentrate solely on -the application. By using standard software components, the -time and cost required to develop sophisticated real-time -applications is significantly reduced. +Fortunately, real-time operating systems or real-time executives serve as a +cornerstone on which to build the application system. A real-time multitasking +executive allows an application to be cast into a set of logical, autonomous +processes or tasks which become quite manageable. Each task is internally +synchronous, but different tasks execute independently, resulting in an +asynchronous processing stream. Tasks can be dynamically paused for many +reasons resulting in a different task being allowed to execute for a period of +time. The executive also provides an interface to other system components such +as interrupt handlers and device drivers. System components may request the +executive to allocate and coordinate resources, and to wait for and trigger +synchronizing conditions. The executive system calls effectively extend the +CPU instruction set to support efficient multitasking. By causing tasks to +travel through well-defined state transitions, system calls permit an +application to demand-switch between tasks in response to real-time events. + +By proper grouping of responses to stimuli into separate tasks, a system can +now asynchronously switch between independent streams of execution, directly +responding to external stimuli as they occur. This allows the system design to +meet critical performance specifications which are typically measured by +guaranteed response time and transaction throughput. The multiprocessor +extensions of RTEMS provide the features necessary to manage the extra +requirements introduced by a system distributed across several processors. It +removes the physical barriers of processor boundaries from the world of the +system designer, enabling more critical aspects of the system to receive the +required attention. Such a system, based on an efficient real-time, +multiprocessor executive, is a more realistic model of the outside world or +environment for which it is designed. As a result, the system will always be +more logical, efficient, and reliable. + +By using the directives provided by RTEMS, the real-time applications developer +is freed from the problem of controlling and synchronizing multiple tasks and +processors. In addition, one need not develop, test, debug, and document +routines to manage memory, pass messages, or provide mutual exclusion. The +developer is then able to concentrate solely on the application. By using +standard software components, the time and cost required to develop +sophisticated real-time applications is significantly reduced. RTEMS Application Architecture ============================== -One important design goal of RTEMS was to provide a -bridge between two critical layers of typical real-time systems. -As shown in the following figure, RTEMS serves as a buffer between the -project dependent application code and the target hardware. -Most hardware dependencies for real-time applications can be +One important design goal of RTEMS was to provide a bridge between two critical +layers of typical real-time systems. As shown in the following figure, RTEMS +serves as a buffer between the project dependent application code and the +target hardware. Most hardware dependencies for real-time applications can be localized to the low level device drivers. -.. code:: c - - +-----------------------------------------------------------+ - | Application Dependent Software | - | +----------------------------------------+ | - | | Standard Application Components | | - | | +-------------+---+ | - | +---+-----------+ | | | - | | Board Support | | RTEMS | | - | | Package | | | | - +----+---------------+--------------+-----------------+-----| - | Target Hardware | - +-----------------------------------------------------------+ +.. COMMENT: .. code:: c +.. COMMENT: +.. COMMENT: +-----------------------------------------------------------+ +.. COMMENT: | Application Dependent Software | +.. COMMENT: | +----------------------------------------+ | +.. COMMENT: | | Standard Application Components | | +.. COMMENT: | | +-------------+---+ | +.. COMMENT: | +---+-----------+ | | | +.. COMMENT: | | Board Support | | RTEMS | | +.. COMMENT: | | Package | | | | +.. COMMENT: +----+---------------+--------------+-----------------+-----| +.. COMMENT: | Target Hardware | +.. COMMENT: +-----------------------------------------------------------+ + +.. figure:: rtemsarc.png + :width: 488 + :height: 100px + :align: center + :alt: RTEMS Application Architecture The RTEMS I/O interface manager provides an efficient tool for incorporating -these hardware dependencies into the system while simultaneously -providing a general mechanism to the application code that -accesses them. A well designed real-time system can benefit -from this architecture by building a rich library of standard -application components which can be used repeatedly in other +these hardware dependencies into the system while simultaneously providing a +general mechanism to the application code that accesses them. A well designed +real-time system can benefit from this architecture by building a rich library +of standard application components which can be used repeatedly in other real-time projects. RTEMS Internal Architecture =========================== -RTEMS can be viewed as a set of layered components that work in -harmony to provide a set of services to a real-time application -system. The executive interface presented to the application is -formed by grouping directives into logical sets called resource managers. -Functions utilized by multiple managers such as scheduling, -dispatching, and object management are provided in the executive -core. The executive core depends on a small set of CPU dependent routines. -Together these components provide a powerful run time -environment that promotes the development of efficient real-time -application systems. The following figure illustrates this organization: - -.. code:: c - - +-----------------------------------------------+ - | RTEMS Executive Interface | - +-----------------------------------------------+ - | RTEMS Core | - +-----------------------------------------------+ - | CPU Dependent Code | - +-----------------------------------------------+ - -Subsequent chapters present a detailed description of the capabilities -provided by each of the following RTEMS managers: +RTEMS can be viewed as a set of layered components that work in harmony to +provide a set of services to a real-time application system. The executive +interface presented to the application is formed by grouping directives into +logical sets called resource managers. Functions utilized by multiple managers +such as scheduling, dispatching, and object management are provided in the +executive core. The executive core depends on a small set of CPU dependent +routines. Together these components provide a powerful run time environment +that promotes the development of efficient real-time application systems. The +following figure illustrates this organization: + +.. COMMENT: .. code:: c +.. COMMENT: +.. COMMENT: +-----------------------------------------------+ +.. COMMENT: | RTEMS Executive Interface | +.. COMMENT: +-----------------------------------------------+ +.. COMMENT: | RTEMS Core | +.. COMMENT: +-----------------------------------------------+ +.. COMMENT: | CPU Dependent Code | +.. COMMENT: +-----------------------------------------------+ + +.. figure:: rtemspie.png + :width: 70% + :align: center + :alt: RTEMS Internal Architecture + +Subsequent chapters present a detailed description of the capabilities provided +by each of the following RTEMS managers: - initialization @@ -223,112 +215,96 @@ provided by each of the following RTEMS managers: User Customization and Extensibility ==================================== -As thirty-two bit microprocessors have decreased in -cost, they have become increasingly common in a variety of -embedded systems. A wide range of custom and general-purpose -processor boards are based on various thirty-two bit processors. -RTEMS was designed to make no assumptions concerning the -characteristics of individual microprocessor families or of -specific support hardware. In addition, RTEMS allows the system -developer a high degree of freedom in customizing and extending -its features. - -RTEMS assumes the existence of a supported -microprocessor and sufficient memory for both RTEMS and the -real-time application. Board dependent components such as -clocks, interrupt controllers, or I/O devices can be easily -integrated with RTEMS. The customization and extensibility -features allow RTEMS to efficiently support as many environments -as possible. +As thirty-two bit microprocessors have decreased in cost, they have become +increasingly common in a variety of embedded systems. A wide range of custom +and general-purpose processor boards are based on various thirty-two bit +processors. RTEMS was designed to make no assumptions concerning the +characteristics of individual microprocessor families or of specific support +hardware. In addition, RTEMS allows the system developer a high degree of +freedom in customizing and extending its features. + +RTEMS assumes the existence of a supported microprocessor and sufficient memory +for both RTEMS and the real-time application. Board dependent components such +as clocks, interrupt controllers, or I/O devices can be easily integrated with +RTEMS. The customization and extensibility features allow RTEMS to efficiently +support as many environments as possible. Portability =========== -The issue of portability was the major factor in the -creation of RTEMS. Since RTEMS is designed to isolate the -hardware dependencies in the specific board support packages, -the real-time application should be easily ported to any other -processor. The use of RTEMS allows the development of real-time -applications which can be completely independent of a particular -microprocessor architecture. +The issue of portability was the major factor in the creation of RTEMS. Since +RTEMS is designed to isolate the hardware dependencies in the specific board +support packages, the real-time application should be easily ported to any +other processor. The use of RTEMS allows the development of real-time +applications which can be completely independent of a particular microprocessor +architecture. Memory Requirements =================== -Since memory is a critical resource in many real-time -embedded systems, RTEMS was specifically designed to automatically -leave out all services that are not required from the run-time -environment. Features such as networking, various fileystems, -and many other features are completely optional. This allows -the application designer the flexibility to tailor RTEMS to most -efficiently meet system requirements while still satisfying even -the most stringent memory constraints. As a result, the size -of the RTEMS executive is application dependent. +Since memory is a critical resource in many real-time embedded systems, RTEMS +was specifically designed to automatically leave out all services that are not +required from the run-time environment. Features such as networking, various +fileystems, and many other features are completely optional. This allows the +application designer the flexibility to tailor RTEMS to most efficiently meet +system requirements while still satisfying even the most stringent memory +constraints. As a result, the size of the RTEMS executive is application +dependent. -RTEMS requires RAM to manage each instance of an RTEMS object -that is created. Thus the more RTEMS objects an application -needs, the more memory that must be reserved. See `Configuring a System`_. +RTEMS requires RAM to manage each instance of an RTEMS object that is created. +Thus the more RTEMS objects an application needs, the more memory that must be +reserved. See Configuring a System_. -RTEMS utilizes memory for both code and data space. -Although RTEMS' data space must be in RAM, its code space can be -located in either ROM or RAM. +RTEMS utilizes memory for both code and data space. Although RTEMS' data space +must be in RAM, its code space can be located in either ROM or RAM. Audience ======== -This manual was written for experienced real-time -software developers. Although some background is provided, it -is assumed that the reader is familiar with the concepts of task -management as well as intertask communication and -synchronization. Since directives, user related data -structures, and examples are presented in C, a basic -understanding of the C programming language -is required to fully -understand the material presented. However, because of the -similarity of the Ada and C RTEMS implementations, users will -find that the use and behavior of the two implementations is -very similar. A working knowledge of the target processor is -helpful in understanding some of RTEMS' features. A thorough -understanding of the executive cannot be obtained without -studying the entire manual because many of RTEMS' concepts and -features are interrelated. Experienced RTEMS users will find -that the manual organization facilitates its use as a reference -document. +This manual was written for experienced real-time software developers. +Although some background is provided, it is assumed that the reader is familiar +with the concepts of task management as well as intertask communication and +synchronization. Since directives, user related data structures, and examples +are presented in C, a basic understanding of the C programming language is +required to fully understand the material presented. However, because of the +similarity of the Ada and C RTEMS implementations, users will find that the use +and behavior of the two implementations is very similar. A working knowledge +of the target processor is helpful in understanding some of RTEMS' features. A +thorough understanding of the executive cannot be obtained without studying the +entire manual because many of RTEMS' concepts and features are interrelated. +Experienced RTEMS users will find that the manual organization facilitates its +use as a reference document. Conventions =========== The following conventions are used in this manual: -- Significant words or phrases as well as all directive - names are printed in bold type. +- Significant words or phrases as well as all directive names are printed in + bold type. -- Items in bold capital letters are constants defined by - RTEMS. Each language interface provided by RTEMS includes a - file containing the standard set of constants, data types, and - structure definitions which can be incorporated into the user - application. +- Items in bold capital letters are constants defined by RTEMS. Each language + interface provided by RTEMS includes a file containing the standard set of + constants, data types, and structure definitions which can be incorporated + into the user application. -- A number of type definitions are provided by RTEMS and - can be found in rtems.h. +- A number of type definitions are provided by RTEMS and can be found in + rtems.h. -- The characters "0x" preceding a number indicates that - the number is in hexadecimal format. Any other numbers are - assumed to be in decimal format. +- The characters "0x" preceding a number indicates that the number is in + hexadecimal format. Any other numbers are assumed to be in decimal format. Manual Organization =================== -This first chapter has presented the introductory and -background material for the RTEMS executive. The remaining -chapters of this manual present a detailed description of RTEMS -and the environment, including run time behavior, it creates for -the user. +This first chapter has presented the introductory and background material for +the RTEMS executive. The remaining chapters of this manual present a detailed +description of RTEMS and the environment, including run time behavior, it +creates for the user. -A chapter is dedicated to each manager and provides a -detailed discussion of each RTEMS manager and the directives -which it provides. The presentation format for each directive -includes the following sections: +A chapter is dedicated to each manager and provides a detailed discussion of +each RTEMS manager and the directives which it provides. The presentation +format for each directive includes the following sections: - Calling sequence @@ -338,152 +314,136 @@ includes the following sections: - Notes -The following provides an overview of the remainder -of this manual: +The following provides an overview of the remainder of this manual: Chapter 2: - Key Concepts: presents an introduction to the ideas which are common - across multiple RTEMS managers. + Key Concepts: presents an introduction to the ideas which are common across + multiple RTEMS managers. Chapter 3: - RTEMS Data Types: describes the fundamental data types shared - by the services in the RTEMS Classic API. + RTEMS Data Types: describes the fundamental data types shared by the + services in the RTEMS Classic API. Chapter 4: - Scheduling Concepts: details the various RTEMS scheduling algorithms - and task state transitions. + Scheduling Concepts: details the various RTEMS scheduling algorithms and + task state transitions. Chapter 5: - Initialization Manager: describes the functionality and directives - provided by the Initialization Manager. + Initialization Manager: describes the functionality and directives provided + by the Initialization Manager. Chapter 6: - Task Manager: describes the functionality and directives provided - by the Task Manager. + Task Manager: describes the functionality and directives provided by the + Task Manager. Chapter 7: - Interrupt Manager: describes the functionality and directives - provided by the Interrupt Manager. + Interrupt Manager: describes the functionality and directives provided by + the Interrupt Manager. Chapter 8: - Clock Manager: describes the functionality and directives - provided by the Clock Manager. + Clock Manager: describes the functionality and directives provided by the + Clock Manager. Chapter 9: - Timer Manager: describes the functionality and directives provided - by the Timer Manager. + Timer Manager: describes the functionality and directives provided by the + Timer Manager. Chapter 10: - Rate Monotonic Manager: describes the functionality and directives - provided by the Rate Monotonic Manager. + Rate Monotonic Manager: describes the functionality and directives provided + by the Rate Monotonic Manager. Chapter 11: - Semaphore Manager: describes the functionality and directives - provided by the Semaphore Manager. + Semaphore Manager: describes the functionality and directives provided by + the Semaphore Manager. Chapter 12: - Barrier Manager: describes the functionality and directives - provided by the Barrier Manager. + Barrier Manager: describes the functionality and directives provided by the + Barrier Manager. Chapter 13: - Message Manager: describes the functionality and directives - provided by the Message Manager. + Message Manager: describes the functionality and directives provided by the + Message Manager. Chapter 14: - Event Manager: describes the - functionality and directives provided by the Event Manager. + Event Manager: describes the functionality and directives provided by the + Event Manager. Chapter 15: - Signal Manager: describes the - functionality and directives provided by the Signal Manager. + Signal Manager: describes the functionality and directives provided by the + Signal Manager. Chapter 16: - Partition Manager: describes the - functionality and directives provided by the Partition Manager. + Partition Manager: describes the functionality and directives provided by + the Partition Manager. Chapter 17: - Region Manager: describes the - functionality and directives provided by the Region Manager. + Region Manager: describes the functionality and directives provided by the + Region Manager. Chapter 18: - Dual-Ported Memory Manager: describes - the functionality and directives provided by the Dual-Ported - Memory Manager. + Dual-Ported Memory Manager: describes the functionality and directives + provided by the Dual-Ported Memory Manager. Chapter 19: - I/O Manager: describes the - functionality and directives provided by the I/O Manager. + I/O Manager: describes the functionality and directives provided by the I/O + Manager. Chapter 20: - Fatal Error Manager: describes the functionality and directives - provided by the Fatal Error Manager. + Fatal Error Manager: describes the functionality and directives provided by + the Fatal Error Manager. Chapter 21: - Board Support Packages: defines the - functionality required of user-supplied board support packages. + Board Support Packages: defines the functionality required of user-supplied + board support packages. Chapter 22: - User Extensions: shows the user how to - extend RTEMS to incorporate custom features. + User Extensions: shows the user how to extend RTEMS to incorporate custom + features. Chapter 23: - Configuring a System: details the process by which one tailors RTEMS - for a particular single-processor or multiprocessor application. + Configuring a System: details the process by which one tailors RTEMS for a + particular single-processor or multiprocessor application. Chapter 24: - Multiprocessing Manager: presents a - conceptual overview of the multiprocessing capabilities provided - by RTEMS as well as describing the Multiprocessing - Communications Interface Layer and Multiprocessing Manager + Multiprocessing Manager: presents a conceptual overview of the + multiprocessing capabilities provided by RTEMS as well as describing the + Multiprocessing Communications Interface Layer and Multiprocessing Manager directives. Chapter 25: - Stack Bounds Checker: presents the capabilities of the RTEMS - task stack checker which can report stack usage as well as detect - bounds violations. + Stack Bounds Checker: presents the capabilities of the RTEMS task stack + checker which can report stack usage as well as detect bounds violations. Chapter 26: - CPU Usage Statistics: presents the capabilities of the CPU Usage - statistics gathered on a per task basis along with the mechanisms - for reporting and resetting the statistics. + CPU Usage Statistics: presents the capabilities of the CPU Usage statistics + gathered on a per task basis along with the mechanisms for reporting and + resetting the statistics. Chapter 27: - Object Services: presents a collection of helper services useful - when manipulating RTEMS objects. These include methods to assist - in obtaining an object's name in printable form. Additional services - are provided to decompose an object Id and determine which API - and object class it belongs to. + Object Services: presents a collection of helper services useful when + manipulating RTEMS objects. These include methods to assist in obtaining an + object's name in printable form. Additional services are provided to + decompose an object Id and determine which API and object class it belongs + to. Chapter 28: - Chains: presents the methods provided to build, iterate and - manipulate doubly-linked chains. This manager makes the - chain implementation used internally by RTEMS to user space - applications. + Chains: presents the methods provided to build, iterate and manipulate + doubly-linked chains. This manager makes the chain implementation used + internally by RTEMS to user space applications. Chapter 29: - Timespec Helpers: presents a set of helper services useful - when manipulating POSIX ``struct timespec`` instances. + Timespec Helpers: presents a set of helper services useful when + manipulating POSIX ``struct timespec`` instances. Chapter 30: Constant Bandwidth Server Scheduler API. Chapter 31: - Directive Status Codes: provides a definition of each of the - directive status codes referenced in this manual. + Directive Status Codes: provides a definition of each of the directive + status codes referenced in this manual. Chapter 32: Example Application: provides a template for simple RTEMS applications. Chapter 33: Glossary: defines terms used throughout this manual. - -.. COMMENT: COPYRIGHT (c) 1988-2007. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -.. COMMENT: The following figure was replaced with an ASCII equivalent. - -.. COMMENT: Figure 2-1 Object ID Composition - diff --git a/c_user/preface.rst b/c_user/preface.rst index ce828b0..d63b5f2 100644 --- a/c_user/preface.rst +++ b/c_user/preface.rst @@ -1,144 +1,123 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Preface ####### -In recent years, the cost required to develop a -software product has increased significantly while the target -hardware costs have decreased. Now a larger portion of money is -expended in developing, using, and maintaining software. The -trend in computing costs is the complete dominance of software -over hardware costs. Because of this, it is necessary that -formal disciplines be established to increase the probability -that software is characterized by a high degree of correctness, -maintainability, and portability. In addition, these -disciplines must promote practices that aid in the consistent -and orderly development of a software system within schedule and -budgetary constraints. To be effective, these disciplines must -adopt standards which channel individual software efforts toward -a common goal. - -The push for standards in the software development -field has been met with various degrees of success. The -Microprocessor Operating Systems Interfaces (MOSI) effort has -experienced only limited success. As popular as the UNIX -operating system has grown, the attempt to develop a standard -interface definition to allow portable application development -has only recently begun to produce the results needed in this -area. Unfortunately, very little effort has been expended to -provide standards addressing the needs of the real-time -community. Several organizations have addressed this need -during recent years. - -The Real Time Executive Interface Definition (RTEID) -was developed by Motorola with technical input from Software -Components Group. RTEID was adopted by the VMEbus International -Trade Association (VITA) as a baseline draft for their proposed -standard multiprocessor, real-time executive interface, Open -Real-Time Kernel Interface Definition (ORKID). These two groups -are currently working together with the IEEE P1003.4 committee -to insure that the functionality of their proposed standards is -adopted as the real-time extensions to POSIX. - -This emerging standard defines an interface for the -development of real-time software to ease the writing of -real-time application programs that are directly portable across -multiple real-time executive implementations. This interface -includes both the source code interfaces and run-time behavior -as seen by a real-time application. It does not include the -details of how a kernel implements these functions. The -standard's goal is to serve as a complete definition of external -interfaces so that application code that conforms to these -interfaces will execute properly in all real-time executive -environments. With the use of a standards compliant executive, -routines that acquire memory blocks, create and manage message -queues, establish and use semaphores, and send and receive -signals need not be redeveloped for a different real-time -environment as long as the new environment is compliant with the -standard. Software developers need only concentrate on the -hardware dependencies of the real-time system. Furthermore, -most hardware dependencies for real-time applications can be -localized to the device drivers. - -A compliant executive provides simple and flexible -real-time multiprocessing. It easily lends itself to both -tightly-coupled and loosely-coupled configurations (depending on -the system hardware configuration). Objects such as tasks, -queues, events, signals, semaphores, and memory blocks can be -designated as global objects and accessed by any task regardless -of which processor the object and the accessing task reside. - -The acceptance of a standard for real-time executives -will produce the same advantages enjoyed from the push for UNIX -standardization by AT&T's System V Interface Definition and -IEEE's POSIX efforts. A compliant multiprocessing executive -will allow close coupling between UNIX systems and real-time -executives to provide the many benefits of the UNIX development -environment to be applied to real-time software development. -Together they provide the necessary laboratory environment to -implement real-time, distributed, embedded systems using a wide -variety of computer architectures. - -A study was completed in 1988, within the Research, -Development, and Engineering Center, U.S. Army Missile Command, -which compared the various aspects of the Ada programming -language as they related to the application of Ada code in -distributed and/or multiple processing systems. Several -critical conclusions were derived from the study. These -conclusions have a major impact on the way the Army develops -application software for embedded applications. These impacts -apply to both in-house software development and contractor -developed software. - -A conclusion of the analysis, which has been -previously recognized by other agencies attempting to utilize -Ada in a distributed or multiprocessing environment, is that the -Ada programming language does not adequately support -multiprocessing. Ada does provide a mechanism for -multi-tasking, however, this capability exists only for a single -processor system. The language also does not have inherent -capabilities to access global named variables, flags or program -code. These critical features are essential in order for data -to be shared between processors. However, these drawbacks do -have workarounds which are sometimes awkward and defeat the -intent of software maintainability and portability goals. - -Another conclusion drawn from the analysis, was that -the run time executives being delivered with the Ada compilers -were too slow and inefficient to be used in modern missile -systems. A run time executive is the core part of the run time -system code, or operating system code, that controls task -scheduling, input/output management and memory management. -Traditionally, whenever efficient executive (also known as -kernel) code was required by the application, the user developed -in-house software. This software was usually written in -assembly language for optimization. - -Because of this shortcoming in the Ada programming -language, software developers in research and development and -contractors for project managed systems, are mandated by -technology to purchase and utilize off-the-shelf third party -kernel code. The contractor, and eventually the Government, -must pay a licensing fee for every copy of the kernel code used -in an embedded system. - -The main drawback to this development environment is -that the Government does not own, nor has the right to modify -code contained within the kernel. V&V techniques in this -situation are more difficult than if the complete source code -were available. Responsibility for system failures due to faulty -software is yet another area to be resolved under this -environment. - -The Guidance and Control Directorate began a software -development effort to address these problems. A project to -develop an experimental run time kernel was begun that will -eliminate the major drawbacks of the Ada programming language -mentioned above. The Real Time Executive for Multiprocessor Systems -(RTEMS) provides full capabilities for management of tasks, -interrupts, time, and multiple processors in addition to those -features typical of generic operating systems. The code is -Government owned, so no licensing fees are necessary. RTEMS has -been implemented in both the Ada and C programming languages. -It has been ported to the following processor families: +In recent years, the cost required to develop a software product has increased +significantly while the target hardware costs have decreased. Now a larger +portion of money is expended in developing, using, and maintaining software. +The trend in computing costs is the complete dominance of software over +hardware costs. Because of this, it is necessary that formal disciplines be +established to increase the probability that software is characterized by a +high degree of correctness, maintainability, and portability. In addition, +these disciplines must promote practices that aid in the consistent and orderly +development of a software system within schedule and budgetary constraints. To +be effective, these disciplines must adopt standards which channel individual +software efforts toward a common goal. + +The push for standards in the software development field has been met with +various degrees of success. The Microprocessor Operating Systems Interfaces +(MOSI) effort has experienced only limited success. As popular as the UNIX +operating system has grown, the attempt to develop a standard interface +definition to allow portable application development has only recently begun to +produce the results needed in this area. Unfortunately, very little effort has +been expended to provide standards addressing the needs of the real-time +community. Several organizations have addressed this need during recent years. + +The Real Time Executive Interface Definition (RTEID) was developed by Motorola +with technical input from Software Components Group. RTEID was adopted by the +VMEbus International Trade Association (VITA) as a baseline draft for their +proposed standard multiprocessor, real-time executive interface, Open Real-Time +Kernel Interface Definition (ORKID). These two groups are currently working +together with the IEEE P1003.4 committee to insure that the functionality of +their proposed standards is adopted as the real-time extensions to POSIX. + +This emerging standard defines an interface for the development of real-time +software to ease the writing of real-time application programs that are +directly portable across multiple real-time executive implementations. This +interface includes both the source code interfaces and run-time behavior as +seen by a real-time application. It does not include the details of how a +kernel implements these functions. The standard's goal is to serve as a +complete definition of external interfaces so that application code that +conforms to these interfaces will execute properly in all real-time executive +environments. With the use of a standards compliant executive, routines that +acquire memory blocks, create and manage message queues, establish and use +semaphores, and send and receive signals need not be redeveloped for a +different real-time environment as long as the new environment is compliant +with the standard. Software developers need only concentrate on the hardware +dependencies of the real-time system. Furthermore, most hardware dependencies +for real-time applications can be localized to the device drivers. + +A compliant executive provides simple and flexible real-time multiprocessing. +It easily lends itself to both tightly-coupled and loosely-coupled +configurations (depending on the system hardware configuration). Objects such +as tasks, queues, events, signals, semaphores, and memory blocks can be +designated as global objects and accessed by any task regardless of which +processor the object and the accessing task reside. + +The acceptance of a standard for real-time executives will produce the same +advantages enjoyed from the push for UNIX standardization by AT&T's System V +Interface Definition and IEEE's POSIX efforts. A compliant multiprocessing +executive will allow close coupling between UNIX systems and real-time +executives to provide the many benefits of the UNIX development environment to +be applied to real-time software development. Together they provide the +necessary laboratory environment to implement real-time, distributed, embedded +systems using a wide variety of computer architectures. + +A study was completed in 1988, within the Research, Development, and +Engineering Center, U.S. Army Missile Command, which compared the various +aspects of the Ada programming language as they related to the application of +Ada code in distributed and/or multiple processing systems. Several critical +conclusions were derived from the study. These conclusions have a major impact +on the way the Army develops application software for embedded +applications. These impacts apply to both in-house software development and +contractor developed software. + +A conclusion of the analysis, which has been previously recognized by other +agencies attempting to utilize Ada in a distributed or multiprocessing +environment, is that the Ada programming language does not adequately support +multiprocessing. Ada does provide a mechanism for multi-tasking, however, this +capability exists only for a single processor system. The language also does +not have inherent capabilities to access global named variables, flags or +program code. These critical features are essential in order for data to be +shared between processors. However, these drawbacks do have workarounds which +are sometimes awkward and defeat the intent of software maintainability and +portability goals. + +Another conclusion drawn from the analysis, was that the run time executives +being delivered with the Ada compilers were too slow and inefficient to be used +in modern missile systems. A run time executive is the core part of the run +time system code, or operating system code, that controls task scheduling, +input/output management and memory management. Traditionally, whenever +efficient executive (also known as kernel) code was required by the +application, the user developed in-house software. This software was usually +written in assembly language for optimization. + +Because of this shortcoming in the Ada programming language, software +developers in research and development and contractors for project managed +systems, are mandated by technology to purchase and utilize off-the-shelf third +party kernel code. The contractor, and eventually the Government, must pay a +licensing fee for every copy of the kernel code used in an embedded system. + +The main drawback to this development environment is that the Government does +not own, nor has the right to modify code contained within the kernel. V&V +techniques in this situation are more difficult than if the complete source +code were available. Responsibility for system failures due to faulty software +is yet another area to be resolved under this environment. + +The Guidance and Control Directorate began a software development effort to +address these problems. A project to develop an experimental run time kernel +was begun that will eliminate the major drawbacks of the Ada programming +language mentioned above. The Real Time Executive for Multiprocessor Systems +(RTEMS) provides full capabilities for management of tasks, interrupts, time, +and multiple processors in addition to those features typical of generic +operating systems. The code is Government owned, so no licensing fees are +necessary. RTEMS has been implemented in both the Ada and C programming +languages. It has been ported to the following processor families: + +- Adapteva Epiphany - Altera NIOS II @@ -162,6 +141,10 @@ It has been ported to the following processor families: - MIPS +- Moxie Processor + +- OpenRISC + - PowerPC - Renesas (formerly Hitachi) SuperH @@ -172,38 +155,20 @@ It has been ported to the following processor families: - SPARC v7, v8, and V9 -Support for other processor families, including RISC, CISC, and DSP, is -planned. Since almost all of RTEMS is written in a high level language, -ports to additional processor families require minimal effort. - -RTEMS multiprocessor support is capable of handling -either homogeneous or heterogeneous systems. The kernel -automatically compensates for architectural differences (byte -swapping, etc.) between processors. This allows a much easier -transition from one processor family to another without a major -system redesign. - -Since the proposed standards are still in draft form, -RTEMS cannot and does not claim compliance. However, the status -of the standard is being carefully monitored to guarantee that -RTEMS provides the functionality specified in the standard. -Once approved, RTEMS will be made compliant. - -This document is a detailed users guide for a -functionally compliant real-time multiprocessor executive. It -describes the user interface and run-time behavior of Release -4.10.99.0 of the C interface -to RTEMS. - -.. COMMENT: COPYRIGHT (c) 1988-2008. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -.. COMMENT: This chapter is missing the following figures: +Since almost all of RTEMS is written in a high level language, ports to +additional processor families require minimal effort. -.. COMMENT: Figure 1-1 RTEMS Application Architecture +RTEMS multiprocessor support is capable of handling either homogeneous or +heterogeneous systems. The kernel automatically compensates for architectural +differences (byte swapping, etc.) between processors. This allows a much +easier transition from one processor family to another without a major system +redesign. -.. COMMENT: Figure 1-2 RTEMS Internal Architecture +Since the proposed standards are still in draft form, RTEMS cannot and does not +claim compliance. However, the status of the standard is being carefully +monitored to guarantee that RTEMS provides the functionality specified in the +standard. Once approved, RTEMS will be made compliant. +This document is a detailed users guide for a functionally compliant real-time +multiprocessor executive. It describes the user interface and run-time +behavior of Release 4.10.99.0 of the C interface to RTEMS. diff --git a/c_user/rate_monotonic_manager.rst b/c_user/rate_monotonic_manager.rst index 5bd3b1b..1acb0c1 100644 --- a/c_user/rate_monotonic_manager.rst +++ b/c_user/rate_monotonic_manager.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Rate Monotonic Manager ###################### @@ -9,41 +13,40 @@ Introduction The rate monotonic manager provides facilities to implement tasks which execute in a periodic fashion. Critically, it also gathers information about the -execution of those periods and can provide important statistics to the -user which can be used to analyze and tune the application. The directives -provided by the rate monotonic manager are: +execution of those periods and can provide important statistics to the user +which can be used to analyze and tune the application. The directives provided +by the rate monotonic manager are: -- ``rtems_rate_monotonic_create`` - Create a rate monotonic period +- rtems_rate_monotonic_create_ - Create a rate monotonic period -- ``rtems_rate_monotonic_ident`` - Get ID of a period +- rtems_rate_monotonic_ident_ - Get ID of a period -- ``rtems_rate_monotonic_cancel`` - Cancel a period +- rtems_rate_monotonic_cancel_ - Cancel a period -- ``rtems_rate_monotonic_delete`` - Delete a rate monotonic period +- rtems_rate_monotonic_delete_ - Delete a rate monotonic period -- ``rtems_rate_monotonic_period`` - Conclude current/Start next period +- rtems_rate_monotonic_period_ - Conclude current/Start next period -- ``rtems_rate_monotonic_get_status`` - Obtain status from a period +- rtems_rate_monotonic_get_status_ - Obtain status from a period -- ``rtems_rate_monotonic_get_statistics`` - Obtain statistics from a period +- rtems_rate_monotonic_get_statistics_ - Obtain statistics from a period -- ``rtems_rate_monotonic_reset_statistics`` - Reset statistics for a period +- rtems_rate_monotonic_reset_statistics_ - Reset statistics for a period -- ``rtems_rate_monotonic_reset_all_statistics`` - Reset statistics for all periods +- rtems_rate_monotonic_reset_all_statistics_ - Reset statistics for all periods -- ``rtems_rate_monotonic_report_statistics`` - Print period statistics report +- rtems_rate_monotonic_report_statistics_ - Print period statistics report Background ========== -The rate monotonic manager provides facilities to -manage the execution of periodic tasks. This manager was -designed to support application designers who utilize the Rate -Monotonic Scheduling Algorithm (RMS) to ensure that their -periodic tasks will meet their deadlines, even under transient -overload conditions. Although designed for hard real-time -systems, the services provided by the rate monotonic manager may -be used by any application which requires periodic tasks. +The rate monotonic manager provides facilities to manage the execution of +periodic tasks. This manager was designed to support application designers who +utilize the Rate Monotonic Scheduling Algorithm (RMS) to ensure that their +periodic tasks will meet their deadlines, even under transient overload +conditions. Although designed for hard real-time systems, the services +provided by the rate monotonic manager may be used by any application which +requires periodic tasks. Rate Monotonic Manager Required Support --------------------------------------- @@ -58,38 +61,38 @@ statistics are reset implictly at period creation time and may be reset or obtained at any time by the application. The following is a list of the information kept: -- ``owner`` +``owner`` is the id of the thread that owns this period. -- ``count`` +``count`` is the total number of periods executed. -- ``missed_count`` +``missed_count`` is the number of periods that were missed. -- ``min_cpu_time`` - is the minimum amount of CPU execution time consumed - on any execution of the periodic loop. +``min_cpu_time`` + is the minimum amount of CPU execution time consumed on any execution of the + periodic loop. -- ``max_cpu_time`` - is the maximum amount of CPU execution time consumed - on any execution of the periodic loop. +``max_cpu_time`` + is the maximum amount of CPU execution time consumed on any execution of the + periodic loop. -- ``total_cpu_time`` - is the total amount of CPU execution time consumed - by executions of the periodic loop. +``total_cpu_time`` + is the total amount of CPU execution time consumed by executions of the + periodic loop. -- ``min_wall_time`` - is the minimum amount of wall time that passed - on any execution of the periodic loop. +``min_wall_time`` + is the minimum amount of wall time that passed on any execution of the + periodic loop. -- ``max_wall_time`` - is the maximum amount of wall time that passed - on any execution of the periodic loop. +``max_wall_time`` + is the maximum amount of wall time that passed on any execution of the + periodic loop. -- ``total_wall_time`` - is the total amount of wall time that passed - during executions of the periodic loop. +``total_wall_time`` + is the total amount of wall time that passed during executions of the + periodic loop. Each period is divided into two consecutive phases. The period starts with the active phase of the task and is followed by the inactive phase of the task. In @@ -102,105 +105,95 @@ executing. In case the wall time exceeds the period time, then this is a period miss. The gap between the wall time and the period time is the margin between a period miss or success. -The period statistics information is inexpensive to maintain -and can provide very useful insights into the execution -characteristics of a periodic task loop. But it is just information. -The period statistics reported must be analyzed by the user in terms -of what the applications is. For example, in an application where -priorities are assigned by the Rate Monotonic Algorithm, it would -be very undesirable for high priority (i.e. frequency) tasks to -miss their period. Similarly, in nearly any application, if a -task were supposed to execute its periodic loop every 10 milliseconds -and it averaged 11 milliseconds, then application requirements -are not being met. - -The information reported can be used to determine the "hot spots" -in the application. Given a period's id, the user can determine -the length of that period. From that information and the CPU usage, -the user can calculate the percentage of CPU time consumed by that -periodic task. For example, a task executing for 20 milliseconds -every 200 milliseconds is consuming 10 percent of the processor's -execution time. This is usually enough to make it a good candidate -for optimization. - -However, execution time alone is not enough to gauge the value of -optimizing a particular task. It is more important to optimize -a task executing 2 millisecond every 10 milliseconds (20 percent -of the CPU) than one executing 10 milliseconds every 100 (10 percent -of the CPU). As a general rule of thumb, the higher frequency at -which a task executes, the more important it is to optimize that -task. +The period statistics information is inexpensive to maintain and can provide +very useful insights into the execution characteristics of a periodic task +loop. But it is just information. The period statistics reported must be +analyzed by the user in terms of what the applications is. For example, in an +application where priorities are assigned by the Rate Monotonic Algorithm, it +would be very undesirable for high priority (i.e. frequency) tasks to miss +their period. Similarly, in nearly any application, if a task were supposed to +execute its periodic loop every 10 milliseconds and it averaged 11 +milliseconds, then application requirements are not being met. + +The information reported can be used to determine the "hot spots" in the +application. Given a period's id, the user can determine the length of that +period. From that information and the CPU usage, the user can calculate the +percentage of CPU time consumed by that periodic task. For example, a task +executing for 20 milliseconds every 200 milliseconds is consuming 10 percent of +the processor's execution time. This is usually enough to make it a good +candidate for optimization. + +However, execution time alone is not enough to gauge the value of optimizing a +particular task. It is more important to optimize a task executing 2 +millisecond every 10 milliseconds (20 percent of the CPU) than one executing 10 +milliseconds every 100 (10 percent of the CPU). As a general rule of thumb, +the higher frequency at which a task executes, the more important it is to +optimize that task. Rate Monotonic Manager Definitions ---------------------------------- .. index:: periodic task, definition -A periodic task is one which must be executed at a -regular interval. The interval between successive iterations of -the task is referred to as its period. Periodic tasks can be -characterized by the length of their period and execution time. -The period and execution time of a task can be used to determine -the processor utilization for that task. Processor utilization -is the percentage of processor time used and can be calculated -on a per-task or system-wide basis. Typically, the task's -worst-case execution time will be less than its period. For -example, a periodic task's requirements may state that it should -execute for 10 milliseconds every 100 milliseconds. Although -the execution time may be the average, worst, or best case, the -worst-case execution time is more appropriate for use when -analyzing system behavior under transient overload conditions... index:: aperiodic task, definition - -In contrast, an aperiodic task executes at irregular -intervals and has only a soft deadline. In other words, the -deadlines for aperiodic tasks are not rigid, but adequate -response times are desirable. For example, an aperiodic task -may process user input from a terminal... index:: sporadic task, definition - -Finally, a sporadic task is an aperiodic task with a -hard deadline and minimum interarrival time. The minimum -interarrival time is the minimum period of time which exists -between successive iterations of the task. For example, a -sporadic task could be used to process the pressing of a fire -button on a joystick. The mechanical action of the fire button -ensures a minimum time period between successive activations, -but the missile must be launched by a hard deadline. +A periodic task is one which must be executed at a regular interval. The +interval between successive iterations of the task is referred to as its +period. Periodic tasks can be characterized by the length of their period and +execution time. The period and execution time of a task can be used to +determine the processor utilization for that task. Processor utilization is +the percentage of processor time used and can be calculated on a per-task or +system-wide basis. Typically, the task's worst-case execution time will be +less than its period. For example, a periodic task's requirements may state +that it should execute for 10 milliseconds every 100 milliseconds. Although +the execution time may be the average, worst, or best case, the worst-case +execution time is more appropriate for use when analyzing system behavior under +transient overload conditions... index:: aperiodic task, definition + +In contrast, an aperiodic task executes at irregular intervals and has only a +soft deadline. In other words, the deadlines for aperiodic tasks are not +rigid, but adequate response times are desirable. For example, an aperiodic +task may process user input from a terminal. + +.. index:: sporadic task, definition + +Finally, a sporadic task is an aperiodic task with a hard deadline and minimum +interarrival time. The minimum interarrival time is the minimum period of time +which exists between successive iterations of the task. For example, a +sporadic task could be used to process the pressing of a fire button on a +joystick. The mechanical action of the fire button ensures a minimum time +period between successive activations, but the missile must be launched by a +hard deadline. Rate Monotonic Scheduling Algorithm ----------------------------------- .. index:: Rate Monotonic Scheduling Algorithm, definition .. index:: RMS Algorithm, definition -The Rate Monotonic Scheduling Algorithm (RMS) is -important to real-time systems designers because it allows one -to guarantee that a set of tasks is schedulable. A set of tasks -is said to be schedulable if all of the tasks can meet their -deadlines. RMS provides a set of rules which can be used to -perform a guaranteed schedulability analysis for a task set. -This analysis determines whether a task set is schedulable under -worst-case conditions and emphasizes the predictability of the -system's behavior. It has been proven that: - -- *RMS is an optimal static priority algorithm for - scheduling independent, preemptible, periodic tasks - on a single processor.* - -RMS is optimal in the sense that if a set of tasks -can be scheduled by any static priority algorithm, then RMS will -be able to schedule that task set. RMS bases it schedulability -analysis on the processor utilization level below which all -deadlines can be met. - -RMS calls for the static assignment of task -priorities based upon their period. The shorter a task's -period, the higher its priority. For example, a task with a 1 -millisecond period has higher priority than a task with a 100 -millisecond period. If two tasks have the same period, then RMS -does not distinguish between the tasks. However, RTEMS -specifies that when given tasks of equal priority, the task -which has been ready longest will execute first. RMS's priority -assignment scheme does not provide one with exact numeric values -for task priorities. For example, consider the following task -set and priority assignments: +The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems +designers because it allows one to guarantee that a set of tasks is +schedulable. A set of tasks is said to be schedulable if all of the tasks can +meet their deadlines. RMS provides a set of rules which can be used to perform +a guaranteed schedulability analysis for a task set. This analysis determines +whether a task set is schedulable under worst-case conditions and emphasizes +the predictability of the system's behavior. It has been proven that: + +.. sidebar:: *RMS* + + RMS is an optimal static priority algorithm for scheduling independent, + preemptible, periodic tasks on a single processor. + +RMS is optimal in the sense that if a set of tasks can be scheduled by any +static priority algorithm, then RMS will be able to schedule that task set. +RMS bases it schedulability analysis on the processor utilization level below +which all deadlines can be met. + +RMS calls for the static assignment of task priorities based upon their period. +The shorter a task's period, the higher its priority. For example, a task with +a 1 millisecond period has higher priority than a task with a 100 millisecond +period. If two tasks have the same period, then RMS does not distinguish +between the tasks. However, RTEMS specifies that when given tasks of equal +priority, the task which has been ready longest will execute first. RMS's +priority assignment scheme does not provide one with exact numeric values for +task priorities. For example, consider the following task set and priority +assignments: +--------------------+---------------------+---------------------+ | Task | Period | Priority | @@ -215,22 +208,19 @@ set and priority assignments: | 4 | 25 | High | +--------------------+---------------------+---------------------+ -RMS only calls for task 1 to have the lowest -priority, task 4 to have the highest priority, and tasks 2 and 3 -to have an equal priority between that of tasks 1 and 4. The -actual RTEMS priorities assigned to the tasks must only adhere -to those guidelines. - -Many applications have tasks with both hard and soft -deadlines. The tasks with hard deadlines are typically referred -to as the critical task set, with the soft deadline tasks being -the non-critical task set. The critical task set can be -scheduled using RMS, with the non-critical tasks not executing -under transient overload, by simply assigning priorities such -that the lowest priority critical task (i.e. longest period) has -a higher priority than the highest priority non-critical task. -Although RMS may be used to assign priorities to the -non-critical tasks, it is not necessary. In this instance, +RMS only calls for task 1 to have the lowest priority, task 4 to have the +highest priority, and tasks 2 and 3 to have an equal priority between that of +tasks 1 and 4. The actual RTEMS priorities assigned to the tasks must only +adhere to those guidelines. + +Many applications have tasks with both hard and soft deadlines. The tasks with +hard deadlines are typically referred to as the critical task set, with the +soft deadline tasks being the non-critical task set. The critical task set can +be scheduled using RMS, with the non-critical tasks not executing under +transient overload, by simply assigning priorities such that the lowest +priority critical task (i.e. longest period) has a higher priority than the +highest priority non-critical task. Although RMS may be used to assign +priorities to the non-critical tasks, it is not necessary. In this instance, schedulability is only guaranteed for the critical task set. Schedulability Analysis @@ -238,74 +228,67 @@ Schedulability Analysis .. index:: RMS schedulability analysis -RMS allows application designers to ensure that tasks -can meet all deadlines, even under transient overload, without -knowing exactly when any given task will execute by applying -proven schedulability analysis rules. +RMS allows application designers to ensure that tasks can meet all deadlines, +even under transient overload, without knowing exactly when any given task will +execute by applying proven schedulability analysis rules. Assumptions ~~~~~~~~~~~ -The schedulability analysis rules for RMS were -developed based on the following assumptions: +The schedulability analysis rules for RMS were developed based on the following +assumptions: -- The requests for all tasks for which hard deadlines - exist are periodic, with a constant interval between requests. +- The requests for all tasks for which hard deadlines exist are periodic, with + a constant interval between requests. -- Each task must complete before the next request for it - occurs. +- Each task must complete before the next request for it occurs. -- The tasks are independent in that a task does not depend - on the initiation or completion of requests for other tasks. +- The tasks are independent in that a task does not depend on the initiation or + completion of requests for other tasks. -- The execution time for each task without preemption or - interruption is constant and does not vary. +- The execution time for each task without preemption or interruption is + constant and does not vary. -- Any non-periodic tasks in the system are special. These - tasks displace periodic tasks while executing and do not have - hard, critical deadlines. +- Any non-periodic tasks in the system are special. These tasks displace + periodic tasks while executing and do not have hard, critical deadlines. -Once the basic schedulability analysis is understood, -some of the above assumptions can be relaxed and the -side-effects accounted for. +Once the basic schedulability analysis is understood, some of the above +assumptions can be relaxed and the side-effects accounted for. Processor Utilization Rule ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: RMS Processor Utilization Rule -The Processor Utilization Rule requires that -processor utilization be calculated based upon the period and -execution time of each task. The fraction of processor time -spent executing task index is Time(index) / Period(index). The -processor utilization can be calculated as follows: +The Processor Utilization Rule requires that processor utilization be +calculated based upon the period and execution time of each task. The fraction +of processor time spent executing task index is ``Time(index) / +Period(index)``. The processor utilization can be calculated as follows: + .. code:: c Utilization = 0 for index = 1 to maximum_tasks Utilization = Utilization + (Time(index)/Period(index)) -To ensure schedulability even under transient -overload, the processor utilization must adhere to the following -rule: +To ensure schedulability even under transient overload, the processor +utilization must adhere to the following rule: + .. code:: c Utilization = maximum_tasks * (2**(1/maximum_tasks) - 1) -As the number of tasks increases, the above formula -approaches ln(2) for a worst-case utilization factor of -approximately 0.693. Many tasks sets can be scheduled with a -greater utilization factor. In fact, the average processor -utilization threshold for a randomly generated task set is -approximately 0.88. +As the number of tasks increases, the above formula approaches ln(2) for a +worst-case utilization factor of approximately 0.693. Many tasks sets can be +scheduled with a greater utilization factor. In fact, the average processor +utilization threshold for a randomly generated task set is approximately 0.88. Processor Utilization Rule Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This example illustrates the application of the -Processor Utilization Rule to an application with three critical -periodic tasks. The following table details the RMS priority, -period, execution time, and processor utilization for each task: - +This example illustrates the application of the Processor Utilization Rule to +an application with three critical periodic tasks. The following table details +the RMS priority, period, execution time, and processor utilization for each +task: +------------+----------+--------+-----------+-------------+ | Tas k | RMS | Period | Execution | Processor | @@ -318,46 +301,40 @@ period, execution time, and processor utilization for each task: | 3 | Low | 300 | 100 | 0.33 | +------------+----------+--------+-----------+-------------+ -The total processor utilization for this task set is -0.73 which is below the upper bound of 3 * (2**(1/3) - 1), or -0.779, imposed by the Processor Utilization Rule. Therefore, -this task set is guaranteed to be schedulable using RMS. +The total processor utilization for this task set is 0.73 which is below the +upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor +Utilization Rule. Therefore, this task set is guaranteed to be schedulable +using RMS. First Deadline Rule ~~~~~~~~~~~~~~~~~~~ .. index:: RMS First Deadline Rule -If a given set of tasks do exceed the processor -utilization upper limit imposed by the Processor Utilization -Rule, they can still be guaranteed to meet all their deadlines -by application of the First Deadline Rule. This rule can be +If a given set of tasks do exceed the processor utilization upper limit imposed +by the Processor Utilization Rule, they can still be guaranteed to meet all +their deadlines by application of the First Deadline Rule. This rule can be stated as follows: -For a given set of independent periodic tasks, if -each task meets its first deadline when all tasks are started at -the same time, then the deadlines will always be met for any -combination of start times. - -A key point with this rule is that ALL periodic tasks -are assumed to start at the exact same instant in time. -Although this assumption may seem to be invalid, RTEMS makes it -quite easy to ensure. By having a non-preemptible user -initialization task, all application tasks, regardless of -priority, can be created and started before the initialization -deletes itself. This technique ensures that all tasks begin to -compete for execution time at the same instant - when the user -initialization task deletes itself. +For a given set of independent periodic tasks, if each task meets its first +deadline when all tasks are started at the same time, then the deadlines will +always be met for any combination of start times. + +A key point with this rule is that ALL periodic tasks are assumed to start at +the exact same instant in time. Although this assumption may seem to be +invalid, RTEMS makes it quite easy to ensure. By having a non-preemptible user +initialization task, all application tasks, regardless of priority, can be +created and started before the initialization deletes itself. This technique +ensures that all tasks begin to compete for execution time at the same instant +- when the user initialization task deletes itself. First Deadline Rule Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The First Deadline Rule can ensure schedulability -even when the Processor Utilization Rule fails. The example -below is a modification of the Processor Utilization Rule -example where task execution time has been increased from 15 to -25 units. The following table details the RMS priority, period, -execution time, and processor utilization for each task: -.. code:: c +The First Deadline Rule can ensure schedulability even when the Processor +Utilization Rule fails. The example below is a modification of the Processor +Utilization Rule example where task execution time has been increased from 15 +to 25 units. The following table details the RMS priority, period, execution +time, and processor utilization for each task: +------------+----------+--------+-----------+-------------+ | Task | RMS | Period | Execution | Processor | @@ -370,19 +347,15 @@ execution time, and processor utilization for each task: | 3 | Low | 300 | 100 | 0.33 | +------------+----------+--------+-----------+-------------+ -The total processor utilization for the modified task -set is 0.83 which is above the upper bound of 3 * (2**(1/3) - 1), -or 0.779, imposed by the Processor Utilization Rule. Therefore, -this task set is not guaranteed to be schedulable using RMS. -However, the First Deadline Rule can guarantee the -schedulability of this task set. This rule calls for one to -examine each occurrence of deadline until either all tasks have -met their deadline or one task failed to meet its first -deadline. The following table details the time of each deadline -occurrence, the maximum number of times each task may have run, -the total execution time, and whether all the deadlines have -been met. -.. code:: c +The total processor utilization for the modified task set is 0.83 which is +above the upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor +Utilization Rule. Therefore, this task set is not guaranteed to be schedulable +using RMS. However, the First Deadline Rule can guarantee the schedulability +of this task set. This rule calls for one to examine each occurrence of +deadline until either all tasks have met their deadline or one task failed to +meet its first deadline. The following table details the time of each deadline +occurrence, the maximum number of times each task may have run, the total +execution time, and whether all the deadlines have been met: +----------+------+------+------+----------------------+---------------+ | Deadline | Task | Task | Task | Total | All Deadlines | @@ -393,85 +366,74 @@ been met. | 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES | +----------+------+------+------+----------------------+---------------+ -The key to this analysis is to recognize when each -task will execute. For example at time 100, task 1 must have -met its first deadline, but tasks 2 and 3 may also have begun -execution. In this example, at time 100 tasks 1 and 2 have -completed execution and thus have met their first deadline. -Tasks 1 and 2 have used (25 + 50) = 75 time units, leaving (100 -- 75) = 25 time units for task 3 to begin. Because task 3 takes -100 ticks to execute, it will not have completed execution at -time 100. Thus at time 100, all of the tasks except task 3 have -met their first deadline. - -At time 200, task 1 must have met its second deadline -and task 2 its first deadline. As a result, of the first 200 -time units, task 1 uses (2 * 25) = 50 and task 2 uses 50, -leaving (200 - 100) time units for task 3. Task 3 requires 100 -time units to execute, thus it will have completed execution at -time 200. Thus, all of the tasks have met their first deadlines -at time 200, and the task set is schedulable using the First -Deadline Rule. +The key to this analysis is to recognize when each task will execute. For +example at time 100, task 1 must have met its first deadline, but tasks 2 and 3 +may also have begun execution. In this example, at time 100 tasks 1 and 2 have +completed execution and thus have met their first deadline. Tasks 1 and 2 have +used (25 + 50) = 75 time units, leaving (100 - 75) = 25 time units for task 3 +to begin. Because task 3 takes 100 ticks to execute, it will not have +completed execution at time 100. Thus at time 100, all of the tasks except +task 3 have met their first deadline. + +At time 200, task 1 must have met its second deadline and task 2 its first +deadline. As a result, of the first 200 time units, task 1 uses (2 * 25) = 50 +and task 2 uses 50, leaving (200 - 100) time units for task 3. Task 3 requires +100 time units to execute, thus it will have completed execution at time 200. +Thus, all of the tasks have met their first deadlines at time 200, and the task +set is schedulable using the First Deadline Rule. Relaxation of Assumptions ~~~~~~~~~~~~~~~~~~~~~~~~~ -The assumptions used to develop the RMS -schedulability rules are uncommon in most real-time systems. -For example, it was assumed that tasks have constant unvarying -execution time. It is possible to relax this assumption, simply -by using the worst-case execution time of each task. - -Another assumption is that the tasks are independent. -This means that the tasks do not wait for one another or -contend for resources. This assumption can be relaxed by -accounting for the amount of time a task spends waiting to -acquire resources. Similarly, each task's execution time must -account for any I/O performed and any RTEMS directive calls. - -In addition, the assumptions did not account for the -time spent executing interrupt service routines. This can be -accounted for by including all the processor utilization by -interrupt service routines in the utilization calculation. -Similarly, one should also account for the impact of delays in -accessing local memory caused by direct memory access and other -processors accessing local dual-ported memory. - -The assumption that nonperiodic tasks are used only -for initialization or failure-recovery can be relaxed by placing -all periodic tasks in the critical task set. This task set can -be scheduled and analyzed using RMS. All nonperiodic tasks are -placed in the non-critical task set. Although the critical task -set can be guaranteed to execute even under transient overload, +The assumptions used to develop the RMS schedulability rules are uncommon in +most real-time systems. For example, it was assumed that tasks have constant +unvarying execution time. It is possible to relax this assumption, simply by +using the worst-case execution time of each task. + +Another assumption is that the tasks are independent. This means that the +tasks do not wait for one another or contend for resources. This assumption +can be relaxed by accounting for the amount of time a task spends waiting to +acquire resources. Similarly, each task's execution time must account for any +I/O performed and any RTEMS directive calls. + +In addition, the assumptions did not account for the time spent executing +interrupt service routines. This can be accounted for by including all the +processor utilization by interrupt service routines in the utilization +calculation. Similarly, one should also account for the impact of delays in +accessing local memory caused by direct memory access and other processors +accessing local dual-ported memory. + +The assumption that nonperiodic tasks are used only for initialization or +failure-recovery can be relaxed by placing all periodic tasks in the critical +task set. This task set can be scheduled and analyzed using RMS. All +nonperiodic tasks are placed in the non-critical task set. Although the +critical task set can be guaranteed to execute even under transient overload, the non-critical task set is not guaranteed to execute. -In conclusion, the application designer must be fully -cognizant of the system and its run-time behavior when -performing schedulability analysis for a system using RMS. -Every hardware and software factor which impacts the execution -time of each task must be accounted for in the schedulability -analysis. +In conclusion, the application designer must be fully cognizant of the system +and its run-time behavior when performing schedulability analysis for a system +using RMS. Every hardware and software factor which impacts the execution time +of each task must be accounted for in the schedulability analysis. Further Reading ~~~~~~~~~~~~~~~ -For more information on Rate Monotonic Scheduling and -its schedulability analysis, the reader is referred to the -following: +For more information on Rate Monotonic Scheduling and its schedulability +analysis, the reader is referred to the following: -- *C. L. Liu and J. W. Layland. "Scheduling Algorithms for - Multiprogramming in a Hard Real Time Environment." *Journal of - the Association of Computing Machinery*. January 1973. pp. 46-61.* +- C. L. Liu and J. W. Layland. "Scheduling Algorithms for Multiprogramming in a + Hard Real Time Environment." *Journal of the Association of Computing + Machinery*. January 1973. pp. 46-61. -- *John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic - Scheduling Algorithm: Exact Characterization and Average Case - Behavior." *IEEE Real-Time Systems Symposium*. 1989. pp. 166-171.* +- John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic Scheduling + Algorithm: Exact Characterization and Average Case Behavior." *IEEE + Real-Time Systems Symposium*. 1989. pp. 166-171. -- *Lui Sha and John Goodenough. "Real-Time Scheduling - theory and Ada." *IEEE Computer*. April 1990. pp. 53-62.* +- Lui Sha and John Goodenough. "Real-Time Scheduling theory and Ada." *IEEE + Computer*. April 1990. pp. 53-62. -- *Alan Burns. "Scheduling hard real-time systems: a - review." *Software Engineering Journal*. May 1991. pp. 116-128.* +- Alan Burns. "Scheduling hard real-time systems: a review." *Software + Engineering Journal*. May 1991. pp. 116-128. Operations ========== @@ -479,205 +441,202 @@ Operations Creating a Rate Monotonic Period -------------------------------- -The ``rtems_rate_monotonic_create`` directive creates a rate -monotonic period which is to be used by the calling task to -delineate a period. RTEMS allocates a Period Control Block -(PCB) from the PCB free list. This data structure is used by -RTEMS to manage the newly created rate monotonic period. RTEMS -returns a unique period ID to the application which is used by -other rate monotonic manager directives to access this rate -monotonic period. +The ``rtems_rate_monotonic_create`` directive creates a rate monotonic period +which is to be used by the calling task to delineate a period. RTEMS allocates +a Period Control Block (PCB) from the PCB free list. This data structure is +used by RTEMS to manage the newly created rate monotonic period. RTEMS returns +a unique period ID to the application which is used by other rate monotonic +manager directives to access this rate monotonic period. Manipulating a Period --------------------- -The ``rtems_rate_monotonic_period`` directive is used to -establish and maintain periodic execution utilizing a previously -created rate monotonic period. Once initiated by the``rtems_rate_monotonic_period`` directive, the period is -said to run until it either expires or is reinitiated. The state of the rate +The ``rtems_rate_monotonic_period`` directive is used to establish and maintain +periodic execution utilizing a previously created rate monotonic period. Once +initiated by the ``rtems_rate_monotonic_period`` directive, the period is said +to run until it either expires or is reinitiated. The state of the rate monotonic period results in one of the following scenarios: -- If the rate monotonic period is running, the calling - task will be blocked for the remainder of the outstanding period - and, upon completion of that period, the period will be - reinitiated with the specified period. +- If the rate monotonic period is running, the calling task will be blocked for + the remainder of the outstanding period and, upon completion of that period, + the period will be reinitiated with the specified period. -- If the rate monotonic period is not currently running - and has not expired, it is initiated with a length of period - ticks and the calling task returns immediately. +- If the rate monotonic period is not currently running and has not expired, it + is initiated with a length of period ticks and the calling task returns + immediately. -- If the rate monotonic period has expired before the task - invokes the ``rtems_rate_monotonic_period`` directive, - the period will be initiated with a length of period ticks and the calling task - returns immediately with a timeout error status. +- If the rate monotonic period has expired before the task invokes the + ``rtems_rate_monotonic_period`` directive, the period will be initiated with + a length of period ticks and the calling task returns immediately with a + timeout error status. Obtaining the Status of a Period -------------------------------- -If the ``rtems_rate_monotonic_period`` directive is invoked -with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current -state of the specified rate monotonic period will be returned. The following -table details the relationship between the period's status and -the directive status code returned by the``rtems_rate_monotonic_period`` -directive: +If the ``rtems_rate_monotonic_period`` directive is invoked with a period of +``RTEMS_PERIOD_STATUS`` ticks, the current state of the specified rate +monotonic period will be returned. The following table details the +relationship between the period's status and the directive status code returned +by the ``rtems_rate_monotonic_period`` directive: -- ``RTEMS_SUCCESSFUL`` - period is running +``RTEMS_SUCCESSFUL`` + period is running -- ``RTEMS_TIMEOUT`` - period has expired +``RTEMS_TIMEOUT`` + period has expired -- ``RTEMS_NOT_DEFINED`` - period has never been initiated +``RTEMS_NOT_DEFINED`` + period has never been initiated -Obtaining the status of a rate monotonic period does -not alter the state or length of that period. +Obtaining the status of a rate monotonic period does not alter the state or +length of that period. Canceling a Period ------------------ -The ``rtems_rate_monotonic_cancel`` directive is used to stop -the period maintained by the specified rate monotonic period. -The period is stopped and the rate monotonic period can be -reinitiated using the ``rtems_rate_monotonic_period`` directive. +The ``rtems_rate_monotonic_cancel`` directive is used to stop the period +maintained by the specified rate monotonic period. The period is stopped and +the rate monotonic period can be reinitiated using the +``rtems_rate_monotonic_period`` directive. Deleting a Rate Monotonic Period -------------------------------- -The ``rtems_rate_monotonic_delete`` directive is used to delete -a rate monotonic period. If the period is running and has not -expired, the period is automatically canceled. The rate -monotonic period's control block is returned to the PCB free -list when it is deleted. A rate monotonic period can be deleted -by a task other than the task which created the period. +The ``rtems_rate_monotonic_delete`` directive is used to delete a rate +monotonic period. If the period is running and has not expired, the period is +automatically canceled. The rate monotonic period's control block is returned +to the PCB free list when it is deleted. A rate monotonic period can be +deleted by a task other than the task which created the period. Examples -------- -The following sections illustrate common uses of rate -monotonic periods to construct periodic tasks. +The following sections illustrate common uses of rate monotonic periods to +construct periodic tasks. Simple Periodic Task -------------------- -This example consists of a single periodic task -which, after initialization, executes every 100 clock ticks. -.. code:: c +This example consists of a single periodic task which, after initialization, +executes every 100 clock ticks. + +.. code-block:: c + :linenos: rtems_task Periodic_task(rtems_task_argument arg) { - rtems_name name; - rtems_id period; - rtems_status_code status; - name = rtems_build_name( 'P', 'E', 'R', 'D' ); - status = rtems_rate_monotonic_create( name, &period ); - if ( status != RTEMS_STATUS_SUCCESSFUL ) { - printf( "rtems_monotonic_create failed with status of %d.\\n", rc ); - exit( 1 ); - } - while ( 1 ) { - if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT ) - break; - /* Perform some periodic actions \*/ - } - /* missed period so delete period and SELF \*/ - status = rtems_rate_monotonic_delete( period ); - if ( status != RTEMS_STATUS_SUCCESSFUL ) { - printf( "rtems_rate_monotonic_delete failed with status of %d.\\n", status ); - exit( 1 ); - } - status = rtems_task_delete( SELF ); /* should not return \*/ - printf( "rtems_task_delete returned with status of %d.\\n", status ); - exit( 1 ); + rtems_name name; + rtems_id period; + rtems_status_code status; + name = rtems_build_name( 'P', 'E', 'R', 'D' ); + status = rtems_rate_monotonic_create( name, &period ); + if ( status != RTEMS_STATUS_SUCCESSFUL ) { + printf( "rtems_monotonic_create failed with status of %d.\n", rc ); + exit( 1 ); + } + while ( 1 ) { + if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT ) + break; + /* Perform some periodic actions */ + } + /* missed period so delete period and SELF */ + status = rtems_rate_monotonic_delete( period ); + if ( status != RTEMS_STATUS_SUCCESSFUL ) { + printf( "rtems_rate_monotonic_delete failed with status of %d.\n", status ); + exit( 1 ); + } + status = rtems_task_delete( SELF ); /* should not return */ + printf( "rtems_task_delete returned with status of %d.\n", status ); + exit( 1 ); } -The above task creates a rate monotonic period as -part of its initialization. The first time the loop is -executed, the ``rtems_rate_monotonic_period`` -directive will initiate the period for 100 ticks and return -immediately. Subsequent invocations of the``rtems_rate_monotonic_period`` directive will result -in the task blocking for the remainder of the 100 tick period. -If, for any reason, the body of the loop takes more than 100 -ticks to execute, the ``rtems_rate_monotonic_period`` -directive will return the ``RTEMS_TIMEOUT`` status. -If the above task misses its deadline, it will delete the rate +The above task creates a rate monotonic period as part of its initialization. +The first time the loop is executed, the ``rtems_rate_monotonic_period`` +directive will initiate the period for 100 ticks and return immediately. +Subsequent invocations of the ``rtems_rate_monotonic_period`` directive will +result in the task blocking for the remainder of the 100 tick period. If, for +any reason, the body of the loop takes more than 100 ticks to execute, the +``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT`` +status. If the above task misses its deadline, it will delete the rate monotonic period and itself. Task with Multiple Periods -------------------------- -This example consists of a single periodic task -which, after initialization, performs two sets of actions every -100 clock ticks. The first set of actions is performed in the -first forty clock ticks of every 100 clock ticks, while the -second set of actions is performed between the fortieth and -seventieth clock ticks. The last thirty clock ticks are not -used by this task. -.. code:: c +This example consists of a single periodic task which, after initialization, +performs two sets of actions every 100 clock ticks. The first set of actions +is performed in the first forty clock ticks of every 100 clock ticks, while the +second set of actions is performed between the fortieth and seventieth clock +ticks. The last thirty clock ticks are not used by this task. + +.. code-block:: c + :linenos: rtems_task Periodic_task(rtems_task_argument arg) { - rtems_name name_1, name_2; - rtems_id period_1, period_2; - rtems_status_code status; - name_1 = rtems_build_name( 'P', 'E', 'R', '1' ); - name_2 = rtems_build_name( 'P', 'E', 'R', '2' ); - (void ) rtems_rate_monotonic_create( name_1, &period_1 ); - (void ) rtems_rate_monotonic_create( name_2, &period_2 ); - while ( 1 ) { - if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT ) - break; - if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT ) - break; - /* - * Perform first set of actions between clock - * ticks 0 and 39 of every 100 ticks. - \*/ - if ( rtems_rate_monotonic_period( period_2, 30 ) == TIMEOUT ) - break; - /* - * Perform second set of actions between clock 40 and 69 - * of every 100 ticks. THEN ... - * - * Check to make sure we didn't miss the period_2 period. - \*/ - if ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT ) - break; - (void) rtems_rate_monotonic_cancel( period_2 ); - } - /* missed period so delete period and SELF \*/ - (void ) rtems_rate_monotonic_delete( period_1 ); - (void ) rtems_rate_monotonic_delete( period_2 ); - (void ) task_delete( SELF ); + rtems_name name_1, name_2; + rtems_id period_1, period_2; + rtems_status_code status; + name_1 = rtems_build_name( 'P', 'E', 'R', '1' ); + name_2 = rtems_build_name( 'P', 'E', 'R', '2' ); + (void ) rtems_rate_monotonic_create( name_1, &period_1 ); + (void ) rtems_rate_monotonic_create( name_2, &period_2 ); + while ( 1 ) { + if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT ) + break; + if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT ) + break; + /* + * Perform first set of actions between clock + * ticks 0 and 39 of every 100 ticks. + */ + if ( rtems_rate_monotonic_period( period_2, 30 ) == TIMEOUT ) + break; + /* + * Perform second set of actions between clock 40 and 69 + * of every 100 ticks. THEN ... + * + * Check to make sure we didn't miss the period_2 period. + */ + if ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT ) + break; + (void) rtems_rate_monotonic_cancel( period_2 ); + } + /* missed period so delete period and SELF */ + (void ) rtems_rate_monotonic_delete( period_1 ); + (void ) rtems_rate_monotonic_delete( period_2 ); + (void ) task_delete( SELF ); } -The above task creates two rate monotonic periods as -part of its initialization. The first time the loop is -executed, the ``rtems_rate_monotonic_period`` -directive will initiate the period_1 period for 100 ticks -and return immediately. Subsequent invocations of the``rtems_rate_monotonic_period`` directive -for period_1 will result in the task blocking for the remainder -of the 100 tick period. The period_2 period is used to control -the execution time of the two sets of actions within each 100 -tick period established by period_1. The``rtems_rate_monotonic_cancel( period_2 )`` -call is performed to ensure that the period_2 period -does not expire while the task is blocked on the period_1 -period. If this cancel operation were not performed, every time -the ``rtems_rate_monotonic_period( period_2, 40 )`` -call is executed, except for the initial one, a directive status -of ``RTEMS_TIMEOUT`` is returned. It is important to -note that every time this call is made, the period_2 period will be -initiated immediately and the task will not block. - -If, for any reason, the task misses any deadline, the``rtems_rate_monotonic_period`` directive will -return the ``RTEMS_TIMEOUT`` -directive status. If the above task misses its deadline, it -will delete the rate monotonic periods and itself. +The above task creates two rate monotonic periods as part of its +initialization. The first time the loop is executed, the +``rtems_rate_monotonic_period`` directive will initiate the period_1 period for +100 ticks and return immediately. Subsequent invocations of the +``rtems_rate_monotonic_period`` directive for period_1 will result in the task +blocking for the remainder of the 100 tick period. The period_2 period is used +to control the execution time of the two sets of actions within each 100 tick +period established by period_1. The ``rtems_rate_monotonic_cancel( period_2 +)`` call is performed to ensure that the period_2 period does not expire while +the task is blocked on the period_1 period. If this cancel operation were not +performed, every time the ``rtems_rate_monotonic_period( period_2, 40 )`` call +is executed, except for the initial one, a directive status of +``RTEMS_TIMEOUT`` is returned. It is important to note that every time this +call is made, the period_2 period will be initiated immediately and the task +will not block. + +If, for any reason, the task misses any deadline, the +``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT`` +directive status. If the above task misses its deadline, it will delete the +rate monotonic periods and itself. Directives ========== -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. +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. + +.. _rtems_rate_monotonic_create: RATE_MONOTONIC_CREATE - Create a rate monotonic period ------------------------------------------------------ @@ -690,29 +649,34 @@ RATE_MONOTONIC_CREATE - Create a rate monotonic period .. code:: c rtems_status_code rtems_rate_monotonic_create( - rtems_name name, - rtems_id \*id + rtems_name name, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``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:** -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 +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. +This directive will not cause the calling task to be preempted. + +.. _rtems_rate_monotonic_ident: RATE_MONOTONIC_IDENT - Get ID of a period ----------------------------------------- @@ -726,28 +690,31 @@ RATE_MONOTONIC_IDENT - Get ID of a period .. code:: c rtems_status_code rtems_rate_monotonic_ident( - rtems_name name, - rtems_id \*id + rtems_name name, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``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:** -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. +This directive will not cause the running task to be preempted. + +.. _rtems_rate_monotonic_cancel: RATE_MONOTONIC_CANCEL - Cancel a period --------------------------------------- @@ -760,27 +727,33 @@ RATE_MONOTONIC_CANCEL - Cancel a period .. code:: c rtems_status_code rtems_rate_monotonic_cancel( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``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:** -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. +This directive will not cause the running task to be preempted. + +The rate monotonic period specified by id must have been created by the calling +task. -The rate monotonic period specified by id must have -been created by the calling task. +.. _rtems_rate_monotonic_delete: RATE_MONOTONIC_DELETE - Delete a rate monotonic period ------------------------------------------------------ @@ -793,27 +766,31 @@ RATE_MONOTONIC_DELETE - Delete a rate monotonic period .. code:: c rtems_status_code rtems_rate_monotonic_delete( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - period deleted successfully -``RTEMS_INVALID_ID`` - invalid rate monotonic period id +``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. +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. +This directive will not cause the running task to be preempted. -A rate monotonic period can be deleted by a task -other than the task which created the period. +A rate monotonic period can be deleted by a task other than the task which +created the period. + +.. _rtems_rate_monotonic_period: RATE_MONOTONIC_PERIOD - Conclude current/Start next period ---------------------------------------------------------- @@ -828,37 +805,46 @@ RATE_MONOTONIC_PERIOD - Conclude current/Start next period .. code:: c rtems_status_code rtems_rate_monotonic_period( - rtems_id id, - rtems_interval length + rtems_id id, + rtems_interval length ); **DIRECTIVE STATUS CODES:** -``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:** -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. +.. _rtems_rate_monotonic_get_status: + RATE_MONOTONIC_GET_STATUS - Obtain status from a period ------------------------------------------------------- .. index:: get status of period @@ -871,46 +857,57 @@ RATE_MONOTONIC_GET_STATUS - Obtain status from a period .. code:: c rtems_status_code rtems_rate_monotonic_get_status( - rtems_id id, - rtems_rate_monotonic_period_status \*status + rtems_id id, + rtems_rate_monotonic_period_status \status ); **DIRECTIVE STATUS CODES:** -``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:.. index:: rtems_rate_monotonic_period_status +This directive returns status information associated with the rate monotonic +period id in the following data structure: + +.. index:: rtems_rate_monotonic_period_status .. code:: c 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_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. +.. 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. +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:** This directive will not cause the running task to be preempted. +.. _rtems_rate_monotonic_get_statistics: + RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period --------------------------------------------------------------- .. index:: get statistics of period @@ -923,54 +920,63 @@ RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period .. code:: c rtems_status_code rtems_rate_monotonic_get_statistics( - rtems_id id, - rtems_rate_monotonic_period_statistics \*statistics + rtems_id id, + rtems_rate_monotonic_period_statistics *statistics ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - period initiated successfully -``RTEMS_INVALID_ID`` - invalid rate monotonic period id -``RTEMS_INVALID_ADDRESS`` - invalid address of statistics +``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 +This directive returns statistics information associated with the rate +monotonic period id in the following data structure: + +.. index:: rtems_rate_monotonic_period_statistics .. code:: 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 + 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. +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. +.. _rtems_rate_monotonic_reset_statistics: + RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period --------------------------------------------------------------- .. index:: reset statistics of period @@ -982,23 +988,28 @@ RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period .. code:: c rtems_status_code rtems_rate_monotonic_reset_statistics( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``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:** -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. +.. _rtems_rate_monotonic_reset_all_statistics: + RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods ---------------------------------------------------------------------- .. index:: reset statistics of all periods @@ -1017,13 +1028,15 @@ NONE **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. +.. _rtems_rate_monotonic_report_statistics: + RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report ----------------------------------------------------------------- .. index:: print period statistics report @@ -1043,9 +1056,11 @@ NONE **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 +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:: c @@ -1060,10 +1075,3 @@ output generated by this directive... index:: rtems_rate_monotonic_period_statis **NOTES:** This directive will not cause the running task to be preempted. - -.. COMMENT: COPYRIGHT (c) 1988-2007. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - diff --git a/c_user/rtems_data_types.rst b/c_user/rtems_data_types.rst index 83e9fe2..65d336f 100644 --- a/c_user/rtems_data_types.rst +++ b/c_user/rtems_data_types.rst @@ -1,379 +1,386 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + RTEMS Data Types ################ Introduction ============ -This chapter contains a complete list of the RTEMS primitive -data types in alphabetical order. This is intended to be -an overview and the user is encouraged to look at the appropriate -chapters in the manual for more information about the -usage of the various data types. +This chapter contains a complete list of the RTEMS primitive data types in +alphabetical order. This is intended to be an overview and the user is +encouraged to look at the appropriate chapters in the manual for more +information about the usage of the various data types. List of Data Types ================== -The following is a complete list of the RTEMS primitive -data types in alphabetical order: +The following is a complete list of the RTEMS primitive data types in +alphabetical order: -- .. index:: rtems_address +.. index:: rtems_address - ``rtems_address`` is the data type used to manage - addresses. It is equivalent to - a "void \*" pointer. +``rtems_address`` + The data type used to manage addresses. It is equivalent to a ``void *`` + pointer. -- .. index:: rtems_asr +.. index:: rtems_asr - ``rtems_asr`` is the return type for an - RTEMS ASR. +``rtems_asr`` + The return type for an RTEMS ASR. -- .. index:: rtems_asr_entry +.. index:: rtems_asr_entry - ``rtems_asr_entry`` is the address of - the entry point to an RTEMS ASR. +``rtems_asr_entry`` + The address of the entry point to an RTEMS ASR. -- .. index:: rtems_attribute + .. index:: rtems_attribute - ``rtems_attribute`` is the data type used - to manage the attributes for RTEMS objects. It is primarily - used as an argument to object create routines to specify +``rtems_attribute`` + The data type used to manage the attributes for RTEMS objects. It is + primarily used as an argument to object create routines to specify characteristics of the new object. -- .. index:: rtems_boolean +.. index:: rtems_boolean - ``rtems_boolean`` may only take on the - values of ``TRUE`` and ``FALSE``. - This type is deprecated. Use "bool" instead. +``rtems_boolean`` + May only take on the values of ``TRUE`` and ``FALSE``. This type is + deprecated. Use ``bool`` instead. -- .. index:: rtems_context +.. index:: rtems_context - ``rtems_context`` is the CPU dependent - data structure used to manage the integer and system +``rtems_context`` + The CPU dependent data structure used to manage the integer and system register portion of each task's context. -- .. index:: rtems_context_fp +.. index:: rtems_context_fp - ``rtems_context_fp`` is the CPU dependent - data structure used to manage the floating point portion of +``rtems_context_fp`` + The CPU dependent data structure used to manage the floating point portion of each task's context. -- .. index:: rtems_device_driver +.. index:: rtems_device_driver - ``rtems_device_driver`` is the - return type for a RTEMS device driver routine. +``rtems_device_driver`` + The return type for a RTEMS device driver routine. -- .. index:: rtems_device_driver_entry +.. index:: rtems_device_driver_entry - ``rtems_device_driver_entry`` is the - entry point to a RTEMS device driver routine. +``rtems_device_driver_entry`` + The entry point to a RTEMS device driver routine. -- .. index:: rtems_device_major_number +.. index:: rtems_device_major_number - ``rtems_device_major_number`` is the - data type used to manage device major numbers. +``rtems_device_major_number`` + The data type used to manage device major numbers. -- .. index:: rtems_device_minor_number +.. index:: rtems_device_minor_number - ``rtems_device_minor_number`` is the - data type used to manage device minor numbers. +``rtems_device_minor_number`` + The data type used to manage device minor numbers. -- .. index:: rtems_double +.. index:: rtems_double - ``rtems_double`` is the RTEMS data - type that corresponds to double precision floating point - on the target hardware. - This type is deprecated. Use "double" instead. +``rtems_double`` + The RTEMS data type that corresponds to double precision floating point on + the target hardware. This type is deprecated. Use ``double`` instead. -- .. index:: rtems_event_set +.. index:: rtems_event_set - ``rtems_event_set`` is the data - type used to manage and manipulate RTEMS event sets - with the Event Manager. +``rtems_event_set`` + The data type used to manage and manipulate RTEMS event sets with the Event + Manager. -- .. index:: rtems_extension +.. index:: rtems_extension - ``rtems_extension`` is the return type - for RTEMS user extension routines. +``rtems_extension`` + The return type for RTEMS user extension routines. -- .. index:: rtems_fatal_extension +.. index:: rtems_fatal_extension - ``rtems_fatal_extension`` is the - entry point for a fatal error user extension handler routine. +``rtems_fatal_extension`` -- .. index:: rtems_id + The entry point for a fatal error user extension handler routine. - ``rtems_id`` is the data type used - to manage and manipulate RTEMS object IDs. +.. index:: rtems_id -- .. index:: rtems_interrupt_frame +``rtems_id`` + The data type used to manage and manipulate RTEMS object IDs. - ``rtems_interrupt_frame`` is the - data structure that defines the format of the interrupt - stack frame as it appears to a user ISR. This data - structure may not be defined on all ports. +.. index:: rtems_interrupt_frame -- .. index:: rtems_interrupt_level +``rtems_interrupt_frame`` + The data structure that defines the format of the interrupt stack frame as it + appears to a user ISR. This data structure may not be defined on all ports. - ``rtems_interrupt_level`` is the - data structure used with the ``rtems_interrupt_disable``,``rtems_interrupt_enable``, and``rtems_interrupt_flash`` routines. This - data type is CPU dependent and usually corresponds to - the contents of the processor register containing - the interrupt mask level. +.. index:: rtems_interrupt_level -- .. index:: rtems_interval +``rtems_interrupt_level`` - ``rtems_interval`` is the data - type used to manage and manipulate time intervals. - Intervals are non-negative integers used to measure - the length of time in clock ticks. + The data structure used with the ``rtems_interrupt_disable``, + ``rtems_interrupt_enable``, and ``rtems_interrupt_flash`` routines. This + data type is CPU dependent and usually corresponds to the contents of the + processor register containing the interrupt mask level. -- .. index:: rtems_isr +.. index:: rtems_interval - ``rtems_isr`` is the return type - of a function implementing an RTEMS ISR. +``rtems_interval`` + The data type used to manage and manipulate time intervals. Intervals are + non-negative integers used to measure the length of time in clock ticks. -- .. index:: rtems_isr_entry +.. index:: rtems_isr - ``rtems_isr_entry`` is the address of - the entry point to an RTEMS ISR. It is equivalent to the +``rtems_isr`` + The return type of a function implementing an RTEMS ISR. + +.. index:: rtems_isr_entry + +``rtems_isr_entry`` + The address of the entry point to an RTEMS ISR. It is equivalent to the entry point of the function implementing the ISR. -- .. index:: rtems_mp_packet_classes +.. index:: rtems_mp_packet_classes - ``rtems_mp_packet_classes`` is the - enumerated type which specifies the categories of - multiprocessing messages. For example, one of the - classes is for messages that must be processed by - the Task Manager. +``rtems_mp_packet_classes`` + The enumerated type which specifies the categories of multiprocessing + messages. For example, one of the classes is for messages that must be + processed by the Task Manager. -- .. index:: rtems_mode +.. index:: rtems_mode - ``rtems_mode`` is the data type - used to manage and dynamically manipulate the execution - mode of an RTEMS task. +``rtems_mode`` + The data type used to manage and dynamically manipulate the execution mode of + an RTEMS task. -- .. index:: rtems_mpci_entry +.. index:: rtems_mpci_entry - ``rtems_mpci_entry`` is the return type - of an RTEMS MPCI routine. +``rtems_mpci_entry`` + The return type of an RTEMS MPCI routine. -- .. index:: rtems_mpci_get_packet_entry +.. index:: rtems_mpci_get_packet_entry - ``rtems_mpci_get_packet_entry`` is the address of - the entry point to the get packet routine for an MPCI implementation. +``rtems_mpci_get_packet_entry`` + The address of the entry point to the get packet routine for an MPCI + implementation. -- .. index:: rtems_mpci_initialization_entry +.. index:: rtems_mpci_initialization_entry - ``rtems_mpci_initialization_entry`` is the address of - the entry point to the initialization routine for an MPCI implementation. +``rtems_mpci_initialization_entry`` + The address of the entry point to the initialization routine for an MPCI + implementation. -- .. index:: rtems_mpci_receive_packet_entry +.. index:: rtems_mpci_receive_packet_entry - ``rtems_mpci_receive_packet_entry`` is the address of - the entry point to the receive packet routine for an MPCI implementation. +``rtems_mpci_receive_packet_entry`` + The address of the entry point to the receive packet routine for an MPCI + implementation. -- .. index:: rtems_mpci_return_packet_entry +.. index:: rtems_mpci_return_packet_entry - ``rtems_mpci_return_packet_entry`` is the address of - the entry point to the return packet routine for an MPCI implementation. +``rtems_mpci_return_packet_entry`` + The address of the entry point to the return packet routine for an MPCI + implementation. -- .. index:: rtems_mpci_send_packet_entry +.. index:: rtems_mpci_send_packet_entry - ``rtems_mpci_send_packet_entry`` is the address of - the entry point to the send packet routine for an MPCI implementation. +``rtems_mpci_send_packet_entry`` + The address of the entry point to the send packet routine for an MPCI + implementation. -- .. index:: rtems_mpci_table +.. index:: rtems_mpci_table - ``rtems_mpci_table`` is the data structure - containing the configuration information for an MPCI. +``rtems_mpci_table`` + The data structure containing the configuration information for an MPCI. -- .. index:: rtems_name +.. index:: rtems_name - ``rtems_name`` is the data type used to - contain the name of a Classic API object. It is an unsigned - thirty-two bit integer which can be treated as a numeric - value or initialized using ``rtems_build_name`` to - contain four ASCII characters. +``rtems_name`` + The data type used to contain the name of a Classic API object. It is an + unsigned thirty-two bit integer which can be treated as a numeric value or + initialized using ``rtems_build_name`` to contain four ASCII characters. -- .. index:: rtems_option +.. index:: rtems_option - ``rtems_option`` is the data type - used to specify which behavioral options the caller desires. - It is commonly used with potentially blocking directives to specify - whether the caller is willing to block or return immediately with an error - indicating that the resource was not available. +``rtems_option`` + The data type used to specify which behavioral options the caller desires. + It is commonly used with potentially blocking directives to specify whether + the caller is willing to block or return immediately with an error indicating + that the resource was not available. -- .. index:: rtems_packet_prefix +.. index:: rtems_packet_prefix - ``rtems_packet_prefix`` is the data structure - that defines the first bytes in every packet sent between nodes - in an RTEMS multiprocessor system. It contains routing information +``rtems_packet_prefix`` + The data structure that defines the first bytes in every packet sent between + nodes in an RTEMS multiprocessor system. It contains routing information that is expected to be used by the MPCI layer. -- .. index:: rtems_signal_set +.. index:: rtems_signal_set - ``rtems_signal_set`` is the data - type used to manage and manipulate RTEMS signal sets - with the Signal Manager. +``rtems_signal_set`` + The data type used to manage and manipulate RTEMS signal sets with the Signal + Manager. -- .. index:: int8_t +.. index:: int8_t - ``int8_t`` is the C99 data type that corresponds to signed eight - bit integers. This data type is defined by RTEMS in a manner that - ensures it is portable across different target processors. +``int8_t`` + The C99 data type that corresponds to signed eight bit integers. This data + type is defined by RTEMS in a manner that ensures it is portable across + different target processors. -- .. index:: int16_t +.. index:: int16_t - ``int16_t`` is the C99 data type that corresponds to signed - sixteen bit integers. This data type is defined by RTEMS in a manner - that ensures it is portable across different target processors. +``int16_t`` + The C99 data type that corresponds to signed sixteen bit integers. This data + type is defined by RTEMS in a manner that ensures it is portable across + different target processors. -- .. index:: int32_t +.. index:: int32_t - ``int32_t`` is the C99 data type that corresponds to signed - thirty-two bit integers. This data type is defined by RTEMS in a manner - that ensures it is portable across different target processors. +``int32_t`` + The C99 data type that corresponds to signed thirty-two bit integers. This + data type is defined by RTEMS in a manner that ensures it is portable across + different target processors. -- .. index:: int64_t +.. index:: int64_t - ``int64_t`` is the C99 data type that corresponds to signed - sixty-four bit integers. This data type is defined by RTEMS in a manner - that ensures it is portable across different target processors. +``int64_t`` + The C99 data type that corresponds to signed sixty-four bit integers. This + data type is defined by RTEMS in a manner that ensures it is portable across + different target processors. -- .. index:: rtems_single +.. index:: rtems_single - ``rtems_single`` is the RTEMS data - type that corresponds to single precision floating point - on the target hardware. - This type is deprecated. Use "float" instead. +``rtems_single`` + The RTEMS data type that corresponds to single precision floating point on + the target hardware. This type is deprecated. Use ``float`` instead. -- .. index:: rtems_status_codes +.. index:: rtems_status_codes - ``rtems_status_codes`` is the return type for most - RTEMS services. This is an enumerated type of approximately twenty-five - values. In general, when a service returns a particular status code, it - indicates that a very specific error condition has occurred. +``rtems_status_codes`` + The return type for most RTEMS services. This is an enumerated type of + approximately twenty-five values. In general, when a service returns a + particular status code, it indicates that a very specific error condition has + occurred. -- .. index:: rtems_task +.. index:: rtems_task - ``rtems_task`` is the return type for an - RTEMS Task. +``rtems_task`` + The return type for an RTEMS Task. -- .. index:: rtems_task_argument +.. index:: rtems_task_argument - ``rtems_task_argument`` is the data - type for the argument passed to each RTEMS task. In RTEMS 4.7 - and older, this is an unsigned thirty-two bit integer. In - RTEMS 4.8 and newer, this is based upon the C99 type ``uintptr_t`` - which is guaranteed to be an integer large enough to hold a - pointer on the target architecture. +``rtems_task_argument`` + The data type for the argument passed to each RTEMS task. In RTEMS 4.7 and + older, this is an unsigned thirty-two bit integer. In RTEMS 4.8 and newer, + this is based upon the C99 type ``uintptr_t`` which is guaranteed to be an + integer large enough to hold a pointer on the target architecture. -- .. index:: rtems_task_begin_extension +.. index:: rtems_task_begin_extension - ``rtems_task_begin_extension`` is the - entry point for a task beginning execution user extension handler routine. +``rtems_task_begin_extension`` + The entry point for a task beginning execution user extension handler + routine. -- .. index:: rtems_task_create_extension +.. index:: rtems_task_create_extension - ``rtems_task_create_extension`` is the - entry point for a task creation execution user extension handler routine. +``rtems_task_create_extension`` + The entry point for a task creation execution user extension handler routine. -- .. index:: rtems_task_delete_extension +.. index:: rtems_task_delete_extension - ``rtems_task_delete_extension`` is the - entry point for a task deletion user extension handler routine. +``rtems_task_delete_extension`` + The entry point for a task deletion user extension handler routine. -- .. index:: rtems_task_entry +.. index:: rtems_task_entry - ``rtems_task_entry`` is the address of - the entry point to an RTEMS ASR. It is equivalent to the +``rtems_task_entry`` + The address of the entry point to an RTEMS ASR. It is equivalent to the entry point of the function implementing the ASR. -- .. index:: rtems_task_exitted_extension +.. index:: rtems_task_exitted_extension - ``rtems_task_exitted_extension`` is the - entry point for a task exitted user extension handler routine. +``rtems_task_exitted_extension`` + The entry point for a task exitted user extension handler routine. -- .. index:: rtems_task_priority +.. index:: rtems_task_priority - ``rtems_task_priority`` is the data type - used to manage and manipulate task priorities. +``rtems_task_priority`` + The data type used to manage and manipulate task priorities. -- .. index:: rtems_task_restart_extension +.. index:: rtems_task_restart_extension - ``rtems_task_restart_extension`` is the - entry point for a task restart user extension handler routine. +``rtems_task_restart_extension`` + The entry point for a task restart user extension handler routine. -- .. index:: rtems_task_start_extension +.. index:: rtems_task_start_extension - ``rtems_task_start_extension`` is the - entry point for a task start user extension handler routine. +``rtems_task_start_extension`` + The entry point for a task start user extension handler routine. -- .. index:: rtems_task_switch_extension +.. index:: rtems_task_switch_extension - ``rtems_task_switch_extension`` is the - entry point for a task context switch user extension handler routine. +``rtems_task_switch_extension`` + The entry point for a task context switch user extension handler routine. -- .. index:: rtems_tcb +.. index:: rtems_tcb - ``rtems_tcb`` is the data structure associated - with each task in an RTEMS system. +``rtems_tcb`` + The data structure associated with each task in an RTEMS system. -- .. index:: rtems_time_of_day +.. index:: rtems_time_of_day - ``rtems_time_of_day`` is the data structure - used to manage and manipulate calendar time in RTEMS. +``rtems_time_of_day`` + The data structure used to manage and manipulate calendar time in RTEMS. -- .. index:: rtems_timer_service_routine +.. index:: rtems_timer_service_routine - ``rtems_timer_service_routine`` is the - return type for an RTEMS Timer Service Routine. +``rtems_timer_service_routine`` + The return type for an RTEMS Timer Service Routine. -- .. index:: rtems_timer_service_routine_entry +.. index:: rtems_timer_service_routine_entry - ``rtems_timer_service_routine_entry`` is the address of - the entry point to an RTEMS TSR. It is equivalent to the +``rtems_timer_service_routine_entry`` + The address of the entry point to an RTEMS TSR. It is equivalent to the entry point of the function implementing the TSR. -- .. index:: rtems_vector_number - - ``rtems_vector_number`` is the data - type used to manage and manipulate interrupt vector numbers. +.. index:: rtems_vector_number -- .. index:: uint8_t +``rtems_vector_number`` + The data type used to manage and manipulate interrupt vector numbers. - ``uint8_t`` is the C99 data type that corresponds to unsigned - eight bit integers. This data type is defined by RTEMS in a manner that - ensures it is portable across different target processors. +.. index:: uint8_t -- .. index:: uint16_t +``uint8_t`` + The C99 data type that corresponds to unsigned eight bit integers. This data + type is defined by RTEMS in a manner that ensures it is portable across + different target processors. - ``uint16_t`` is the C99 data type that corresponds to unsigned - sixteen bit integers. This data type is defined by RTEMS in a manner - that ensures it is portable across different target processors. +.. index:: uint16_t -- .. index:: uint32_t +``uint16_t`` + The C99 data type that corresponds to unsigned sixteen bit integers. This + data type is defined by RTEMS in a manner that ensures it is portable across + different target processors. - ``uint32_t`` is the C99 data type that corresponds to unsigned - thirty-two bit integers. This data type is defined by RTEMS in a manner - that ensures it is portable across different target processors. +.. index:: uint32_t -- .. index:: uint64_t +``uint32_t`` + The C99 data type that corresponds to unsigned thirty-two bit integers. This + data type is defined by RTEMS in a manner that ensures it is portable across + different target processors. - ``uint64_t`` is the C99 data type that corresponds to unsigned - sixty-four bit integers. This data type is defined by RTEMS in a manner - that ensures it is portable across different target processors. +.. index:: uint64_t -- .. index:: uintptr_t +``uint64_t`` + The C99 data type that corresponds to unsigned sixty-four bit integers. This + data type is defined by RTEMS in a manner that ensures it is portable across + different target processors. - ``uintptr_t`` is the C99 data type that corresponds to the - unsigned integer type that is of sufficient size to represent addresses - as unsigned integers. This data type is defined by RTEMS in a manner - that ensures it is portable across different target processors. - -.. COMMENT: COPYRIGHT (c) 1988-2011. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. +.. index:: uintptr_t +``uintptr_t`` + The C99 data type that corresponds to the unsigned integer type that is of + sufficient size to represent addresses as unsigned integers. This data type + is defined by RTEMS in a manner that ensures it is portable across different + target processors. diff --git a/c_user/rtemsarc.png b/c_user/rtemsarc.png Binary files differnew file mode 100644 index 0000000..13c3b30 --- /dev/null +++ b/c_user/rtemsarc.png diff --git a/c_user/rtemspie.png b/c_user/rtemspie.png Binary files differnew file mode 100644 index 0000000..f6245ff --- /dev/null +++ b/c_user/rtemspie.png diff --git a/c_user/scheduling_concepts.rst b/c_user/scheduling_concepts.rst index d5b261e..ea77157 100644 --- a/c_user/scheduling_concepts.rst +++ b/c_user/scheduling_concepts.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Scheduling Concepts ################### @@ -7,102 +11,101 @@ Scheduling Concepts Introduction ============ -The concept of scheduling in real-time systems dictates the ability to -provide immediate response to specific external events, particularly -the necessity of scheduling tasks to run within a specified time limit -after the occurrence of an event. For example, software embedded in -life-support systems used to monitor hospital patients must take instant -action if a change in the patient's status is detected. +The concept of scheduling in real-time systems dictates the ability to provide +immediate response to specific external events, particularly the necessity of +scheduling tasks to run within a specified time limit after the occurrence of +an event. For example, software embedded in life-support systems used to +monitor hospital patients must take instant action if a change in the patient's +status is detected. The component of RTEMS responsible for providing this capability is -appropriately called the scheduler. The scheduler's sole purpose is -to allocate the all important resource of processor time to the various -tasks competing for attention. +appropriately called the scheduler. The scheduler's sole purpose is to +allocate the all important resource of processor time to the various tasks +competing for attention. Scheduling Algorithms ===================== .. index:: scheduling algorithms -RTEMS provides a plugin framework which allows it to support -multiple scheduling algorithms. RTEMS now includes multiple -scheduling algorithms in the SuperCore and the user can select which -of these they wish to use in their application. In addition, -the user can implement their own scheduling algorithm and -configure RTEMS to use it. - -Supporting multiple scheduling algorithms gives the end user the -option to select the algorithm which is most appropriate to their use -case. Most real-time operating systems schedule tasks using a priority -based algorithm, possibly with preemption control. The classic -RTEMS scheduling algorithm which was the only algorithm available -in RTEMS 4.10 and earlier, is a priority based scheduling algorithm. -This scheduling algoritm is suitable for single core (e.g. non-SMP) -systems and is now known as the *Deterministic Priority Scheduler*. -Unless the user configures another scheduling algorithm, RTEMS will use -this on single core systems. +RTEMS provides a plugin framework which allows it to support multiple +scheduling algorithms. RTEMS now includes multiple scheduling algorithms in the +SuperCore and the user can select which of these they wish to use in their +application. In addition, the user can implement their own scheduling +algorithm and configure RTEMS to use it. + +Supporting multiple scheduling algorithms gives the end user the option to +select the algorithm which is most appropriate to their use case. Most +real-time operating systems schedule tasks using a priority based algorithm, +possibly with preemption control. The classic RTEMS scheduling algorithm which +was the only algorithm available in RTEMS 4.10 and earlier, is a priority based +scheduling algorithm. This scheduling algoritm is suitable for single core +(e.g. non-SMP) systems and is now known as the *Deterministic Priority +Scheduler*. Unless the user configures another scheduling algorithm, RTEMS +will use this on single core systems. Priority Scheduling ------------------- .. index:: priority scheduling -When using priority based scheduling, RTEMS allocates the processor using -a priority-based, preemptive algorithm augmented to provide round-robin -characteristics within individual priority groups. The goal of this -algorithm is to guarantee that the task which is executing on the -processor at any point in time is the one with the highest priority -among all tasks in the ready state. - -When a task is added to the ready chain, it is placed behind all other -tasks of the same priority. This rule provides a round-robin within -priority group scheduling characteristic. This means that in a group of -equal priority tasks, tasks will execute in the order they become ready -or FIFO order. Even though there are ways to manipulate and adjust task -priorities, the most important rule to remember is: - -- *Priority based scheduling algorithms will always select the - highest priority task that is ready to run when allocating the processor - to a task.* - -Priority scheduling is the most commonly used scheduling algorithm. -It should be used by applications in which multiple tasks contend for -CPU time or other resources and there is a need to ensure certain tasks -are given priority over other tasks. +When using priority based scheduling, RTEMS allocates the processor using a +priority-based, preemptive algorithm augmented to provide round-robin +characteristics within individual priority groups. The goal of this algorithm +is to guarantee that the task which is executing on the processor at any point +in time is the one with the highest priority among all tasks in the ready +state. + +When a task is added to the ready chain, it is placed behind all other tasks of +the same priority. This rule provides a round-robin within priority group +scheduling characteristic. This means that in a group of equal priority tasks, +tasks will execute in the order they become ready or FIFO order. Even though +there are ways to manipulate and adjust task priorities, the most important +rule to remember is: + +.. note:: + + Priority based scheduling algorithms will always select the highest priority + task that is ready to run when allocating the processor to a task. + +Priority scheduling is the most commonly used scheduling algorithm. It should +be used by applications in which multiple tasks contend for CPU time or other +resources and there is a need to ensure certain tasks are given priority over +other tasks. There are a few common methods of accomplishing the mechanics of this algorithm. These ways involve a list or chain of tasks in the ready state. -- The least efficient method is to randomly place tasks in the ready - chain forcing the scheduler to scan the entire chain to determine which - task receives the processor. +- The least efficient method is to randomly place tasks in the ready chain + forcing the scheduler to scan the entire chain to determine which task + receives the processor. -- A more efficient method is to schedule the task by placing it - in the proper place on the ready chain based on the designated scheduling - criteria at the time it enters the ready state. Thus, when the processor - is free, the first task on the ready chain is allocated the processor. +- A more efficient method is to schedule the task by placing it in the proper + place on the ready chain based on the designated scheduling criteria at the + time it enters the ready state. Thus, when the processor is free, the first + task on the ready chain is allocated the processor. -- Another mechanism is to maintain a list of FIFOs per priority. - When a task is readied, it is placed on the rear of the FIFO for its - priority. This method is often used with a bitmap to assist in locating - which FIFOs have ready tasks on them. +- Another mechanism is to maintain a list of FIFOs per priority. When a task + is readied, it is placed on the rear of the FIFO for its priority. This + method is often used with a bitmap to assist in locating which FIFOs have + ready tasks on them. -RTEMS currently includes multiple priority based scheduling algorithms -as well as other algorithms which incorporate deadline. Each algorithm -is discussed in the following sections. +RTEMS currently includes multiple priority based scheduling algorithms as well +as other algorithms which incorporate deadline. Each algorithm is discussed in +the following sections. Deterministic Priority Scheduler -------------------------------- -This is the scheduler implementation which has always been in RTEMS. -After the 4.10 release series, it was factored into pluggable scheduler -selection. It schedules tasks using a priority based algorithm which -takes into account preemption. It is implemented using an array of FIFOs -with a FIFO per priority. It maintains a bitmap which is used to track -which priorities have ready tasks. +This is the scheduler implementation which has always been in RTEMS. After the +4.10 release series, it was factored into pluggable scheduler selection. It +schedules tasks using a priority based algorithm which takes into account +preemption. It is implemented using an array of FIFOs with a FIFO per +priority. It maintains a bitmap which is used to track which priorities have +ready tasks. -This algorithm is deterministic (e.g. predictable and fixed) in execution -time. This comes at the cost of using slightly over three (3) kilobytes -of RAM on a system configured to support 256 priority levels. +This algorithm is deterministic (e.g. predictable and fixed) in execution time. +This comes at the cost of using slightly over three (3) kilobytes of RAM on a +system configured to support 256 priority levels. This scheduler is only aware of a single core. @@ -110,94 +113,92 @@ Simple Priority Scheduler ------------------------- This scheduler implementation has the same behaviour as the Deterministic -Priority Scheduler but uses only one linked list to manage all ready -tasks. When a task is readied, a linear search of that linked list is -performed to determine where to insert the newly readied task. +Priority Scheduler but uses only one linked list to manage all ready tasks. +When a task is readied, a linear search of that linked list is performed to +determine where to insert the newly readied task. -This algorithm uses much less RAM than the Deterministic Priority -Scheduler but is *O(n)* where *n* is the number of ready tasks. -In a small system with a small number of tasks, this will not be a -performance issue. Reducing RAM consumption is often critical in small -systems which are incapable of supporting a large number of tasks. +This algorithm uses much less RAM than the Deterministic Priority Scheduler but +is *O(n)* where *n* is the number of ready tasks. In a small system with a +small number of tasks, this will not be a performance issue. Reducing RAM +consumption is often critical in small systems which are incapable of +supporting a large number of tasks. This scheduler is only aware of a single core. Simple SMP Priority Scheduler ----------------------------- -This scheduler is based upon the Simple Priority Scheduler and is designed -to have the same behaviour on a single core system. But this scheduler -is capable of scheduling threads across multiple cores in an SMP system. -When given a choice of replacing one of two threads at equal priority -on different cores, this algorithm favors replacing threads which are -preemptible and have executed the longest. +This scheduler is based upon the Simple Priority Scheduler and is designed to +have the same behaviour on a single core system. But this scheduler is capable +of scheduling threads across multiple cores in an SMP system. When given a +choice of replacing one of two threads at equal priority on different cores, +this algorithm favors replacing threads which are preemptible and have executed +the longest. -This algorithm is non-deterministic. When scheduling, it must consider -which tasks are to be executed on each core while avoiding superfluous -task migrations. +This algorithm is non-deterministic. When scheduling, it must consider which +tasks are to be executed on each core while avoiding superfluous task +migrations. Earliest Deadline First Scheduler --------------------------------- .. index:: earliest deadline first scheduling -This is an alternative scheduler in RTEMS for single core applications. -The primary EDF advantage is high total CPU utilization (theoretically -up to 100%). It assumes that tasks have priorities equal to deadlines. +This is an alternative scheduler in RTEMS for single core applications. The +primary EDF advantage is high total CPU utilization (theoretically up to +100%). It assumes that tasks have priorities equal to deadlines. This EDF is initially preemptive, however, individual tasks may be declared not-preemptive. Deadlines are declared using only Rate Monotonic manager which goal is to handle periodic behavior. Period is always equal to deadline. All ready tasks reside in a single ready queue implemented using a red-black tree. -This implementation of EDF schedules two different types of task -priority types while each task may switch between the two types within -its execution. If a task does have a deadline declared using the Rate -Monotonic manager, the task is deadline-driven and its priority is equal -to deadline. On the contrary if a task does not have any deadline or -the deadline is cancelled using the Rate Monotonic manager, the task is -considered a background task with priority equal to that assigned -upon initialization in the same manner as for priority scheduler. Each -background task is of a lower importance than each deadline-driven one -and is scheduled when no deadline-driven task and no higher priority -background task is ready to run. - -Every deadline-driven scheduling algorithm requires means for tasks -to claim a deadline. The Rate Monotonic Manager is responsible for -handling periodic execution. In RTEMS periods are equal to deadlines, -thus if a task announces a period, it has to be finished until the -end of this period. The call of ``rtems_rate_monotonic_period`` -passes the scheduler the length of oncoming deadline. Moreover, the``rtems_rate_monotonic_cancel`` and ``rtems_rate_monotonic_delete`` -calls clear the deadlines assigned to the task. +This implementation of EDF schedules two different types of task priority types +while each task may switch between the two types within its execution. If a +task does have a deadline declared using the Rate Monotonic manager, the task +is deadline-driven and its priority is equal to deadline. On the contrary if a +task does not have any deadline or the deadline is cancelled using the Rate +Monotonic manager, the task is considered a background task with priority equal +to that assigned upon initialization in the same manner as for priority +scheduler. Each background task is of a lower importance than each +deadline-driven one and is scheduled when no deadline-driven task and no higher +priority background task is ready to run. + +Every deadline-driven scheduling algorithm requires means for tasks to claim a +deadline. The Rate Monotonic Manager is responsible for handling periodic +execution. In RTEMS periods are equal to deadlines, thus if a task announces a +period, it has to be finished until the end of this period. The call of +``rtems_rate_monotonic_period`` passes the scheduler the length of oncoming +deadline. Moreover, the ``rtems_rate_monotonic_cancel`` and +``rtems_rate_monotonic_delete`` calls clear the deadlines assigned to the task. Constant Bandwidth Server Scheduling (CBS) ------------------------------------------ .. index:: constant bandwidth server scheduling -This is an alternative scheduler in RTEMS for single core applications. -The CBS is a budget aware extension of EDF scheduler. The main goal of this +This is an alternative scheduler in RTEMS for single core applications. The +CBS is a budget aware extension of EDF scheduler. The main goal of this scheduler is to ensure temporal isolation of tasks meaning that a task's -execution in terms of meeting deadlines must not be influenced by other -tasks as if they were run on multiple independent processors. +execution in terms of meeting deadlines must not be influenced by other tasks +as if they were run on multiple independent processors. -Each task can be assigned a server (current implementation supports only -one task per server). The server is characterized by period (deadline) -and computation time (budget). The ratio budget/period yields bandwidth, -which is the fraction of CPU to be reserved by the scheduler for each -subsequent period. +Each task can be assigned a server (current implementation supports only one +task per server). The server is characterized by period (deadline) and +computation time (budget). The ratio budget/period yields bandwidth, which is +the fraction of CPU to be reserved by the scheduler for each subsequent period. The CBS is equipped with a set of rules applied to tasks attached to servers -ensuring that deadline miss because of another task cannot occur. -In case a task breaks one of the rules, its priority is pulled to background -until the end of its period and then restored again. The rules are: +ensuring that deadline miss because of another task cannot occur. In case a +task breaks one of the rules, its priority is pulled to background until the +end of its period and then restored again. The rules are: - Task cannot exceed its registered budget, -- Task cannot be - unblocked when a ratio between remaining budget and remaining deadline - is higher than declared bandwidth. +- Task cannot be unblocked when a ratio between remaining budget and remaining + deadline is higher than declared bandwidth. -The CBS provides an extensive API. Unlike EDF, the``rtems_rate_monotonic_period`` does not declare a deadline because -it is carried out using CBS API. This call only announces next period. +The CBS provides an extensive API. Unlike EDF, the +``rtems_rate_monotonic_period`` does not declare a deadline because it is +carried out using CBS API. This call only announces next period. Scheduling Modification Mechanisms ================================== @@ -215,268 +216,249 @@ scheduling decisions: - manual round-robin selection -Each of these methods provides a powerful capability to customize sets -of tasks to satisfy the unique and particular requirements encountered -in custom real-time applications. Although each mechanism operates -independently, there is a precedence relationship which governs the -effects of scheduling modifications. The evaluation order for scheduling -characteristics is always priority, preemption mode, and timeslicing. -When reading the descriptions of timeslicing and manual round-robin -it is important to keep in mind that preemption (if enabled) of a task -by higher priority tasks will occur as required, overriding the other -factors presented in the description. +Each of these methods provides a powerful capability to customize sets of tasks +to satisfy the unique and particular requirements encountered in custom +real-time applications. Although each mechanism operates independently, there +is a precedence relationship which governs the effects of scheduling +modifications. The evaluation order for scheduling characteristics is always +priority, preemption mode, and timeslicing. When reading the descriptions of +timeslicing and manual round-robin it is important to keep in mind that +preemption (if enabled) of a task by higher priority tasks will occur as +required, overriding the other factors presented in the description. Task Priority and Scheduling ---------------------------- .. index:: task priority -The most significant task scheduling modification mechanism is the ability -for the user to assign a priority level to each individual task when it -is created and to alter a task's priority at run-time. RTEMS supports -up to 255 priority levels. Level 255 is the lowest priority and level -1 is the highest. +The most significant task scheduling modification mechanism is the ability for +the user to assign a priority level to each individual task when it is created +and to alter a task's priority at run-time. RTEMS supports up to 255 priority +levels. Level 255 is the lowest priority and level 1 is the highest. Preemption -----------.. index:: preemption +---------- +.. index:: preemption Another way the user can alter the basic scheduling algorithm is by -manipulating the preemption mode flag (``RTEMS_PREEMPT_MASK``) -of individual tasks. If preemption is disabled for a task -(``RTEMS_NO_PREEMPT``), then the task will not relinquish -control of the processor until it terminates, blocks, or re-enables -preemption. Even tasks which become ready to run and possess higher -priority levels will not be allowed to execute. Note that the preemption -setting has no effect on the manner in which a task is scheduled. +manipulating the preemption mode flag (``RTEMS_PREEMPT_MASK``) of individual +tasks. If preemption is disabled for a task (``RTEMS_NO_PREEMPT``), then the +task will not relinquish control of the processor until it terminates, blocks, +or re-enables preemption. Even tasks which become ready to run and possess +higher priority levels will not be allowed to execute. Note that the +preemption setting has no effect on the manner in which a task is scheduled. It only applies once a task has control of the processor. Timeslicing ------------.. index:: timeslicing +----------- +.. index:: timeslicing .. index:: round robin scheduling -Timeslicing or round-robin scheduling is an additional method which -can be used to alter the basic scheduling algorithm. Like preemption, -timeslicing is specified on a task by task basis using the timeslicing -mode flag (``RTEMS_TIMESLICE_MASK``). If timeslicing is -enabled for a task (``RTEMS_TIMESLICE``), then RTEMS will -limit the amount of time the task can execute before the processor is -allocated to another task. Each tick of the real-time clock reduces -the currently running task's timeslice. When the execution time equals -the timeslice, RTEMS will dispatch another task of the same priority -to execute. If there are no other tasks of the same priority ready to -execute, then the current task is allocated an additional timeslice and -continues to run. Remember that a higher priority task will preempt -the task (unless preemption is disabled) as soon as it is ready to run, -even if the task has not used up its entire timeslice. +Timeslicing or round-robin scheduling is an additional method which can be used +to alter the basic scheduling algorithm. Like preemption, timeslicing is +specified on a task by task basis using the timeslicing mode flag +(``RTEMS_TIMESLICE_MASK``). If timeslicing is enabled for a task +(``RTEMS_TIMESLICE``), then RTEMS will limit the amount of time the task can +execute before the processor is allocated to another task. Each tick of the +real-time clock reduces the currently running task's timeslice. When the +execution time equals the timeslice, RTEMS will dispatch another task of the +same priority to execute. If there are no other tasks of the same priority +ready to execute, then the current task is allocated an additional timeslice +and continues to run. Remember that a higher priority task will preempt the +task (unless preemption is disabled) as soon as it is ready to run, even if the +task has not used up its entire timeslice. Manual Round-Robin -------------------.. index:: manual round robin +------------------ +.. index:: manual round robin -The final mechanism for altering the RTEMS scheduling algorithm is -called manual round-robin. Manual round-robin is invoked by using the``rtems_task_wake_after`` directive with a time interval -of ``RTEMS_YIELD_PROCESSOR``. This allows a task to give -up the processor and be immediately returned to the ready chain at the -end of its priority group. If no other tasks of the same priority are -ready to run, then the task does not lose control of the processor. +The final mechanism for altering the RTEMS scheduling algorithm is called +manual round-robin. Manual round-robin is invoked by using +the ``rtems_task_wake_after`` directive with a time interval of +``RTEMS_YIELD_PROCESSOR``. This allows a task to give up the processor and be +immediately returned to the ready chain at the end of its priority group. If +no other tasks of the same priority are ready to run, then the task does not +lose control of the processor. Dispatching Tasks -=================.. index:: dispatching - -The dispatcher is the RTEMS component responsible for -allocating the processor to a ready task. In order to allocate -the processor to one task, it must be deallocated or retrieved -from the task currently using it. This involves a concept -called a context switch. To perform a context switch, the -dispatcher saves the context of the current task and restores -the context of the task which has been allocated to the -processor. Saving and restoring a task's context is the -storing/loading of all the essential information about a task to -enable it to continue execution without any effects of the -interruption. For example, the contents of a task's register -set must be the same when it is given the processor as they were -when it was taken away. All of the information that must be -saved or restored for a context switch is located either in the -TCB or on the task's stacks. - -Tasks that utilize a numeric coprocessor and are created with the``RTEMS_FLOATING_POINT`` attribute require additional -operations during a context switch. These additional operations -are necessary to save and restore the floating point context of``RTEMS_FLOATING_POINT`` tasks. To avoid unnecessary save -and restore operations, the state of the numeric coprocessor is only -saved when a ``RTEMS_FLOATING_POINT`` task is dispatched -and that task was not the last task to utilize the coprocessor. +================= +.. index:: dispatching + +The dispatcher is the RTEMS component responsible for allocating the processor +to a ready task. In order to allocate the processor to one task, it must be +deallocated or retrieved from the task currently using it. This involves a +concept called a context switch. To perform a context switch, the dispatcher +saves the context of the current task and restores the context of the task +which has been allocated to the processor. Saving and restoring a task's +context is the storing/loading of all the essential information about a task to +enable it to continue execution without any effects of the interruption. For +example, the contents of a task's register set must be the same when it is +given the processor as they were when it was taken away. All of the +information that must be saved or restored for a context switch is located +either in the TCB or on the task's stacks. + +Tasks that utilize a numeric coprocessor and are created with the +``RTEMS_FLOATING_POINT`` attribute require additional operations during a +context switch. These additional operations are necessary to save and restore +the floating point context of ``RTEMS_FLOATING_POINT`` tasks. To avoid +unnecessary save and restore operations, the state of the numeric coprocessor +is only saved when a ``RTEMS_FLOATING_POINT`` task is dispatched and that task +was not the last task to utilize the coprocessor. Task State Transitions -======================.. index:: task state transitions - -Tasks in an RTEMS system must always be in one of the -five allowable task states. These states are: executing, ready, -blocked, dormant, and non-existent. - -A task occupies the non-existent state before -a ``rtems_task_create`` has been issued on its behalf. -A task enters the non-existent state from any other state in the system -when it is deleted with the ``rtems_task_delete`` directive. -While a task occupies this state it does not have a TCB or a task ID -assigned to it; therefore, no other tasks in the system may reference -this task. - -When a task is created via the ``rtems_task_create`` -directive it enters the dormant state. This state is not entered through -any other means. Although the task exists in the system, it cannot -actively compete for system resources. It will remain in the dormant -state until it is started via the ``rtems_task_start`` -directive, at which time it enters the ready state. The task is now -permitted to be scheduled for the processor and to compete for other -system resources. - -.. code:: c - - +-------------------------------------------------------------+ - | Non-existent | - | +-------------------------------------------------------+ | - | | | | - | | | | - | | Creating +---------+ Deleting | | - | | -------------------> | Dormant | -------------------> | | - | | +---------+ | | - | | | | | - | | Starting | | | - | | | | | - | | V Deleting | | - | | +-------> +-------+ -------------------> | | - | | Yielding / +----- | Ready | ------+ | | - | | / / +-------+ <--+ \\ | | - | | / / \\ \\ Blocking | | - | | / / Dispatching Readying \\ \\ | | - | | / V \\ V | | - | | +-----------+ Blocking +---------+ | | - | | | Executing | --------------> | Blocked | | | - | | +-----------+ +---------+ | | - | | | | - | | | | - | +-------------------------------------------------------+ | - | Non-existent | - +-------------------------------------------------------------+ - -A task occupies the blocked state whenever it is unable to be scheduled -to run. A running task may block itself or be blocked by other tasks in -the system. The running task blocks itself through voluntary operations -that cause the task to wait. The only way a task can block a task other -than itself is with the ``rtems_task_suspend`` directive. -A task enters the blocked state due to any of the following conditions: - -- A task issues a ``rtems_task_suspend`` directive - which blocks either itself or another task in the system. - -- The running task issues a ``rtems_barrier_wait`` - directive. - -- The running task issues a ``rtems_message_queue_receive`` - directive with the wait option and the message queue is empty. - -- The running task issues an ``rtems_event_receive`` - directive with the wait option and the currently pending events do not - satisfy the request. - -- The running task issues a ``rtems_semaphore_obtain`` - directive with the wait option and the requested semaphore is unavailable. - -- The running task issues a ``rtems_task_wake_after`` - directive which blocks the task for the given time interval. If the time - interval specified is zero, the task yields the processor and remains - in the ready state. - -- The running task issues a ``rtems_task_wake_when`` - directive which blocks the task until the requested date and time arrives. - -- The running task issues a ``rtems_rate_monotonic_period`` - directive and must wait for the specified rate monotonic period - to conclude. - -- The running task issues a ``rtems_region_get_segment`` - directive with the wait option and there is not an available segment large - enough to satisfy the task's request. - -A blocked task may also be suspended. Therefore, both the suspension -and the blocking condition must be removed before the task becomes ready -to run again. - -A task occupies the ready state when it is able to be scheduled to run, -but currently does not have control of the processor. Tasks of the same -or higher priority will yield the processor by either becoming blocked, -completing their timeslice, or being deleted. All tasks with the same -priority will execute in FIFO order. A task enters the ready state due -to any of the following conditions: - -- A running task issues a ``rtems_task_resume`` - directive for a task that is suspended and the task is not blocked - waiting on any resource. - -- A running task issues a ``rtems_message_queue_send``,``rtems_message_queue_broadcast``, or a``rtems_message_queue_urgent`` directive - which posts a message to the queue on which the blocked task is +====================== +.. index:: task state transitions + +Tasks in an RTEMS system must always be in one of the five allowable task +states. These states are: executing, ready, blocked, dormant, and +non-existent. + +A task occupies the non-existent state before a ``rtems_task_create`` has been +issued on its behalf. A task enters the non-existent state from any other +state in the system when it is deleted with the ``rtems_task_delete`` +directive. While a task occupies this state it does not have a TCB or a task +ID assigned to it; therefore, no other tasks in the system may reference this +task. + +When a task is created via the ``rtems_task_create`` directive it enters the +dormant state. This state is not entered through any other means. Although +the task exists in the system, it cannot actively compete for system resources. +It will remain in the dormant state until it is started via the +``rtems_task_start`` directive, at which time it enters the ready state. The +task is now permitted to be scheduled for the processor and to compete for +other system resources. + +.. COMMENT: .. code:: c +.. COMMENT: +.. COMMENT: +-------------------------------------------------------------+ +.. COMMENT: | Non-existent | +.. COMMENT: | +-------------------------------------------------------+ | +.. COMMENT: | | | | +.. COMMENT: | | | | +.. COMMENT: | | Creating +---------+ Deleting | | +.. COMMENT: | | -------------------> | Dormant | -------------------> | | +.. COMMENT: | | +---------+ | | +.. COMMENT: | | | | | +.. COMMENT: | | Starting | | | +.. COMMENT: | | | | | +.. COMMENT: | | V Deleting | | +.. COMMENT: | | +-------> +-------+ -------------------> | | +.. COMMENT: | | Yielding / +----- | Ready | ------+ | | +.. COMMENT: | | / / +-------+ <--+ \\ | | +.. COMMENT: | | / / \\ \\ Blocking | | +.. COMMENT: | | / / Dispatching Readying \\ \\ | | +.. COMMENT: | | / V \\ V | | +.. COMMENT: | | +-----------+ Blocking +---------+ | | +.. COMMENT: | | | Executing | --------------> | Blocked | | | +.. COMMENT: | | +-----------+ +---------+ | | +.. COMMENT: | | | | +.. COMMENT: | | | | +.. COMMENT: | +-------------------------------------------------------+ | +.. COMMENT: | Non-existent | +.. COMMENT: +-------------------------------------------------------------+ + +.. figure:: states.png + :width: 70% + :align: center + :alt: Task State Transitions + +A task occupies the blocked state whenever it is unable to be scheduled to run. +A running task may block itself or be blocked by other tasks in the system. +The running task blocks itself through voluntary operations that cause the task +to wait. The only way a task can block a task other than itself is with the +``rtems_task_suspend`` directive. A task enters the blocked state due to any +of the following conditions: + +- A task issues a ``rtems_task_suspend`` directive which blocks either itself + or another task in the system. + +- The running task issues a ``rtems_barrier_wait`` directive. + +- The running task issues a ``rtems_message_queue_receive`` directive with the + wait option and the message queue is empty. + +- The running task issues an ``rtems_event_receive`` directive with the wait + option and the currently pending events do not satisfy the request. + +- The running task issues a ``rtems_semaphore_obtain`` directive with the wait + option and the requested semaphore is unavailable. + +- The running task issues a ``rtems_task_wake_after`` directive which blocks + the task for the given time interval. If the time interval specified is + zero, the task yields the processor and remains in the ready state. + +- The running task issues a ``rtems_task_wake_when`` directive which blocks the + task until the requested date and time arrives. + +- The running task issues a ``rtems_rate_monotonic_period`` directive and must + wait for the specified rate monotonic period to conclude. + +- The running task issues a ``rtems_region_get_segment`` directive with the + wait option and there is not an available segment large enough to satisfy the + task's request. + +A blocked task may also be suspended. Therefore, both the suspension and the +blocking condition must be removed before the task becomes ready to run again. + +A task occupies the ready state when it is able to be scheduled to run, but +currently does not have control of the processor. Tasks of the same or higher +priority will yield the processor by either becoming blocked, completing their +timeslice, or being deleted. All tasks with the same priority will execute in +FIFO order. A task enters the ready state due to any of the following +conditions: + +- A running task issues a ``rtems_task_resume`` directive for a task that is + suspended and the task is not blocked waiting on any resource. + +- A running task issues a ``rtems_message_queue_send``, + ``rtems_message_queue_broadcast``, or a ``rtems_message_queue_urgent`` + directive which posts a message to the queue on which the blocked task is waiting. -- A running task issues an ``rtems_event_send`` - directive which sends an event condition to a task which is blocked - waiting on that event condition. +- A running task issues an ``rtems_event_send`` directive which sends an event + condition to a task which is blocked waiting on that event condition. -- A running task issues a ``rtems_semaphore_release`` - directive which releases the semaphore on which the blocked task is - waiting. - -- A timeout interval expires for a task which was blocked - by a call to the ``rtems_task_wake_after`` directive. - -- A timeout period expires for a task which blocked by a - call to the ``rtems_task_wake_when`` directive. - -- A running task issues a ``rtems_region_return_segment`` - directive which releases a segment to the region on which the blocked task - is waiting and a resulting segment is large enough to satisfy - the task's request. +- A running task issues a ``rtems_semaphore_release`` directive which releases + the semaphore on which the blocked task is waiting. -- A rate monotonic period expires for a task which blocked - by a call to the ``rtems_rate_monotonic_period`` directive. +- A timeout interval expires for a task which was blocked by a call to the + ``rtems_task_wake_after`` directive. -- A timeout interval expires for a task which was blocked - waiting on a message, event, semaphore, or segment with a - timeout specified. +- A timeout period expires for a task which blocked by a call to the + ``rtems_task_wake_when`` directive. -- A running task issues a directive which deletes a - message queue, a semaphore, or a region on which the blocked - task is waiting. +- A running task issues a ``rtems_region_return_segment`` directive which + releases a segment to the region on which the blocked task is waiting and a + resulting segment is large enough to satisfy the task's request. -- A running task issues a ``rtems_task_restart`` - directive for the blocked task. +- A rate monotonic period expires for a task which blocked by a call to the + ``rtems_rate_monotonic_period`` directive. -- The running task, with its preemption mode enabled, may - be made ready by issuing any of the directives that may unblock - a task with a higher priority. This directive may be issued - from the running task itself or from an ISR. - A ready task occupies the executing state when it has - control of the CPU. A task enters the executing state due to - any of the following conditions: +- A timeout interval expires for a task which was blocked waiting on a message, + event, semaphore, or segment with a timeout specified. -- The task is the highest priority ready task in the - system. +- A running task issues a directive which deletes a message queue, a semaphore, + or a region on which the blocked task is waiting. -- The running task blocks and the task is next in the - scheduling queue. The task may be of equal priority as in - round-robin scheduling or the task may possess the highest - priority of the remaining ready tasks. +- A running task issues a ``rtems_task_restart`` directive for the blocked + task. -- The running task may reenable its preemption mode and a - task exists in the ready queue that has a higher priority than - the running task. +- The running task, with its preemption mode enabled, may be made ready by + issuing any of the directives that may unblock a task with a higher priority. + This directive may be issued from the running task itself or from an ISR. A + ready task occupies the executing state when it has control of the CPU. A + task enters the executing state due to any of the following conditions: -- The running task lowers its own priority and another - task is of higher priority as a result. +- The task is the highest priority ready task in the system. -- The running task raises the priority of a task above its - own and the running task is in preemption mode. +- The running task blocks and the task is next in the scheduling queue. The + task may be of equal priority as in round-robin scheduling or the task may + possess the highest priority of the remaining ready tasks. -.. COMMENT: COPYRIGHT (c) 1988-2008. - -.. COMMENT: On-Line Applications Research Corporation (OAR). +- The running task may reenable its preemption mode and a task exists in the + ready queue that has a higher priority than the running task. -.. COMMENT: All rights reserved. +- The running task lowers its own priority and another task is of higher + priority as a result. +- The running task raises the priority of a task above its own and the running + task is in preemption mode. diff --git a/c_user/states.png b/c_user/states.png Binary files differnew file mode 100644 index 0000000..26d8b77 --- /dev/null +++ b/c_user/states.png diff --git a/c_user/task_manager.rst b/c_user/task_manager.rst index 57c47f4..8e2b54c 100644 --- a/c_user/task_manager.rst +++ b/c_user/task_manager.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Task Manager ############ @@ -6,43 +10,42 @@ Task Manager Introduction ============ -The task manager provides a comprehensive set of directives to -create, delete, and administer tasks. The directives provided -by the task manager are: +The task manager provides a comprehensive set of directives to create, delete, +and administer tasks. The directives provided by the task manager are: -- ``rtems_task_create`` - Create a task +- rtems_task_create_ - Create a task -- ``rtems_task_ident`` - Get ID of a task +- rtems_task_ident_ - Get ID of a task -- ``rtems_task_self`` - Obtain ID of caller +- rtems_task_self_ - Obtain ID of caller -- ``rtems_task_start`` - Start a task +- rtems_task_start_ - Start a task -- ``rtems_task_restart`` - Restart a task +- rtems_task_restart_ - Restart a task -- ``rtems_task_delete`` - Delete a task +- rtems_task_delete_ - Delete a task -- ``rtems_task_suspend`` - Suspend a task +- rtems_task_suspend_ - Suspend a task -- ``rtems_task_resume`` - Resume a task +- rtems_task_resume_ - Resume a task -- ``rtems_task_is_suspended`` - Determine if a task is suspended +- rtems_task_is_suspended_ - Determine if a task is suspended -- ``rtems_task_set_priority`` - Set task priority +- rtems_task_set_priority_ - Set task priority -- ``rtems_task_mode`` - Change current task's mode +- rtems_task_mode_ - Change current task's mode -- ``rtems_task_wake_after`` - Wake up after interval +- rtems_task_wake_after_ - Wake up after interval -- ``rtems_task_wake_when`` - Wake up when specified +- rtems_task_wake_when_ - Wake up when specified -- ``rtems_iterate_over_all_threads`` - Iterate Over Tasks +- rtems_iterate_over_all_threads_ - Iterate Over Tasks -- ``rtems_task_variable_add`` - Associate per task variable +- rtems_task_variable_add_ - Associate per task variable -- ``rtems_task_variable_get`` - Obtain value of a a per task variable +- rtems_task_variable_get_ - Obtain value of a a per task variable -- ``rtems_task_variable_delete`` - Remove per task variable +- rtems_task_variable_delete_ - Remove per task variable Background ========== @@ -52,11 +55,10 @@ Task Definition .. index:: task, definition Many definitions of a task have been proposed in computer literature. -Unfortunately, none of these definitions encompasses all facets of the -concept in a manner which is operating system independent. Several of the -more common definitions are provided to enable each user to select a -definition which best matches their own experience and understanding of the -task concept: +Unfortunately, none of these definitions encompasses all facets of the concept +in a manner which is operating system independent. Several of the more common +definitions are provided to enable each user to select a definition which best +matches their own experience and understanding of the task concept: - a "dispatchable" unit. @@ -66,38 +68,33 @@ task concept: - single threads of execution which concurrently compete for resources. -- a sequence of closely related computations which can execute - concurrently with other computational sequences. +- a sequence of closely related computations which can execute concurrently + with other computational sequences. -From RTEMS' perspective, a task is the smallest thread of -execution which can compete on its own for system resources. A -task is manifested by the existence of a task control block -(TCB). +From RTEMS' perspective, a task is the smallest thread of execution which can +compete on its own for system resources. A task is manifested by the existence +of a task control block (TCB). Task Control Block ------------------ -The Task Control Block (TCB) is an RTEMS defined data structure -which contains all the information that is pertinent to the -execution of a task. During system initialization, RTEMS -reserves a TCB for each task configured. A TCB is allocated -upon creation of the task and is returned to the TCB free list -upon deletion of the task. - -The TCB's elements are modified as a result of system calls made -by the application in response to external and internal stimuli. -TCBs are the only RTEMS internal data structure that can be -accessed by an application via user extension routines. The TCB -contains a task's name, ID, current priority, current and -starting states, execution mode, TCB user extension pointer, -scheduling control structures, as well as data required by a -blocked task. - -A task's context is stored in the TCB when a task switch occurs. -When the task regains control of the processor, its context is -restored from the TCB. When a task is restarted, the initial -state of the task is restored from the starting context area in -the task's TCB. +The Task Control Block (TCB) is an RTEMS defined data structure which contains +all the information that is pertinent to the execution of a task. During +system initialization, RTEMS reserves a TCB for each task configured. A TCB is +allocated upon creation of the task and is returned to the TCB free list upon +deletion of the task. + +The TCB's elements are modified as a result of system calls made by the +application in response to external and internal stimuli. TCBs are the only +RTEMS internal data structure that can be accessed by an application via user +extension routines. The TCB contains a task's name, ID, current priority, +current and starting states, execution mode, TCB user extension pointer, +scheduling control structures, as well as data required by a blocked task. + +A task's context is stored in the TCB when a task switch occurs. When the task +regains control of the processor, its context is restored from the TCB. When a +task is restarted, the initial state of the task is restored from the starting +context area in the task's TCB. Task States ----------- @@ -115,15 +112,13 @@ A task may exist in one of the following five states: - *non-existent* - Uncreated or deleted task -An active task may occupy the executing, ready, blocked or -dormant state, otherwise the task is considered non-existent. -One or more tasks may be active in the system simultaneously. -Multiple tasks communicate, synchronize, and compete for system -resources with each other via system calls. The multiple tasks -appear to execute in parallel, but actually each is dispatched -to the CPU for periods of time determined by the RTEMS -scheduling algorithm. The scheduling of a task is based on its -current state and priority. +An active task may occupy the executing, ready, blocked or dormant state, +otherwise the task is considered non-existent. One or more tasks may be active +in the system simultaneously. Multiple tasks communicate, synchronize, and +compete for system resources with each other via system calls. The multiple +tasks appear to execute in parallel, but actually each is dispatched to the CPU +for periods of time determined by the RTEMS scheduling algorithm. The +scheduling of a task is based on its current state and priority. Task Priority ------------- @@ -131,35 +126,30 @@ Task Priority .. index:: priority, task .. index:: rtems_task_priority -A task's priority determines its importance in relation to the -other tasks executing on the same processor. RTEMS supports 255 -levels of priority ranging from 1 to 255. The data type``rtems_task_priority`` is used to store task +A task's priority determines its importance in relation to the other tasks +executing on the same processor. RTEMS supports 255 levels of priority ranging +from 1 to 255. The data type ``rtems_task_priority`` is used to store task priorities. -Tasks of numerically -smaller priority values are more important tasks than tasks of -numerically larger priority values. For example, a task at -priority level 5 is of higher privilege than a task at priority -level 10. There is no limit to the number of tasks assigned to -the same priority. +Tasks of numerically smaller priority values are more important tasks than +tasks of numerically larger priority values. For example, a task at priority +level 5 is of higher privilege than a task at priority level 10. There is no +limit to the number of tasks assigned to the same priority. -Each task has a priority associated with it at all times. The -initial value of this priority is assigned at task creation -time. The priority of a task may be changed at any subsequent -time. +Each task has a priority associated with it at all times. The initial value of +this priority is assigned at task creation time. The priority of a task may be +changed at any subsequent time. -Priorities are used by the scheduler to determine which ready -task will be allowed to execute. In general, the higher the -logical priority of a task, the more likely it is to receive -processor execution time. +Priorities are used by the scheduler to determine which ready task will be +allowed to execute. In general, the higher the logical priority of a task, the +more likely it is to receive processor execution time. Task Mode --------- .. index:: task mode .. index:: rtems_task_mode -A task's execution mode is a combination of the following -four components: +A task's execution mode is a combination of the following four components: - preemption @@ -169,126 +159,142 @@ four components: - interrupt level -It is used to modify RTEMS' scheduling process and to alter the -execution environment of the task. The data type``rtems_task_mode`` is used to manage the task -execution mode... index:: preemption +It is used to modify RTEMS' scheduling process and to alter the execution +environment of the task. The data type ``rtems_task_mode`` is used to manage +the task execution mode. + +.. index:: preemption The preemption component allows a task to determine when control of the -processor is relinquished. If preemption is disabled -(``RTEMS_NO_PREEMPT``), the task will retain control of the -processor as long as it is in the executing state - even if a higher -priority task is made ready. If preemption is enabled -(``RTEMS_PREEMPT``) and a higher priority task is made ready, -then the processor will be taken away from the current task immediately and -given to the higher priority task... index:: timeslicing +processor is relinquished. If preemption is disabled (``RTEMS_NO_PREEMPT``), +the task will retain control of the processor as long as it is in the executing +state - even if a higher priority task is made ready. If preemption is enabled +(``RTEMS_PREEMPT``) and a higher priority task is made ready, then the +processor will be taken away from the current task immediately and given to the +higher priority task. + +.. index:: timeslicing -The timeslicing component is used by the RTEMS scheduler to determine how -the processor is allocated to tasks of equal priority. If timeslicing is -enabled (``RTEMS_TIMESLICE``), then RTEMS will limit the amount -of time the task can execute before the processor is allocated to another -ready task of equal priority. The length of the timeslice is application -dependent and specified in the Configuration Table. If timeslicing is -disabled (``RTEMS_NO_TIMESLICE``), then the task will be -allowed to execute until a task of higher priority is made ready. If``RTEMS_NO_PREEMPT`` is selected, then the timeslicing -component is ignored by the scheduler. +The timeslicing component is used by the RTEMS scheduler to determine how the +processor is allocated to tasks of equal priority. If timeslicing is enabled +(``RTEMS_TIMESLICE``), then RTEMS will limit the amount of time the task can +execute before the processor is allocated to another ready task of equal +priority. The length of the timeslice is application dependent and specified in +the Configuration Table. If timeslicing is disabled (``RTEMS_NO_TIMESLICE``), +then the task will be allowed to execute until a task of higher priority is +made ready. If ``RTEMS_NO_PREEMPT`` is selected, then the timeslicing component +is ignored by the scheduler. -The asynchronous signal processing component is used to determine when -received signals are to be processed by the task. -If signal processing is enabled (``RTEMS_ASR``), then signals -sent to the task will be processed the next time the task executes. If -signal processing is disabled (``RTEMS_NO_ASR``), then all -signals received by the task will remain posted until signal processing is -enabled. This component affects only tasks which have established a -routine to process asynchronous signals... index:: interrupt level, task +The asynchronous signal processing component is used to determine when received +signals are to be processed by the task. If signal processing is enabled +(``RTEMS_ASR``), then signals sent to the task will be processed the next time +the task executes. If signal processing is disabled (``RTEMS_NO_ASR``), then +all signals received by the task will remain posted until signal processing is +enabled. This component affects only tasks which have established a routine to +process asynchronous signals. -The interrupt level component is used to determine which -interrupts will be enabled when the task is executing.``RTEMS_INTERRUPT_LEVEL(n)`` -specifies that the task will execute at interrupt level n. +.. index:: interrupt level, task -- ``RTEMS_PREEMPT`` - enable preemption (default) +The interrupt level component is used to determine which interrupts will be +enabled when the task is executing. ``RTEMS_INTERRUPT_LEVEL(n)`` specifies that +the task will execute at interrupt level n. -- ``RTEMS_NO_PREEMPT`` - disable preemption +``RTEMS_PREEMPT`` + enable preemption (default) -- ``RTEMS_NO_TIMESLICE`` - disable timeslicing (default) +``RTEMS_NO_PREEMPT`` + disable preemption -- ``RTEMS_TIMESLICE`` - enable timeslicing +``RTEMS_NO_TIMESLICE`` + disable timeslicing (default) -- ``RTEMS_ASR`` - enable ASR processing (default) +``RTEMS_TIMESLICE`` + enable timeslicing -- ``RTEMS_NO_ASR`` - disable ASR processing +``RTEMS_ASR`` + enable ASR processing (default) -- ``RTEMS_INTERRUPT_LEVEL(0)`` - enable all interrupts (default) +``RTEMS_NO_ASR`` + disable ASR processing -- ``RTEMS_INTERRUPT_LEVEL(n)`` - execute at interrupt level n +``RTEMS_INTERRUPT_LEVEL(0)`` + enable all interrupts (default) -The set of default modes may be selected by specifying the``RTEMS_DEFAULT_MODES`` constant. +``RTEMS_INTERRUPT_LEVEL(n)`` + execute at interrupt level n + +The set of default modes may be selected by specifying the +``RTEMS_DEFAULT_MODES`` constant. Accessing Task Arguments ------------------------ .. index:: task arguments .. index:: task prototype -All RTEMS tasks are invoked with a single argument which is -specified when they are started or restarted. The argument is -commonly used to communicate startup information to the task. -The simplest manner in which to define a task which accesses it -argument is:.. index:: rtems_task +All RTEMS tasks are invoked with a single argument which is specified when they +are started or restarted. The argument is commonly used to communicate startup +information to the task. The simplest manner in which to define a task which +accesses it argument is: + +.. index:: rtems_task .. code:: c rtems_task user_task( - rtems_task_argument argument + rtems_task_argument argument ); -Application tasks requiring more information may view this -single argument as an index into an array of parameter blocks. +Application tasks requiring more information may view this single argument as +an index into an array of parameter blocks. Floating Point Considerations ----------------------------- .. index:: floating point -Creating a task with the ``RTEMS_FLOATING_POINT`` attribute -flag results -in additional memory being allocated for the TCB to store the state of the -numeric coprocessor during task switches. This additional memory is*NOT* allocated for ``RTEMS_NO_FLOATING_POINT`` tasks. Saving -and restoring the context of a ``RTEMS_FLOATING_POINT`` task -takes longer than that of a ``RTEMS_NO_FLOATING_POINT`` task -because of the relatively large amount of time required for the numeric -coprocessor to save or restore its computational state. - -Since RTEMS was designed specifically for embedded military applications -which are floating point intensive, the executive is optimized to avoid -unnecessarily saving and restoring the state of the numeric coprocessor. -The state of the numeric coprocessor is only saved when a``RTEMS_FLOATING_POINT`` task is dispatched and that task was -not the last task to utilize the coprocessor. In a system with only one``RTEMS_FLOATING_POINT`` task, the state of the numeric +Creating a task with the ``RTEMS_FLOATING_POINT`` attribute flag results in +additional memory being allocated for the TCB to store the state of the numeric +coprocessor during task switches. This additional memory is *NOT* allocated for +``RTEMS_NO_FLOATING_POINT`` tasks. Saving and restoring the context of a +``RTEMS_FLOATING_POINT`` task takes longer than that of a +``RTEMS_NO_FLOATING_POINT`` task because of the relatively large amount of time +required for the numeric coprocessor to save or restore its computational +state. + +Since RTEMS was designed specifically for embedded military applications which +are floating point intensive, the executive is optimized to avoid unnecessarily +saving and restoring the state of the numeric coprocessor. The state of the +numeric coprocessor is only saved when a ``RTEMS_FLOATING_POINT`` task is +dispatched and that task was not the last task to utilize the coprocessor. In +a system with only one ``RTEMS_FLOATING_POINT`` task, the state of the numeric coprocessor will never be saved or restored. -Although the overhead imposed by ``RTEMS_FLOATING_POINT`` tasks -is minimal, some applications may wish to completely avoid the overhead -associated with ``RTEMS_FLOATING_POINT`` tasks and still -utilize a numeric coprocessor. By preventing a task from being preempted -while performing a sequence of floating point operations, a``RTEMS_NO_FLOATING_POINT`` task can utilize the numeric -coprocessor without incurring the overhead of a``RTEMS_FLOATING_POINT`` context switch. This approach also -avoids the allocation of a floating point context area. However, if this -approach is taken by the application designer, NO tasks should be created -as ``RTEMS_FLOATING_POINT`` tasks. Otherwise, the floating -point context will not be correctly maintained because RTEMS assumes that -the state of the numeric coprocessor will not be altered by``RTEMS_NO_FLOATING_POINT`` tasks. - -If the supported processor type does not have hardware floating -capabilities or a standard numeric coprocessor, RTEMS will not provide -built-in support for hardware floating point on that processor. In this -case, all tasks are considered ``RTEMS_NO_FLOATING_POINT`` -whether created as ``RTEMS_FLOATING_POINT`` or``RTEMS_NO_FLOATING_POINT`` tasks. A floating point emulation -software library must be utilized for floating point operations. +Although the overhead imposed by ``RTEMS_FLOATING_POINT`` tasks is minimal, +some applications may wish to completely avoid the overhead associated with +``RTEMS_FLOATING_POINT`` tasks and still utilize a numeric coprocessor. By +preventing a task from being preempted while performing a sequence of floating +point operations, a ``RTEMS_NO_FLOATING_POINT`` task can utilize the numeric +coprocessor without incurring the overhead of a ``RTEMS_FLOATING_POINT`` +context switch. This approach also avoids the allocation of a floating point +context area. However, if this approach is taken by the application designer, +NO tasks should be created as ``RTEMS_FLOATING_POINT`` tasks. Otherwise, the +floating point context will not be correctly maintained because RTEMS assumes +that the state of the numeric coprocessor will not be altered by +``RTEMS_NO_FLOATING_POINT`` tasks. + +If the supported processor type does not have hardware floating capabilities or +a standard numeric coprocessor, RTEMS will not provide built-in support for +hardware floating point on that processor. In this case, all tasks are +considered ``RTEMS_NO_FLOATING_POINT`` whether created as +``RTEMS_FLOATING_POINT`` or``RTEMS_NO_FLOATING_POINT`` tasks. A floating point +emulation software library must be utilized for floating point operations. On some processors, it is possible to disable the floating point unit dynamically. If this capability is supported by the target processor, then -RTEMS will utilize this capability to enable the floating point unit only -for tasks which are created with the ``RTEMS_FLOATING_POINT`` -attribute. The consequence of a ``RTEMS_NO_FLOATING_POINT`` -task attempting to access the floating point unit is CPU dependent but will -generally result in an exception condition. +RTEMS will utilize this capability to enable the floating point unit only for +tasks which are created with the ``RTEMS_FLOATING_POINT`` attribute. The +consequence of a ``RTEMS_NO_FLOATING_POINT`` task attempting to access the +floating point unit is CPU dependent but will generally result in an exception +condition. Per Task Variables ------------------ @@ -296,86 +302,88 @@ Per Task Variables Per task variables are deprecated, see the warning below. -Per task variables are used to support global variables whose value -may be unique to a task. After indicating that a variable should be -treated as private (i.e. per-task) the task can access and modify the -variable, but the modifications will not appear to other tasks, and -other tasks' modifications to that variable will not affect the value -seen by the task. This is accomplished by saving and restoring the -variable's value each time a task switch occurs to or from the calling task. +Per task variables are used to support global variables whose value may be +unique to a task. After indicating that a variable should be treated as private +(i.e. per-task) the task can access and modify the variable, but the +modifications will not appear to other tasks, and other tasks' modifications to +that variable will not affect the value seen by the task. This is accomplished +by saving and restoring the variable's value each time a task switch occurs to +or from the calling task. The value seen by other tasks, including those which have not added the -variable to their set and are thus accessing the variable as a common -location shared among tasks, cannot be affected by a task once it has -added a variable to its local set. Changes made to the variable by -other tasks will not affect the value seen by a task which has added the -variable to its private set. - -This feature can be used when a routine is to be spawned repeatedly as -several independent tasks. Although each task will have its own stack, -and thus separate stack variables, they will all share the same static and -global variables. To make a variable not shareable (i.e. a "global" variable -that is specific to a single task), the tasks can call``rtems_task_variable_add`` to make a separate copy of the variable -for each task, but all at the same physical address. - -Task variables increase the context switch time to and from the -tasks that own them so it is desirable to minimize the number of -task variables. One efficient method is to have a single task -variable that is a pointer to a dynamically allocated structure -containing the task's private "global" data. +variable to their set and are thus accessing the variable as a common location +shared among tasks, cannot be affected by a task once it has added a variable +to its local set. Changes made to the variable by other tasks will not affect +the value seen by a task which has added the variable to its private set. + +This feature can be used when a routine is to be spawned repeatedly as several +independent tasks. Although each task will have its own stack, and thus +separate stack variables, they will all share the same static and global +variables. To make a variable not shareable (i.e. a "global" variable that is +specific to a single task), the tasks can call ``rtems_task_variable_add`` to +make a separate copy of the variable for each task, but all at the same +physical address. + +Task variables increase the context switch time to and from the tasks that own +them so it is desirable to minimize the number of task variables. One +efficient method is to have a single task variable that is a pointer to a +dynamically allocated structure containing the task's private "global" data. A critical point with per-task variables is that each task must separately request that the same global variable is per-task private. -*WARNING*: Per-Task variables are inherently broken on SMP systems. They -only work correctly when there is one task executing in the system and -that task is the logical owner of the value in the per-task variable's -location. There is no way for a single memory image to contain the -correct value for each task executing on each core. Consequently, -per-task variables are disabled in SMP configurations of RTEMS. -Instead the application developer should -consider the use of POSIX Keys or Thread Local Storage (TLS). POSIX Keys -are not enabled in all RTEMS configurations. +.. warning: + + Per-Task variables are inherently broken on SMP systems. They only work + correctly when there is one task executing in the system and that task is the + logical owner of the value in the per-task variable's location. There is no + way for a single memory image to contain the correct value for each task + executing on each core. Consequently, per-task variables are disabled in SMP + configurations of RTEMS. Instead the application developer should consider + the use of POSIX Keys or Thread Local Storage (TLS). POSIX Keys are not + enabled in all RTEMS configurations. Building a Task Attribute Set ----------------------------- .. index:: task attributes, building -In general, an attribute set is built by a bitwise OR of the -desired components. The set of valid task attribute components -is listed below: +In general, an attribute set is built by a bitwise OR of the desired +components. The set of valid task attribute components is listed below: -- ``RTEMS_NO_FLOATING_POINT`` - does not use coprocessor (default) +``RTEMS_NO_FLOATING_POINT`` + does not use coprocessor (default) -- ``RTEMS_FLOATING_POINT`` - uses numeric coprocessor +``RTEMS_FLOATING_POINT`` + uses numeric coprocessor -- ``RTEMS_LOCAL`` - local task (default) +``RTEMS_LOCAL`` + local task (default) -- ``RTEMS_GLOBAL`` - global task +``RTEMS_GLOBAL`` + global task -Attribute values are specifically designed to be mutually -exclusive, therefore bitwise OR and addition operations are -equivalent as long as each attribute appears exactly once in the -component list. A component listed as a default is not required -to appear in the component list, although it is a good -programming practice to specify default components. If all -defaults are desired, then ``RTEMS_DEFAULT_ATTRIBUTES`` should be used. +Attribute values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each attribute +appears exactly once in the component list. A component listed as a default is +not required to appear in the component list, although it is a good programming +practice to specify default components. If all defaults are desired, then +``RTEMS_DEFAULT_ATTRIBUTES`` should be used. -This example demonstrates the attribute_set parameter needed to -create a local task which utilizes the numeric coprocessor. The -attribute_set parameter could be ``RTEMS_FLOATING_POINT`` or``RTEMS_LOCAL | RTEMS_FLOATING_POINT``. -The attribute_set parameter can be set to``RTEMS_FLOATING_POINT`` because ``RTEMS_LOCAL`` is the default for all created -tasks. If the task were global and used the numeric -coprocessor, then the attribute_set parameter would be``RTEMS_GLOBAL | RTEMS_FLOATING_POINT``. +This example demonstrates the attribute_set parameter needed to create a local +task which utilizes the numeric coprocessor. The attribute_set parameter could +be ``RTEMS_FLOATING_POINT`` or``RTEMS_LOCAL | RTEMS_FLOATING_POINT``. The +attribute_set parameter can be set to``RTEMS_FLOATING_POINT`` because +``RTEMS_LOCAL`` is the default for all created tasks. If the task were global +and used the numeric coprocessor, then the attribute_set parameter would be +``RTEMS_GLOBAL | RTEMS_FLOATING_POINT``. Building a Mode and Mask ------------------------ .. index:: task mode, building -In general, a mode and its corresponding mask is built by a -bitwise OR of the desired components. The set of valid mode -constants and each mode's corresponding mask constant is -listed below: +In general, a mode and its corresponding mask is built by a bitwise OR of the +desired components. The set of valid mode constants and each mode's +corresponding mask constant is listed below: - ``RTEMS_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and enables preemption @@ -394,21 +402,20 @@ listed below: - ``RTEMS_INTERRUPT_LEVEL(n)`` is masked by``RTEMS_INTERRUPT_MASK`` and sets interrupts level n Mode values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each mode -appears exactly once in the component list. A mode component listed as a -default is not required to appear in the mode component list, although it -is a good programming practice to specify default components. If all -defaults are desired, the mode ``RTEMS_DEFAULT_MODES`` and the -mask ``RTEMS_ALL_MODE_MASKS`` should be used. - -The following example demonstrates the mode and mask parameters used with -the ``rtems_task_mode`` -directive to place a task at interrupt level 3 and make it -non-preemptible. The mode should be set to``RTEMS_INTERRUPT_LEVEL(3) | -RTEMS_NO_PREEMPT`` to indicate the desired preemption mode and -interrupt level, while the mask parameter should be set to``RTEMS_INTERRUPT_MASK | -RTEMS_NO_PREEMPT_MASK`` to indicate that the calling task's -interrupt level and preemption mode are being altered. +bitwise OR and addition operations are equivalent as long as each mode appears +exactly once in the component list. A mode component listed as a default is +not required to appear in the mode component list, although it is a good +programming practice to specify default components. If all defaults are +desired, the mode ``RTEMS_DEFAULT_MODES`` and the mask ``RTEMS_ALL_MODE_MASKS`` +should be used. + +The following example demonstrates the mode and mask parameters used with the +``rtems_task_mode`` directive to place a task at interrupt level 3 and make it +non-preemptible. The mode should be set to``RTEMS_INTERRUPT_LEVEL(3) | +RTEMS_NO_PREEMPT`` to indicate the desired preemption mode and interrupt level, +while the mask parameter should be set to ``RTEMS_INTERRUPT_MASK | +RTEMS_NO_PREEMPT_MASK`` to indicate that the calling task's interrupt level and +preemption mode are being altered. Operations ========== @@ -416,183 +423,155 @@ Operations Creating Tasks -------------- -The ``rtems_task_create`` -directive creates a task by allocating a task -control block, assigning the task a user-specified name, -allocating it a stack and floating point context area, setting a -user-specified initial priority, setting a user-specified -initial mode, and assigning it a task ID. Newly created tasks -are initially placed in the dormant state. All RTEMS tasks -execute in the most privileged mode of the processor. +The ``rtems_task_create`` directive creates a task by allocating a task control +block, assigning the task a user-specified name, allocating it a stack and +floating point context area, setting a user-specified initial priority, setting +a user-specified initial mode, and assigning it a task ID. Newly created tasks +are initially placed in the dormant state. All RTEMS tasks execute in the most +privileged mode of the processor. Obtaining Task IDs ------------------ -When a task is created, RTEMS generates a unique task ID and -assigns it to the created task until it is deleted. The task ID -may be obtained by either of two methods. First, as the result -of an invocation of the ``rtems_task_create`` -directive, the task ID is -stored in a user provided location. Second, the task ID may be -obtained later using the ``rtems_task_ident`` -directive. The task ID is -used by other directives to manipulate this task. +When a task is created, RTEMS generates a unique task ID and assigns it to the +created task until it is deleted. The task ID may be obtained by either of two +methods. First, as the result of an invocation of the ``rtems_task_create`` +directive, the task ID is stored in a user provided location. Second, the task +ID may be obtained later using the ``rtems_task_ident`` directive. The task ID +is used by other directives to manipulate this task. Starting and Restarting Tasks ----------------------------- -The ``rtems_task_start`` -directive is used to place a dormant task in the -ready state. This enables the task to compete, based on its -current priority, for the processor and other system resources. -Any actions, such as suspension or change of priority, performed -on a task prior to starting it are nullified when the task is -started. - -With the ``rtems_task_start`` -directive the user specifies the task's -starting address and argument. The argument is used to -communicate some startup information to the task. As part of -this directive, RTEMS initializes the task's stack based upon -the task's initial execution mode and start address. The -starting argument is passed to the task in accordance with the -target processor's calling convention. - -The ``rtems_task_restart`` -directive restarts a task at its initial -starting address with its original priority and execution mode, -but with a possibly different argument. The new argument may be -used to distinguish between the original invocation of the task -and subsequent invocations. The task's stack and control block -are modified to reflect their original creation values. -Although references to resources that have been requested are -cleared, resources allocated by the task are NOT automatically -returned to RTEMS. A task cannot be restarted unless it has -previously been started (i.e. dormant tasks cannot be -restarted). All restarted tasks are placed in the ready state. +The ``rtems_task_start`` directive is used to place a dormant task in the ready +state. This enables the task to compete, based on its current priority, for +the processor and other system resources. Any actions, such as suspension or +change of priority, performed on a task prior to starting it are nullified when +the task is started. + +With the ``rtems_task_start`` directive the user specifies the task's starting +address and argument. The argument is used to communicate some startup +information to the task. As part of this directive, RTEMS initializes the +task's stack based upon the task's initial execution mode and start address. +The starting argument is passed to the task in accordance with the target +processor's calling convention. + +The ``rtems_task_restart`` directive restarts a task at its initial starting +address with its original priority and execution mode, but with a possibly +different argument. The new argument may be used to distinguish between the +original invocation of the task and subsequent invocations. The task's stack +and control block are modified to reflect their original creation values. +Although references to resources that have been requested are cleared, +resources allocated by the task are NOT automatically returned to RTEMS. A +task cannot be restarted unless it has previously been started (i.e. dormant +tasks cannot be restarted). All restarted tasks are placed in the ready state. Suspending and Resuming Tasks ----------------------------- -The ``rtems_task_suspend`` -directive is used to place either the caller or -another task into a suspended state. The task remains suspended -until a ``rtems_task_resume`` -directive is issued. This implies that a -task may be suspended as well as blocked waiting either to -acquire a resource or for the expiration of a timer. - -The ``rtems_task_resume`` -directive is used to remove another task from -the suspended state. If the task is not also blocked, resuming -it will place it in the ready state, allowing it to once again -compete for the processor and resources. If the task was -blocked as well as suspended, this directive clears the -suspension and leaves the task in the blocked state. - -Suspending a task which is already suspended or resuming a -task which is not suspended is considered an error. -The ``rtems_task_is_suspended`` can be used to -determine if a task is currently suspended. +The ``rtems_task_suspend`` directive is used to place either the caller or +another task into a suspended state. The task remains suspended until a +``rtems_task_resume`` directive is issued. This implies that a task may be +suspended as well as blocked waiting either to acquire a resource or for the +expiration of a timer. + +The ``rtems_task_resume`` directive is used to remove another task from the +suspended state. If the task is not also blocked, resuming it will place it in +the ready state, allowing it to once again compete for the processor and +resources. If the task was blocked as well as suspended, this directive clears +the suspension and leaves the task in the blocked state. + +Suspending a task which is already suspended or resuming a task which is not +suspended is considered an error. The ``rtems_task_is_suspended`` can be used +to determine if a task is currently suspended. Delaying the Currently Executing Task ------------------------------------- -The ``rtems_task_wake_after`` directive creates a sleep timer -which allows a task to go to sleep for a specified interval. The task is -blocked until the delay interval has elapsed, at which time the task is -unblocked. A task calling the ``rtems_task_wake_after`` -directive with a delay -interval of ``RTEMS_YIELD_PROCESSOR`` ticks will yield the -processor to any other ready task of equal or greater priority and remain -ready to execute. +The ``rtems_task_wake_after`` directive creates a sleep timer which allows a +task to go to sleep for a specified interval. The task is blocked until the +delay interval has elapsed, at which time the task is unblocked. A task +calling the ``rtems_task_wake_after`` directive with a delay interval of +``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready +task of equal or greater priority and remain ready to execute. -The ``rtems_task_wake_when`` -directive creates a sleep timer which allows -a task to go to sleep until a specified date and time. The -calling task is blocked until the specified date and time has -occurred, at which time the task is unblocked. +The ``rtems_task_wake_when`` directive creates a sleep timer which allows a +task to go to sleep until a specified date and time. The calling task is +blocked until the specified date and time has occurred, at which time the task +is unblocked. Changing Task Priority ---------------------- -The ``rtems_task_set_priority`` -directive is used to obtain or change the -current priority of either the calling task or another task. If -the new priority requested is``RTEMS_CURRENT_PRIORITY`` or the task's -actual priority, then the current priority will be returned and -the task's priority will remain unchanged. If the task's -priority is altered, then the task will be scheduled according -to its new priority. - -The ``rtems_task_restart`` -directive resets the priority of a task to its +The ``rtems_task_set_priority`` directive is used to obtain or change the +current priority of either the calling task or another task. If the new +priority requested is``RTEMS_CURRENT_PRIORITY`` or the task's actual priority, +then the current priority will be returned and the task's priority will remain +unchanged. If the task's priority is altered, then the task will be scheduled +according to its new priority. + +The ``rtems_task_restart`` directive resets the priority of a task to its original value. Changing Task Mode ------------------ -The ``rtems_task_mode`` -directive is used to obtain or change the current -execution mode of the calling task. A task's execution mode is -used to enable preemption, timeslicing, ASR processing, and to -set the task's interrupt level. +The ``rtems_task_mode`` directive is used to obtain or change the current +execution mode of the calling task. A task's execution mode is used to enable +preemption, timeslicing, ASR processing, and to set the task's interrupt level. -The ``rtems_task_restart`` -directive resets the mode of a task to its -original value. +The ``rtems_task_restart`` directive resets the mode of a task to its original +value. Task Deletion ------------- -RTEMS provides the ``rtems_task_delete`` -directive to allow a task to -delete itself or any other task. This directive removes all -RTEMS references to the task, frees the task's control block, -removes it from resource wait queues, and deallocates its stack -as well as the optional floating point context. The task's name -and ID become inactive at this time, and any subsequent -references to either of them is invalid. In fact, RTEMS may -reuse the task ID for another task which is created later in the -application. - -Unexpired delay timers (i.e. those used by``rtems_task_wake_after`` and``rtems_task_wake_when``) and -timeout timers associated with the task are -automatically deleted, however, other resources dynamically -allocated by the task are NOT automatically returned to RTEMS. -Therefore, before a task is deleted, all of its dynamically -allocated resources should be deallocated by the user. This may -be accomplished by instructing the task to delete itself rather -than directly deleting the task. Other tasks may instruct a -task to delete itself by sending a "delete self" message, event, -or signal, or by restarting the task with special arguments -which instruct the task to delete itself. +RTEMS provides the ``rtems_task_delete`` directive to allow a task to delete +itself or any other task. This directive removes all RTEMS references to the +task, frees the task's control block, removes it from resource wait queues, and +deallocates its stack as well as the optional floating point context. The +task's name and ID become inactive at this time, and any subsequent references +to either of them is invalid. In fact, RTEMS may reuse the task ID for another +task which is created later in the application. + +Unexpired delay timers (i.e. those used by``rtems_task_wake_after`` +and``rtems_task_wake_when``) and timeout timers associated with the task are +automatically deleted, however, other resources dynamically allocated by the +task are NOT automatically returned to RTEMS. Therefore, before a task is +deleted, all of its dynamically allocated resources should be deallocated by +the user. This may be accomplished by instructing the task to delete itself +rather than directly deleting the task. Other tasks may instruct a task to +delete itself by sending a "delete self" message, event, or signal, or by +restarting the task with special arguments which instruct the task to delete +itself. Transition Advice for Obsolete Directives ----------------------------------------- Notepads -~~~~~~~~.. index:: rtems_task_get_note +~~~~~~~~ +.. index:: rtems_task_get_note .. index:: rtems_task_set_note -Task notepads and the associated directives``rtems_task_get_note`` and``rtems_task_set_note`` were removed after the 4.11 Release -Series. These were never thread-safe to access and subject to conflicting -use of the notepad index by libraries which were designed independently. +Task notepads and the associated directives ``rtems_task_get_note`` and +``rtems_task_set_note`` were removed after the 4.11 Release Series. These were +never thread-safe to access and subject to conflicting use of the notepad index +by libraries which were designed independently. -It is recommended that applications be modified to use services -which are thread safe and not subject to issues with multiple applications -conflicting over the key (e.g. notepad index) selection. For most -applications, POSIX Keys should be used. These are available in all RTEMS -build configurations. It is also possible that Thread Local Storage is -an option for some use cases. +It is recommended that applications be modified to use services which are +thread safe and not subject to issues with multiple applications conflicting +over the key (e.g. notepad index) selection. For most applications, POSIX Keys +should be used. These are available in all RTEMS build configurations. It is +also possible that Thread Local Storage is an option for some use cases. Directives ========== -This section details the task 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. +This section details the task 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. + +.. _rtems_task_create: TASK_CREATE - Create a task --------------------------- @@ -605,40 +584,53 @@ TASK_CREATE - Create a task .. code:: c rtems_status_code rtems_task_create( - rtems_name name, - rtems_task_priority initial_priority, - size_t stack_size, - rtems_mode initial_modes, - rtems_attribute attribute_set, - rtems_id \*id + rtems_name name, + rtems_task_priority initial_priority, + size_t stack_size, + rtems_mode initial_modes, + rtems_attribute attribute_set, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - task created successfully -``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL -``RTEMS_INVALID_NAME`` - invalid task name -``RTEMS_INVALID_PRIORITY`` - invalid task priority -``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured -``RTEMS_TOO_MANY`` - too many tasks created -``RTEMS_UNSATISFIED`` - not enough memory for stack/FP context -``RTEMS_TOO_MANY`` - too many global objects +``RTEMS_SUCCESSFUL`` + task created successfully + +``RTEMS_INVALID_ADDRESS`` + ``id`` is NULL + +``RTEMS_INVALID_NAME`` + invalid task name + +``RTEMS_INVALID_PRIORITY`` + invalid task priority + +``RTEMS_MP_NOT_CONFIGURED`` + multiprocessing not configured + +``RTEMS_TOO_MANY`` + too many tasks created + +``RTEMS_UNSATISFIED`` + not enough memory for stack/FP context + +``RTEMS_TOO_MANY`` + too many global objects + **DESCRIPTION:** -This directive creates a task which resides on the local node. -It allocates and initializes a TCB, a stack, and an optional -floating point context area. The mode parameter contains values -which sets the task's initial execution mode. The``RTEMS_FLOATING_POINT`` attribute should be -specified if the created task -is to use a numeric coprocessor. For performance reasons, it is -recommended that tasks not using the numeric coprocessor should -specify the ``RTEMS_NO_FLOATING_POINT`` attribute. -If the ``RTEMS_GLOBAL`` -attribute is specified, the task can be accessed from remote -nodes. The task id, returned in id, is used in other task -related directives to access the task. When created, a task is -placed in the dormant state and can only be made ready to +This directive creates a task which resides on the local node. It allocates +and initializes a TCB, a stack, and an optional floating point context area. +The mode parameter contains values which sets the task's initial execution +mode. The ``RTEMS_FLOATING_POINT`` attribute should be specified if the +created task is to use a numeric coprocessor. For performance reasons, it is +recommended that tasks not using the numeric coprocessor should specify the +``RTEMS_NO_FLOATING_POINT`` attribute. If the ``RTEMS_GLOBAL`` attribute is +specified, the task can be accessed from remote nodes. The task id, returned +in id, is used in other task related directives to access the task. When +created, a task is placed in the dormant state and can only be made ready to execute using the directive ``rtems_task_start``. **NOTES:** @@ -647,78 +639,86 @@ This directive will not cause the calling task to be preempted. Valid task priorities range from a high of 1 to a low of 255. -If the requested stack size is less than the configured -minimum stack size, then RTEMS will use the configured -minimum as the stack size for this task. In addition -to being able to specify the task stack size as a integer, -there are two constants which may be specified: - -- ``RTEMS_MINIMUM_STACK_SIZE`` - is the minimum stack size *RECOMMENDED* for use on this processor. - This value is selected by the RTEMS developers conservatively to - minimize the risk of blown stacks for most user applications. - Using this constant when specifying the task stack size, indicates - that the stack size will be at least``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the - user configured minimum stack size is larger than the recommended - minimum, then it will be used. - -- ``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE`` - indicates that this task is to be created with a stack size - of the minimum stack size that was configured by the application. - If not explicitly configured by the application, the default - configured minimum stack size is the processor dependent value``RTEMS_MINIMUM_STACK_SIZE``. Since this uses - the configured minimum stack size value, you may get a stack - size that is smaller or larger than the recommended minimum. This - can be used to provide large stacks for all tasks on complex - applications or small stacks on applications that are trying - to conserve memory. - -Application developers should consider the stack usage of the -device drivers when calculating the stack size required for -tasks which utilize the driver. +If the requested stack size is less than the configured minimum stack size, +then RTEMS will use the configured minimum as the stack size for this task. In +addition to being able to specify the task stack size as a integer, there are +two constants which may be specified: + +``RTEMS_MINIMUM_STACK_SIZE`` + The minimum stack size *RECOMMENDED* for use on this processor. This value + is selected by the RTEMS developers conservatively to minimize the risk of + blown stacks for most user applications. Using this constant when specifying + the task stack size, indicates that the stack size will be at least + ``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the user configured minimum + stack size is larger than the recommended minimum, then it will be used. + +``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE`` + Indicates this task is to be created with a stack size of the minimum stack + size that was configured by the application. If not explicitly configured by + the application, the default configured minimum stack size is the processor + dependent value ``RTEMS_MINIMUM_STACK_SIZE``. Since this uses the configured + minimum stack size value, you may get a stack size that is smaller or larger + than the recommended minimum. This can be used to provide large stacks for + all tasks on complex applications or small stacks on applications that are + trying to conserve memory. + +Application developers should consider the stack usage of the device drivers +when calculating the stack size required for tasks which utilize the driver. The following task attribute constants are defined by RTEMS: -- ``RTEMS_NO_FLOATING_POINT`` - does not use coprocessor (default) +``RTEMS_NO_FLOATING_POINT`` + does not use coprocessor (default) -- ``RTEMS_FLOATING_POINT`` - uses numeric coprocessor +``RTEMS_FLOATING_POINT`` + uses numeric coprocessor -- ``RTEMS_LOCAL`` - local task (default) +``RTEMS_LOCAL`` + local task (default) -- ``RTEMS_GLOBAL`` - global task +``RTEMS_GLOBAL`` + global task The following task mode constants are defined by RTEMS: -- ``RTEMS_PREEMPT`` - enable preemption (default) +``RTEMS_PREEMPT`` + enable preemption (default) -- ``RTEMS_NO_PREEMPT`` - disable preemption +``RTEMS_NO_PREEMPT`` + disable preemption -- ``RTEMS_NO_TIMESLICE`` - disable timeslicing (default) +``RTEMS_NO_TIMESLICE`` + disable timeslicing (default) -- ``RTEMS_TIMESLICE`` - enable timeslicing +``RTEMS_TIMESLICE`` + enable timeslicing -- ``RTEMS_ASR`` - enable ASR processing (default) +``RTEMS_ASR`` + enable ASR processing (default) -- ``RTEMS_NO_ASR`` - disable ASR processing +``RTEMS_NO_ASR`` + disable ASR processing -- ``RTEMS_INTERRUPT_LEVEL(0)`` - enable all interrupts (default) +``RTEMS_INTERRUPT_LEVEL(0)`` + enable all interrupts (default) -- ``RTEMS_INTERRUPT_LEVEL(n)`` - execute at interrupt level n +``RTEMS_INTERRUPT_LEVEL(n)`` + execute at interrupt level n -The interrupt level portion of the task execution mode -supports a maximum of 256 interrupt levels. These levels are -mapped onto the interrupt levels actually supported by the -target processor in a processor dependent fashion. +The interrupt level portion of the task execution mode supports a maximum of +256 interrupt levels. These levels are mapped onto the interrupt levels +actually supported by the target processor in a processor dependent fashion. -Tasks should not be made global unless remote tasks must -interact with them. This avoids the system overhead incurred by -the creation of a global task. When a global task is created, -the task's name and id must be transmitted to every node in the -system for insertion in the local copy of the global object +Tasks should not be made global unless remote tasks must interact with them. +This avoids the system overhead incurred by the creation of a global task. +When a global task is created, the task's name and id must be transmitted to +every node in the system for insertion in the local copy of the global object table. -The total number of global objects, including tasks, is limited -by the maximum_global_objects field in the Configuration Table. +The total number of global objects, including tasks, is limited by the +maximum_global_objects field in the Configuration Table. + +.. _rtems_task_ident: TASK_IDENT - Get ID of a task ----------------------------- @@ -731,41 +731,50 @@ TASK_IDENT - Get ID of a task .. code:: c rtems_status_code rtems_task_ident( - rtems_name name, - uint32_t node, - rtems_id \*id + rtems_name name, + uint32_t node, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - task identified successfully -``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL -``RTEMS_INVALID_NAME`` - invalid task name -``RTEMS_INVALID_NODE`` - invalid node id +``RTEMS_SUCCESSFUL`` + task identified successfully + +``RTEMS_INVALID_ADDRESS`` + ``id`` is NULL + +``RTEMS_INVALID_NAME`` + invalid task name + +``RTEMS_INVALID_NODE`` + invalid node id + **DESCRIPTION:** -This directive obtains the task id associated with the task name -specified in name. A task may obtain its own id by specifying``RTEMS_SELF`` or its own task name in name. If the task name is not -unique, then the task id returned will match one of the tasks -with that name. However, this task id is not guaranteed to -correspond to the desired task. The task id, returned in id, is +This directive obtains the task id associated with the task name specified in +name. A task may obtain its own id by specifying ``RTEMS_SELF`` or its own +task name in name. If the task name is not unique, then the task id returned +will match one of the tasks with that name. However, this task id is not +guaranteed to correspond to the desired task. The task id, returned in id, is used in other task related directives to access the task. **NOTES:** This directive will not cause the running task to be preempted. -If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the -local node being searched first. All other nodes are searched -with the lowest numbered node searched first. +If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the local +node being searched first. All other nodes are searched with the lowest +numbered node searched first. -If node is a valid node number which does not represent the -local node, then only the tasks exported by the designated node -are searched. +If node is a valid node number which does not represent the local node, then +only the tasks exported by the designated node are searched. -This directive does not generate activity on remote nodes. It -accesses only the local copy of the global object table. +This directive does not generate activity on remote nodes. It accesses only +the local copy of the global object table. + +.. _rtems_task_self: TASK_SELF - Obtain ID of caller ------------------------------- @@ -789,8 +798,10 @@ This directive returns the Id of the calling task. **NOTES:** -If called from an interrupt service routine, this directive -will return the Id of the interrupted task. +If called from an interrupt service routine, this directive will return the Id +of the interrupted task. + +.. _rtems_task_start: TASK_START - Start a task ------------------------- @@ -803,38 +814,49 @@ TASK_START - Start a task .. code:: c rtems_status_code rtems_task_start( - rtems_id id, - rtems_task_entry entry_point, - rtems_task_argument argument + rtems_id id, + rtems_task_entry entry_point, + rtems_task_argument argument ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - ask started successfully -``RTEMS_INVALID_ADDRESS`` - invalid task entry point -``RTEMS_INVALID_ID`` - invalid task id -``RTEMS_INCORRECT_STATE`` - task not in the dormant state -``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot start remote task +``RTEMS_SUCCESSFUL`` + ask started successfully + +``RTEMS_INVALID_ADDRESS`` + invalid task entry point + +``RTEMS_INVALID_ID`` + invalid task id + +``RTEMS_INCORRECT_STATE`` + task not in the dormant state + +``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + cannot start remote task **DESCRIPTION:** -This directive readies the task, specified by ``id``, for execution -based on the priority and execution mode specified when the task -was created. The starting address of the task is given in``entry_point``. The task's starting argument is contained in -argument. This argument can be a single value or used as an index into an -array of parameter blocks. The type of this numeric argument is an unsigned -integer type with 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. +This directive readies the task, specified by ``id``, for execution based on +the priority and execution mode specified when the task was created. The +starting address of the task is given in ``entry_point``. The task's starting +argument is contained in argument. This argument can be a single value or used +as an index into an array of parameter blocks. The type of this numeric +argument is an unsigned integer type with 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. **NOTES:** -The calling task will be preempted if its preemption mode is -enabled and the task being started has a higher priority. +The calling task will be preempted if its preemption mode is enabled and the +task being started has a higher priority. -Any actions performed on a dormant task such as suspension or -change of priority are nullified when the task is initiated via -the ``rtems_task_start`` directive. +Any actions performed on a dormant task such as suspension or change of +priority are nullified when the task is initiated via the ``rtems_task_start`` +directive. + +.. _rtems_task_restart: TASK_RESTART - Restart a task ----------------------------- @@ -847,52 +869,56 @@ TASK_RESTART - Restart a task .. code:: c rtems_status_code rtems_task_restart( - rtems_id id, - rtems_task_argument argument + rtems_id id, + rtems_task_argument argument ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - task restarted successfully -``RTEMS_INVALID_ID`` - task id invalid -``RTEMS_INCORRECT_STATE`` - task never started -``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot restart remote task +``RTEMS_SUCCESSFUL`` + task restarted successfully + +``RTEMS_INVALID_ID`` + task id invalid + +``RTEMS_INCORRECT_STATE`` + task never started + +``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + cannot restart remote task **DESCRIPTION:** -This directive resets the task specified by id to begin -execution at its original starting address. 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. +This directive resets the task specified by id to begin execution at its +original starting address. 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 starting argument is contained in argument. This argument can be a single value or an index into an array of parameter blocks. The type of this numeric argument is an unsigned integer type with 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. This -new argument may be used to distinguish -between the initial ``rtems_task_start`` -of the task and any ensuing calls -to ``rtems_task_restart`` -of the task. This can be beneficial in deleting -a task. Instead of deleting a task using -the ``rtems_task_delete`` -directive, a task can delete another task by restarting that -task, and allowing that task to release resources back to RTEMS -and then delete itself. +new argument may be used to distinguish between the initial +``rtems_task_start`` of the task and any ensuing calls to +``rtems_task_restart`` of the task. This can be beneficial in deleting a task. +Instead of deleting a task using the ``rtems_task_delete`` directive, a task +can delete another task by restarting that task, and allowing that task to +release resources back to RTEMS and then delete itself. **NOTES:** -If id is ``RTEMS_SELF``, the calling task will be restarted and will not -return from this directive. +If id is ``RTEMS_SELF``, the calling task will be restarted and will not return +from this directive. -The calling task will be preempted if its preemption mode is -enabled and the task being restarted has a higher priority. +The calling task will be preempted if its preemption mode is enabled and the +task being restarted has a higher priority. -The task must reside on the local node, even if the task was -created with the ``RTEMS_GLOBAL`` option. +The task must reside on the local node, even if the task was created with the +``RTEMS_GLOBAL`` option. + +.. _rtems_task_delete: TASK_DELETE - Delete a task --------------------------- @@ -905,45 +931,49 @@ TASK_DELETE - Delete a task .. code:: c rtems_status_code rtems_task_delete( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - task deleted successfully -``RTEMS_INVALID_ID`` - task id invalid -``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot restart remote task +``RTEMS_SUCCESSFUL`` + task deleted successfully + +``RTEMS_INVALID_ID`` + task id invalid + +``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + cannot restart remote task **DESCRIPTION:** -This directive deletes a task, either the calling task or -another task, as specified by id. RTEMS stops the execution of -the task and reclaims the stack memory, any allocated delay or -timeout timers, the TCB, and, if the task is ``RTEMS_FLOATING_POINT``, its -floating point context area. RTEMS does not reclaim the -following resources: region segments, partition buffers, +This directive deletes a task, either the calling task or another task, as +specified by id. RTEMS stops the execution of the task and reclaims the stack +memory, any allocated delay or timeout timers, the TCB, and, if the task is +``RTEMS_FLOATING_POINT``, its floating point context area. RTEMS does not +reclaim the following resources: region segments, partition buffers, semaphores, timers, or rate monotonic periods. **NOTES:** -A task is responsible for releasing its resources back to RTEMS -before deletion. To insure proper deallocation of resources, a -task should not be deleted unless it is unable to execute or -does not hold any RTEMS resources. If a task holds RTEMS -resources, the task should be allowed to deallocate its -resources before deletion. A task can be directed to release -its resources and delete itself by restarting it with a special -argument or by sending it a message, an event, or a signal. +A task is responsible for releasing its resources back to RTEMS before +deletion. To insure proper deallocation of resources, a task should not be +deleted unless it is unable to execute or does not hold any RTEMS resources. +If a task holds RTEMS resources, the task should be allowed to deallocate its +resources before deletion. A task can be directed to release its resources and +delete itself by restarting it with a special argument or by sending it a +message, an event, or a signal. Deletion of the current task (``RTEMS_SELF``) will force RTEMS to select another task to execute. -When a global task is deleted, the task id must be transmitted -to every node in the system for deletion from the local copy of -the global object table. +When a global task is deleted, the task id must be transmitted to every node in +the system for deletion from the local copy of the global object table. -The task must reside on the local node, even if the task was -created with the ``RTEMS_GLOBAL`` option. +The task must reside on the local node, even if the task was created with the +``RTEMS_GLOBAL`` option. + +.. _rtems_task_suspend: TASK_SUSPEND - Suspend a task ----------------------------- @@ -956,36 +986,41 @@ TASK_SUSPEND - Suspend a task .. code:: c rtems_status_code rtems_task_suspend( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - task suspended successfully -``RTEMS_INVALID_ID`` - task id invalid -``RTEMS_ALREADY_SUSPENDED`` - task already suspended +``RTEMS_SUCCESSFUL`` + task suspended successfully + +``RTEMS_INVALID_ID`` + task id invalid + +``RTEMS_ALREADY_SUSPENDED`` + task already suspended **DESCRIPTION:** -This directive suspends the task specified by id from further -execution by placing it in the suspended state. This state is -additive to any other blocked state that the task may already be -in. The task will not execute again until another task issues -the ``rtems_task_resume`` -directive for this task and any blocked state -has been removed. +This directive suspends the task specified by id from further execution by +placing it in the suspended state. This state is additive to any other blocked +state that the task may already be in. The task will not execute again until +another task issues the ``rtems_task_resume`` directive for this task and any +blocked state has been removed. **NOTES:** -The requesting task can suspend itself by specifying ``RTEMS_SELF`` as id. -In this case, the task will be suspended and a successful -return code will be returned when the task is resumed. +The requesting task can suspend itself by specifying ``RTEMS_SELF`` as id. In +this case, the task will be suspended and a successful return code will be +returned when the task is resumed. -Suspending a global task which does not reside on the local node -will generate a request to the remote node to suspend the -specified task. +Suspending a global task which does not reside on the local node will generate +a request to the remote node to suspend the specified task. -If the task specified by id is already suspended, then the``RTEMS_ALREADY_SUSPENDED`` status code is returned. +If the task specified by id is already suspended, then the +``RTEMS_ALREADY_SUSPENDED`` status code is returned. + +.. _rtems_task_resume: TASK_RESUME - Resume a task --------------------------- @@ -998,33 +1033,39 @@ TASK_RESUME - Resume a task .. code:: c rtems_status_code rtems_task_resume( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - task resumed successfully -``RTEMS_INVALID_ID`` - task id invalid -``RTEMS_INCORRECT_STATE`` - task not suspended +``RTEMS_SUCCESSFUL`` + task resumed successfully + +``RTEMS_INVALID_ID`` + task id invalid + +``RTEMS_INCORRECT_STATE`` + task not suspended **DESCRIPTION:** -This directive removes the task specified by id from the -suspended state. If the task is in the ready state after the -suspension is removed, then it will be scheduled to run. If the -task is still in a blocked state after the suspension is -removed, then it will remain in that blocked state. +This directive removes the task specified by id from the suspended state. If +the task is in the ready state after the suspension is removed, then it will be +scheduled to run. If the task is still in a blocked state after the suspension +is removed, then it will remain in that blocked state. **NOTES:** -The running task may be preempted if its preemption mode is -enabled and the local task being resumed has a higher priority. +The running task may be preempted if its preemption mode is enabled and the +local task being resumed has a higher priority. -Resuming a global task which does not reside on the local node -will generate a request to the remote node to resume the -specified task. +Resuming a global task which does not reside on the local node will generate a +request to the remote node to resume the specified task. + +If the task specified by id is not suspended, then the +``RTEMS_INCORRECT_STATE`` status code is returned. -If the task specified by id is not suspended, then the``RTEMS_INCORRECT_STATE`` status code is returned. +.. _rtems_task_is_suspended: TASK_IS_SUSPENDED - Determine if a task is Suspended ---------------------------------------------------- @@ -1037,25 +1078,34 @@ TASK_IS_SUSPENDED - Determine if a task is Suspended .. code:: c rtems_status_code rtems_task_is_suspended( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - task is NOT suspended -``RTEMS_ALREADY_SUSPENDED`` - task is currently suspended -``RTEMS_INVALID_ID`` - task id invalid -``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks +``RTEMS_SUCCESSFUL`` + task is NOT suspended + +``RTEMS_ALREADY_SUSPENDED`` + task is currently suspended + +``RTEMS_INVALID_ID`` + task id invalid + +``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + not supported on remote tasks **DESCRIPTION:** -This directive returns a status code indicating whether or -not the specified task is currently suspended. +This directive returns a status code indicating whether or not the specified +task is currently suspended. **NOTES:** This operation is not currently supported on remote tasks. +.. _rtems_task_set_priority: + TASK_SET_PRIORITY - Set task priority ------------------------------------- .. index:: rtems_task_set_priority @@ -1069,51 +1119,55 @@ TASK_SET_PRIORITY - Set task priority .. code:: c rtems_status_code rtems_task_set_priority( - rtems_id id, - rtems_task_priority new_priority, - rtems_task_priority \*old_priority + rtems_id id, + rtems_task_priority new_priority, + rtems_task_priority *old_priority ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - task priority set successfully -``RTEMS_INVALID_ID`` - invalid task id -``RTEMS_INVALID_ADDRESS`` - invalid return argument pointer -``RTEMS_INVALID_PRIORITY`` - invalid task priority +``RTEMS_SUCCESSFUL`` + task priority set successfully + +``RTEMS_INVALID_ID`` + invalid task id + +``RTEMS_INVALID_ADDRESS`` + invalid return argument pointer + +``RTEMS_INVALID_PRIORITY`` + invalid task priority **DESCRIPTION:** -This directive manipulates the priority of the task specified by -id. An id of ``RTEMS_SELF`` is used to indicate -the calling task. When new_priority is not equal to``RTEMS_CURRENT_PRIORITY``, the specified -task's previous priority is returned in old_priority. When -new_priority is ``RTEMS_CURRENT_PRIORITY``, -the specified task's current -priority is returned in old_priority. Valid priorities range -from a high of 1 to a low of 255. +This directive manipulates the priority of the task specified by id. An id of +``RTEMS_SELF`` is used to indicate the calling task. When new_priority is not +equal to ``RTEMS_CURRENT_PRIORITY``, the specified task's previous priority is +returned in old_priority. When new_priority is ``RTEMS_CURRENT_PRIORITY``, the +specified task's current priority is returned in old_priority. Valid +priorities range from a high of 1 to a low of 255. **NOTES:** -The calling task may be preempted if its preemption mode is -enabled and it lowers its own priority or raises another task's -priority. +The calling task may be preempted if its preemption mode is enabled and it +lowers its own priority or raises another task's priority. In case the new priority equals the current priority of the task, then nothing happens. -Setting the priority of a global task which does not reside on -the local node will generate a request to the remote node to -change the priority of the specified task. +Setting the priority of a global task which does not reside on the local node +will generate a request to the remote node to change the priority of the +specified task. + +If the task specified by id is currently holding any binary semaphores which +use the priority inheritance algorithm, then the task's priority cannot be +lowered immediately. If the task's priority were lowered immediately, then +priority inversion results. The requested lowering of the task's priority will +occur when the task has released all priority inheritance binary semaphores. +The task's priority can be increased regardless of the task's use of priority +inheritance binary semaphores. -If the task specified by id is currently holding any binary -semaphores which use the priority inheritance algorithm, then -the task's priority cannot be lowered immediately. If the -task's priority were lowered immediately, then priority -inversion results. The requested lowering of the task's -priority will occur when the task has released all priority -inheritance binary semaphores. The task's priority can be -increased regardless of the task's use of priority inheritance -binary semaphores. +.. _rtems_task_mode: TASK_MODE - Change the current task mode ---------------------------------------- @@ -1131,60 +1185,70 @@ TASK_MODE - Change the current task mode .. code:: c rtems_status_code rtems_task_mode( - rtems_mode mode_set, - rtems_mode mask, - rtems_mode \*previous_mode_set + rtems_mode mode_set, + rtems_mode mask, + rtems_mode *previous_mode_set ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - task mode set successfully -``RTEMS_INVALID_ADDRESS`` - ``previous_mode_set`` is NULL +``RTEMS_SUCCESSFUL`` + task mode set successfully + +``RTEMS_INVALID_ADDRESS`` + ``previous_mode_set`` is NULL **DESCRIPTION:** -This directive manipulates the execution mode of the calling -task. A task's execution mode enables and disables preemption, -timeslicing, asynchronous signal processing, as well as -specifying the current interrupt level. To modify an execution -mode, the mode class(es) to be changed must be specified in the -mask parameter and the desired mode(s) must be specified in the -mode parameter. +This directive manipulates the execution mode of the calling task. A task's +execution mode enables and disables preemption, timeslicing, asynchronous +signal processing, as well as specifying the current interrupt level. To +modify an execution mode, the mode class(es) to be changed must be specified in +the mask parameter and the desired mode(s) must be specified in the mode +parameter. **NOTES:** -The calling task will be preempted if it enables preemption and -a higher priority task is ready to run. +The calling task will be preempted if it enables preemption and a higher +priority task is ready to run. -Enabling timeslicing has no effect if preemption is disabled. For -a task to be timesliced, that task must have both preemption and -timeslicing enabled. +Enabling timeslicing has no effect if preemption is disabled. For a task to be +timesliced, that task must have both preemption and timeslicing enabled. -A task can obtain its current execution mode, without modifying -it, by calling this directive with a mask value of``RTEMS_CURRENT_MODE``. +A task can obtain its current execution mode, without modifying it, by calling +this directive with a mask value of ``RTEMS_CURRENT_MODE``. -To temporarily disable the processing of a valid ASR, a task -should call this directive with the ``RTEMS_NO_ASR`` -indicator specified in mode. +To temporarily disable the processing of a valid ASR, a task should call this +directive with the ``RTEMS_NO_ASR`` indicator specified in mode. -The set of task mode constants and each mode's corresponding -mask constant is provided in the following table: +The set of task mode constants and each mode's corresponding mask constant is +provided in the following table: -- ``RTEMS_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and enables preemption +``RTEMS_PREEMPT`` + is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption -- ``RTEMS_NO_PREEMPT`` is masked by``RTEMS_PREEMPT_MASK`` and disables preemption +``RTEMS_NO_PREEMPT`` + is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption -- ``RTEMS_NO_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and disables timeslicing +``RTEMS_NO_TIMESLICE`` + is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing -- ``RTEMS_TIMESLICE`` is masked by``RTEMS_TIMESLICE_MASK`` and enables timeslicing +``RTEMS_TIMESLICE`` + is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing -- ``RTEMS_ASR`` is masked by``RTEMS_ASR_MASK`` and enables ASR processing +``RTEMS_ASR`` + is masked by ``RTEMS_ASR_MASK`` and enables ASR processing -- ``RTEMS_NO_ASR`` is masked by``RTEMS_ASR_MASK`` and disables ASR processing +``RTEMS_NO_ASR`` + is masked by ``RTEMS_ASR_MASK`` and disables ASR processing -- ``RTEMS_INTERRUPT_LEVEL(0)`` is masked by``RTEMS_INTERRUPT_MASK`` and enables all interrupts +``RTEMS_INTERRUPT_LEVEL(0)`` + is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts -- ``RTEMS_INTERRUPT_LEVEL(n)`` is masked by``RTEMS_INTERRUPT_MASK`` and sets interrupts level n +``RTEMS_INTERRUPT_LEVEL(n)`` + is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n + +.. _rtems_task_wake_after: TASK_WAKE_AFTER - Wake up after interval ---------------------------------------- @@ -1198,7 +1262,7 @@ TASK_WAKE_AFTER - Wake up after interval .. code:: c rtems_status_code rtems_task_wake_after( - rtems_interval ticks + rtems_interval ticks ); **DIRECTIVE STATUS CODES:** @@ -1207,24 +1271,25 @@ TASK_WAKE_AFTER - Wake up after interval **DESCRIPTION:** -This directive blocks the calling task for the specified number -of system clock ticks. When the requested interval has elapsed, -the task is made ready. The ``rtems_clock_tick`` -directive automatically updates the delay period. +This directive blocks the calling task for the specified number of system clock +ticks. When the requested interval has elapsed, the task is made ready. The +``rtems_clock_tick`` directive automatically updates the delay period. **NOTES:** -Setting the system date and time with the``rtems_clock_set`` directive -has no effect on a ``rtems_task_wake_after`` blocked task. +Setting the system date and time with the ``rtems_clock_set`` directive has no +effect on a ``rtems_task_wake_after`` blocked task. -A task may give up the processor and remain in the ready state -by specifying a value of ``RTEMS_YIELD_PROCESSOR`` in ticks. +A task may give up the processor and remain in the ready state by specifying a +value of ``RTEMS_YIELD_PROCESSOR`` in ticks. -The maximum timer interval that can be specified is the maximum -value which can be represented by the uint32_t type. +The maximum timer interval that can be specified is the maximum value which can +be represented by the uint32_t type. A clock tick is required to support the functionality of this directive. +.. _rtems_task_wake_when: + TASK_WAKE_WHEN - Wake up when specified --------------------------------------- .. index:: delay a task until a wall time @@ -1237,29 +1302,38 @@ TASK_WAKE_WHEN - Wake up when specified .. code:: c rtems_status_code rtems_task_wake_when( - rtems_time_of_day \*time_buffer + rtems_time_of_day *time_buffer ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - awakened at date/time successfully -``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL -``RTEMS_INVALID_TIME_OF_DAY`` - invalid time buffer -``RTEMS_NOT_DEFINED`` - system date and time is not set +``RTEMS_SUCCESSFUL`` + awakened at date/time successfully + +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL + +``RTEMS_INVALID_TIME_OF_DAY`` + invalid time buffer + +``RTEMS_NOT_DEFINED`` + system date and time is not set **DESCRIPTION:** -This directive blocks a task until the date and time specified -in time_buffer. At the requested date and time, the calling -task will be unblocked and made ready to execute. +This directive blocks a task until the date and time specified in time_buffer. +At the requested date and time, the calling task will be unblocked and made +ready to execute. **NOTES:** -The ticks portion of time_buffer structure is ignored. The -timing granularity of this directive is a second. +The ticks portion of time_buffer structure is ignored. The timing granularity +of this directive is a second. A clock tick is required to support the functionality of this directive. +.. _rtems_iterate_over_all_threads: + ITERATE_OVER_ALL_THREADS - Iterate Over Tasks --------------------------------------------- .. index:: iterate over all threads @@ -1270,30 +1344,32 @@ ITERATE_OVER_ALL_THREADS - Iterate Over Tasks .. code:: c - typedef void (\*rtems_per_thread_routine)( - Thread_Control \*the_thread - ); + typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread); void rtems_iterate_over_all_threads( - rtems_per_thread_routine routine + rtems_per_thread_routine routine ); -**DIRECTIVE STATUS CODES: NONE** +**DIRECTIVE STATUS CODES:** + +NONE **DESCRIPTION:** -This directive iterates over all of the existant threads in the -system and invokes ``routine`` on each of them. The user should -be careful in accessing the contents of ``the_thread``. +This directive iterates over all of the existant threads in the system and +invokes ``routine`` on each of them. The user should be careful in accessing +the contents of ``the_thread``. -This routine is intended for use in diagnostic utilities and is -not intented for routine use in an operational system. +This routine is intended for use in diagnostic utilities and is not intented +for routine use in an operational system. **NOTES:** -There is NO protection while this routine is called. Thus it is -possible that ``the_thread`` could be deleted while this is operating. -By not having protection, the user is free to invoke support routines -from the C Library which require semaphores for data structures. +There is NO protection while this routine is called. Thus it is possible that +``the_thread`` could be deleted while this is operating. By not having +protection, the user is free to invoke support routines from the C Library +which require semaphores for data structures. + +.. _rtems_task_variable_add: TASK_VARIABLE_ADD - Associate per task variable ----------------------------------------------- @@ -1301,6 +1377,10 @@ TASK_VARIABLE_ADD - Associate per task variable .. index:: task private variable .. index:: task private data +.. warning:: + + This directive is deprecated and task variables will be removed. + **CALLING SEQUENCE:** .. index:: rtems_task_variable_add @@ -1308,51 +1388,62 @@ TASK_VARIABLE_ADD - Associate per task variable .. code:: c rtems_status_code rtems_task_variable_add( - rtems_id tid, - void \**task_variable, - void (\*dtor)(void \*) + rtems_id tid, + void **task_variable, + void (*dtor)(void *) ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - per task variable added successfully -``RTEMS_INVALID_ADDRESS`` - ``task_variable`` is NULL -``RTEMS_INVALID_ID`` - invalid task id -``RTEMS_NO_MEMORY`` - invalid task id -``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks +``RTEMS_SUCCESSFUL`` + per task variable added successfully + +``RTEMS_INVALID_ADDRESS`` + ``task_variable`` is NULL + +``RTEMS_INVALID_ID`` + invalid task id + +``RTEMS_NO_MEMORY`` + invalid task id + +``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + not supported on remote tasks **DESCRIPTION:** -This directive adds the memory location specified by the -ptr argument to the context of the given task. The variable will -then be private to the task. The task can access and modify the -variable, but the modifications will not appear to other tasks, and -other tasks' modifications to that variable will not affect the value -seen by the task. This is accomplished by saving and restoring the +This directive adds the memory location specified by the ptr argument to the +context of the given task. The variable will then be private to the task. The +task can access and modify the variable, but the modifications will not appear +to other tasks, and other tasks' modifications to that variable will not affect +the value seen by the task. This is accomplished by saving and restoring the variable's value each time a task switch occurs to or from the calling task. If the dtor argument is non-NULL it specifies the address of a 'destructor' -function which will be called when the task is deleted. The argument -passed to the destructor function is the task's value of the variable. +function which will be called when the task is deleted. The argument passed to +the destructor function is the task's value of the variable. **NOTES:** -This directive is deprecated and task variables will be removed. - -Task variables increase the context switch time to and from the -tasks that own them so it is desirable to minimize the number of -task variables. One efficient method -is to have a single task variable that is a pointer to a dynamically -allocated structure containing the task's private 'global' data. +Task variables increase the context switch time to and from the tasks that own +them so it is desirable to minimize the number of task variables. One +efficient method is to have a single task variable that is a pointer to a +dynamically allocated structure containing the task's private 'global' data. In this case the destructor function could be 'free'. -Per-task variables are disabled in SMP configurations and this service -is not available. +Per-task variables are disabled in SMP configurations and this service is not +available. + +.. _rtems_task_variable_get: TASK_VARIABLE_GET - Obtain value of a per task variable ------------------------------------------------------- .. index:: get per-task variable .. index:: obtain per-task variable +.. warning:: + + This directive is deprecated and task variables will be removed. + **CALLING SEQUENCE:** .. index:: rtems_task_variable_get @@ -1360,38 +1451,49 @@ TASK_VARIABLE_GET - Obtain value of a per task variable .. code:: c rtems_status_code rtems_task_variable_get( - rtems_id tid, - void \**task_variable, - void \**task_variable_value + rtems_id tid, + void **task_variable, + void **task_variable_value ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - per task variable obtained successfully -``RTEMS_INVALID_ADDRESS`` - ``task_variable`` is NULL -``RTEMS_INVALID_ADDRESS`` - ``task_variable_value`` is NULL -``RTEMS_INVALID_ADDRESS`` - ``task_variable`` is not found -``RTEMS_NO_MEMORY`` - invalid task id -``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks +``RTEMS_SUCCESSFUL`` + per task variable obtained successfully + +``RTEMS_INVALID_ADDRESS`` + ``task_variable`` is NULL + +``RTEMS_INVALID_ADDRESS`` + ``task_variable_value`` is NULL + +``RTEMS_INVALID_ADDRESS`` + ``task_variable`` is not found + +``RTEMS_NO_MEMORY`` + invalid task id + +``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + not supported on remote tasks **DESCRIPTION:** -This directive looks up the private value of a task variable for a -specified task and stores that value in the location pointed to by -the result argument. The specified task is usually not the calling -task, which can get its private value by directly accessing the variable. +This directive looks up the private value of a task variable for a specified +task and stores that value in the location pointed to by the result argument. +The specified task is usually not the calling task, which can get its private +value by directly accessing the variable. **NOTES:** -This directive is deprecated and task variables will be removed. +If you change memory which ``task_variable_value`` points to, remember to +declare that memory as volatile, so that the compiler will optimize it +correctly. In this case both the pointer ``task_variable_value`` and data +referenced by ``task_variable_value`` should be considered volatile. -If you change memory which ``task_variable_value`` points to, -remember to declare that memory as volatile, so that the compiler -will optimize it correctly. In this case both the pointer``task_variable_value`` and data referenced by ``task_variable_value`` -should be considered volatile. +Per-task variables are disabled in SMP configurations and this service is not +available. -Per-task variables are disabled in SMP configurations and this service -is not available. +.. _rtems_task_variable_delete: TASK_VARIABLE_DELETE - Remove per task variable ----------------------------------------------- @@ -1399,6 +1501,10 @@ TASK_VARIABLE_DELETE - Remove per task variable .. index:: task private variable .. index:: task private data +.. warning:: + + This directive is deprecated and task variables will be removed. + **CALLING SEQUENCE:** .. index:: rtems_task_variable_delete @@ -1406,17 +1512,26 @@ TASK_VARIABLE_DELETE - Remove per task variable .. code:: c rtems_status_code rtems_task_variable_delete( - rtems_id id, - void \**task_variable + rtems_id id, + void **task_variable ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - per task variable deleted successfully -``RTEMS_INVALID_ID`` - invalid task id -``RTEMS_NO_MEMORY`` - invalid task id -``RTEMS_INVALID_ADDRESS`` - ``task_variable`` is NULL -``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - not supported on remote tasks +``RTEMS_SUCCESSFUL`` + per task variable deleted successfully + +``RTEMS_INVALID_ID`` + invalid task id + +``RTEMS_NO_MEMORY`` + invalid task id + +``RTEMS_INVALID_ADDRESS`` + ``task_variable`` is NULL + +``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + not supported on remote tasks **DESCRIPTION:** @@ -1424,14 +1539,5 @@ This directive removes the given location from a task's context. **NOTES:** -This directive is deprecated and task variables will be removed. - Per-task variables are disabled in SMP configurations and this service is not available. - -.. COMMENT: COPYRIGHT (c) 1988-2008. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - diff --git a/c_user/timer_manager.rst b/c_user/timer_manager.rst index 2d83bf9..2e43770 100644 --- a/c_user/timer_manager.rst +++ b/c_user/timer_manager.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Timer Manager ############# @@ -9,25 +13,25 @@ Introduction The timer manager provides support for timer facilities. The directives provided by the timer manager are: -- ``rtems_timer_create`` - Create a timer +- rtems_timer_create_ - Create a timer -- ``rtems_timer_ident`` - Get ID of a timer +- rtems_timer_ident_ - Get ID of a timer -- ``rtems_timer_cancel`` - Cancel a timer +- rtems_timer_cancel_ - Cancel a timer -- ``rtems_timer_delete`` - Delete a timer +- rtems_timer_delete_ - Delete a timer -- ``rtems_timer_fire_after`` - Fire timer after interval +- rtems_timer_fire_after_ - Fire timer after interval -- ``rtems_timer_fire_when`` - Fire timer when specified +- rtems_timer_fire_when_ - Fire timer when specified -- ``rtems_timer_initiate_server`` - Initiate server for task-based timers +- rtems_timer_initiate_server_ - Initiate server for task-based timers -- ``rtems_timer_server_fire_after`` - Fire task-based timer after interval +- rtems_timer_server_fire_after_ - Fire task-based timer after interval -- ``rtems_timer_server_fire_when`` - Fire task-based timer when specified +- rtems_timer_server_fire_when_ - Fire task-based timer when specified -- ``rtems_timer_reset`` - Reset an interval timer +- rtems_timer_reset_ - Reset an interval timer Background ========== @@ -40,65 +44,60 @@ A clock tick is required to support the functionality provided by this manager. Timers ------ -A timer is an RTEMS object which allows the -application to schedule operations to occur at specific times in -the future. User supplied timer service routines are invoked by -either the ``rtems_clock_tick`` directive or -a special Timer Server task when the timer fires. Timer service -routines may perform any operations or directives which normally -would be performed by the application code which invoked the``rtems_clock_tick`` directive. - -The timer can be used to implement watchdog routines -which only fire to denote that an application error has -occurred. The timer is reset at specific points in the -application to ensure that the watchdog does not fire. Thus, if -the application does not reset the watchdog timer, then the -timer service routine will fire to indicate that the application -has failed to reach a reset point. This use of a timer is -sometimes referred to as a "keep alive" or a "deadman" timer. +A timer is an RTEMS object which allows the application to schedule operations +to occur at specific times in the future. User supplied timer service routines +are invoked by either the ``rtems_clock_tick`` directive or a special Timer +Server task when the timer fires. Timer service routines may perform any +operations or directives which normally would be performed by the application +code which invoked the ``rtems_clock_tick`` directive. + +The timer can be used to implement watchdog routines which only fire to denote +that an application error has occurred. The timer is reset at specific points +in the application to ensure that the watchdog does not fire. Thus, if the +application does not reset the watchdog timer, then the timer service routine +will fire to indicate that the application has failed to reach a reset point. +This use of a timer is sometimes referred to as a "keep alive" or a "deadman" +timer. Timer Server ------------ -The Timer Server task is responsible for executing the timer -service routines associated with all task-based timers. -This task executes at a priority higher than any RTEMS application -task, and is created non-preemptible, and thus can be viewed logically as -the lowest priority interrupt. - -By providing a mechanism where timer service routines execute -in task rather than interrupt space, the application is -allowed a bit more flexibility in what operations a timer -service routine can perform. For example, the Timer Server -can be configured to have a floating point context in which case -it would be safe to perform floating point operations -from a task-based timer. Most of the time, executing floating -point instructions from an interrupt service routine -is not considered safe. However, since the Timer Server task -is non-preemptible, only directives allowed from an ISR can be -called in the timer service routine. - -The Timer Server is designed to remain blocked until a -task-based timer fires. This reduces the execution overhead -of the Timer Server. +The Timer Server task is responsible for executing the timer service routines +associated with all task-based timers. This task executes at a priority higher +than any RTEMS application task, and is created non-preemptible, and thus can +be viewed logically as the lowest priority interrupt. + +By providing a mechanism where timer service routines execute in task rather +than interrupt space, the application is allowed a bit more flexibility in what +operations a timer service routine can perform. For example, the Timer Server +can be configured to have a floating point context in which case it would be +safe to perform floating point operations from a task-based timer. Most of the +time, executing floating point instructions from an interrupt service routine +is not considered safe. However, since the Timer Server task is +non-preemptible, only directives allowed from an ISR can be called in the timer +service routine. + +The Timer Server is designed to remain blocked until a task-based timer fires. +This reduces the execution overhead of the Timer Server. Timer Service Routines ---------------------- -The timer service routine should adhere to C calling -conventions and have a prototype similar to the following:.. index:: rtems_timer_service_routine +The timer service routine should adhere to C calling conventions and have a +prototype similar to the following: + +.. index:: rtems_timer_service_routine .. code:: c rtems_timer_service_routine user_routine( - rtems_id timer_id, - void \*user_data + rtems_id timer_id, + void *user_data ); -Where the timer_id parameter is the RTEMS object ID -of the timer which is being fired and user_data is a pointer to -user-defined information which may be utilized by the timer -service routine. The argument user_data may be NULL. +Where the timer_id parameter is the RTEMS object ID of the timer which is being +fired and user_data is a pointer to user-defined information which may be +utilized by the timer service routine. The argument user_data may be NULL. Operations ========== @@ -106,95 +105,89 @@ Operations Creating a Timer ---------------- -The ``rtems_timer_create`` directive creates a timer by -allocating a Timer Control Block (TMCB), assigning the timer a -user-specified name, and assigning it a timer ID. Newly created -timers do not have a timer service routine associated with them -and are not active. +The ``rtems_timer_create`` directive creates a timer by allocating a Timer +Control Block (TMCB), assigning the timer a user-specified name, and assigning +it a timer ID. Newly created timers do not have a timer service routine +associated with them and are not active. Obtaining Timer IDs ------------------- -When a timer is created, RTEMS generates a unique -timer ID and assigns it to the created timer until it is -deleted. The timer ID may be obtained by either of two methods. -First, as the result of an invocation of the``rtems_timer_create`` -directive, the timer ID is stored in a user provided location. -Second, the timer ID may be obtained later using the``rtems_timer_ident`` directive. The timer ID -is used by other directives to manipulate this timer. +When a timer is created, RTEMS generates a unique timer ID and assigns it to +the created timer until it is deleted. The timer ID may be obtained by either +of two methods. First, as the result of an invocation of the +``rtems_timer_create`` directive, the timer ID is stored in a user provided +location. Second, the timer ID may be obtained later using the +``rtems_timer_ident`` directive. The timer ID is used by other directives to +manipulate this timer. Initiating an Interval Timer ---------------------------- -The ``rtems_timer_fire_after`` -and ``rtems_timer_server_fire_after`` -directives initiate a timer to fire a user provided -timer service routine after the specified -number of clock ticks have elapsed. When the interval has -elapsed, the timer service routine will be invoked from the``rtems_clock_tick`` directive if it was initiated -by the ``rtems_timer_fire_after`` directive -and from the Timer Server task if initiated by the``rtems_timer_server_fire_after`` directive. +The ``rtems_timer_fire_after`` and ``rtems_timer_server_fire_after`` directives +initiate a timer to fire a user provided timer service routine after the +specified number of clock ticks have elapsed. When the interval has elapsed, +the timer service routine will be invoked from the ``rtems_clock_tick`` +directive if it was initiated by the ``rtems_timer_fire_after`` directive and +from the Timer Server task if initiated by the +``rtems_timer_server_fire_after`` directive. Initiating a Time of Day Timer ------------------------------ -The ``rtems_timer_fire_when`` -and ``rtems_timer_server_fire_when`` -directive initiate a timer to -fire a user provided timer service routine when the specified -time of day has been reached. When the interval has elapsed, -the timer service routine will be invoked from the``rtems_clock_tick`` directive -by the ``rtems_timer_fire_when`` directive -and from the Timer Server task if initiated by the``rtems_timer_server_fire_when`` directive. +The ``rtems_timer_fire_when`` and ``rtems_timer_server_fire_when`` directive +initiate a timer to fire a user provided timer service routine when the +specified time of day has been reached. When the interval has elapsed, the +timer service routine will be invoked from the ``rtems_clock_tick`` directive +by the ``rtems_timer_fire_when`` directive and from the Timer Server task if +initiated by the ``rtems_timer_server_fire_when`` directive. Canceling a Timer ----------------- -The ``rtems_timer_cancel`` directive is used to halt the -specified timer. Once canceled, the timer service routine will -not fire unless the timer is reinitiated. The timer can be -reinitiated using the ``rtems_timer_reset``,``rtems_timer_fire_after``, and``rtems_timer_fire_when`` directives. +The ``rtems_timer_cancel`` directive is used to halt the specified timer. Once +canceled, the timer service routine will not fire unless the timer is +reinitiated. The timer can be reinitiated using the ``rtems_timer_reset``, +``rtems_timer_fire_after``, and ``rtems_timer_fire_when`` directives. Resetting a Timer ----------------- -The ``rtems_timer_reset`` directive is used to restore an -interval timer initiated by a previous invocation of``rtems_timer_fire_after`` or``rtems_timer_server_fire_after`` to -its original interval length. If the -timer has not been used or the last usage of this timer -was by the ``rtems_timer_fire_when`` -or ``rtems_timer_server_fire_when`` -directive, then an error is returned. The timer service routine -is not changed or fired by this directive. +The ``rtems_timer_reset`` directive is used to restore an interval timer +initiated by a previous invocation of ``rtems_timer_fire_after`` or +``rtems_timer_server_fire_after`` to its original interval length. If the +timer has not been used or the last usage of this timer was by the +``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, then +an error is returned. The timer service routine is not changed or fired by +this directive. Initiating the Timer Server --------------------------- -The ``rtems_timer_initiate_server`` directive is used to -allocate and start the execution of the Timer Server task. The -application can specify both the stack size and attributes of the -Timer Server. The Timer Server executes at a priority higher than -any application task and thus the user can expect to be preempted -as the result of executing the ``rtems_timer_initiate_server`` +The ``rtems_timer_initiate_server`` directive is used to allocate and start the +execution of the Timer Server task. The application can specify both the stack +size and attributes of the Timer Server. The Timer Server executes at a +priority higher than any application task and thus the user can expect to be +preempted as the result of executing the ``rtems_timer_initiate_server`` directive. Deleting a Timer ---------------- -The ``rtems_timer_delete`` directive is used to delete a timer. -If the timer is running and has not expired, the timer is -automatically canceled. The timer's control block is returned -to the TMCB free list when it is deleted. A timer can be -deleted by a task other than the task which created the timer. +The ``rtems_timer_delete`` directive is used to delete a timer. If the timer +is running and has not expired, the timer is automatically canceled. The +timer's control block is returned to the TMCB free list when it is deleted. A +timer can be deleted by a task other than the task which created the timer. Any subsequent references to the timer's name and ID are invalid. Directives ========== -This section details the timer 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. +This section details the timer 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. + +.. _rtems_timer_create: TIMER_CREATE - Create a timer ----------------------------- @@ -207,29 +200,36 @@ TIMER_CREATE - Create a timer .. code:: c rtems_status_code rtems_timer_create( - rtems_name name, - rtems_id \*id + rtems_name name, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer created successfully -``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL -``RTEMS_INVALID_NAME`` - invalid timer name -``RTEMS_TOO_MANY`` - too many timers created +``RTEMS_SUCCESSFUL`` + timer created successfully + +``RTEMS_INVALID_ADDRESS`` + ``id`` is NULL + +``RTEMS_INVALID_NAME`` + invalid timer name + +``RTEMS_TOO_MANY`` + too many timers created **DESCRIPTION:** -This directive creates a timer. The assigned timer -id is returned in id. This id is used to access the timer with -other timer manager directives. For control and maintenance of -the timer, RTEMS allocates a TMCB from the local TMCB free pool -and initializes it. +This directive creates a timer. The assigned timer id is returned in id. This +id is used to access the timer with other timer manager directives. For +control and maintenance of the timer, RTEMS allocates a TMCB from the local +TMCB free pool and initializes it. **NOTES:** -This directive will not cause the calling task to be -preempted. +This directive will not cause the calling task to be preempted. + +.. _rtems_timer_ident: TIMER_IDENT - Get ID of a timer ------------------------------- @@ -242,29 +242,34 @@ TIMER_IDENT - Get ID of a timer .. code:: c rtems_status_code rtems_timer_ident( - rtems_name name, - rtems_id \*id + rtems_name name, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer identified successfully -``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL -``RTEMS_INVALID_NAME`` - timer name not found +``RTEMS_SUCCESSFUL`` + timer identified successfully + +``RTEMS_INVALID_ADDRESS`` + ``id`` is NULL + +``RTEMS_INVALID_NAME`` + timer name not found **DESCRIPTION:** -This directive obtains the timer id associated with -the timer name to be acquired. If the timer name is not unique, -then the timer id will match one of the timers with that name. -However, this timer id is not guaranteed to correspond to the -desired timer. The timer id is used to access this timer in +This directive obtains the timer id associated with the timer name to be +acquired. If the timer name is not unique, then the timer id will match one of +the timers with that name. However, this timer id is not guaranteed to +correspond to the desired timer. The timer id is used to access this timer in other timer related directives. **NOTES:** -This directive will not cause the running task to be -preempted. +This directive will not cause the running task to be preempted. + +.. _rtems_timer_cancel: TIMER_CANCEL - Cancel a timer ----------------------------- @@ -277,23 +282,29 @@ TIMER_CANCEL - Cancel a timer .. code:: c rtems_status_code rtems_timer_cancel( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer canceled successfully -``RTEMS_INVALID_ID`` - invalid timer id +``RTEMS_SUCCESSFUL`` + timer canceled successfully + +``RTEMS_INVALID_ID`` + invalid timer id **DESCRIPTION:** -This directive cancels the timer id. This timer will -be reinitiated by the next invocation of ``rtems_timer_reset``,``rtems_timer_fire_after``, or``rtems_timer_fire_when`` with this id. +This directive cancels the timer id. This timer will be reinitiated by the +next invocation of ``rtems_timer_reset``, ``rtems_timer_fire_after``, or +``rtems_timer_fire_when`` with this id. **NOTES:** This directive will not cause the running task to be preempted. +.. _rtems_timer_delete: + TIMER_DELETE - Delete a timer ----------------------------- .. index:: delete a timer @@ -305,27 +316,30 @@ TIMER_DELETE - Delete a timer .. code:: c rtems_status_code rtems_timer_delete( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer deleted successfully -``RTEMS_INVALID_ID`` - invalid timer id +``RTEMS_SUCCESSFUL`` + timer deleted successfully + +``RTEMS_INVALID_ID`` + invalid timer id **DESCRIPTION:** -This directive deletes the timer specified by id. If -the timer is running, it is automatically canceled. The TMCB -for the deleted timer is reclaimed by RTEMS. +This directive deletes the timer specified by id. If the timer is running, it +is automatically canceled. The TMCB for the deleted timer is reclaimed by +RTEMS. **NOTES:** -This directive will not cause the running task to be -preempted. +This directive will not cause the running task to be preempted. + +A timer can be deleted by a task other than the task which created the timer. -A timer can be deleted by a task other than the task -which created the timer. +.. _rtems_timer_fire_after: TIMER_FIRE_AFTER - Fire timer after interval -------------------------------------------- @@ -338,32 +352,38 @@ TIMER_FIRE_AFTER - Fire timer after interval .. code:: c rtems_status_code rtems_timer_fire_after( - rtems_id id, - rtems_interval ticks, - rtems_timer_service_routine_entry routine, - void \*user_data + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer initiated successfully -``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL -``RTEMS_INVALID_ID`` - invalid timer id -``RTEMS_INVALID_NUMBER`` - invalid interval +``RTEMS_SUCCESSFUL`` + timer initiated successfully + +``RTEMS_INVALID_ADDRESS`` + ``routine`` is NULL + +``RTEMS_INVALID_ID`` + invalid timer id + +``RTEMS_INVALID_NUMBER`` + invalid interval **DESCRIPTION:** -This directive initiates the timer specified by id. -If the timer is running, it is automatically canceled before -being initiated. The timer is scheduled to fire after an -interval ticks clock ticks has passed. When the timer fires, -the timer service routine routine will be invoked with the -argument user_data. +This directive initiates the timer specified by id. If the timer is running, +it is automatically canceled before being initiated. The timer is scheduled to +fire after an interval ticks clock ticks has passed. When the timer fires, the +timer service routine routine will be invoked with the argument user_data. **NOTES:** -This directive will not cause the running task to be -preempted. +This directive will not cause the running task to be preempted. + +.. _rtems_timer_fire_when: TIMER_FIRE_WHEN - Fire timer when specified ------------------------------------------- @@ -376,34 +396,44 @@ TIMER_FIRE_WHEN - Fire timer when specified .. code:: c rtems_status_code rtems_timer_fire_when( - rtems_id id, - rtems_time_of_day \*wall_time, - rtems_timer_service_routine_entry routine, - void \*user_data + rtems_id id, + rtems_time_of_day *wall_time, + rtems_timer_service_routine_entry routine, + void *user_data ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer initiated successfully -``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL -``RTEMS_INVALID_ADDRESS`` - ``wall_time`` is NULL -``RTEMS_INVALID_ID`` - invalid timer id -``RTEMS_NOT_DEFINED`` - system date and time is not set -``RTEMS_INVALID_CLOCK`` - invalid time of day +``RTEMS_SUCCESSFUL`` + timer initiated successfully + +``RTEMS_INVALID_ADDRESS`` + ``routine`` is NULL + +``RTEMS_INVALID_ADDRESS`` + ``wall_time`` is NULL + +``RTEMS_INVALID_ID`` + invalid timer id + +``RTEMS_NOT_DEFINED`` + system date and time is not set + +``RTEMS_INVALID_CLOCK`` + invalid time of day **DESCRIPTION:** -This directive initiates the timer specified by id. -If the timer is running, it is automatically canceled before -being initiated. The timer is scheduled to fire at the time of -day specified by wall_time. When the timer fires, the timer -service routine routine will be invoked with the argument -user_data. +This directive initiates the timer specified by id. If the timer is running, +it is automatically canceled before being initiated. The timer is scheduled to +fire at the time of day specified by wall_time. When the timer fires, the +timer service routine routine will be invoked with the argument user_data. **NOTES:** -This directive will not cause the running task to be -preempted. +This directive will not cause the running task to be preempted. + +.. _rtems_timer_initiate_server: TIMER_INITIATE_SERVER - Initiate server for task-based timers ------------------------------------------------------------- @@ -416,32 +446,38 @@ TIMER_INITIATE_SERVER - Initiate server for task-based timers .. code:: c rtems_status_code rtems_timer_initiate_server( - uint32_t priority, - uint32_t stack_size, - rtems_attribute attribute_set + uint32_t priority, + uint32_t stack_size, + rtems_attribute attribute_set ) ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - Timer Server initiated successfully -``RTEMS_TOO_MANY`` - too many tasks created +``RTEMS_SUCCESSFUL`` + Timer Server initiated successfully + +``RTEMS_TOO_MANY`` + too many tasks created **DESCRIPTION:** -This directive initiates the Timer Server task. This task -is responsible for executing all timers initiated via the``rtems_timer_server_fire_after`` or``rtems_timer_server_fire_when`` directives. +This directive initiates the Timer Server task. This task is responsible for +executing all timers initiated via the ``rtems_timer_server_fire_after`` or +``rtems_timer_server_fire_when`` directives. **NOTES:** This directive could cause the calling task to be preempted. -The Timer Server task is created using the``rtems_task_create`` service and must be accounted -for when configuring the system. +The Timer Server task is created using the ``rtems_task_create`` service and +must be accounted for when configuring the system. + +Even through this directive invokes the ``rtems_task_create`` and +``rtems_task_start`` directives, it should only fail due to resource allocation +problems. -Even through this directive invokes the ``rtems_task_create`` -and ``rtems_task_start`` directives, it should only fail -due to resource allocation problems. +.. _rtems_timer_server_fire_after: TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval -------------------------------------------------------------- @@ -454,35 +490,44 @@ TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval .. code:: c rtems_status_code rtems_timer_server_fire_after( - rtems_id id, - rtems_interval ticks, - rtems_timer_service_routine_entry routine, - void \*user_data + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer initiated successfully -``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL -``RTEMS_INVALID_ID`` - invalid timer id -``RTEMS_INVALID_NUMBER`` - invalid interval -``RTEMS_INCORRECT_STATE`` - Timer Server not initiated +``RTEMS_SUCCESSFUL`` + timer initiated successfully + +``RTEMS_INVALID_ADDRESS`` + ``routine`` is NULL + +``RTEMS_INVALID_ID`` + invalid timer id + +``RTEMS_INVALID_NUMBER`` + invalid interval + +``RTEMS_INCORRECT_STATE`` + Timer Server not initiated **DESCRIPTION:** -This directive initiates the timer specified by id and specifies -that when it fires it will be executed by the Timer Server. +This directive initiates the timer specified by id and specifies that when it +fires it will be executed by the Timer Server. -If the timer is running, it is automatically canceled before -being initiated. The timer is scheduled to fire after an -interval ticks clock ticks has passed. When the timer fires, -the timer service routine routine will be invoked with the -argument user_data. +If the timer is running, it is automatically canceled before being initiated. +The timer is scheduled to fire after an interval ticks clock ticks has passed. +When the timer fires, the timer service routine routine will be invoked with +the argument user_data. **NOTES:** -This directive will not cause the running task to be -preempted. +This directive will not cause the running task to be preempted. + +.. _rtems_timer_server_fire_when: TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified ------------------------------------------------------------- @@ -495,37 +540,50 @@ TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified .. code:: c rtems_status_code rtems_timer_server_fire_when( - rtems_id id, - rtems_time_of_day \*wall_time, - rtems_timer_service_routine_entry routine, - void \*user_data + rtems_id id, + rtems_time_of_day *wall_time, + rtems_timer_service_routine_entry routine, + void *user_data ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer initiated successfully -``RTEMS_INVALID_ADDRESS`` - ``routine`` is NULL -``RTEMS_INVALID_ADDRESS`` - ``wall_time`` is NULL -``RTEMS_INVALID_ID`` - invalid timer id -``RTEMS_NOT_DEFINED`` - system date and time is not set -``RTEMS_INVALID_CLOCK`` - invalid time of day -``RTEMS_INCORRECT_STATE`` - Timer Server not initiated +``RTEMS_SUCCESSFUL`` + timer initiated successfully + +``RTEMS_INVALID_ADDRESS`` + ``routine`` is NULL + +``RTEMS_INVALID_ADDRESS`` + ``wall_time`` is NULL + +``RTEMS_INVALID_ID`` + invalid timer id + +``RTEMS_NOT_DEFINED`` + system date and time is not set + +``RTEMS_INVALID_CLOCK`` + invalid time of day + +``RTEMS_INCORRECT_STATE`` + Timer Server not initiated **DESCRIPTION:** -This directive initiates the timer specified by id and specifies -that when it fires it will be executed by the Timer Server. +This directive initiates the timer specified by id and specifies that when it +fires it will be executed by the Timer Server. -If the timer is running, it is automatically canceled before -being initiated. The timer is scheduled to fire at the time of -day specified by wall_time. When the timer fires, the timer -service routine routine will be invoked with the argument -user_data. +If the timer is running, it is automatically canceled before being initiated. +The timer is scheduled to fire at the time of day specified by wall_time. When +the timer fires, the timer service routine routine will be invoked with the +argument user_data. **NOTES:** -This directive will not cause the running task to be -preempted. +This directive will not cause the running task to be preempted. + +.. _rtems_timer_reset: TIMER_RESET - Reset an interval timer ------------------------------------- @@ -538,45 +596,36 @@ TIMER_RESET - Reset an interval timer .. code:: c rtems_status_code rtems_timer_reset( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - timer reset successfully -``RTEMS_INVALID_ID`` - invalid timer id -``RTEMS_NOT_DEFINED`` - attempted to reset a when or newly created timer +``RTEMS_SUCCESSFUL`` + timer reset successfully + +``RTEMS_INVALID_ID`` + invalid timer id + +``RTEMS_NOT_DEFINED`` + attempted to reset a when or newly created timer **DESCRIPTION:** -This directive resets the timer associated with id. -This timer must have been previously initiated with either the``rtems_timer_fire_after`` or``rtems_timer_server_fire_after`` -directive. If active the timer is canceled, -after which the timer is reinitiated using the same interval and -timer service routine which the original``rtems_timer_fire_after````rtems_timer_server_fire_after`` -directive used. +This directive resets the timer associated with id. This timer must have been +previously initiated with either the ``rtems_timer_fire_after`` or +``rtems_timer_server_fire_after`` directive. If active the timer is canceled, +after which the timer is reinitiated using the same interval and timer service +routine which the original ``rtems_timer_fire_after`` or +``rtems_timer_server_fire_after`` directive used. **NOTES:** -If the timer has not been used or the last usage of this timer -was by a ``rtems_timer_fire_when`` or``rtems_timer_server_fire_when`` -directive, then the ``RTEMS_NOT_DEFINED`` error is -returned. +If the timer has not been used or the last usage of this timer was by a +``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, then +the ``RTEMS_NOT_DEFINED`` error is returned. -Restarting a cancelled after timer results in the timer being -reinitiated with its previous timer service routine and interval. +Restarting a cancelled after timer results in the timer being reinitiated with +its previous timer service routine and interval. This directive will not cause the running task to be preempted. - -.. COMMENT: COPYRIGHT (c) 1988-2013. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -.. COMMENT: Open Issues - -.. COMMENT: - nicen up the tables - -.. COMMENT: - use math mode to print formulas - |
