Changeset b8d3f6b in rtems-docs


Ignore:
Timestamp:
Jan 24, 2016, 10:37:53 AM (4 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, master
Children:
c18d76a
Parents:
0f5ccd4
git-author:
Chris Johns <chrisj@…> (01/24/16 10:37:53)
git-committer:
Amar Takhar <verm@…> (05/03/16 00:51:25)
Message:

C user guide clean up. Up to timer manager.

Location:
c_user
Files:
3 added
11 edited

Legend:

Unmodified
Added
Removed
  • c_user/clock_manager.rst

    r0f5ccd4 rb8d3f6b  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Clock Manager
    26#############
     
    1115the clock manager are:
    1216
    13 - ``rtems_clock_set`` - Set date and time
    14 
    15 - ``rtems_clock_get`` - Get date and time information
    16 
    17 - ``rtems_clock_get_tod`` - Get date and time in TOD format
    18 
    19 - ``rtems_clock_get_tod_timeval`` - Get date and time in timeval format
    20 
    21 - ``rtems_clock_get_seconds_since_epoch`` - Get seconds since epoch
    22 
    23 - ``rtems_clock_get_ticks_per_second`` - Get ticks per second
    24 
    25 - ``rtems_clock_get_ticks_since_boot`` - Get current ticks counter value
    26 
    27 - ``rtems_clock_tick_later`` - Get tick value in the future
    28 
    29 - ``rtems_clock_tick_later_usec`` - Get tick value in the future in microseconds
    30 
    31 - ``rtems_clock_tick_before`` - Is tick value is before a point in time
    32 
    33 - ``rtems_clock_get_uptime`` - Get time since boot
    34 
    35 - ``rtems_clock_get_uptime_timeval`` - Get time since boot in timeval format
    36 
    37 - ``rtems_clock_get_uptime_seconds`` - Get seconds since boot
    38 
    39 - ``rtems_clock_get_uptime_nanoseconds`` - Get nanoseconds since boot
    40 
    41 - ``rtems_clock_set_nanoseconds_extension`` - Install the nanoseconds since last tick handler
    42 
    43 - ``rtems_clock_tick`` - Announce a clock tick
     17- rtems_clock_set_ - Set date and time
     18
     19- rtems_clock_get_ - Get date and time information
     20
     21- rtems_clock_get_tod_ - Get date and time in TOD format
     22
     23- rtems_clock_get_tod_timeval_ - Get date and time in timeval format
     24
     25- rtems_clock_get_seconds_since_epoch_ - Get seconds since epoch
     26
     27- rtems_clock_get_ticks_per_second_ - Get ticks per second
     28
     29- rtems_clock_get_ticks_since_boot_ - Get current ticks counter value
     30
     31- rtems_clock_tick_later_ - Get tick value in the future
     32
     33- rtems_clock_tick_later_usec_ - Get tick value in the future in microseconds
     34
     35- rtems_clock_tick_before_ - Is tick value is before a point in time
     36
     37- rtems_clock_get_uptime_ - Get time since boot
     38
     39- rtems_clock_get_uptime_timeval_ - Get time since boot in timeval format
     40
     41- rtems_clock_get_uptime_seconds_ - Get seconds since boot
     42
     43- rtems_clock_get_uptime_nanoseconds_ - Get nanoseconds since boot
     44
     45- rtems_clock_set_nanoseconds_extension_ - Install the nanoseconds since last tick handler
     46
     47- rtems_clock_tick_ - Announce a clock tick
    4448
    4549Background
     
    4953----------------
    5054
    51 For the features provided by the clock manager to be
    52 utilized, periodic timer interrupts are required.  Therefore, a
    53 real-time clock or hardware timer is necessary to create the
    54 timer interrupts.  The ``rtems_clock_tick``
    55 directive is normally called
    56 by the timer ISR to announce to RTEMS that a system clock tick
    57 has occurred.  Elapsed time is measured in ticks.  A tick is
    58 defined to be an integral number of microseconds which is
    59 specified by the user in the Configuration Table.
     55For the features provided by the clock manager to be utilized, periodic timer
     56interrupts are required.  Therefore, a real-time clock or hardware timer is
     57necessary to create the timer interrupts.  The ``rtems_clock_tick`` directive
     58is normally called by the timer ISR to announce to RTEMS that a system clock
     59tick has occurred.  Elapsed time is measured in ticks.  A tick is defined to be
     60an integral number of microseconds which is specified by the user in the
     61Configuration Table.
    6062
    6163
     
    6365-----------------------------
    6466
    65 The clock facilities of the clock manager operate
    66 upon calendar time.  These directives utilize the following date
    67 and time structure for the native time and date format:
     67The clock facilities of the clock manager operate upon calendar time.  These
     68directives utilize the following date and time structure for the native time
     69and date format:
     70
    6871.. index:: rtems_time_of_day
    6972
     
    7174
    7275    struct rtems_tod_control {
    73     uint32_t year;   /* greater than 1987 \*/
    74     uint32_t month;  /* 1 - 12 \*/
    75     uint32_t day;    /* 1 - 31 \*/
    76     uint32_t hour;   /* 0 - 23 \*/
    77     uint32_t minute; /* 0 - 59 \*/
    78     uint32_t second; /* 0 - 59 \*/
    79     uint32_t ticks;  /* elapsed between seconds \*/
     76        uint32_t year;   /* greater than 1987 */
     77        uint32_t month;  /* 1 - 12 */
     78        uint32_t day;    /* 1 - 31 */
     79        uint32_t hour;   /* 0 - 23 */
     80        uint32_t minute; /* 0 - 59 */
     81        uint32_t second; /* 0 - 59 */
     82        uint32_t ticks;  /* elapsed between seconds */
    8083    };
    8184    typedef struct rtems_tod_control rtems_time_of_day;
    8285
    83 The native date and time format is the only format
    84 supported when setting the system date and time using the``rtems_clock_set`` directive.  Some applications
    85 expect to operate on a "UNIX-style" date and time data structure.  The``rtems_clock_get_tod_timeval`` always returns
    86 the date and time in ``struct timeval`` format.  The``rtems_clock_get`` directive can optionally return
    87 the current date and time in this format.
    88 
    89 The ``struct timeval`` data structure has two fields: ``tv_sec``
    90 and ``tv_usec`` which are seconds and microseconds, respectively.
    91 The ``tv_sec`` field in this data structure is the number of seconds
    92 since the POSIX epoch of January 1, 1970 but will never be prior to
    93 the RTEMS epoch of January 1, 1988.
     86The native date and time format is the only format supported when setting the
     87system date and time using the ``rtems_clock_set`` directive.  Some
     88applications expect to operate on a *UNIX-style* date and time data structure.
     89The ``rtems_clock_get_tod_timeval`` always returns the date and time in
     90``struct timeval`` format.  The ``rtems_clock_get`` directive can optionally
     91return the current date and time in this format.
     92
     93The ``struct timeval`` data structure has two fields: ``tv_sec`` and
     94``tv_usec`` which are seconds and microseconds, respectively.  The ``tv_sec``
     95field in this data structure is the number of seconds since the POSIX epoch of
     96*January 1, 1970* but will never be prior to the RTEMS epoch of *January 1,
     971988*.
    9498
    9599Clock Tick and Timeslicing
     
    97101.. index:: timeslicing
    98102
    99 Timeslicing is a task scheduling discipline in which
    100 tasks of equal priority are executed for a specific period of
    101 time before control of the CPU is passed to another task.  It is
    102 also sometimes referred to as the automatic round-robin
    103 scheduling algorithm.  The length of time allocated to each task
    104 is known as the quantum or timeslice.
    105 
    106 The system's timeslice is defined as an integral
    107 number of ticks, and is specified in the Configuration Table.
    108 The timeslice is defined for the entire system of tasks, but
    109 timeslicing is enabled and disabled on a per task basis.
    110 
    111 The ``rtems_clock_tick``
    112 directive implements timeslicing by
    113 decrementing the running task's time-remaining counter when both
    114 timeslicing and preemption are enabled.  If the task's timeslice
    115 has expired, then that task will be preempted if there exists a
    116 ready task of equal priority.
     103Timeslicing is a task scheduling discipline in which tasks of equal priority
     104are executed for a specific period of time before control of the CPU is passed
     105to another task.  It is also sometimes referred to as the automatic round-robin
     106scheduling algorithm.  The length of time allocated to each task is known as
     107the quantum or timeslice.
     108
     109The system's timeslice is defined as an integral number of ticks, and is
     110specified in the Configuration Table.  The timeslice is defined for the entire
     111system of tasks, but timeslicing is enabled and disabled on a per task basis.
     112
     113The ``rtems_clock_tick`` directive implements timeslicing by decrementing the
     114running task's time-remaining counter when both timeslicing and preemption are
     115enabled.  If the task's timeslice has expired, then that task will be preempted
     116if there exists a ready task of equal priority.
    117117
    118118Delays
     
    120120.. index:: delays
    121121
    122 A sleep timer allows a task to delay for a given
    123 interval or up until a given time, and then wake and continue
    124 execution.  This type of timer is created automatically by the``rtems_task_wake_after``
    125 and ``rtems_task_wake_when`` directives and, as a result,
    126 does not have an RTEMS ID.  Once activated, a sleep timer cannot
    127 be explicitly deleted.  Each task may activate one and only one
    128 sleep timer at a time.
     122A sleep timer allows a task to delay for a given interval or up until a given
     123time, and then wake and continue execution.  This type of timer is created
     124automatically by the ``rtems_task_wake_after`` and ``rtems_task_wake_when``
     125directives and, as a result, does not have an RTEMS ID.  Once activated, a
     126sleep timer cannot be explicitly deleted.  Each task may activate one and only
     127one sleep timer at a time.
    129128
    130129Timeouts
     
    132131.. index:: timeouts
    133132
    134 Timeouts are a special type of timer automatically
    135 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.
    136 Each task may have one and only one timeout active at a time.
    137 When a timeout expires, it unblocks the task with a timeout status code.
     133Timeouts are a special type of timer automatically created when the timeout
     134option is used on the ``rtems_message_queue_receive``, ``rtems_event_receive``,
     135``rtems_semaphore_obtain`` and ``rtems_region_get_segment`` directives.  Each
     136task may have one and only one timeout active at a time.  When a timeout
     137expires, it unblocks the task with a timeout status code.
    138138
    139139Operations
     
    143143-----------------
    144144
    145 RTEMS provides the ``rtems_clock_tick`` directive which is
    146 called from the user's real-time clock ISR to inform RTEMS that
    147 a tick has elapsed.  The tick frequency value, defined in
    148 microseconds, is a configuration parameter found in the
    149 Configuration Table.  RTEMS divides one million microseconds
    150 (one second) by the number of microseconds per tick to determine
    151 the number of calls to the``rtems_clock_tick`` directive per second.  The
    152 frequency of ``rtems_clock_tick``
    153 calls determines the resolution
    154 (granularity) for all time dependent RTEMS actions.  For
    155 example, calling ``rtems_clock_tick``
    156 ten times per second yields a higher
    157 resolution than calling ``rtems_clock_tick``
    158 two times per second.  The ``rtems_clock_tick``
    159 directive is responsible for maintaining both
    160 calendar time and the dynamic set of timers.
     145RTEMS provides the ``rtems_clock_tick`` directive which is called from the
     146user's real-time clock ISR to inform RTEMS that a tick has elapsed.  The tick
     147frequency value, defined in microseconds, is a configuration parameter found in
     148the Configuration Table.  RTEMS divides one million microseconds (one second)
     149by the number of microseconds per tick to determine the number of calls to
     150the``rtems_clock_tick`` directive per second.  The frequency of
     151``rtems_clock_tick`` calls determines the resolution (granularity) for all time
     152dependent RTEMS actions.  For example, calling ``rtems_clock_tick`` ten times
     153per second yields a higher resolution than calling ``rtems_clock_tick`` two
     154times per second.  The ``rtems_clock_tick`` directive is responsible for
     155maintaining both calendar time and the dynamic set of timers.
    161156
    162157Setting the Time
    163158----------------
    164159
    165 The ``rtems_clock_set`` directive allows a task or an ISR to
    166 set the date and time maintained by RTEMS.  If setting the date
    167 and time causes any outstanding timers to pass their deadline,
    168 then the expired timers will be fired during the invocation of
    169 the ``rtems_clock_set`` directive.
     160The ``rtems_clock_set`` directive allows a task or an ISR to set the date and
     161time maintained by RTEMS.  If setting the date and time causes any outstanding
     162timers to pass their deadline, then the expired timers will be fired during the
     163invocation of the ``rtems_clock_set`` directive.
    170164
    171165Obtaining the Time
    172166------------------
    173167
    174 The ``rtems_clock_get`` directive allows a task or an ISR to
    175 obtain the current date and time or date and time related
    176 information.  The current date and time can be returned in
    177 either native or UNIX-style format.  Additionally, the
    178 application can obtain date and time related information such as
    179 the number of seconds since the RTEMS epoch, the number of ticks
    180 since the executive was initialized, and the number of ticks per
    181 second.  The information returned by the``rtems_clock_get`` directive is
    182 dependent on the option selected by the caller.  This
    183 is specified using one of the following constants
    184 associated with the enumerated type``rtems_clock_get_options``:.. index:: rtems_clock_get_options
    185 
    186 - ``RTEMS_CLOCK_GET_TOD`` - obtain native style date and time
    187 
    188 - ``RTEMS_CLOCK_GET_TIME_VALUE`` - obtain UNIX-style
    189   date and time
    190 
    191 - ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` - obtain number of ticks
    192   since RTEMS was initialized
    193 
    194 - ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` - obtain number
    195   of seconds since RTEMS epoch
    196 
    197 - ``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` - obtain number of clock
    198   ticks per second
    199 
    200 Calendar time operations will return an error code if
    201 invoked before the date and time have been set.
     168The ``rtems_clock_get`` directive allows a task or an ISR to obtain the current
     169date and time or date and time related information.  The current date and time
     170can be returned in either native or *UNIX-style* format.  Additionally, the
     171application can obtain date and time related information such as the number of
     172seconds since the RTEMS epoch, the number of ticks since the executive was
     173initialized, and the number of ticks per second.  The information returned by
     174the``rtems_clock_get`` directive is dependent on the option selected by the
     175caller.  This is specified using one of the following constants associated with
     176the enumerated type ``rtems_clock_get_options``:
     177
     178.. index:: rtems_clock_get_options
     179
     180``RTEMS_CLOCK_GET_TOD``
     181  obtain native style date and time
     182
     183``RTEMS_CLOCK_GET_TIME_VALUE``
     184  obtain *UNIX-style* date and time
     185
     186``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``
     187  obtain number of ticks since RTEMS was initialized
     188
     189``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``
     190  obtain number of seconds since RTEMS epoch
     191
     192``RTEMS_CLOCK_GET_TICKS_PER_SECOND``
     193  obtain number of clock ticks per second
     194
     195Calendar time operations will return an error code if invoked before the date
     196and time have been set.
    202197
    203198Directives
    204199==========
    205200
    206 This section details the clock manager's directives.
    207 A subsection is dedicated to each of this manager's directives
    208 and describes the calling sequence, related constants, usage,
    209 and status codes.
     201This section details the clock manager's directives.  A subsection is dedicated
     202to each of this manager's directives and describes the calling sequence,
     203related constants, usage, and status codes.
     204
     205.. _rtems_clock_set:
    210206
    211207CLOCK_SET - Set date and time
     
    221217
    222218    rtems_status_code rtems_clock_set(
    223     rtems_time_of_day \*time_buffer
    224     );
    225 
    226 **DIRECTIVE STATUS CODES:**
    227 
    228 ``RTEMS_SUCCESSFUL`` - date and time set successfully
    229 ``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
    230 ``RTEMS_INVALID_CLOCK`` - invalid time of day
    231 
    232 **DESCRIPTION:**
    233 
    234 This directive sets the system date and time.  The
    235 date, time, and ticks in the time_buffer structure are all
    236 range-checked, and an error is returned if any one is out of its
    237 valid range.
     219        rtems_time_of_day *time_buffer
     220    );
     221
     222**DIRECTIVE STATUS CODES:**
     223
     224``RTEMS_SUCCESSFUL``
     225  date and time set successfully
     226
     227``RTEMS_INVALID_ADDRESS``
     228  ``time_buffer`` is NULL
     229
     230``RTEMS_INVALID_CLOCK``
     231  invalid time of day
     232
     233**DESCRIPTION:**
     234
     235This directive sets the system date and time.  The date, time, and ticks in the
     236time_buffer structure are all range-checked, and an error is returned if any
     237one is out of its valid range.
    238238
    239239**NOTES:**
     
    241241Years before 1988 are invalid.
    242242
    243 The system date and time are based on the configured
    244 tick rate (number of microseconds in a tick).
    245 
    246 Setting the time forward may cause a higher priority
    247 task, blocked waiting on a specific time, to be made ready.  In
    248 this case, the calling task will be preempted after the next
    249 clock tick.
    250 
    251 Re-initializing RTEMS causes the system date and time
    252 to be reset to an uninitialized state.  Another call to``rtems_clock_set`` is required to re-initialize
    253 the system date and time to application specific specifications.
     243The system date and time are based on the configured tick rate (number of
     244microseconds in a tick).
     245
     246Setting the time forward may cause a higher priority task, blocked waiting on a
     247specific time, to be made ready.  In this case, the calling task will be
     248preempted after the next clock tick.
     249
     250Re-initializing RTEMS causes the system date and time to be reset to an
     251uninitialized state.  Another call to ``rtems_clock_set`` is required to
     252re-initialize the system date and time to application specific specifications.
     253
     254.. _rtems_clock_get:
    254255
    255256CLOCK_GET - Get date and time information
     
    257258.. index:: obtain the time of day
    258259
     260.. warning::
     261
     262  This directive is deprecated and will be removed.
     263
    259264**CALLING SEQUENCE:**
    260265
     
    264269
    265270    rtems_status_code rtems_clock_get(
    266     rtems_clock_get_options  option,
    267     void                    \*time_buffer
    268     );
    269 
    270 **DIRECTIVE STATUS CODES:**
    271 
    272 ``RTEMS_SUCCESSFUL`` - current time obtained successfully
    273 ``RTEMS_NOT_DEFINED`` - system date and time is not set
    274 ``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
    275 
    276 **DESCRIPTION:**
    277 
    278 This directive is deprecated.
    279 
    280 This directive obtains the system date and time.  If
    281 the caller is attempting to obtain the date and time (i.e.
    282 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
    283 has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned.
    284 The caller can always obtain the number of ticks per second (option is``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number of
    285 ticks since the executive was initialized option is``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``).
    286 
    287 The ``option`` argument may taken on any value of the enumerated
    288 type ``rtems_clock_get_options``.  The data type expected for``time_buffer`` is based on the value of ``option`` as
    289 indicated below:.. index:: rtems_clock_get_options
    290 
    291 - ``RTEMS_CLOCK_GET_TOD`` - (rtems_time_of_day \*)
    292 
    293 - ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` - (rtems_interval \*)
    294 
    295 - ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` - (rtems_interval \*)
    296 
    297 - ``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` - (rtems_interval \*)
    298 
    299 - ``RTEMS_CLOCK_GET_TIME_VALUE`` - (struct timeval \*)
     271       rtems_clock_get_options  option,
     272       void                    *time_buffer
     273    );
     274
     275**DIRECTIVE STATUS CODES:**
     276
     277``RTEMS_SUCCESSFUL``
     278  current time obtained successfully
     279
     280``RTEMS_NOT_DEFINED``
     281  system date and time is not set
     282
     283``RTEMS_INVALID_ADDRESS``
     284  ``time_buffer`` is NULL
     285
     286**DESCRIPTION:**
     287
     288This directive obtains the system date and time.  If the caller is attempting
     289to obtain the date and time (i.e.  option is set to either
     290``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``, ``RTEMS_CLOCK_GET_TOD``, or
     291``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time has not been set with a
     292previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status
     293code is returned.  The caller can always obtain the number of ticks per second
     294(option is ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number of ticks since
     295the executive was initialized option is ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``).
     296
     297The ``option`` argument may taken on any value of the enumerated type
     298``rtems_clock_get_options``.  The data type expected for``time_buffer`` is
     299based on the value of ``option`` as indicated below:
     300
     301.. index:: rtems_clock_get_options
     302
     303+-----------------------------------------+---------------------------+
     304| Option                                  | Return type               |
     305+=========================================+===========================+
     306| ``RTEMS_CLOCK_GET_TOD``                 | ``(rtems_time_of_day *)`` |
     307+-----------------------------------------+---------------------------+
     308| ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` | ``(rtems_interval *)``    |
     309+-----------------------------------------+---------------------------+
     310| ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``    | ``(rtems_interval *)``    |
     311+-----------------------------------------+---------------------------+
     312|``RTEMS_CLOCK_GET_TICKS_PER_SECOND``     | ``(rtems_interval *)``    |
     313+-----------------------------------------+---------------------------+
     314| ``RTEMS_CLOCK_GET_TIME_VALUE``          | ``(struct timeval *)``    |
     315+-----------------------------------------+---------------------------+
    300316
    301317**NOTES:**
     
    303319This directive is callable from an ISR.
    304320
    305 This directive will not cause the running task to be
    306 preempted.  Re-initializing RTEMS causes the system date and
    307 time to be reset to an uninitialized state.  Another call to``rtems_clock_set`` is required to re-initialize the
    308 system date and time to application specific specifications.
     321This directive will not cause the running task to be preempted.
     322Re-initializing RTEMS causes the system date and time to be reset to an
     323uninitialized state.  Another call to ``rtems_clock_set`` is required to
     324re-initialize the system date and time to application specific specifications.
     325
     326.. _rtems_clock_get_tod:
    309327
    310328CLOCK_GET_TOD - Get date and time in TOD format
     
    319337
    320338    rtems_status_code rtems_clock_get_tod(
    321     rtems_time_of_day \*time_buffer
    322     );
    323 
    324 **DIRECTIVE STATUS CODES:**
    325 
    326 ``RTEMS_SUCCESSFUL`` - current time obtained successfully
    327 ``RTEMS_NOT_DEFINED`` - system date and time is not set
    328 ``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
    329 
    330 **DESCRIPTION:**
    331 
    332 This directive obtains the system date and time.  If the date and time
    333 has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned.
     339        rtems_time_of_day *time_buffer
     340    );
     341
     342**DIRECTIVE STATUS CODES:**
     343
     344``RTEMS_SUCCESSFUL``
     345  current time obtained successfully
     346
     347``RTEMS_NOT_DEFINED``
     348  system date and time is not set
     349
     350``RTEMS_INVALID_ADDRESS``
     351  ``time_buffer`` is NULL
     352
     353**DESCRIPTION:**
     354
     355This directive obtains the system date and time.  If the date and time has not
     356been set with a previous call to ``rtems_clock_set``, then the
     357``RTEMS_NOT_DEFINED`` status code is returned.
    334358
    335359**NOTES:**
     
    337361This directive is callable from an ISR.
    338362
    339 This directive will not cause the running task to be
    340 preempted.  Re-initializing RTEMS causes the system date and
    341 time to be reset to an uninitialized state.  Another call to``rtems_clock_set`` is required to re-initialize the
    342 system date and time to application specific specifications.
     363This directive will not cause the running task to be preempted.
     364Re-initializing RTEMS causes the system date and time to be reset to an
     365uninitialized state.  Another call to ``rtems_clock_set`` is required to
     366re-initialize the system date and time to application specific specifications.
     367
     368.. _rtems_clock_get_tod_timeval:
    343369
    344370CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
     
    352378.. code:: c
    353379
    354     rtems_status_code rtems_clock_get_tod(
    355     struct timeval  \*time
    356     );
    357 
    358 **DIRECTIVE STATUS CODES:**
    359 
    360 ``RTEMS_SUCCESSFUL`` - current time obtained successfully
    361 ``RTEMS_NOT_DEFINED`` - system date and time is not set
    362 ``RTEMS_INVALID_ADDRESS`` - ``time`` is NULL
    363 
    364 **DESCRIPTION:**
    365 
    366 This directive obtains the system date and time in POSIX``struct timeval`` format.  If the date and time
    367 has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned.
     380    rtems_status_code rtems_clock_get_tod_interval(
     381        struct timeval  *time
     382    );
     383
     384**DIRECTIVE STATUS CODES:**
     385
     386``RTEMS_SUCCESSFUL``
     387  current time obtained successfully
     388
     389``RTEMS_NOT_DEFINED``
     390  system date and time is not set
     391
     392``RTEMS_INVALID_ADDRESS``
     393  ``time`` is NULL
     394
     395**DESCRIPTION:**
     396
     397This directive obtains the system date and time in POSIX ``struct timeval``
     398format.  If the date and time has not been set with a previous call to
     399``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status code is returned.
    368400
    369401**NOTES:**
     
    371403This directive is callable from an ISR.
    372404
    373 This directive will not cause the running task to be
    374 preempted.  Re-initializing RTEMS causes the system date and
    375 time to be reset to an uninitialized state.  Another call to``rtems_clock_set`` is required to re-initialize the
    376 system date and time to application specific specifications.
     405This directive will not cause the running task to be preempted.
     406Re-initializing RTEMS causes the system date and time to be reset to an
     407uninitialized state.  Another call to ``rtems_clock_set`` is required to
     408re-initialize the system date and time to application specific specifications.
     409
     410.. _rtems_clock_get_seconds_since_epoch:
    377411
    378412CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
     
    387421
    388422    rtems_status_code rtems_clock_get_seconds_since_epoch(
    389     rtems_interval \*the_interval
    390     );
    391 
    392 **DIRECTIVE STATUS CODES:**
    393 
    394 ``RTEMS_SUCCESSFUL`` - current time obtained successfully
    395 ``RTEMS_NOT_DEFINED`` - system date and time is not set
    396 ``RTEMS_INVALID_ADDRESS`` - ``the_interval`` is NULL
    397 
    398 **DESCRIPTION:**
    399 
    400 This directive returns the number of seconds since the RTEMS
    401 epoch and the current system date and time.  If the date and time
    402 has not been set with a previous call to``rtems_clock_set``, then the``RTEMS_NOT_DEFINED`` status code is returned.
     423        rtems_interval *the_interval
     424    );
     425
     426**DIRECTIVE STATUS CODES:**
     427
     428``RTEMS_SUCCESSFUL``
     429  current time obtained successfully
     430
     431``RTEMS_NOT_DEFINED``
     432  system date and time is not set
     433
     434``RTEMS_INVALID_ADDRESS``
     435  ``the_interval`` is NULL
     436
     437**DESCRIPTION:**
     438
     439This directive returns the number of seconds since the RTEMS epoch and the
     440current system date and time.  If the date and time has not been set with a
     441previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status
     442code is returned.
    403443
    404444**NOTES:**
     
    406446This directive is callable from an ISR.
    407447
    408 This directive will not cause the running task to be
    409 preempted.  Re-initializing RTEMS causes the system date and
    410 time to be reset to an uninitialized state.  Another call to``rtems_clock_set`` is required to re-initialize the
    411 system date and time to application specific specifications.
     448This directive will not cause the running task to be preempted.
     449Re-initializing RTEMS causes the system date and time to be reset to an
     450uninitialized state.  Another call to ``rtems_clock_set`` is required to
     451re-initialize the system date and time to application specific specifications.
     452
     453.. _rtems_clock_get_ticks_per_second:
    412454
    413455CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
     
    429471**DESCRIPTION:**
    430472
    431 This directive returns the number of clock ticks per second.  This
    432 is strictly based upon the microseconds per clock tick that the
    433 application has configured.
     473This directive returns the number of clock ticks per second.  This is strictly
     474based upon the microseconds per clock tick that the application has configured.
    434475
    435476**NOTES:**
     
    438479
    439480This directive will not cause the running task to be preempted.
     481
     482.. _rtems_clock_get_ticks_since_boot:
    440483
    441484CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value
     
    460503This directive returns the current tick counter value.  With a 1ms clock tick,
    461504this counter overflows after 50 days since boot.  This is the historical
    462 measure of uptime in an RTEMS system.  The newer service``rtems_clock_get_uptime`` is another and potentially more
    463 accurate way of obtaining similar information.
     505measure of uptime in an RTEMS system.  The newer service
     506``rtems_clock_get_uptime`` is another and potentially more accurate way of
     507obtaining similar information.
    464508
    465509**NOTES:**
     
    468512
    469513This directive will not cause the running task to be preempted.
     514
     515.. _rtems_clock_tick_later:
    470516
    471517CLOCK_TICK_LATER - Get tick value in the future
     
    479525
    480526    rtems_interval rtems_clock_tick_later(
    481     rtems_interval delta
     527        rtems_interval delta
    482528    );
    483529
     
    491537
    492538This directive will not cause the running task to be preempted.
     539
     540.. _rtems_clock_tick_later_usec:
    493541
    494542CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds
     
    502550
    503551    rtems_interval rtems_clock_tick_later_usec(
    504     rtems_interval delta_in_usec
     552        rtems_interval delta_in_usec
    505553    );
    506554
     
    514562
    515563This directive will not cause the running task to be preempted.
     564
     565.. _rtems_clock_tick_before:
    516566
    517567CLOCK_TICK_BEFORE - Is tick value is before a point in time
     
    525575
    526576    rtems_interval rtems_clock_tick_before(
    527     rtems_interval tick
     577        rtems_interval tick
    528578    );
    529579
     
    545595    status busy( void )
    546596    {
    547     rtems_interval timeout = rtems_clock_tick_later_usec( 10000 );
    548     do {
    549     if ( ok() ) {
    550     return success;
     597        rtems_interval timeout = rtems_clock_tick_later_usec( 10000 );
     598        do {
     599            if ( ok() ) {
     600                return success;
     601            }
     602        } while ( rtems_clock_tick_before( timeout ) );
     603        return timeout;
    551604    }
    552     } while ( rtems_clock_tick_before( timeout ) );
    553     return timeout;
    554     }
     605
     606.. _rtems_clock_get_uptime:
    555607
    556608CLOCK_GET_UPTIME - Get the time since boot
     
    566618
    567619    rtems_status_code rtems_clock_get_uptime(
    568     struct timespec \*uptime
    569     );
    570 
    571 **DIRECTIVE STATUS CODES:**
    572 
    573 ``RTEMS_SUCCESSFUL`` - clock tick processed successfully
    574 ``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
    575 
    576 **DESCRIPTION:**
    577 
    578 This directive returns the seconds and nanoseconds since the
    579 system was booted.  If the BSP supports nanosecond clock
    580 accuracy, the time reported will probably be different on every
    581 call.
     620        struct timespec *uptime
     621    );
     622
     623**DIRECTIVE STATUS CODES:**
     624
     625``RTEMS_SUCCESSFUL``
     626  clock tick processed successfully
     627
     628``RTEMS_INVALID_ADDRESS``
     629  ``time_buffer`` is NULL
     630
     631**DESCRIPTION:**
     632
     633This directive returns the seconds and nanoseconds since the system was booted.
     634If the BSP supports nanosecond clock accuracy, the time reported will probably
     635be different on every call.
    582636
    583637**NOTES:**
    584638
    585639This directive may be called from an ISR.
     640
     641.. _rtems_clock_get_uptime_timeval:
    586642
    587643CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
    588644--------------------------------------------------------------------
    589 .. index:: clock get uptime
     645.. index:: clock get uptime interval
    590646.. index:: uptime
    591647
     
    597653
    598654    void rtems_clock_get_uptime_timeval(
    599     struct timeval \*uptime
     655        struct timeval *uptime
    600656    );
    601657
     
    606662**DESCRIPTION:**
    607663
    608 This directive returns the seconds and microseconds since the
    609 system was booted.  If the BSP supports nanosecond clock
    610 accuracy, the time reported will probably be different on every
    611 call.
     664This directive returns the seconds and microseconds since the system was
     665booted.  If the BSP supports nanosecond clock accuracy, the time reported will
     666probably be different on every call.
    612667
    613668**NOTES:**
    614669
    615670This directive may be called from an ISR.
     671
     672.. _rtems_clock_get_uptime_seconds:
    616673
    617674CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
    618675-----------------------------------------------------
    619 .. index:: clock get uptime
     676.. index:: clock get uptime seconds
    620677.. index:: uptime
    621678
     
    639696
    640697This directive may be called from an ISR.
     698
     699.. _rtems_clock_get_uptime_nanoseconds:
    641700
    642701CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot
     
    664723
    665724This directive may be called from an ISR.
     725
     726.. _rtems_clock_set_nanoseconds_extension:
    666727
    667728CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
     
    678739
    679740    rtems_status_code rtems_clock_set_nanoseconds_extension(
    680     rtems_nanoseconds_extension_routine routine
    681     );
    682 
    683 **DIRECTIVE STATUS CODES:**
    684 
    685 ``RTEMS_SUCCESSFUL`` - clock tick processed successfully
    686 ``RTEMS_INVALID_ADDRESS`` - ``time_buffer`` is NULL
    687 
    688 **DESCRIPTION:**
    689 
    690 This directive is used by the Clock device driver to install the``routine`` which will be invoked by the internal RTEMS method used to
    691 obtain a highly accurate time of day.  It is usually called during
    692 the initialization of the driver.
    693 
    694 When the ``routine`` is invoked, it will determine the number of
    695 nanoseconds which have elapsed since the last invocation of
    696 the ``rtems_clock_tick`` directive.  It should do
    697 this as quickly as possible with as little impact as possible
    698 on the device used as a clock source.
     741        rtems_nanoseconds_extension_routine routine
     742    );
     743
     744**DIRECTIVE STATUS CODES:**
     745
     746``RTEMS_SUCCESSFUL``
     747  clock tick processed successfully
     748
     749``RTEMS_INVALID_ADDRESS``
     750  ``time_buffer`` is NULL
     751
     752**DESCRIPTION:**
     753
     754This directive is used by the Clock device driver to install the ``routine``
     755which will be invoked by the internal RTEMS method used to obtain a highly
     756accurate time of day.  It is usually called during the initialization of the
     757driver.
     758
     759When the ``routine`` is invoked, it will determine the number of nanoseconds
     760which have elapsed since the last invocation of the ``rtems_clock_tick``
     761directive.  It should do this as quickly as possible with as little impact as
     762possible on the device used as a clock source.
    699763
    700764**NOTES:**
     
    702766This directive may be called from an ISR.
    703767
    704 This directive is called as part of every service to obtain the
    705 current date and time as well as timestamps.
     768This directive is called as part of every service to obtain the current date
     769and time as well as timestamps.
     770
     771.. _rtems_clock_tick:
    706772
    707773CLOCK_TICK - Announce a clock tick
     
    719785**DIRECTIVE STATUS CODES:**
    720786
    721 ``RTEMS_SUCCESSFUL`` - clock tick processed successfully
    722 
    723 **DESCRIPTION:**
    724 
    725 This directive announces to RTEMS that a system clock
    726 tick has occurred.  The directive is usually called from the
    727 timer interrupt ISR of the local processor.  This directive
    728 maintains the system date and time, decrements timers for
    729 delayed tasks, timeouts, rate monotonic periods, and implements
     787``RTEMS_SUCCESSFUL``
     788  clock tick processed successfully
     789
     790**DESCRIPTION:**
     791
     792This directive announces to RTEMS that a system clock tick has occurred.  The
     793directive is usually called from the timer interrupt ISR of the local
     794processor.  This directive maintains the system date and time, decrements
     795timers for delayed tasks, timeouts, rate monotonic periods, and implements
    730796timeslicing.
    731797
     
    734800This directive is typically called from an ISR.
    735801
    736 The ``microseconds_per_tick`` and ``ticks_per_timeslice``
    737 parameters in the Configuration Table contain the number of
    738 microseconds per tick and number of ticks per timeslice,
    739 respectively.
    740 
    741 .. COMMENT: COPYRIGHT (c) 1988-2008.
    742 
    743 .. COMMENT: On-Line Applications Research Corporation (OAR).
    744 
    745 .. COMMENT: All rights reserved.
    746 
     802The ``microseconds_per_tick`` and ``ticks_per_timeslice`` parameters in the
     803Configuration Table contain the number of microseconds per tick and number of
     804ticks per timeslice, respectively.
  • c_user/initialization.rst

    r0f5ccd4 rb8d3f6b  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Initialization Manager
    26######################
     
    59============
    610
    7 The Initialization Manager is responsible for
    8 initiating and shutting down RTEMS.  Initiating RTEMS involves
    9 creating and starting all configured initialization tasks, and
    10 for invoking the initialization routine for each user-supplied
    11 device driver.  In a multiprocessor configuration, this manager
    12 also initializes the interprocessor communications layer.  The
    13 directives provided by the Initialization Manager are:
     11The Initialization Manager is responsible for initiating and shutting down
     12RTEMS.  Initiating RTEMS involves creating and starting all configured
     13initialization tasks, and for invoking the initialization routine for each
     14user-supplied device driver.  In a multiprocessor configuration, this manager
     15also initializes the interprocessor communications layer.  The directives
     16provided by the Initialization Manager are:
    1417
    1518- ``rtems_initialize_executive`` - Initialize RTEMS
     
    2427.. index:: initialization tasks
    2528
    26 Initialization task(s) are the mechanism by which
    27 RTEMS transfers initial control to the user's application.
    28 Initialization tasks differ from other application tasks in that
    29 they are defined in the User Initialization Tasks Table and
    30 automatically created and started by RTEMS as part of its
    31 initialization sequence.  Since the initialization tasks are
    32 scheduled using the same algorithm as all other RTEMS tasks,
    33 they must be configured at a priority and mode which will ensure
    34 that they will complete execution before other application tasks
    35 execute.  Although there is no upper limit on the number of
    36 initialization tasks, an application is required to define at
    37 least one.
    38 
    39 A typical initialization task will create and start
    40 the static set of application tasks.  It may also create any
    41 other objects used by the application.  Initialization tasks
    42 which only perform initialization should delete themselves upon
    43 completion to free resources for other tasks.  Initialization
    44 tasks may transform themselves into a "normal" application task.
    45 This transformation typically involves changing priority and
    46 execution mode.  RTEMS does not automatically delete the
    47 initialization tasks.
     29Initialization task(s) are the mechanism by which RTEMS transfers initial
     30control to the user's application.  Initialization tasks differ from other
     31application tasks in that they are defined in the User Initialization Tasks
     32Table and automatically created and started by RTEMS as part of its
     33initialization sequence.  Since the initialization tasks are scheduled using
     34the same algorithm as all other RTEMS tasks, they must be configured at a
     35priority and mode which will ensure that they will complete execution before
     36other application tasks execute.  Although there is no upper limit on the
     37number of initialization tasks, an application is required to define at least
     38one.
     39
     40A typical initialization task will create and start the static set of
     41application tasks.  It may also create any other objects used by the
     42application.  Initialization tasks which only perform initialization should
     43delete themselves upon completion to free resources for other tasks.
     44Initialization tasks may transform themselves into a "normal" application task.
     45This transformation typically involves changing priority and execution mode.
     46RTEMS does not automatically delete the initialization tasks.
    4847
    4948System Initialization
    5049---------------------
    5150
    52 System Initialization begins with board reset and continues
    53 through RTEMS initialization, initialization of all device
    54 drivers, and eventually a context switch to the first user
    55 task.  Remember, that interrupts are disabled during
    56 initialization and the *initialization context* is not
    57 a task in any sense and the user should be very careful
    58 during initialization.
    59 
    60 The BSP must ensure that the there is enough stack
    61 space reserved for the initialization context to
    62 successfully execute the initialization routines for
    63 all device drivers and, in multiprocessor configurations, the
    64 Multiprocessor Communications Interface Layer initialization
    65 routine.
     51System Initialization begins with board reset and continues through RTEMS
     52initialization, initialization of all device drivers, and eventually a context
     53switch to the first user task.  Remember, that interrupts are disabled during
     54initialization and the *initialization context* is not a task in any sense and
     55the user should be very careful during initialization.
     56
     57The BSP must ensure that the there is enough stack space reserved for the
     58initialization context to successfully execute the initialization routines for
     59all device drivers and, in multiprocessor configurations, the Multiprocessor
     60Communications Interface Layer initialization routine.
    6661
    6762The Idle Task
    6863-------------
    6964
    70 The Idle Task is the lowest priority task in a system
    71 and executes only when no other task is ready to execute.  This
    72 default implementation of this task consists of an infinite
    73 loop. RTEMS allows the Idle Task body to be replaced by a CPU
    74 specific implementation, a BSP specific implementation or an
    75 application specific implementation.
    76 
    77 The Idle Task is preemptible and *WILL* be preempted when
    78 any other task is made ready to execute.  This characteristic is
    79 critical to the overall behavior of any application.
     65The Idle Task is the lowest priority task in a system and executes only when no
     66other task is ready to execute.  This default implementation of this task
     67consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by
     68a CPU specific implementation, a BSP specific implementation or an application
     69specific implementation.
     70
     71The Idle Task is preemptible and *WILL* be preempted when any other task is
     72made ready to execute.  This characteristic is critical to the overall behavior
     73of any application.
    8074
    8175Initialization Manager Failure
    8276------------------------------
    8377
    84 The ``rtems_fatal_error_occurred`` directive will
    85 be invoked from ``rtems_initialize_executive``
    86 for any of the following reasons:
    87 
    88 - If either the Configuration Table or the CPU Dependent
    89   Information Table is not provided.
    90 
    91 - If the starting address of the RTEMS RAM Workspace,
    92   supplied by the application in the Configuration Table, is NULL
    93   or is not aligned on a four-byte boundary.
    94 
    95 - If the size of the RTEMS RAM Workspace is not large
    96   enough to initialize and configure the system.
     78The ``rtems_fatal_error_occurred`` directive will be invoked from
     79``rtems_initialize_executive`` for any of the following reasons:
     80
     81- If either the Configuration Table or the CPU Dependent Information Table is
     82  not provided.
     83
     84- If the starting address of the RTEMS RAM Workspace, supplied by the
     85  application in the Configuration Table, is NULL or is not aligned on a
     86  four-byte boundary.
     87
     88- If the size of the RTEMS RAM Workspace is not large enough to initialize and
     89  configure the system.
    9790
    9891- If the interrupt stack size specified is too small.
    9992
    100 - If multiprocessing is configured and the node entry in
    101   the Multiprocessor Configuration Table is not between one and
    102   the maximum_nodes entry.
    103 
    104 - If a multiprocessor system is being configured and no
    105   Multiprocessor Communications Interface is specified.
    106 
    107 - If no user initialization tasks are configured.  At
    108   least one initialization task must be configured to allow RTEMS
    109   to pass control to the application at the end of the executive
    110   initialization sequence.
    111 
    112 - If any of the user initialization tasks cannot be
    113   created or started successfully.
    114 
    115 A discussion of RTEMS actions when a fatal error occurs
    116 may be found `Announcing a Fatal Error`_.
     93- If multiprocessing is configured and the node entry in the Multiprocessor
     94  Configuration Table is not between one and the maximum_nodes entry.
     95
     96- If a multiprocessor system is being configured and no Multiprocessor
     97  Communications Interface is specified.
     98
     99- If no user initialization tasks are configured.  At least one initialization
     100  task must be configured to allow RTEMS to pass control to the application at
     101  the end of the executive initialization sequence.
     102
     103- If any of the user initialization tasks cannot be created or started
     104  successfully.
     105
     106A discussion of RTEMS actions when a fatal error occurs may be found
     107`Announcing a Fatal Error`_.
    117108
    118109Operations
     
    122113------------------
    123114
    124 The Initialization Manager ``rtems_initialize_executive``
    125 directives is called by the ``boot_card`` routine.  The ``boot_card``
    126 routine is invoked by the Board Support Package once a basic C run-time
    127 environment is set up.  This consists of
     115The Initialization Manager ``rtems_initialize_executive`` directives is called
     116by the ``boot_card`` routine.  The ``boot_card`` routine is invoked by the
     117Board Support Package once a basic C run-time environment is set up.  This
     118consists of
    128119
    129120- a valid and accessible text section, read-only data, read-write data and
     
    137128- disabled interrupts.
    138129
    139 The ``rtems_initialize_executive`` directive uses a system
    140 initialization linker set to initialize only those parts of the overall RTEMS
    141 feature set that is necessary for a particular application.  See `Linker Sets`_. 
    142 Each RTEMS feature used the application may optionally register an
    143 initialization handler.  The system initialization API is available via``#included <rtems/sysinit.h>``.
     130The ``rtems_initialize_executive`` directive uses a system initialization
     131linker set to initialize only those parts of the overall RTEMS feature set that
     132is necessary for a particular application.  See `Linker Sets`_.  Each RTEMS
     133feature used the application may optionally register an initialization handler.
     134The system initialization API is available via``#included <rtems/sysinit.h>``.
    144135
    145136A list of all initialization steps follows.  Some steps are optional depending
     
    147138execute in the order presented here.
    148139
    149 :dfn:`RTEMS_SYSINIT_BSP_WORK_AREAS`
     140`RTEMS_SYSINIT_BSP_WORK_AREAS`
    150141    The work areas consisting of C Program Heap and the RTEMS Workspace are
    151142    initialized by the Board Support Package.  This step is mandatory.
    152143
    153 :dfn:`RTEMS_SYSINIT_BSP_START`
    154     Basic initialization step provided by the Board Support Package.  This step is
    155     mandatory.
    156 
    157 :dfn:`RTEMS_SYSINIT_DATA_STRUCTURES`
    158     This directive is called when the Board Support Package has completed its basic
    159     initialization and allows RTEMS to initialize the application environment based
    160     upon the information in the Configuration Table, User Initialization Tasks
    161     Table, Device Driver Table, User Extension Table, Multiprocessor Configuration
    162     Table, and the Multiprocessor Communications Interface (MPCI) Table.
    163 
    164 :dfn:`RTEMS_SYSINIT_BSP_LIBC`
    165     Depending on the application configuration the IO library and root filesystem
    166     is initialized.  This step is mandatory.
    167 
    168 :dfn:`RTEMS_SYSINIT_BEFORE_DRIVERS`
    169     This directive performs initialization that must occur between basis RTEMS data
    170     structure initialization and device driver initialization.  In particular, in a
    171     multiprocessor configuration, this directive will create the MPCI Server Task.
    172 
    173 :dfn:`RTEMS_SYSINIT_BSP_PRE_DRIVERS`
     144`RTEMS_SYSINIT_BSP_START`
     145    Basic initialization step provided by the Board Support Package.  This step
     146    is mandatory.
     147
     148`RTEMS_SYSINIT_DATA_STRUCTURES`
     149    This directive is called when the Board Support Package has completed its
     150    basic initialization and allows RTEMS to initialize the application
     151    environment based upon the information in the Configuration Table, User
     152    Initialization Tasks Table, Device Driver Table, User Extension Table,
     153    Multiprocessor Configuration Table, and the Multiprocessor Communications
     154    Interface (MPCI) Table.
     155
     156`RTEMS_SYSINIT_BSP_LIBC`
     157    Depending on the application configuration the IO library and root
     158    filesystem is initialized.  This step is mandatory.
     159
     160`RTEMS_SYSINIT_BEFORE_DRIVERS`
     161    This directive performs initialization that must occur between basis RTEMS
     162    data structure initialization and device driver initialization.  In
     163    particular, in a multiprocessor configuration, this directive will create
     164    the MPCI Server Task.
     165
     166`RTEMS_SYSINIT_BSP_PRE_DRIVERS`
    174167    Initialization step performed right before device drivers are initialized
    175168    provided by the Board Support Package.  This step is mandatory.
    176169
    177 :dfn:`RTEMS_SYSINIT_DEVICE_DRIVERS`
    178     This step initializes all statically configured device drivers and performs all
    179     RTEMS initialization which requires device drivers to be initialized.  This
    180     step is mandatory.
    181     In a multiprocessor configuration, this service will initialize the
    182     Multiprocessor Communications Interface (MPCI) and synchronize with the other
    183     nodes in the system.
    184 
    185 :dfn:`RTEMS_SYSINIT_BSP_POST_DRIVERS`
     170`RTEMS_SYSINIT_DEVICE_DRIVERS`
     171    This step initializes all statically configured device drivers and performs
     172    all RTEMS initialization which requires device drivers to be initialized.
     173    This step is mandatory.  In a multiprocessor configuration, this service
     174    will initialize the Multiprocessor Communications Interface (MPCI) and
     175    synchronize with the other nodes in the system.
     176
     177`RTEMS_SYSINIT_BSP_POST_DRIVERS`
    186178    Initialization step performed right after device drivers are initialized
    187179    provided by the Board Support Package.  This step is mandatory.
    188180
    189 The final action of the ``rtems_initialize_executive`` directive
    190 is to start multitasking.  RTEMS does not return to the initialization context
    191 and the initialization stack may be re-used for interrupt processing.
    192 
    193 Many of RTEMS actions during initialization are based upon
    194 the contents of the Configuration Table.  For more information
    195 regarding the format and contents of this table, please refer
    196 to the chapter `Configuring a System`_.
    197 
    198 The final action in the initialization sequence is the
    199 initiation of multitasking.  When the scheduler and dispatcher
    200 are enabled, the highest priority, ready task will be dispatched
    201 to run.  Control will not be returned to the Board Support
    202 Package after multitasking is enabled.  The initialization stack may be re-used
    203 for interrupt processing.
     181The final action of the ``rtems_initialize_executive`` directive is to start
     182multitasking.  RTEMS does not return to the initialization context and the
     183initialization stack may be re-used for interrupt processing.
     184
     185Many of RTEMS actions during initialization are based upon the contents of the
     186Configuration Table.  For more information regarding the format and contents of
     187this table, please refer to the chapter `Configuring a System`_.
     188
     189The final action in the initialization sequence is the initiation of
     190multitasking.  When the scheduler and dispatcher are enabled, the highest
     191priority, ready task will be dispatched to run.  Control will not be returned
     192to the Board Support Package after multitasking is enabled.  The initialization
     193stack may be re-used for interrupt processing.
    204194
    205195Shutting Down RTEMS
    206196-------------------
    207197
    208 The ``rtems_shutdown_executive`` directive is invoked by the
    209 application to end multitasking and terminate the system.
     198The ``rtems_shutdown_executive`` directive is invoked by the application to end
     199multitasking and terminate the system.
    210200
    211201Directives
    212202==========
    213203
    214 This section details the Initialization Manager's
    215 directives.  A subsection is dedicated to each of this manager's
    216 directives and describes the calling sequence, related
    217 constants, usage, and status codes.
     204This section details the Initialization Manager's directives.  A subsection is
     205dedicated to each of this manager's directives and describes the calling
     206sequence, related constants, usage, and status codes.
    218207
    219208INITIALIZE_EXECUTIVE - Initialize RTEMS
     
    257246
    258247    void rtems_shutdown_executive(
    259     uint32_t result
     248        uint32_t result
    260249    );
    261250
     
    267256
    268257This directive is called when the application wishes to shutdown RTEMS.  The
    269 system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and
    270 the specified ``result`` code.
     258system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and the
     259specified ``result`` code.
    271260
    272261**NOTES:**
    273262
    274 This directive *must* be the last RTEMS directive
    275 invoked by an application and it *does not return* to the caller.
     263This directive *must* be the last RTEMS directive invoked by an application and
     264it *does not return* to the caller.
    276265
    277266This directive may be called any time.
    278 
    279 .. COMMENT: COPYRIGHT (c) 1988-2014.
    280 
    281 .. COMMENT: On-Line Applications Research Corporation (OAR).
    282 
    283 .. COMMENT: All rights reserved.
    284 
  • c_user/interrupt_manager.rst

    r0f5ccd4 rb8d3f6b  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Interrupt Manager
    26#################
     
    59============
    610
    7 Any real-time executive must provide a mechanism for
    8 quick response to externally generated interrupts to satisfy the
    9 critical time constraints of the application.  The interrupt
    10 manager provides this mechanism for RTEMS.  This manager permits
    11 quick interrupt response times by providing the critical ability
    12 to alter task execution which allows a task to be preempted upon
    13 exit from an ISR.  The interrupt manager includes the following
    14 directive:
    15 
    16 - ``rtems_interrupt_catch`` - Establish an ISR
    17 
    18 - ``rtems_interrupt_disable`` - Disable Interrupts
    19 
    20 - ``rtems_interrupt_enable`` - Enable Interrupts
    21 
    22 - ``rtems_interrupt_flash`` - Flash Interrupt
    23 
    24 - ``rtems_interrupt_local_disable`` - Disable Interrupts on Current Processor
    25 
    26 - ``rtems_interrupt_local_enable`` - Enable Interrupts on Current Processor
    27 
    28 - ``rtems_interrupt_lock_initialize`` - Initialize an ISR Lock
    29 
    30 - ``rtems_interrupt_lock_acquire`` - Acquire an ISR Lock
    31 
    32 - ``rtems_interrupt_lock_release`` - Release an ISR Lock
    33 
    34 - ``rtems_interrupt_lock_acquire_isr`` - Acquire an ISR Lock from ISR
    35 
    36 - ``rtems_interrupt_lock_release_isr`` - Release an ISR Lock from ISR
    37 
    38 - ``rtems_interrupt_is_in_progress`` - Is an ISR in Progress
     11Any real-time executive must provide a mechanism for quick response to
     12externally generated interrupts to satisfy the critical time constraints of the
     13application.  The interrupt manager provides this mechanism for RTEMS.  This
     14manager permits quick interrupt response times by providing the critical
     15ability to alter task execution which allows a task to be preempted upon exit
     16from an ISR.  The interrupt manager includes the following directive:
     17
     18- rtems_interrupt_catch_ - Establish an ISR
     19
     20- rtems_interrupt_disable_ - Disable Interrupts
     21
     22- rtems_interrupt_enable_ - Enable Interrupts
     23
     24- rtems_interrupt_flash_ - Flash Interrupt
     25
     26- rtems_interrupt_local_disable_ - Disable Interrupts on Current Processor
     27
     28- rtems_interrupt_local_enable_ - Enable Interrupts on Current Processor
     29
     30- rtems_interrupt_lock_initialize_ - Initialize an ISR Lock
     31
     32- rtems_interrupt_lock_acquire_ - Acquire an ISR Lock
     33
     34- rtems_interrupt_lock_release_ - Release an ISR Lock
     35
     36- rtems_interrupt_lock_acquire_isr_ - Acquire an ISR Lock from ISR
     37
     38- rtems_interrupt_lock_release_isr_ - Release an ISR Lock from ISR
     39
     40- rtems_interrupt_is_in_progress_ - Is an ISR in Progress
    3941
    4042Background
     
    4547.. index:: interrupt processing
    4648
    47 The interrupt manager allows the application to
    48 connect a function to a hardware interrupt vector.  When an
    49 interrupt occurs, the processor will automatically vector to
    50 RTEMS.  RTEMS saves and restores all registers which are not
    51 preserved by the normal C calling convention
    52 for the target
    53 processor and invokes the user's ISR.  The user's ISR is
    54 responsible for processing the interrupt, clearing the interrupt
    55 if necessary, and device specific manipulation... index:: rtems_vector_number
    56 
    57 The ``rtems_interrupt_catch``
    58 directive connects a procedure to
    59 an interrupt vector.  The vector number is managed using
    60 the ``rtems_vector_number`` data type.
    61 
    62 The interrupt service routine is assumed
    63 to abide by these conventions and have a prototype similar to
    64 the following:.. index:: rtems_isr
     49The interrupt manager allows the application to connect a function to a
     50hardware interrupt vector.  When an interrupt occurs, the processor will
     51automatically vector to RTEMS.  RTEMS saves and restores all registers which
     52are not preserved by the normal C calling convention for the target processor
     53and invokes the user's ISR.  The user's ISR is responsible for processing the
     54interrupt, clearing the interrupt if necessary, and device specific
     55manipulation.
     56
     57.. index:: rtems_vector_number
     58
     59The ``rtems_interrupt_catch`` directive connects a procedure to an interrupt
     60vector.  The vector number is managed using the ``rtems_vector_number`` data
     61type.
     62
     63The interrupt service routine is assumed to abide by these conventions and have
     64a prototype similar to the following:
     65
     66.. index:: rtems_isr
    6567
    6668.. code:: c
    6769
    6870    rtems_isr user_isr(
    69     rtems_vector_number vector
    70     );
    71 
    72 The vector number argument is provided by RTEMS to
    73 allow the application to identify the interrupt source.  This
    74 could be used to allow a single routine to service interrupts
    75 from multiple instances of the same device.  For example, a
    76 single routine could service interrupts from multiple serial
    77 ports and use the vector number to identify which port requires
    78 servicing.
    79 
    80 To minimize the masking of lower or equal priority
    81 level interrupts, the ISR should perform the minimum actions
    82 required to service the interrupt.  Other non-essential actions
    83 should be handled by application tasks.  Once the user's ISR has
    84 completed, it returns control to the RTEMS interrupt manager
    85 which will perform task dispatching and restore the registers
    86 saved before the ISR was invoked.
    87 
    88 The RTEMS interrupt manager guarantees that proper
    89 task scheduling and dispatching are performed at the conclusion
    90 of an ISR.  A system call made by the ISR may have readied a
    91 task of higher priority than the interrupted task.  Therefore,
    92 when the ISR completes, the postponed dispatch processing must
    93 be performed.  No dispatch processing is performed as part of
    94 directives which have been invoked by an ISR.
    95 
    96 Applications must adhere to the following rule if
    97 proper task scheduling and dispatching is to be performed:
    98 
    99 - ** *The interrupt manager must be used for all ISRs which
    100   may be interrupted by the highest priority ISR which invokes an
    101   RTEMS directive.*
    102 
    103 Consider a processor which allows a numerically low
    104 interrupt level to interrupt a numerically greater interrupt
    105 level.  In this example, if an RTEMS directive is used in a
    106 level 4 ISR, then all ISRs which execute at levels 0 through 4
    107 must use the interrupt manager.
    108 
    109 Interrupts are nested whenever an interrupt occurs
    110 during the execution of another ISR.  RTEMS supports efficient
    111 interrupt nesting by allowing the nested ISRs to terminate
    112 without performing any dispatch processing.  Only when the
     71        rtems_vector_number vector
     72    );
     73
     74The vector number argument is provided by RTEMS to allow the application to
     75identify the interrupt source.  This could be used to allow a single routine to
     76service interrupts from multiple instances of the same device.  For example, a
     77single routine could service interrupts from multiple serial ports and use the
     78vector number to identify which port requires servicing.
     79
     80To minimize the masking of lower or equal priority level interrupts, the ISR
     81should perform the minimum actions required to service the interrupt.  Other
     82non-essential actions should be handled by application tasks.  Once the user's
     83ISR has completed, it returns control to the RTEMS interrupt manager which will
     84perform task dispatching and restore the registers saved before the ISR was
     85invoked.
     86
     87The RTEMS interrupt manager guarantees that proper task scheduling and
     88dispatching are performed at the conclusion of an ISR.  A system call made by
     89the ISR may have readied a task of higher priority than the interrupted task.
     90Therefore, when the ISR completes, the postponed dispatch processing must be
     91performed.  No dispatch processing is performed as part of directives which
     92have been invoked by an ISR.
     93
     94Applications must adhere to the following rule if proper task scheduling and
     95dispatching is to be performed:
     96
     97.. note::
     98
     99  The interrupt manager must be used for all ISRs which may be interrupted by
     100  the highest priority ISR which invokes an RTEMS directive.
     101
     102Consider a processor which allows a numerically low interrupt level to
     103interrupt a numerically greater interrupt level.  In this example, if an RTEMS
     104directive is used in a level 4 ISR, then all ISRs which execute at levels 0
     105through 4 must use the interrupt manager.
     106
     107Interrupts are nested whenever an interrupt occurs during the execution of
     108another ISR.  RTEMS supports efficient interrupt nesting by allowing the nested
     109ISRs to terminate without performing any dispatch processing.  Only when the
    113110outermost ISR terminates will the postponed dispatching occur.
    114111
     
    117114.. index:: interrupt levels
    118115
    119 Many processors support multiple interrupt levels or
    120 priorities.  The exact number of interrupt levels is processor
    121 dependent.  RTEMS internally supports 256 interrupt levels which
    122 are mapped to the processor's interrupt levels.  For specific
    123 information on the mapping between RTEMS and the target
    124 processor's interrupt levels, refer to the Interrupt Processing
    125 chapter of the Applications Supplement document for a specific
    126 target processor.
     116Many processors support multiple interrupt levels or priorities.  The exact
     117number of interrupt levels is processor dependent.  RTEMS internally supports
     118256 interrupt levels which are mapped to the processor's interrupt levels.  For
     119specific information on the mapping between RTEMS and the target processor's
     120interrupt levels, refer to the Interrupt Processing chapter of the Applications
     121Supplement document for a specific target processor.
    127122
    128123Disabling of Interrupts by RTEMS
     
    130125.. index:: disabling interrupts
    131126
    132 During the execution of directive calls, critical
    133 sections of code may be executed.  When these sections are
    134 encountered, RTEMS disables all maskable interrupts before the
    135 execution of the section and restores them to the previous level
    136 upon completion of the section.  RTEMS has been optimized to
    137 ensure that interrupts are disabled for a minimum length of
    138 time.  The maximum length of time interrupts are disabled by
    139 RTEMS is processor dependent and is detailed in the Timing
    140 Specification chapter of the Applications Supplement document
    141 for a specific target processor.
    142 
    143 Non-maskable interrupts (NMI) cannot be disabled, and
    144 ISRs which execute at this level MUST NEVER issue RTEMS system
    145 calls.  If a directive is invoked, unpredictable results may
    146 occur due to the inability of RTEMS to protect its critical
    147 sections.  However, ISRs that make no system calls may safely
    148 execute as non-maskable interrupts.
     127During the execution of directive calls, critical sections of code may be
     128executed.  When these sections are encountered, RTEMS disables all maskable
     129interrupts before the execution of the section and restores them to the
     130previous level upon completion of the section.  RTEMS has been optimized to
     131ensure that interrupts are disabled for a minimum length of time.  The maximum
     132length of time interrupts are disabled by RTEMS is processor dependent and is
     133detailed in the Timing Specification chapter of the Applications Supplement
     134document for a specific target processor.
     135
     136Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at
     137this level MUST NEVER issue RTEMS system calls.  If a directive is invoked,
     138unpredictable results may occur due to the inability of RTEMS to protect its
     139critical sections.  However, ISRs that make no system calls may safely execute
     140as non-maskable interrupts.
    149141
    150142Operations
     
    154146-------------------
    155147
    156 The ``rtems_interrupt_catch``
    157 directive establishes an ISR for
    158 the system.  The address of the ISR and its associated CPU
    159 vector number are specified to this directive.  This directive
    160 installs the RTEMS interrupt wrapper in the processor's
    161 Interrupt Vector Table and the address of the user's ISR in the
    162 RTEMS' Vector Table.  This directive returns the previous
    163 contents of the specified vector in the RTEMS' Vector Table.
     148The ``rtems_interrupt_catch`` directive establishes an ISR for the system.  The
     149address of the ISR and its associated CPU vector number are specified to this
     150directive.  This directive installs the RTEMS interrupt wrapper in the
     151processor's Interrupt Vector Table and the address of the user's ISR in the
     152RTEMS' Vector Table.  This directive returns the previous contents of the
     153specified vector in the RTEMS' Vector Table.
    164154
    165155Directives Allowed from an ISR
    166156------------------------------
    167157
    168 Using the interrupt manager ensures that RTEMS knows
    169 when a directive is being called from an ISR.  The ISR may then
    170 use system calls to synchronize itself with an application task.
    171 The synchronization may involve messages, events or signals
    172 being passed by the ISR to the desired task.  Directives invoked
    173 by an ISR must operate only on objects which reside on the local
    174 node.  The following is a list of RTEMS system calls that may be
    175 made from an ISR:
     158Using the interrupt manager ensures that RTEMS knows when a directive is being
     159called from an ISR.  The ISR may then use system calls to synchronize itself
     160with an application task.  The synchronization may involve messages, events or
     161signals being passed by the ISR to the desired task.  Directives invoked by an
     162ISR must operate only on objects which reside on the local node.  The following
     163is a list of RTEMS system calls that may be made from an ISR:
    176164
    177165- Task Management
    178   Although it is acceptable to operate on the RTEMS_SELF task (e.g.
    179   the currently executing task), while in an ISR, this will refer
    180   to the interrupted task.  Most of the time, it is an application
    181   implementation error to use RTEMS_SELF from an ISR.
     166  Although it is acceptable to operate on the RTEMS_SELF task (e.g.  the
     167  currently executing task), while in an ISR, this will refer to the
     168  interrupted task.  Most of the time, it is an application implementation
     169  error to use RTEMS_SELF from an ISR.
    182170  - rtems_task_suspend
    183171  - rtems_task_resume
     
    254242==========
    255243
    256 This section details the interrupt manager's
    257 directives.  A subsection is dedicated to each of this manager's
    258 directives and describes the calling sequence, related
    259 constants, usage, and status codes.
     244This section details the interrupt manager's directives.  A subsection is
     245dedicated to each of this manager's directives and describes the calling
     246sequence, related constants, usage, and status codes.
     247
     248.. _rtems_interrupt_catch:
    260249
    261250INTERRUPT_CATCH - Establish an ISR
     
    271260
    272261    rtems_status_code rtems_interrupt_catch(
    273     rtems_isr_entry      new_isr_handler,
    274     rtems_vector_number  vector,
    275     rtems_isr_entry     \*old_isr_handler
    276     );
    277 
    278 **DIRECTIVE STATUS CODES:**
    279 
    280 ``RTEMS_SUCCESSFUL`` - ISR established successfully
    281 ``RTEMS_INVALID_NUMBER`` - illegal vector number
    282 ``RTEMS_INVALID_ADDRESS`` - illegal ISR entry point or invalid ``old_isr_handler``
    283 
    284 **DESCRIPTION:**
    285 
    286 This directive establishes an interrupt service
    287 routine (ISR) for the specified interrupt vector number.  The``new_isr_handler`` parameter specifies the entry point of the ISR.
    288 The entry point of the previous ISR for the specified vector is
    289 returned in ``old_isr_handler``.
    290 
    291 To release an interrupt vector, pass the old handler's address obtained
    292 when the vector was first capture.
     262        rtems_isr_entry      new_isr_handler,
     263        rtems_vector_number  vector,
     264        rtems_isr_entry     *old_isr_handler
     265    );
     266
     267**DIRECTIVE STATUS CODES:**
     268
     269``RTEMS_SUCCESSFUL``
     270  ISR established successfully
     271
     272``RTEMS_INVALID_NUMBER``
     273  illegal vector number
     274
     275``RTEMS_INVALID_ADDRESS``
     276  illegal ISR entry point or invalid ``old_isr_handler``
     277
     278**DESCRIPTION:**
     279
     280This directive establishes an interrupt service routine (ISR) for the specified
     281interrupt vector number.  The ``new_isr_handler`` parameter specifies the entry
     282point of the ISR.  The entry point of the previous ISR for the specified vector
     283is returned in ``old_isr_handler``.
     284
     285To release an interrupt vector, pass the old handler's address obtained when
     286the vector was first capture.
    293287
    294288**NOTES:**
    295289
    296290This directive will not cause the calling task to be preempted.
     291
     292.. _rtems_interrupt_disable:
    297293
    298294INTERRUPT_DISABLE - Disable Interrupts
     
    307303
    308304    void rtems_interrupt_disable(
    309     rtems_interrupt_level  level
    310     );
    311     /* this is implemented as a macro and sets level as a side-effect \*/
    312 
    313 **DIRECTIVE STATUS CODES:**
    314 
    315 NONE
    316 
    317 **DESCRIPTION:**
    318 
    319 This directive disables all maskable interrupts and returns
    320 the previous ``level``.  A later invocation of the``rtems_interrupt_enable`` directive should be used to
    321 restore the interrupt level.
     305        rtems_interrupt_level  level
     306    );
     307
     308**DIRECTIVE STATUS CODES:**
     309
     310NONE
     311
     312**DESCRIPTION:**
     313
     314.. sidebar:: *Macro*
     315
     316  This directive is implemented as a macro which modifies the ``level``
     317  parameter.
     318
     319This directive disables all maskable interrupts and returns the previous
     320``level``.  A later invocation of the ``rtems_interrupt_enable`` directive
     321should be used to restore the interrupt level.
    322322
    323323**NOTES:**
     
    325325This directive will not cause the calling task to be preempted.
    326326
    327 *This directive is implemented as a macro which modifies the ``level``
    328 parameter.*
    329 
    330327This directive is only available on uni-processor configurations.  The
    331 directive ``rtems_interrupt_local_disable`` is available on all
    332 configurations.
     328directive ``rtems_interrupt_local_disable`` is available on all configurations.
     329
     330.. _rtems_interrupt_enable:
    333331
    334332INTERRUPT_ENABLE - Enable Interrupts
     
    343341
    344342    void rtems_interrupt_enable(
    345     rtems_interrupt_level  level
    346     );
    347 
    348 **DIRECTIVE STATUS CODES:**
    349 
    350 NONE
    351 
    352 **DESCRIPTION:**
    353 
    354 This directive enables maskable interrupts to the ``level``
    355 which was returned by a previous call to``rtems_interrupt_disable``.
    356 Immediately prior to invoking this directive, maskable interrupts should
    357 be disabled by a call to ``rtems_interrupt_disable``
    358 and will be enabled when this directive returns to the caller.
     343       rtems_interrupt_level  level
     344    );
     345
     346**DIRECTIVE STATUS CODES:**
     347
     348NONE
     349
     350**DESCRIPTION:**
     351
     352This directive enables maskable interrupts to the ``level`` which was returned
     353by a previous call to ``rtems_interrupt_disable``.  Immediately prior to
     354invoking this directive, maskable interrupts should be disabled by a call to
     355``rtems_interrupt_disable`` and will be enabled when this directive returns to
     356the caller.
    359357
    360358**NOTES:**
     
    363361
    364362This directive is only available on uni-processor configurations.  The
    365 directive ``rtems_interrupt_local_enable`` is available on all
    366 configurations.
     363directive ``rtems_interrupt_local_enable`` is available on all configurations.
     364
     365.. _rtems_interrupt_flash:
    367366
    368367INTERRUPT_FLASH - Flash Interrupts
     
    377376
    378377    void rtems_interrupt_flash(
    379     rtems_interrupt_level level
    380     );
    381 
    382 **DIRECTIVE STATUS CODES:**
    383 
    384 NONE
    385 
    386 **DESCRIPTION:**
    387 
    388 This directive temporarily enables maskable interrupts to the ``level``
    389 which was returned by a previous call to``rtems_interrupt_disable``.
    390 Immediately prior to invoking this directive, maskable interrupts should
    391 be disabled by a call to ``rtems_interrupt_disable``
    392 and will be redisabled when this directive returns to the caller.
     378        rtems_interrupt_level level
     379    );
     380
     381**DIRECTIVE STATUS CODES:**
     382
     383NONE
     384
     385**DESCRIPTION:**
     386
     387This directive temporarily enables maskable interrupts to the ``level`` which
     388was returned by a previous call to ``rtems_interrupt_disable``.  Immediately
     389prior to invoking this directive, maskable interrupts should be disabled by a
     390call to ``rtems_interrupt_disable`` and will be redisabled when this directive
     391returns to the caller.
    393392
    394393**NOTES:**
     
    397396
    398397This directive is only available on uni-processor configurations.  The
    399 directives ``rtems_interrupt_local_disable`` and``rtems_interrupt_local_enable`` is available on all
    400 configurations.
     398directives ``rtems_interrupt_local_disable``
     399and``rtems_interrupt_local_enable`` is available on all configurations.
     400
     401.. _rtems_interrupt_local_disable:
    401402
    402403INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor
     
    411412
    412413    void rtems_interrupt_local_disable(
    413     rtems_interrupt_level  level
    414     );
    415     /* this is implemented as a macro and sets level as a side-effect \*/
    416 
    417 **DIRECTIVE STATUS CODES:**
    418 
    419 NONE
    420 
    421 **DESCRIPTION:**
    422 
    423 This directive disables all maskable interrupts and returns
    424 the previous ``level``.  A later invocation of the``rtems_interrupt_local_enable`` directive should be used to
    425 restore the interrupt level.
     414        rtems_interrupt_level  level
     415    );
     416
     417**DIRECTIVE STATUS CODES:**
     418
     419NONE
     420
     421**DESCRIPTION:**
     422
     423.. sidebar:: *Macro*
     424
     425  This directive is implemented as a macro which modifies the ``level``
     426  parameter.
     427
     428This directive disables all maskable interrupts and returns the previous
     429``level``.  A later invocation of the ``rtems_interrupt_local_enable`` directive
     430should be used to restore the interrupt level.
    426431
    427432**NOTES:**
    428433
    429434This directive will not cause the calling task to be preempted.
    430 
    431 *This directive is implemented as a macro which modifies the ``level``
    432 parameter.*
    433435
    434436On SMP configurations this will not ensure system wide mutual exclusion.  Use
    435437interrupt locks instead.
     438
     439.. _rtems_interrupt_local_enable:
    436440
    437441INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor
     
    446450
    447451    void rtems_interrupt_local_enable(
    448     rtems_interrupt_level  level
    449     );
    450 
    451 **DIRECTIVE STATUS CODES:**
    452 
    453 NONE
    454 
    455 **DESCRIPTION:**
    456 
    457 This directive enables maskable interrupts to the ``level``
    458 which was returned by a previous call to``rtems_interrupt_local_disable``.
    459 Immediately prior to invoking this directive, maskable interrupts should
    460 be disabled by a call to ``rtems_interrupt_local_disable``
    461 and will be enabled when this directive returns to the caller.
     452        rtems_interrupt_level  level
     453    );
     454
     455**DIRECTIVE STATUS CODES:**
     456
     457NONE
     458
     459**DESCRIPTION:**
     460
     461This directive enables maskable interrupts to the ``level`` which was returned
     462by a previous call to ``rtems_interrupt_local_disable``.  Immediately prior to
     463invoking this directive, maskable interrupts should be disabled by a call to
     464``rtems_interrupt_local_disable`` and will be enabled when this directive
     465returns to the caller.
    462466
    463467**NOTES:**
    464468
    465469This directive will not cause the calling task to be preempted.
     470
     471.. _rtems_interrupt_lock_initialize:
    466472
    467473INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock
     
    475481
    476482    void rtems_interrupt_lock_initialize(
    477     rtems_interrupt_lock \*lock
     483        rtems_interrupt_lock *lock
    478484    );
    479485
     
    489495
    490496Concurrent initialization leads to unpredictable results.
     497
     498.. _rtems_interrupt_lock_acquire:
    491499
    492500INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock
     
    500508
    501509    void rtems_interrupt_lock_acquire(
    502     rtems_interrupt_lock \*lock,
    503     rtems_interrupt_level level
     510        rtems_interrupt_lock *lock,
     511        rtems_interrupt_level level
    504512    );
    505513
     
    518526directive can be used in thread and interrupt context.
    519527
     528.. _rtems_interrupt_lock_release:
     529
    520530INTERRUPT_LOCK_RELEASE - Release an ISR Lock
    521531--------------------------------------------
     
    528538
    529539    void rtems_interrupt_lock_release(
    530     rtems_interrupt_lock \*lock,
    531     rtems_interrupt_level level
     540        rtems_interrupt_lock *lock,
     541        rtems_interrupt_level level
    532542    );
    533543
     
    546556directive can be used in thread and interrupt context.
    547557
     558.. _rtems_interrupt_lock_acquire_isr:
     559
    548560INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR
    549561---------------------------------------------------------
     
    556568
    557569    void rtems_interrupt_lock_acquire_isr(
    558     rtems_interrupt_lock \*lock,
    559     rtems_interrupt_level level
     570        rtems_interrupt_lock *lock,
     571        rtems_interrupt_level level
    560572    );
    561573
     
    578590routine.
    579591
     592.. _rtems_interrupt_lock_release_isr:
     593
    580594INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR
    581595---------------------------------------------------------
     
    588602
    589603    void rtems_interrupt_lock_release_isr(
    590     rtems_interrupt_lock \*lock,
    591     rtems_interrupt_level level
     604        rtems_interrupt_lock *lock,
     605        rtems_interrupt_level level
    592606    );
    593607
     
    605619This directive should be called from the corresponding interrupt service
    606620routine.
     621
     622.. _rtems_interrupt_is_in_progress:
    607623
    608624INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
     
    616632.. code:: c
    617633
    618     bool rtems_interrupt_is_in_progress( void );
    619 
    620 **DIRECTIVE STATUS CODES:**
    621 
    622 NONE
    623 
    624 **DESCRIPTION:**
    625 
    626 This directive returns ``TRUE`` if the processor is currently
    627 servicing an interrupt and ``FALSE`` otherwise.  A return value
    628 of ``TRUE`` indicates that the caller is an interrupt service
    629 routine, *NOT* a task.  The directives available to an interrupt
    630 service routine are restricted.
     634    bool rtems_interrupt_is_in_progress(void);
     635
     636**DIRECTIVE STATUS CODES:**
     637
     638NONE
     639
     640**DESCRIPTION:**
     641
     642This directive returns ``TRUE`` if the processor is currently servicing an
     643interrupt and ``FALSE`` otherwise.  A return value of ``TRUE`` indicates that
     644the caller is an interrupt service routine, *NOT* a task.  The directives
     645available to an interrupt service routine are restricted.
    631646
    632647**NOTES:**
    633648
    634649This directive will not cause the calling task to be preempted.
    635 
    636 .. COMMENT: COPYRIGHT (c) 1988-2008
    637 
    638 .. COMMENT: On-Line Applications Research Corporation (OAR).
    639 
    640 .. COMMENT: All rights reserved.
    641 
  • c_user/key_concepts.rst

    r0f5ccd4 rb8d3f6b  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Key Concepts
    26############
     
    59============
    610
    7 The facilities provided by RTEMS are built upon a
    8 foundation of very powerful concepts.  These concepts must be
    9 understood before the application developer can efficiently
    10 utilize RTEMS.  The purpose of this chapter is to familiarize
     11The facilities provided by RTEMS are built upon a foundation of very powerful
     12concepts.  These concepts must be understood before the application developer
     13can efficiently utilize RTEMS.  The purpose of this chapter is to familiarize
    1114one with these concepts.
     15
     16.. _objects:
    1217
    1318Objects
     
    1621.. index:: objects
    1722
    18 RTEMS provides directives which can be used to
    19 dynamically create, delete, and manipulate a set of predefined
    20 object types.  These types include tasks, message queues,
    21 semaphores, memory regions, memory partitions, timers, ports,
    22 and rate monotonic periods.  The object-oriented nature of RTEMS
    23 encourages the creation of modular applications built upon
    24 re-usable "building block" routines.
    25 
    26 All objects are created on the local node as required
    27 by the application and have an RTEMS assigned ID.  All objects
    28 have a user-assigned name.  Although a relationship exists
    29 between an object's name and its RTEMS assigned ID, the name and
    30 ID are not identical.  Object names are completely arbitrary and
    31 selected by the user as a meaningful "tag" which may commonly
    32 reflect the object's use in the application.  Conversely, object
    33 IDs are designed to facilitate efficient object manipulation by
    34 the executive.
     23RTEMS provides directives which can be used to dynamically create, delete, and
     24manipulate a set of predefined object types.  These types include tasks,
     25message queues, semaphores, memory regions, memory partitions, timers, ports,
     26and rate monotonic periods.  The object-oriented nature of RTEMS encourages the
     27creation of modular applications built upon re-usable "building block"
     28routines.
     29
     30All objects are created on the local node as required by the application and
     31have an RTEMS assigned ID.  All objects have a user-assigned name.  Although a
     32relationship exists between an object's name and its RTEMS assigned ID, the
     33name and ID are not identical.  Object names are completely arbitrary and
     34selected by the user as a meaningful "tag" which may commonly reflect the
     35object's use in the application.  Conversely, object IDs are designed to
     36facilitate efficient object manipulation by the executive.
    3537
    3638Object Names
     
    3941.. index:: rtems_object_name
    4042
    41 An object name is an unsigned thirty-two bit entity
    42 associated with the object by the user.  The data type``rtems_name`` is used to store object names... index:: rtems_build_name
    43 
    44 Although not required by RTEMS, object names are often
    45 composed of four ASCII characters which help identify that object.
    46 For example, a task which causes a light to blink might be
    47 called "LITE".  The ``rtems_build_name`` routine
    48 is provided to build an object name from four ASCII characters.
    49 The following example illustrates this:
     43An object name is an unsigned thirty-two bit entity associated with the object
     44by the user.  The data type ``rtems_name`` is used to store object
     45names... index:: rtems_build_name
     46
     47Although not required by RTEMS, object names are often composed of four ASCII
     48characters which help identify that object.  For example, a task which causes a
     49light to blink might be called "LITE".  The ``rtems_build_name`` routine is
     50provided to build an object name from four ASCII characters.  The following
     51example illustrates this: .. code:: c
     52
    5053.. code:: c
    5154
     
    5356    my_name = rtems_build_name( 'L', 'I', 'T', 'E' );
    5457
    55 However, it is not required that the application use ASCII
    56 characters to build object names.  For example, if an
    57 application requires one-hundred tasks, it would be difficult to
    58 assign meaningful ASCII names to each task.  A more convenient
    59 approach would be to name them the binary values one through
     58However, it is not required that the application use ASCII characters to build
     59object names.  For example, if an application requires one-hundred tasks, it
     60would be difficult to assign meaningful ASCII names to each task.  A more
     61convenient approach would be to name them the binary values one through
    6062one-hundred, respectively... index:: rtems_object_get_name
    6163
    62 RTEMS provides a helper routine, ``rtems_object_get_name``,
    63 which can be used to obtain the name of any RTEMS object using just
    64 its ID.  This routine attempts to convert the name into a printable string.
    65 
    66 The following example illustrates the use of this method to print
    67 an object name:
     64RTEMS provides a helper routine, ``rtems_object_get_name``, which can be used
     65to obtain the name of any RTEMS object using just its ID.  This routine
     66attempts to convert the name into a printable string.
     67
     68The following example illustrates the use of this method to print an object
     69name:
     70
    6871.. code:: c
    6972
     
    7275    void print_name(rtems_id id)
    7376    {
    74     char  buffer[10];   /* name assumed to be 10 characters or less \*/
    75     char \*result;
    76     result = rtems_object_get_name( id, sizeof(buffer), buffer );
    77     printk( "ID=0x%08x name=%s\\n", id, ((result) ? result : "no name") );
     77        char  buffer[10];   /* name assumed to be 10 characters or less */
     78        char *result;
     79        result = rtems_object_get_name( id, sizeof(buffer), buffer );
     80        printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") );
    7881    }
    7982
    8083Object IDs
    8184----------
    82 
    8385.. index:: object ID
    8486.. index:: object ID composition
    8587.. index:: rtems_id
    8688
    87 An object ID is a unique unsigned integer value which uniquely identifies
    88 an object instance.  Object IDs are passed as arguments to many directives
    89 in RTEMS and RTEMS translates the ID to an internal object pointer. The
    90 efficient manipulation of object IDs is critical to the performance
    91 of RTEMS services.  Because of this, there are two object Id formats
    92 defined.  Each target architecture specifies which format it will use.
    93 There is a thirty-two bit format which is used for most of the supported
    94 architectures and supports multiprocessor configurations.  There is also
    95 a simpler sixteen bit format which is appropriate for smaller target
    96 architectures and does not support multiprocessor configurations.
     89An object ID is a unique unsigned integer value which uniquely identifies an
     90object instance.  Object IDs are passed as arguments to many directives in
     91RTEMS and RTEMS translates the ID to an internal object pointer. The efficient
     92manipulation of object IDs is critical to the performance of RTEMS services.
     93Because of this, there are two object Id formats defined.  Each target
     94architecture specifies which format it will use.  There is a thirty-two bit
     95format which is used for most of the supported architectures and supports
     96multiprocessor configurations.  There is also a simpler sixteen bit format
     97which is appropriate for smaller target architectures and does not support
     98multiprocessor configurations.
    9799
    98100Thirty-Two Object ID Format
     
    100102
    101103The thirty-two bit format for an object ID is composed of four parts: API,
    102 object class, node, and index.  The data type ``rtems_id``
    103 is used to store object IDs.
     104object class, node, and index.  The data type ``rtems_id`` is used to store
     105object IDs.
    104106
    105107.. code:: c
     
    112114    +---------+-------+--------------+-------------------------------+
    113115
    114 The most significant five bits are the object class.  The next
    115 three bits indicate the API to which the object class belongs.
    116 The next eight bits (16-23) are the number of the node on which
    117 this object was created.  The node number is always one (1) in a single
    118 processor system.  The least significant sixteen bits form an
    119 identifier within a particular object type.  This identifier,
    120 called the object index, ranges in value from 1 to the maximum
     116The most significant five bits are the object class.  The next three bits
     117indicate the API to which the object class belongs.  The next eight bits
     118(16-23) are the number of the node on which this object was created.  The node
     119number is always one (1) in a single processor system.  The least significant
     120sixteen bits form an identifier within a particular object type.  This
     121identifier, called the object index, ranges in value from 1 to the maximum
    121122number of objects configured for this object type.
    122123
     
    124125~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    125126
    126 The sixteen bit format for an object ID is composed of three parts: API,
    127 object class, and index.  The data type ``rtems_id``
    128 is used to store object IDs.
     127The sixteen bit format for an object ID is composed of three parts: API, object
     128class, and index.  The data type ``rtems_id`` is used to store object IDs.
    129129
    130130.. code:: c
     
    138138
    139139The sixteen-bit format is designed to be as similar as possible to the
    140 thrity-two bit format.  The differences are limited to the eliminatation
    141 of the node field and reduction of the index field from sixteen-bits
    142 to 8-bits.  Thus the sixteen bit format only supports up to 255 object
    143 instances per API/Class combination and single processor systems.
    144 As this format is typically utilized by sixteen-bit processors with
    145 limited address space, this is more than enough object instances.
     140thrity-two bit format.  The differences are limited to the eliminatation of the
     141node field and reduction of the index field from sixteen-bits to 8-bits.  Thus
     142the sixteen bit format only supports up to 255 object instances per API/Class
     143combination and single processor systems.  As this format is typically utilized
     144by sixteen-bit processors with limited address space, this is more than enough
     145object instances.
    146146
    147147Object ID Description
    148148---------------------
    149149
    150 The components of an object ID make it possible
    151 to quickly locate any object in even the most complicated
    152 multiprocessor system.  Object ID's are associated with an
    153 object by RTEMS when the object is created and the corresponding
    154 ID is returned by the appropriate object create directive.  The
    155 object ID is required as input to all directives involving
    156 objects, except those which create an object or obtain the ID of
    157 an object.
    158 
    159 The object identification directives can be used to
    160 dynamically obtain a particular object's ID given its name.
    161 This mapping is accomplished by searching the name table
    162 associated with this object type.  If the name is non-unique,
    163 then the ID associated with the first occurrence of the name
    164 will be returned to the application.  Since object IDs are
    165 returned when the object is created, the object identification
    166 directives are not necessary in a properly designed single
    167 processor application.
    168 
    169 In addition, services are provided to portably examine the
    170 subcomponents of an RTEMS ID.  These services are
    171 described in detail later in this manual but are prototyped
    172 as follows:.. index:: obtaining class from object ID
     150The components of an object ID make it possible to quickly locate any object in
     151even the most complicated multiprocessor system.  Object ID's are associated
     152with an object by RTEMS when the object is created and the corresponding ID is
     153returned by the appropriate object create directive.  The object ID is required
     154as input to all directives involving objects, except those which create an
     155object or obtain the ID of an object.
     156
     157The object identification directives can be used to dynamically obtain a
     158particular object's ID given its name.  This mapping is accomplished by
     159searching the name table associated with this object type.  If the name is
     160non-unique, then the ID associated with the first occurrence of the name will
     161be returned to the application.  Since object IDs are returned when the object
     162is created, the object identification directives are not necessary in a
     163properly designed single processor application.
     164
     165In addition, services are provided to portably examine the subcomponents of an
     166RTEMS ID.  These services are described in detail later in this manual but are
     167prototyped as follows:.. index:: obtaining class from object ID
     168
    173169.. index:: obtaining node from object ID
    174170.. index:: obtaining index from object ID
     
    188184    uint32_t rtems_object_id_get_index( rtems_id );
    189185
    190 An object control block is a data structure defined
    191 by RTEMS which contains the information necessary to manage a
    192 particular object type.  For efficiency reasons, the format of
    193 each object type's control block is different.  However, many of
    194 the fields are similar in function.  The number of each type of
    195 control block is application dependent and determined by the
    196 values specified in the user's Configuration Table.  An object
    197 control block is allocated at object create time and freed when
    198 the object is deleted.  With the exception of user extension
    199 routines, object control blocks are not directly manipulated by
    200 user applications.
     186An object control block is a data structure defined by RTEMS which contains the
     187information necessary to manage a particular object type.  For efficiency
     188reasons, the format of each object type's control block is different.  However,
     189many of the fields are similar in function.  The number of each type of control
     190block is application dependent and determined by the values specified in the
     191user's Configuration Table.  An object control block is allocated at object
     192create time and freed when the object is deleted.  With the exception of user
     193extension routines, object control blocks are not directly manipulated by user
     194applications.
    201195
    202196Communication and Synchronization
     
    204198.. index:: communication and synchronization
    205199
    206 In real-time multitasking applications, the ability
    207 for cooperating execution threads to communicate and synchronize
    208 with each other is imperative.  A real-time executive should
    209 provide an application with the following capabilities:
     200In real-time multitasking applications, the ability for cooperating execution
     201threads to communicate and synchronize with each other is imperative.  A
     202real-time executive should provide an application with the following
     203capabilities:
    210204
    211205- Data transfer between cooperating tasks
     
    217211- Synchronization of tasks and ISRs
    218212
    219 Most RTEMS managers can be used to provide some form
    220 of communication and/or synchronization.  However, managers
    221 dedicated specifically to communication and synchronization
    222 provide well established mechanisms which directly map to the
    223 application's varying needs.  This level of flexibility allows
    224 the application designer to match the features of a particular
    225 manager with the complexity of communication and synchronization
    226 required.  The following managers were specifically designed for
    227 communication and synchronization:
     213Most RTEMS managers can be used to provide some form of communication and/or
     214synchronization.  However, managers dedicated specifically to communication and
     215synchronization provide well established mechanisms which directly map to the
     216application's varying needs.  This level of flexibility allows the application
     217designer to match the features of a particular manager with the complexity of
     218communication and synchronization required.  The following managers were
     219specifically designed for communication and synchronization:
    228220
    229221- Semaphore
     
    235227- Signal
    236228
    237 The semaphore manager supports mutual exclusion
    238 involving the synchronization of access to one or more shared
    239 user resources.  Binary semaphores may utilize the optional
    240 priority inheritance algorithm to avoid the problem of priority
     229The semaphore manager supports mutual exclusion involving the synchronization
     230of access to one or more shared user resources.  Binary semaphores may utilize
     231the optional priority inheritance algorithm to avoid the problem of priority
    241232inversion.  The message manager supports both communication and
    242 synchronization, while the event manager primarily provides a
    243 high performance synchronization mechanism.  The signal manager
    244 supports only asynchronous communication and is typically used
    245 for exception handling.
     233synchronization, while the event manager primarily provides a high performance
     234synchronization mechanism.  The signal manager supports only asynchronous
     235communication and is typically used for exception handling.
    246236
    247237Time
     
    249239.. index:: time
    250240
    251 The development of responsive real-time applications
    252 requires an understanding of how RTEMS maintains and supports
    253 time-related operations.  The basic unit of time in RTEMS is
    254 known as a tick.  The frequency of clock ticks is completely
    255 application dependent and determines the granularity and
    256 accuracy of all interval and calendar time operations... index:: rtems_interval
    257 
    258 By tracking time in units of ticks, RTEMS is capable
    259 of supporting interval timing functions such as task delays,
    260 timeouts, timeslicing, the delayed execution of timer service
    261 routines, and the rate monotonic scheduling of tasks.  An
    262 interval is defined as a number of ticks relative to the current
    263 time.  For example, when a task delays for an interval of ten
    264 ticks, it is implied that the task will not execute until ten
    265 clock ticks have occurred.
    266 All intervals are specified using data type``rtems_interval``.
    267 
    268 A characteristic of interval timing is that the
    269 actual interval period may be a fraction of a tick less than the
    270 interval requested.  This occurs because the time at which the
    271 delay timer is set up occurs at some time between two clock
    272 ticks.  Therefore, the first countdown tick occurs in less than
    273 the complete time interval for a tick.  This can be a problem if
    274 the clock granularity is large.
    275 
    276 The rate monotonic scheduling algorithm is a hard
    277 real-time scheduling methodology.  This methodology provides
    278 rules which allows one to guarantee that a set of independent
    279 periodic tasks will always meet their deadlines - even under
    280 transient overload conditions.  The rate monotonic manager
    281 provides directives built upon the Clock Manager's interval
    282 timer support routines.
    283 
    284 Interval timing is not sufficient for the many
    285 applications which require that time be kept in wall time or
    286 true calendar form.  Consequently, RTEMS maintains the current
    287 date and time.  This allows selected time operations to be
    288 scheduled at an actual calendar date and time.  For example, a
    289 task could request to delay until midnight on New Year's Eve
    290 before lowering the ball at Times Square.
    291 The data type ``rtems_time_of_day`` is used to specify
    292 calendar time in RTEMS services.
    293 See `Time and Date Data Structures`_
     241The development of responsive real-time applications requires an understanding
     242of how RTEMS maintains and supports time-related operations.  The basic unit of
     243time in RTEMS is known as a tick.  The frequency of clock ticks is completely
     244application dependent and determines the granularity and accuracy of all
     245interval and calendar time operations... index:: rtems_interval
     246
     247By tracking time in units of ticks, RTEMS is capable of supporting interval
     248timing functions such as task delays, timeouts, timeslicing, the delayed
     249execution of timer service routines, and the rate monotonic scheduling of
     250tasks.  An interval is defined as a number of ticks relative to the current
     251time.  For example, when a task delays for an interval of ten ticks, it is
     252implied that the task will not execute until ten clock ticks have occurred.
     253All intervals are specified using data type ``rtems_interval``.
     254
     255A characteristic of interval timing is that the actual interval period may be a
     256fraction of a tick less than the interval requested.  This occurs because the
     257time at which the delay timer is set up occurs at some time between two clock
     258ticks.  Therefore, the first countdown tick occurs in less than the complete
     259time interval for a tick.  This can be a problem if the clock granularity is
     260large.
     261
     262The rate monotonic scheduling algorithm is a hard real-time scheduling
     263methodology.  This methodology provides rules which allows one to guarantee
     264that a set of independent periodic tasks will always meet their deadlines -
     265even under transient overload conditions.  The rate monotonic manager provides
     266directives built upon the Clock Manager's interval timer support routines.
     267
     268Interval timing is not sufficient for the many applications which require that
     269time be kept in wall time or true calendar form.  Consequently, RTEMS maintains
     270the current date and time.  This allows selected time operations to be
     271scheduled at an actual calendar date and time.  For example, a task could
     272request to delay until midnight on New Year's Eve before lowering the ball at
     273Times Square.  The data type ``rtems_time_of_day`` is used to specify calendar
     274time in RTEMS services.  See `Time and Date Data Structures`_
    294275
    295276... index:: rtems_time_of_day
    296277
    297 Obviously, the directives which use intervals or wall
    298 time cannot operate without some external mechanism which
    299 provides a periodic clock tick.  This clock tick is typically
    300 provided by a real time clock or counter/timer device.
     278Obviously, the directives which use intervals or wall time cannot operate
     279without some external mechanism which provides a periodic clock tick.  This
     280clock tick is typically provided by a real time clock or counter/timer device.
    301281
    302282Memory Management
     
    304284.. index:: memory management
    305285
    306 RTEMS memory management facilities can be grouped
    307 into two classes: dynamic memory allocation and address
    308 translation.  Dynamic memory allocation is required by
    309 applications whose memory requirements vary through the
    310 application's course of execution.  Address translation is
    311 needed by applications which share memory with another CPU or an
    312 intelligent Input/Output processor.  The following RTEMS
    313 managers provide facilities to manage memory:
     286RTEMS memory management facilities can be grouped into two classes: dynamic
     287memory allocation and address translation.  Dynamic memory allocation is
     288required by applications whose memory requirements vary through the
     289application's course of execution.  Address translation is needed by
     290applications which share memory with another CPU or an intelligent Input/Output
     291processor.  The following RTEMS managers provide facilities to manage memory:
    314292
    315293- Region
     
    319297- Dual Ported Memory
    320298
    321 RTEMS memory management features allow an application
    322 to create simple memory pools of fixed size buffers and/or more
    323 complex memory pools of variable size segments.  The partition
    324 manager provides directives to manage and maintain pools of
    325 fixed size entities such as resource control blocks.
    326 Alternatively, the region manager provides a more general
    327 purpose memory allocation scheme that supports variable size
    328 blocks of memory which are dynamically obtained and freed by the
    329 application.  The dual-ported memory manager provides executive
    330 support for address translation between internal and external
    331 dual-ported RAM address space.
    332 
    333 .. COMMENT: COPYRIGHT (c) 1988-2002.
    334 
    335 .. COMMENT: On-Line Applications Research Corporation (OAR).
    336 
    337 .. COMMENT: All rights reserved.
    338 
     299RTEMS memory management features allow an application to create simple memory
     300pools of fixed size buffers and/or more complex memory pools of variable size
     301segments.  The partition manager provides directives to manage and maintain
     302pools of fixed size entities such as resource control blocks.  Alternatively,
     303the region manager provides a more general purpose memory allocation scheme
     304that supports variable size blocks of memory which are dynamically obtained and
     305freed by the application.  The dual-ported memory manager provides executive
     306support for address translation between internal and external dual-ported RAM
     307address space.
  • c_user/overview.rst

    r0f5ccd4 rb8d3f6b  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Overview
    26########
     
    59============
    610
    7 RTEMS, Real-Time Executive for Multiprocessor Systems, is a
    8 real-time executive (kernel) which provides a high performance
    9 environment for embedded military applications including the
    10 following features:
     11RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time executive
     12(kernel) which provides a high performance environment for embedded military
     13applications including the following features:
    1114
    1215- multitasking capabilities
     
    2831- high level of user configurability
    2932
    30 This manual describes the usage of RTEMS for
    31 applications written in the C programming language.  Those
    32 implementation details that are processor dependent are provided
    33 in the Applications Supplement documents.  A supplement
    34 document which addresses specific architectural issues that
    35 affect RTEMS is provided for each processor type that is
    36 supported.
     33This manual describes the usage of RTEMS for applications written in the C
     34programming language.  Those implementation details that are processor
     35dependent are provided in the Applications Supplement documents.  A supplement
     36document which addresses specific architectural issues that affect RTEMS is
     37provided for each processor type that is supported.
    3738
    3839Real-time Application Systems
    3940=============================
    4041
    41 Real-time application systems are a special class of
    42 computer applications.  They have a complex set of
    43 characteristics that distinguish them from other software
    44 problems.  Generally, they must adhere to more rigorous
    45 requirements.  The correctness of the system depends not only on
    46 the results of computations, but also on the time at which the
    47 results are produced.  The most important and complex
    48 characteristic of real-time application systems is that they
    49 must receive and respond to a set of external stimuli within
    50 rigid and critical time constraints referred to as deadlines.
    51 Systems can be buried by an avalanche of interdependent,
    52 asynchronous or cyclical event streams.
    53 
    54 Deadlines can be further characterized as either hard
    55 or soft based upon the value of the results when produced after
    56 the deadline has passed.  A deadline is hard if the results have
    57 no value or if their use will result in a catastrophic event.
    58 In contrast, results which are produced after a soft deadline
    59 may have some value.
    60 
    61 Another distinguishing requirement of real-time
    62 application systems is the ability to coordinate or manage a
    63 large number of concurrent activities. Since software is a
    64 synchronous entity, this presents special problems.  One
    65 instruction follows another in a repeating synchronous cycle.
    66 Even though mechanisms have been developed to allow for the
    67 processing of external asynchronous events, the software design
    68 efforts required to process and manage these events and tasks
    69 are growing more complicated.
    70 
    71 The design process is complicated further by
    72 spreading this activity over a set of processors instead of a
    73 single processor. The challenges associated with designing and
    74 building real-time application systems become very complex when
    75 multiple processors are involved.  New requirements such as
    76 interprocessor communication channels and global resources that
    77 must be shared between competing processors are introduced.  The
    78 ramifications of multiple processors complicate each and every
    79 characteristic of a real-time system.
     42Real-time application systems are a special class of computer applications.
     43They have a complex set of characteristics that distinguish them from other
     44software problems.  Generally, they must adhere to more rigorous requirements.
     45The correctness of the system depends not only on the results of computations,
     46but also on the time at which the results are produced.  The most important and
     47complex characteristic of real-time application systems is that they must
     48receive and respond to a set of external stimuli within rigid and critical time
     49constraints referred to as deadlines.  Systems can be buried by an avalanche of
     50interdependent, asynchronous or cyclical event streams.
     51
     52Deadlines can be further characterized as either hard or soft based upon the
     53value of the results when produced after the deadline has passed.  A deadline
     54is hard if the results have no value or if their use will result in a
     55catastrophic event.  In contrast, results which are produced after a soft
     56deadline may have some value.
     57
     58Another distinguishing requirement of real-time application systems is the
     59ability to coordinate or manage a large number of concurrent activities. Since
     60software is a synchronous entity, this presents special problems.  One
     61instruction follows another in a repeating synchronous cycle.  Even though
     62mechanisms have been developed to allow for the processing of external
     63asynchronous events, the software design efforts required to process and manage
     64these events and tasks are growing more complicated.
     65
     66The design process is complicated further by spreading this activity over a set
     67of processors instead of a single processor. The challenges associated with
     68designing and building real-time application systems become very complex when
     69multiple processors are involved.  New requirements such as interprocessor
     70communication channels and global resources that must be shared between
     71competing processors are introduced.  The ramifications of multiple processors
     72complicate each and every characteristic of a real-time system.
    8073
    8174Real-time Executive
    8275===================
    8376
    84 Fortunately, real-time operating systems or real-time
    85 executives serve as a cornerstone on which to build the
    86 application system.  A real-time multitasking executive allows
    87 an application to be cast into a set of logical, autonomous
    88 processes or tasks which become quite manageable.  Each task is
    89 internally synchronous, but different tasks execute
    90 independently, resulting in an asynchronous processing stream.
    91 Tasks can be dynamically paused for many reasons resulting in a
    92 different task being allowed to execute for a period of time.
    93 The executive also provides an interface to other system
    94 components such as interrupt handlers and device drivers.
    95 System components may request the executive to allocate and
    96 coordinate resources, and to wait for and trigger synchronizing
    97 conditions.  The executive system calls effectively extend the
    98 CPU instruction set to support efficient multitasking.  By
    99 causing tasks to travel through well-defined state transitions,
    100 system calls permit an application to demand-switch between
    101 tasks in response to real-time events.
    102 
    103 By proper grouping of responses to stimuli into
    104 separate tasks, a system can now asynchronously switch between
    105 independent streams of execution, directly responding to
    106 external stimuli as they occur.  This allows the system design
    107 to meet critical performance specifications which are typically
    108 measured by guaranteed response time and transaction throughput.
    109 The multiprocessor extensions of RTEMS provide the features
    110 necessary to manage the extra requirements introduced by a
    111 system distributed across several processors.  It removes the
    112 physical barriers of processor boundaries from the world of the
    113 system designer, enabling more critical aspects of the system to
    114 receive the required attention. Such a system, based on an
    115 efficient real-time, multiprocessor executive, is a more
    116 realistic model of the outside world or environment for which it
    117 is designed.  As a result, the system will always be more
    118 logical, efficient, and reliable.
    119 
    120 By using the directives provided by RTEMS, the
    121 real-time applications developer is freed from the problem of
    122 controlling and synchronizing multiple tasks and processors.  In
    123 addition, one need not develop, test, debug, and document
    124 routines to manage memory, pass messages, or provide mutual
    125 exclusion.  The developer is then able to concentrate solely on
    126 the application.  By using standard software components, the
    127 time and cost required to develop sophisticated real-time
    128 applications is significantly reduced.
     77Fortunately, real-time operating systems or real-time executives serve as a
     78cornerstone on which to build the application system.  A real-time multitasking
     79executive allows an application to be cast into a set of logical, autonomous
     80processes or tasks which become quite manageable.  Each task is internally
     81synchronous, but different tasks execute independently, resulting in an
     82asynchronous processing stream.  Tasks can be dynamically paused for many
     83reasons resulting in a different task being allowed to execute for a period of
     84time.  The executive also provides an interface to other system components such
     85as interrupt handlers and device drivers.  System components may request the
     86executive to allocate and coordinate resources, and to wait for and trigger
     87synchronizing conditions.  The executive system calls effectively extend the
     88CPU instruction set to support efficient multitasking.  By causing tasks to
     89travel through well-defined state transitions, system calls permit an
     90application to demand-switch between tasks in response to real-time events.
     91
     92By proper grouping of responses to stimuli into separate tasks, a system can
     93now asynchronously switch between independent streams of execution, directly
     94responding to external stimuli as they occur.  This allows the system design to
     95meet critical performance specifications which are typically measured by
     96guaranteed response time and transaction throughput.  The multiprocessor
     97extensions of RTEMS provide the features necessary to manage the extra
     98requirements introduced by a system distributed across several processors.  It
     99removes the physical barriers of processor boundaries from the world of the
     100system designer, enabling more critical aspects of the system to receive the
     101required attention. Such a system, based on an efficient real-time,
     102multiprocessor executive, is a more realistic model of the outside world or
     103environment for which it is designed.  As a result, the system will always be
     104more logical, efficient, and reliable.
     105
     106By using the directives provided by RTEMS, the real-time applications developer
     107is freed from the problem of controlling and synchronizing multiple tasks and
     108processors.  In addition, one need not develop, test, debug, and document
     109routines to manage memory, pass messages, or provide mutual exclusion.  The
     110developer is then able to concentrate solely on the application.  By using
     111standard software components, the time and cost required to develop
     112sophisticated real-time applications is significantly reduced.
    129113
    130114RTEMS Application Architecture
    131115==============================
    132116
    133 One important design goal of RTEMS was to provide a
    134 bridge between two critical layers of typical real-time systems.
    135 As shown in the following figure, RTEMS serves as a buffer between the
    136 project dependent application code and the target hardware.
    137 Most hardware dependencies for real-time applications can be
     117One important design goal of RTEMS was to provide a bridge between two critical
     118layers of typical real-time systems.  As shown in the following figure, RTEMS
     119serves as a buffer between the project dependent application code and the
     120target hardware.  Most hardware dependencies for real-time applications can be
    138121localized to the low level device drivers.
    139122
    140 .. code:: c
    141 
    142     +-----------------------------------------------------------+
    143     |             Application Dependent Software                |
    144     |        +----------------------------------------+         |
    145     |        |    Standard Application Components     |         |
    146     |        |                          +-------------+---+     |
    147     |    +---+-----------+              |                 |     |
    148     |    | Board Support |              |      RTEMS      |     |
    149     |    |    Package    |              |                 |     |
    150     +----+---------------+--------------+-----------------+-----|
    151     |                      Target Hardware                      |
    152     +-----------------------------------------------------------+
     123.. COMMENT: .. code:: c
     124.. COMMENT:
     125.. COMMENT:     +-----------------------------------------------------------+
     126.. COMMENT:     |             Application Dependent Software                |
     127.. COMMENT:     |        +----------------------------------------+         |
     128.. COMMENT:     |        |    Standard Application Components     |         |
     129.. COMMENT:     |        |                          +-------------+---+     |
     130.. COMMENT:     |    +---+-----------+              |                 |     |
     131.. COMMENT:     |    | Board Support |              |      RTEMS      |     |
     132.. COMMENT:     |    |    Package    |              |                 |     |
     133.. COMMENT:     +----+---------------+--------------+-----------------+-----|
     134.. COMMENT:     |                      Target Hardware                      |
     135.. COMMENT:     +-----------------------------------------------------------+
     136
     137.. figure:: rtemsarc.png
     138         :width: 488
     139         :height: 100px
     140         :align: center
     141         :alt: RTEMS Application Architecture
    153142
    154143The RTEMS I/O interface manager provides an efficient tool for incorporating
    155 these hardware dependencies into the system while simultaneously
    156 providing a general mechanism to the application code that
    157 accesses them.  A well designed real-time system can benefit
    158 from this architecture by building a rich library of standard
    159 application components which can be used repeatedly in other
     144these hardware dependencies into the system while simultaneously providing a
     145general mechanism to the application code that accesses them.  A well designed
     146real-time system can benefit from this architecture by building a rich library
     147of standard application components which can be used repeatedly in other
    160148real-time projects.
    161149
     
    163151===========================
    164152
    165 RTEMS can be viewed as a set of layered components that work in
    166 harmony to provide a set of services to a real-time application
    167 system.  The executive interface presented to the application is
    168 formed by grouping directives into logical sets called resource managers.
    169 Functions utilized by multiple managers such as scheduling,
    170 dispatching, and object management are provided in the executive
    171 core.  The executive core depends on a small set of CPU dependent routines.
    172 Together these components provide a powerful run time
    173 environment that promotes the development of efficient real-time
    174 application systems.  The following figure illustrates this organization:
    175 
    176 .. code:: c
    177 
    178     +-----------------------------------------------+
    179     |          RTEMS Executive Interface            |
    180     +-----------------------------------------------+
    181     |                 RTEMS Core                    |
    182     +-----------------------------------------------+
    183     |              CPU Dependent Code               |
    184     +-----------------------------------------------+
    185 
    186 Subsequent chapters present a detailed description of the capabilities
    187 provided by each of the following RTEMS managers:
     153RTEMS can be viewed as a set of layered components that work in harmony to
     154provide a set of services to a real-time application system.  The executive
     155interface presented to the application is formed by grouping directives into
     156logical sets called resource managers.  Functions utilized by multiple managers
     157such as scheduling, dispatching, and object management are provided in the
     158executive core.  The executive core depends on a small set of CPU dependent
     159routines.  Together these components provide a powerful run time environment
     160that promotes the development of efficient real-time application systems.  The
     161following figure illustrates this organization:
     162
     163.. COMMENT: .. code:: c
     164.. COMMENT:
     165.. COMMENT:     +-----------------------------------------------+
     166.. COMMENT:     |          RTEMS Executive Interface            |
     167.. COMMENT:     +-----------------------------------------------+
     168.. COMMENT:     |                 RTEMS Core                    |
     169.. COMMENT:     +-----------------------------------------------+
     170.. COMMENT:     |              CPU Dependent Code               |
     171.. COMMENT:     +-----------------------------------------------+
     172
     173.. figure:: rtemspie.png
     174         :width: 70%
     175         :align: center
     176         :alt: RTEMS Internal Architecture
     177
     178Subsequent chapters present a detailed description of the capabilities provided
     179by each of the following RTEMS managers:
    188180
    189181- initialization
     
    224216====================================
    225217
    226 As thirty-two bit microprocessors have decreased in
    227 cost, they have become increasingly common in a variety of
    228 embedded systems.  A wide range of custom and general-purpose
    229 processor boards are based on various thirty-two bit processors.
    230 RTEMS was designed to make no assumptions concerning the
    231 characteristics of individual microprocessor families or of
    232 specific support hardware.  In addition, RTEMS allows the system
    233 developer a high degree of freedom in customizing and extending
    234 its features.
    235 
    236 RTEMS assumes the existence of a supported
    237 microprocessor and sufficient memory for both RTEMS and the
    238 real-time application.  Board dependent components such as
    239 clocks, interrupt controllers, or I/O devices can be easily
    240 integrated with RTEMS.  The customization and extensibility
    241 features allow RTEMS to efficiently support as many environments
    242 as possible.
     218As thirty-two bit microprocessors have decreased in cost, they have become
     219increasingly common in a variety of embedded systems.  A wide range of custom
     220and general-purpose processor boards are based on various thirty-two bit
     221processors.  RTEMS was designed to make no assumptions concerning the
     222characteristics of individual microprocessor families or of specific support
     223hardware.  In addition, RTEMS allows the system developer a high degree of
     224freedom in customizing and extending its features.
     225
     226RTEMS assumes the existence of a supported microprocessor and sufficient memory
     227for both RTEMS and the real-time application.  Board dependent components such
     228as clocks, interrupt controllers, or I/O devices can be easily integrated with
     229RTEMS.  The customization and extensibility features allow RTEMS to efficiently
     230support as many environments as possible.
    243231
    244232Portability
    245233===========
    246234
    247 The issue of portability was the major factor in the
    248 creation of RTEMS.  Since RTEMS is designed to isolate the
    249 hardware dependencies in the specific board support packages,
    250 the real-time application should be easily ported to any other
    251 processor.  The use of RTEMS allows the development of real-time
    252 applications which can be completely independent of a particular
    253 microprocessor architecture.
     235The issue of portability was the major factor in the creation of RTEMS.  Since
     236RTEMS is designed to isolate the hardware dependencies in the specific board
     237support packages, the real-time application should be easily ported to any
     238other processor.  The use of RTEMS allows the development of real-time
     239applications which can be completely independent of a particular microprocessor
     240architecture.
    254241
    255242Memory Requirements
    256243===================
    257244
    258 Since memory is a critical resource in many real-time
    259 embedded systems, RTEMS was specifically designed to automatically
    260 leave out all services that are not required from the run-time
    261 environment.  Features such as networking, various fileystems,
    262 and many other features are completely optional.  This allows
    263 the application designer the flexibility to tailor RTEMS to most
    264 efficiently meet system requirements while still satisfying even
    265 the most stringent memory constraints.  As a result, the size
    266 of the RTEMS executive is application dependent.
    267 
    268 RTEMS requires RAM to manage each instance of an RTEMS object
    269 that is created.  Thus the more RTEMS objects an application
    270 needs, the more memory that must be reserved.  See `Configuring a System`_.
    271 
    272 RTEMS utilizes memory for both code and data space.
    273 Although RTEMS' data space must be in RAM, its code space can be
    274 located in either ROM or RAM.
     245Since memory is a critical resource in many real-time embedded systems, RTEMS
     246was specifically designed to automatically leave out all services that are not
     247required from the run-time environment.  Features such as networking, various
     248fileystems, and many other features are completely optional.  This allows the
     249application designer the flexibility to tailor RTEMS to most efficiently meet
     250system requirements while still satisfying even the most stringent memory
     251constraints.  As a result, the size of the RTEMS executive is application
     252dependent.
     253
     254RTEMS requires RAM to manage each instance of an RTEMS object that is created.
     255Thus the more RTEMS objects an application needs, the more memory that must be
     256reserved.  See Configuring a System_.
     257
     258RTEMS utilizes memory for both code and data space.  Although RTEMS' data space
     259must be in RAM, its code space can be located in either ROM or RAM.
    275260
    276261Audience
    277262========
    278263
    279 This manual was written for experienced real-time
    280 software developers.  Although some background is provided, it
    281 is assumed that the reader is familiar with the concepts of task
    282 management as well as intertask communication and
    283 synchronization.  Since directives, user related data
    284 structures, and examples are presented in C, a basic
    285 understanding of the C programming language
    286 is required to fully
    287 understand the material presented.  However, because of the
    288 similarity of the Ada and C RTEMS implementations, users will
    289 find that the use and behavior of the two implementations is
    290 very similar.  A working knowledge of the target processor is
    291 helpful in understanding some of RTEMS' features.  A thorough
    292 understanding of the executive cannot be obtained without
    293 studying the entire manual because many of RTEMS' concepts and
    294 features are interrelated.  Experienced RTEMS users will find
    295 that the manual organization facilitates its use as a reference
    296 document.
     264This manual was written for experienced real-time software developers.
     265Although some background is provided, it is assumed that the reader is familiar
     266with the concepts of task management as well as intertask communication and
     267synchronization.  Since directives, user related data structures, and examples
     268are presented in C, a basic understanding of the C programming language is
     269required to fully understand the material presented.  However, because of the
     270similarity of the Ada and C RTEMS implementations, users will find that the use
     271and behavior of the two implementations is very similar.  A working knowledge
     272of the target processor is helpful in understanding some of RTEMS' features.  A
     273thorough understanding of the executive cannot be obtained without studying the
     274entire manual because many of RTEMS' concepts and features are interrelated.
     275Experienced RTEMS users will find that the manual organization facilitates its
     276use as a reference document.
    297277
    298278Conventions
     
    301281The following conventions are used in this manual:
    302282
    303 - Significant words or phrases as well as all directive
    304   names are printed in bold type.
    305 
    306 - Items in bold capital letters are constants defined by
    307   RTEMS.  Each language interface provided by RTEMS includes a
    308   file containing the standard set of constants, data types, and
    309   structure definitions which can be incorporated into the user
    310   application.
    311 
    312 - A number of type definitions are provided by RTEMS and
    313   can be found in rtems.h.
    314 
    315 - The characters "0x" preceding a number indicates that
    316   the number is in hexadecimal format.  Any other numbers are
    317   assumed to be in decimal format.
     283- Significant words or phrases as well as all directive names are printed in
     284  bold type.
     285
     286- Items in bold capital letters are constants defined by RTEMS.  Each language
     287  interface provided by RTEMS includes a file containing the standard set of
     288  constants, data types, and structure definitions which can be incorporated
     289  into the user application.
     290
     291- A number of type definitions are provided by RTEMS and can be found in
     292  rtems.h.
     293
     294- The characters "0x" preceding a number indicates that the number is in
     295  hexadecimal format.  Any other numbers are assumed to be in decimal format.
    318296
    319297Manual Organization
    320298===================
    321299
    322 This first chapter has presented the introductory and
    323 background material for the RTEMS executive.  The remaining
    324 chapters of this manual present a detailed description of RTEMS
    325 and the environment, including run time behavior, it creates for
    326 the user.
    327 
    328 A chapter is dedicated to each manager and provides a
    329 detailed discussion of each RTEMS manager and the directives
    330 which it provides.  The presentation format for each directive
    331 includes the following sections:
     300This first chapter has presented the introductory and background material for
     301the RTEMS executive.  The remaining chapters of this manual present a detailed
     302description of RTEMS and the environment, including run time behavior, it
     303creates for the user.
     304
     305A chapter is dedicated to each manager and provides a detailed discussion of
     306each RTEMS manager and the directives which it provides.  The presentation
     307format for each directive includes the following sections:
    332308
    333309- Calling sequence
     
    339315- Notes
    340316
    341 The following provides an overview of the remainder
    342 of this manual:
     317The following provides an overview of the remainder of this manual:
    343318
    344319Chapter 2:
    345     Key Concepts: presents an introduction to the ideas which are common
    346     across multiple RTEMS managers.
     320    Key Concepts: presents an introduction to the ideas which are common across
     321    multiple RTEMS managers.
    347322
    348323Chapter 3:
    349     RTEMS Data Types: describes the fundamental data types shared
    350     by the services in the RTEMS Classic API.
     324    RTEMS Data Types: describes the fundamental data types shared by the
     325    services in the RTEMS Classic API.
    351326
    352327Chapter 4:
    353     Scheduling Concepts: details the various RTEMS scheduling algorithms
    354     and task state transitions.
     328    Scheduling Concepts: details the various RTEMS scheduling algorithms and
     329    task state transitions.
    355330
    356331Chapter 5:
    357     Initialization Manager: describes the functionality and directives
    358     provided by the Initialization Manager.
     332    Initialization Manager: describes the functionality and directives provided
     333    by the Initialization Manager.
    359334
    360335Chapter 6:
    361     Task Manager: describes the functionality and directives provided
    362     by the Task Manager.
     336    Task Manager: describes the functionality and directives provided by the
     337    Task Manager.
    363338
    364339Chapter 7:
    365     Interrupt Manager: describes the functionality and directives
    366     provided by the Interrupt Manager.
     340    Interrupt Manager: describes the functionality and directives provided by
     341    the Interrupt Manager.
    367342
    368343Chapter 8:
    369     Clock Manager: describes the functionality and directives
    370     provided by the Clock Manager.
     344    Clock Manager: describes the functionality and directives provided by the
     345    Clock Manager.
    371346
    372347Chapter 9:
    373     Timer Manager: describes the functionality and directives provided
    374     by the Timer Manager.
     348    Timer Manager: describes the functionality and directives provided by the
     349    Timer Manager.
    375350
    376351Chapter 10:
    377     Rate Monotonic Manager: describes the functionality and directives
    378     provided by the Rate Monotonic Manager.
     352    Rate Monotonic Manager: describes the functionality and directives provided
     353    by the Rate Monotonic Manager.
    379354
    380355Chapter 11:
    381     Semaphore Manager: describes the functionality and directives
    382     provided by the Semaphore Manager.
     356    Semaphore Manager: describes the functionality and directives provided by
     357    the Semaphore Manager.
    383358
    384359Chapter 12:
    385     Barrier Manager: describes the functionality and directives
    386     provided by the Barrier Manager.
     360    Barrier Manager: describes the functionality and directives provided by the
     361    Barrier Manager.
    387362
    388363Chapter 13:
    389     Message Manager: describes the functionality and directives
    390     provided by the Message Manager.
     364    Message Manager: describes the functionality and directives provided by the
     365    Message Manager.
    391366
    392367Chapter 14:
    393     Event Manager: describes the
    394     functionality and directives provided by the Event Manager.
     368    Event Manager: describes the functionality and directives provided by the
     369    Event Manager.
    395370
    396371Chapter 15:
    397     Signal Manager: describes the
    398     functionality and directives provided by the Signal Manager.
     372    Signal Manager: describes the functionality and directives provided by the
     373    Signal Manager.
    399374
    400375Chapter 16:
    401     Partition Manager: describes the
    402     functionality and directives provided by the Partition Manager.
     376    Partition Manager: describes the functionality and directives provided by
     377    the Partition Manager.
    403378
    404379Chapter 17:
    405     Region Manager: describes the
    406     functionality and directives provided by the Region Manager.
     380    Region Manager: describes the functionality and directives provided by the
     381    Region Manager.
    407382
    408383Chapter 18:
    409     Dual-Ported Memory Manager: describes
    410     the functionality and directives provided by the Dual-Ported
    411     Memory Manager.
     384    Dual-Ported Memory Manager: describes the functionality and directives
     385    provided by the Dual-Ported Memory Manager.
    412386
    413387Chapter 19:
    414     I/O Manager: describes the
    415     functionality and directives provided by the I/O Manager.
     388    I/O Manager: describes the functionality and directives provided by the I/O
     389    Manager.
    416390
    417391Chapter 20:
    418     Fatal Error Manager: describes the functionality and directives
    419     provided by the Fatal Error Manager.
     392    Fatal Error Manager: describes the functionality and directives provided by
     393    the Fatal Error Manager.
    420394
    421395Chapter 21:
    422     Board Support Packages: defines the
    423     functionality required of user-supplied board support packages.
     396    Board Support Packages: defines the functionality required of user-supplied
     397    board support packages.
    424398
    425399Chapter 22:
    426     User Extensions: shows the user how to
    427     extend RTEMS to incorporate custom features.
     400    User Extensions: shows the user how to extend RTEMS to incorporate custom
     401    features.
    428402
    429403Chapter 23:
    430     Configuring a System: details the process by which one tailors RTEMS
    431     for a particular single-processor or multiprocessor application.
     404    Configuring a System: details the process by which one tailors RTEMS for a
     405    particular single-processor or multiprocessor application.
    432406
    433407Chapter 24:
    434     Multiprocessing Manager: presents a
    435     conceptual overview of the multiprocessing capabilities provided
    436     by RTEMS as well as describing the Multiprocessing
    437     Communications Interface Layer and Multiprocessing Manager
     408    Multiprocessing Manager: presents a conceptual overview of the
     409    multiprocessing capabilities provided by RTEMS as well as describing the
     410    Multiprocessing Communications Interface Layer and Multiprocessing Manager
    438411    directives.
    439412
    440413Chapter 25:
    441     Stack Bounds Checker: presents the capabilities of the RTEMS
    442     task stack checker which can report stack usage as well as detect
    443     bounds violations.
     414    Stack Bounds Checker: presents the capabilities of the RTEMS task stack
     415    checker which can report stack usage as well as detect bounds violations.
    444416
    445417Chapter 26:
    446     CPU Usage Statistics: presents the capabilities of the CPU Usage
    447     statistics gathered on a per task basis along with the mechanisms
    448     for reporting and resetting the statistics.
     418    CPU Usage Statistics: presents the capabilities of the CPU Usage statistics
     419    gathered on a per task basis along with the mechanisms for reporting and
     420    resetting the statistics.
    449421
    450422Chapter 27:
    451     Object Services: presents a collection of helper services useful
    452     when manipulating RTEMS objects. These include methods to assist
    453     in obtaining an object's name in printable form. Additional services
    454     are provided to decompose an object Id and determine which API
    455     and object class it belongs to.
     423    Object Services: presents a collection of helper services useful when
     424    manipulating RTEMS objects. These include methods to assist in obtaining an
     425    object's name in printable form. Additional services are provided to
     426    decompose an object Id and determine which API and object class it belongs
     427    to.
    456428
    457429Chapter 28:
    458     Chains: presents the methods provided to build, iterate and
    459     manipulate doubly-linked chains. This manager makes the
    460     chain implementation used internally by RTEMS to user space
    461     applications.
     430    Chains: presents the methods provided to build, iterate and manipulate
     431    doubly-linked chains. This manager makes the chain implementation used
     432    internally by RTEMS to user space applications.
    462433
    463434Chapter 29:
    464     Timespec Helpers: presents a set of helper services useful
    465     when manipulating POSIX ``struct timespec`` instances.
     435    Timespec Helpers: presents a set of helper services useful when
     436    manipulating POSIX ``struct timespec`` instances.
    466437
    467438Chapter 30:
     
    469440
    470441Chapter 31:
    471     Directive Status Codes: provides a definition of each of the
    472     directive status codes referenced in this manual.
     442    Directive Status Codes: provides a definition of each of the directive
     443    status codes referenced in this manual.
    473444
    474445Chapter 32:
     
    477448Chapter 33:
    478449    Glossary: defines terms used throughout this manual.
    479 
    480 .. COMMENT: COPYRIGHT (c) 1988-2007.
    481 
    482 .. COMMENT: On-Line Applications Research Corporation (OAR).
    483 
    484 .. COMMENT: All rights reserved.
    485 
    486 .. COMMENT: The following figure was replaced with an ASCII equivalent.
    487 
    488 .. COMMENT: Figure 2-1 Object ID Composition
    489 
  • c_user/preface.rst

    r0f5ccd4 rb8d3f6b  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Preface
    26#######
    37
    4 In recent years, the cost required to develop a
    5 software product has increased significantly while the target
    6 hardware costs have decreased.  Now a larger portion of money is
    7 expended in developing, using, and maintaining software.  The
    8 trend in computing costs is the complete dominance of software
    9 over hardware costs.  Because of this, it is necessary that
    10 formal disciplines be established to increase the probability
    11 that software is characterized by a high degree of correctness,
    12 maintainability, and portability.  In addition, these
    13 disciplines must promote practices that aid in the consistent
    14 and orderly development of a software system within schedule and
    15 budgetary constraints.  To be effective, these disciplines must
    16 adopt standards which channel individual software efforts toward
    17 a common goal.
     8In recent years, the cost required to develop a software product has increased
     9significantly while the target hardware costs have decreased.  Now a larger
     10portion of money is expended in developing, using, and maintaining software.
     11The trend in computing costs is the complete dominance of software over
     12hardware costs.  Because of this, it is necessary that formal disciplines be
     13established to increase the probability that software is characterized by a
     14high degree of correctness, maintainability, and portability.  In addition,
     15these disciplines must promote practices that aid in the consistent and orderly
     16development of a software system within schedule and budgetary constraints.  To
     17be effective, these disciplines must adopt standards which channel individual
     18software efforts toward a common goal.
    1819
    19 The push for standards in the software development
    20 field has been met with various degrees of success.  The
    21 Microprocessor Operating Systems Interfaces (MOSI) effort has
    22 experienced only limited success.  As popular as the UNIX
    23 operating system has grown, the attempt to develop a standard
    24 interface definition to allow portable application development
    25 has only recently begun to produce the results needed in this
    26 area.  Unfortunately, very little effort has been expended to
    27 provide standards addressing the needs of the real-time
    28 community.  Several organizations have addressed this need
    29 during recent years.
     20The push for standards in the software development field has been met with
     21various degrees of success.  The Microprocessor Operating Systems Interfaces
     22(MOSI) effort has experienced only limited success.  As popular as the UNIX
     23operating system has grown, the attempt to develop a standard interface
     24definition to allow portable application development has only recently begun to
     25produce the results needed in this area.  Unfortunately, very little effort has
     26been expended to provide standards addressing the needs of the real-time
     27community.  Several organizations have addressed this need during recent years.
    3028
    31 The Real Time Executive Interface Definition (RTEID)
    32 was developed by Motorola with technical input from Software
    33 Components Group.  RTEID was adopted by the VMEbus International
    34 Trade Association (VITA) as a baseline draft for their proposed
    35 standard multiprocessor, real-time executive interface, Open
    36 Real-Time Kernel Interface Definition (ORKID).  These two groups
    37 are currently working together with the IEEE P1003.4 committee
    38 to insure that the functionality of their proposed standards is
    39 adopted as the real-time extensions to POSIX.
     29The Real Time Executive Interface Definition (RTEID) was developed by Motorola
     30with technical input from Software Components Group.  RTEID was adopted by the
     31VMEbus International Trade Association (VITA) as a baseline draft for their
     32proposed standard multiprocessor, real-time executive interface, Open Real-Time
     33Kernel Interface Definition (ORKID).  These two groups are currently working
     34together with the IEEE P1003.4 committee to insure that the functionality of
     35their proposed standards is adopted as the real-time extensions to POSIX.
    4036
    41 This emerging standard defines an interface for the
    42 development of real-time software to ease the writing of
    43 real-time application programs that are directly portable across
    44 multiple real-time executive implementations.  This interface
    45 includes both the source code interfaces and run-time behavior
    46 as seen by a real-time application.  It does not include the
    47 details of how a kernel implements these functions.  The
    48 standard's goal is to serve as a complete definition of external
    49 interfaces so that application code that conforms to these
    50 interfaces will execute properly in all real-time executive
    51 environments.  With the use of a standards compliant executive,
    52 routines that acquire memory blocks, create and manage message
    53 queues, establish and use semaphores, and send and receive
    54 signals need not be redeveloped for a different real-time
    55 environment as long as the new environment is compliant with the
    56 standard.  Software developers need only concentrate on the
    57 hardware dependencies of the real-time system.  Furthermore,
    58 most hardware dependencies for real-time applications can be
    59 localized to the device drivers.
     37This emerging standard defines an interface for the development of real-time
     38software to ease the writing of real-time application programs that are
     39directly portable across multiple real-time executive implementations.  This
     40interface includes both the source code interfaces and run-time behavior as
     41seen by a real-time application.  It does not include the details of how a
     42kernel implements these functions.  The standard's goal is to serve as a
     43complete definition of external interfaces so that application code that
     44conforms to these interfaces will execute properly in all real-time executive
     45environments.  With the use of a standards compliant executive, routines that
     46acquire memory blocks, create and manage message queues, establish and use
     47semaphores, and send and receive signals need not be redeveloped for a
     48different real-time environment as long as the new environment is compliant
     49with the standard.  Software developers need only concentrate on the hardware
     50dependencies of the real-time system.  Furthermore, most hardware dependencies
     51for real-time applications can be localized to the device drivers.
    6052
    61 A compliant executive provides simple and flexible
    62 real-time multiprocessing.  It easily lends itself to both
    63 tightly-coupled and loosely-coupled configurations (depending on
    64 the system hardware configuration).  Objects such as tasks,
    65 queues, events, signals, semaphores, and memory blocks can be
    66 designated as global objects and accessed by any task regardless
    67 of which processor the object and the accessing task reside.
     53A compliant executive provides simple and flexible real-time multiprocessing.
     54It easily lends itself to both tightly-coupled and loosely-coupled
     55configurations (depending on the system hardware configuration).  Objects such
     56as tasks, queues, events, signals, semaphores, and memory blocks can be
     57designated as global objects and accessed by any task regardless of which
     58processor the object and the accessing task reside.
    6859
    69 The acceptance of a standard for real-time executives
    70 will produce the same advantages enjoyed from the push for UNIX
    71 standardization by AT&T's System V Interface Definition and
    72 IEEE's POSIX efforts.  A compliant multiprocessing executive
    73 will allow close coupling between UNIX systems and real-time
    74 executives to provide the many benefits of the UNIX development
    75 environment to be applied to real-time software development.
    76 Together they provide the necessary laboratory environment to
    77 implement real-time, distributed, embedded systems using a wide
    78 variety of computer architectures.
     60The acceptance of a standard for real-time executives will produce the same
     61advantages enjoyed from the push for UNIX standardization by AT&T's System V
     62Interface Definition and IEEE's POSIX efforts.  A compliant multiprocessing
     63executive will allow close coupling between UNIX systems and real-time
     64executives to provide the many benefits of the UNIX development environment to
     65be applied to real-time software development.  Together they provide the
     66necessary laboratory environment to implement real-time, distributed, embedded
     67systems using a wide variety of computer architectures.
    7968
    80 A study was completed in 1988, within the Research,
    81 Development, and Engineering Center, U.S. Army Missile Command,
    82 which compared the various aspects of the Ada programming
    83 language as they related to the application of Ada code in
    84 distributed and/or multiple processing systems.  Several
    85 critical conclusions were derived from the study.  These
    86 conclusions have a major impact on the way the Army develops
    87 application software for embedded applications. These impacts
    88 apply to both in-house software development and contractor
    89 developed software.
     69A study was completed in 1988, within the Research, Development, and
     70Engineering Center, U.S. Army Missile Command, which compared the various
     71aspects of the Ada programming language as they related to the application of
     72Ada code in distributed and/or multiple processing systems.  Several critical
     73conclusions were derived from the study.  These conclusions have a major impact
     74on the way the Army develops application software for embedded
     75applications. These impacts apply to both in-house software development and
     76contractor developed software.
    9077
    91 A conclusion of the analysis, which has been
    92 previously recognized by other agencies attempting to utilize
    93 Ada in a distributed or multiprocessing environment, is that the
    94 Ada programming language does not adequately support
    95 multiprocessing.  Ada does provide a mechanism for
    96 multi-tasking, however, this capability exists only for a single
    97 processor system.  The language also does not have inherent
    98 capabilities to access global named variables, flags or program
    99 code.  These critical features are essential in order for data
    100 to be shared between processors.  However, these drawbacks do
    101 have workarounds which are sometimes awkward and defeat the
    102 intent of software maintainability and portability goals.
     78A conclusion of the analysis, which has been previously recognized by other
     79agencies attempting to utilize Ada in a distributed or multiprocessing
     80environment, is that the Ada programming language does not adequately support
     81multiprocessing.  Ada does provide a mechanism for multi-tasking, however, this
     82capability exists only for a single processor system.  The language also does
     83not have inherent capabilities to access global named variables, flags or
     84program code.  These critical features are essential in order for data to be
     85shared between processors.  However, these drawbacks do have workarounds which
     86are sometimes awkward and defeat the intent of software maintainability and
     87portability goals.
    10388
    104 Another conclusion drawn from the analysis, was that
    105 the run time executives being delivered with the Ada compilers
    106 were too slow and inefficient to be used in modern missile
    107 systems.  A run time executive is the core part of the run time
    108 system code, or operating system code, that controls task
    109 scheduling, input/output management and memory management.
    110 Traditionally, whenever efficient executive (also known as
    111 kernel) code was required by the application, the user developed
    112 in-house software.  This software was usually written in
    113 assembly language for optimization.
     89Another conclusion drawn from the analysis, was that the run time executives
     90being delivered with the Ada compilers were too slow and inefficient to be used
     91in modern missile systems.  A run time executive is the core part of the run
     92time system code, or operating system code, that controls task scheduling,
     93input/output management and memory management.  Traditionally, whenever
     94efficient executive (also known as kernel) code was required by the
     95application, the user developed in-house software.  This software was usually
     96written in assembly language for optimization.
    11497
    115 Because of this shortcoming in the Ada programming
    116 language, software developers in research and development and
    117 contractors for project managed systems, are mandated by
    118 technology to purchase and utilize off-the-shelf third party
    119 kernel code.  The contractor, and eventually the Government,
    120 must pay a licensing fee for every copy of the kernel code used
    121 in an embedded system.
     98Because of this shortcoming in the Ada programming language, software
     99developers in research and development and contractors for project managed
     100systems, are mandated by technology to purchase and utilize off-the-shelf third
     101party kernel code.  The contractor, and eventually the Government, must pay a
     102licensing fee for every copy of the kernel code used in an embedded system.
    122103
    123 The main drawback to this development environment is
    124 that the Government does not own, nor has the right to modify
    125 code contained within the kernel.  V&V techniques in this
    126 situation are more difficult than if the complete source code
    127 were available. Responsibility for system failures due to faulty
    128 software is yet another area to be resolved under this
    129 environment.
     104The main drawback to this development environment is that the Government does
     105not own, nor has the right to modify code contained within the kernel.  V&V
     106techniques in this situation are more difficult than if the complete source
     107code were available. Responsibility for system failures due to faulty software
     108is yet another area to be resolved under this environment.
    130109
    131 The Guidance and Control Directorate began a software
    132 development effort to address these problems.  A project to
    133 develop an experimental run time kernel was begun that will
    134 eliminate the major drawbacks of the Ada programming language
    135 mentioned above. The Real Time Executive for Multiprocessor Systems
    136 (RTEMS) provides full capabilities for management of tasks,
    137 interrupts, time, and multiple processors in addition to those
    138 features typical of generic operating systems.  The code is
    139 Government owned, so no licensing fees are necessary.  RTEMS has
    140 been implemented in both the Ada and C programming languages.
    141 It has been ported to the following processor families:
     110The Guidance and Control Directorate began a software development effort to
     111address these problems.  A project to develop an experimental run time kernel
     112was begun that will eliminate the major drawbacks of the Ada programming
     113language mentioned above. The Real Time Executive for Multiprocessor Systems
     114(RTEMS) provides full capabilities for management of tasks, interrupts, time,
     115and multiple processors in addition to those features typical of generic
     116operating systems.  The code is Government owned, so no licensing fees are
     117necessary.  RTEMS has been implemented in both the Ada and C programming
     118languages.  It has been ported to the following processor families:
     119
     120- Adapteva Epiphany
    142121
    143122- Altera NIOS II
     
    163142- MIPS
    164143
     144- Moxie Processor
     145
     146- OpenRISC
     147
    165148- PowerPC
    166149
     
    173156- SPARC v7, v8, and V9
    174157
    175 Support for other processor families, including RISC, CISC, and DSP, is
    176 planned.  Since almost all of RTEMS is written in a high level language,
    177 ports to additional processor families require minimal effort.
     158Since almost all of RTEMS is written in a high level language, ports to
     159additional processor families require minimal effort.
    178160
    179 RTEMS multiprocessor support is capable of handling
    180 either homogeneous or heterogeneous systems.  The kernel
    181 automatically compensates for architectural differences (byte
    182 swapping, etc.) between processors.  This allows a much easier
    183 transition from one processor family to another without a major
    184 system redesign.
     161RTEMS multiprocessor support is capable of handling either homogeneous or
     162heterogeneous systems.  The kernel automatically compensates for architectural
     163differences (byte swapping, etc.) between processors.  This allows a much
     164easier transition from one processor family to another without a major system
     165redesign.
    185166
    186 Since the proposed standards are still in draft form,
    187 RTEMS cannot and does not claim compliance.  However, the status
    188 of the standard is being carefully monitored to guarantee that
    189 RTEMS provides the functionality specified in the standard.
    190 Once approved, RTEMS will be made compliant.
     167Since the proposed standards are still in draft form, RTEMS cannot and does not
     168claim compliance.  However, the status of the standard is being carefully
     169monitored to guarantee that RTEMS provides the functionality specified in the
     170standard.  Once approved, RTEMS will be made compliant.
    191171
    192 This document is a detailed users guide for a
    193 functionally compliant real-time multiprocessor executive.  It
    194 describes the user interface and run-time behavior of Release
    195 4.10.99.0 of the C interface
    196 to RTEMS.
    197 
    198 .. COMMENT: COPYRIGHT (c) 1988-2008.
    199 
    200 .. COMMENT: On-Line Applications Research Corporation (OAR).
    201 
    202 .. COMMENT: All rights reserved.
    203 
    204 .. COMMENT: This chapter is missing the following figures:
    205 
    206 .. COMMENT: Figure 1-1  RTEMS Application Architecture
    207 
    208 .. COMMENT: Figure 1-2  RTEMS Internal Architecture
    209 
     172This document is a detailed users guide for a functionally compliant real-time
     173multiprocessor executive.  It describes the user interface and run-time
     174behavior of Release 4.10.99.0 of the C interface to RTEMS.
  • c_user/rate_monotonic_manager.rst

    r0f5ccd4 rb8d3f6b  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Rate Monotonic Manager
    26######################
     
    1014The rate monotonic manager provides facilities to implement tasks which execute
    1115in a periodic fashion.  Critically, it also gathers information about the
    12 execution of those periods and can provide important statistics to the
    13 user which can be used to analyze and tune the application.  The directives
    14 provided by the rate monotonic manager are:
    15 
    16 - ``rtems_rate_monotonic_create`` - Create a rate monotonic period
    17 
    18 - ``rtems_rate_monotonic_ident`` - Get ID of a period
    19 
    20 - ``rtems_rate_monotonic_cancel`` - Cancel a period
    21 
    22 - ``rtems_rate_monotonic_delete`` - Delete a rate monotonic period
    23 
    24 - ``rtems_rate_monotonic_period`` - Conclude current/Start next period
    25 
    26 - ``rtems_rate_monotonic_get_status`` - Obtain status from a period
    27 
    28 - ``rtems_rate_monotonic_get_statistics`` - Obtain statistics from a period
    29 
    30 - ``rtems_rate_monotonic_reset_statistics`` - Reset statistics for a period
    31 
    32 - ``rtems_rate_monotonic_reset_all_statistics`` - Reset statistics for all periods
    33 
    34 - ``rtems_rate_monotonic_report_statistics`` - Print period statistics report
     16execution of those periods and can provide important statistics to the user
     17which can be used to analyze and tune the application.  The directives provided
     18by the rate monotonic manager are:
     19
     20- rtems_rate_monotonic_create_ - Create a rate monotonic period
     21
     22- rtems_rate_monotonic_ident_ - Get ID of a period
     23
     24- rtems_rate_monotonic_cancel_ - Cancel a period
     25
     26- rtems_rate_monotonic_delete_ - Delete a rate monotonic period
     27
     28- rtems_rate_monotonic_period_ - Conclude current/Start next period
     29
     30- rtems_rate_monotonic_get_status_ - Obtain status from a period
     31
     32- rtems_rate_monotonic_get_statistics_ - Obtain statistics from a period
     33
     34- rtems_rate_monotonic_reset_statistics_ - Reset statistics for a period
     35
     36- rtems_rate_monotonic_reset_all_statistics_ - Reset statistics for all periods
     37
     38- rtems_rate_monotonic_report_statistics_ - Print period statistics report
    3539
    3640Background
    3741==========
    3842
    39 The rate monotonic manager provides facilities to
    40 manage the execution of periodic tasks.  This manager was
    41 designed to support application designers who utilize the Rate
    42 Monotonic Scheduling Algorithm (RMS) to ensure that their
    43 periodic tasks will meet their deadlines, even under transient
    44 overload conditions.  Although designed for hard real-time
    45 systems, the services provided by the rate monotonic manager may
    46 be used by any application which requires periodic tasks.
     43The rate monotonic manager provides facilities to manage the execution of
     44periodic tasks.  This manager was designed to support application designers who
     45utilize the Rate Monotonic Scheduling Algorithm (RMS) to ensure that their
     46periodic tasks will meet their deadlines, even under transient overload
     47conditions.  Although designed for hard real-time systems, the services
     48provided by the rate monotonic manager may be used by any application which
     49requires periodic tasks.
    4750
    4851Rate Monotonic Manager Required Support
     
    5962information kept:
    6063
    61 - ``owner``
     64``owner``
    6265  is the id of the thread that owns this period.
    6366
    64 - ``count``
     67``count``
    6568  is the total number of periods executed.
    6669
    67 - ``missed_count``
     70``missed_count``
    6871  is the number of periods that were missed.
    6972
    70 - ``min_cpu_time``
    71   is the minimum amount of CPU execution time consumed
    72   on any execution of the periodic loop.
    73 
    74 - ``max_cpu_time``
    75   is the maximum amount of CPU execution time consumed
    76   on any execution of the periodic loop.
    77 
    78 - ``total_cpu_time``
    79   is the total amount of CPU execution time consumed
    80   by executions of the periodic loop.
    81 
    82 - ``min_wall_time``
    83   is the minimum amount of wall time that passed
    84   on any execution of the periodic loop.
    85 
    86 - ``max_wall_time``
    87   is the maximum amount of wall time that passed
    88   on any execution of the periodic loop.
    89 
    90 - ``total_wall_time``
    91   is the total amount of wall time that passed
    92   during executions of the periodic loop.
     73``min_cpu_time``
     74  is the minimum amount of CPU execution time consumed on any execution of the
     75  periodic loop.
     76
     77``max_cpu_time``
     78  is the maximum amount of CPU execution time consumed on any execution of the
     79  periodic loop.
     80
     81``total_cpu_time``
     82  is the total amount of CPU execution time consumed by executions of the
     83  periodic loop.
     84
     85``min_wall_time``
     86  is the minimum amount of wall time that passed on any execution of the
     87  periodic loop.
     88
     89``max_wall_time``
     90  is the maximum amount of wall time that passed on any execution of the
     91  periodic loop.
     92
     93``total_wall_time``
     94  is the total amount of wall time that passed during executions of the
     95  periodic loop.
    9396
    9497Each period is divided into two consecutive phases.  The period starts with the
     
    103106between a period miss or success.
    104107
    105 The period statistics information is inexpensive to maintain
    106 and can provide very useful insights into the execution
    107 characteristics of a periodic task loop.  But it is just information.
    108 The period statistics reported must be analyzed by the user in terms
    109 of what the applications is.  For example, in an application where
    110 priorities are assigned by the Rate Monotonic Algorithm, it would
    111 be very undesirable for high priority (i.e. frequency) tasks to
    112 miss their period.  Similarly, in nearly any application, if a
    113 task were supposed to execute its periodic loop every 10 milliseconds
    114 and it averaged 11 milliseconds, then application requirements
    115 are not being met.
    116 
    117 The information reported can be used to determine the "hot spots"
    118 in the application.  Given a period's id, the user can determine
    119 the length of that period.  From that information and the CPU usage,
    120 the user can calculate the percentage of CPU time consumed by that
    121 periodic task.  For example, a task executing for 20 milliseconds
    122 every 200 milliseconds is consuming 10 percent of the processor's
    123 execution time.  This is usually enough to make it a good candidate
    124 for optimization.
    125 
    126 However, execution time alone is not enough to gauge the value of
    127 optimizing a particular task.  It is more important to optimize
    128 a task executing 2 millisecond every 10 milliseconds (20 percent
    129 of the CPU) than one executing 10 milliseconds every 100 (10 percent
    130 of the CPU).  As a general rule of thumb, the higher frequency at
    131 which a task executes, the more important it is to optimize that
    132 task.
     108The period statistics information is inexpensive to maintain and can provide
     109very useful insights into the execution characteristics of a periodic task
     110loop.  But it is just information.  The period statistics reported must be
     111analyzed by the user in terms of what the applications is.  For example, in an
     112application where priorities are assigned by the Rate Monotonic Algorithm, it
     113would be very undesirable for high priority (i.e. frequency) tasks to miss
     114their period.  Similarly, in nearly any application, if a task were supposed to
     115execute its periodic loop every 10 milliseconds and it averaged 11
     116milliseconds, then application requirements are not being met.
     117
     118The information reported can be used to determine the "hot spots" in the
     119application.  Given a period's id, the user can determine the length of that
     120period.  From that information and the CPU usage, the user can calculate the
     121percentage of CPU time consumed by that periodic task.  For example, a task
     122executing for 20 milliseconds every 200 milliseconds is consuming 10 percent of
     123the processor's execution time.  This is usually enough to make it a good
     124candidate for optimization.
     125
     126However, execution time alone is not enough to gauge the value of optimizing a
     127particular task.  It is more important to optimize a task executing 2
     128millisecond every 10 milliseconds (20 percent of the CPU) than one executing 10
     129milliseconds every 100 (10 percent of the CPU).  As a general rule of thumb,
     130the higher frequency at which a task executes, the more important it is to
     131optimize that task.
    133132
    134133Rate Monotonic Manager Definitions
     
    136135.. index:: periodic task, definition
    137136
    138 A periodic task is one which must be executed at a
    139 regular interval.  The interval between successive iterations of
    140 the task is referred to as its period.  Periodic tasks can be
    141 characterized by the length of their period and execution time.
    142 The period and execution time of a task can be used to determine
    143 the processor utilization for that task.  Processor utilization
    144 is the percentage of processor time used and can be calculated
    145 on a per-task or system-wide basis.  Typically, the task's
    146 worst-case execution time will be less than its period.  For
    147 example, a periodic task's requirements may state that it should
    148 execute for 10 milliseconds every 100 milliseconds.  Although
    149 the execution time may be the average, worst, or best case, the
    150 worst-case execution time is more appropriate for use when
    151 analyzing system behavior under transient overload conditions... index:: aperiodic task, definition
    152 
    153 In contrast, an aperiodic task executes at irregular
    154 intervals and has only a soft deadline.  In other words, the
    155 deadlines for aperiodic tasks are not rigid, but adequate
    156 response times are desirable.  For example, an aperiodic task
    157 may process user input from a terminal... index:: sporadic task, definition
    158 
    159 Finally, a sporadic task is an aperiodic task with a
    160 hard deadline and minimum interarrival time.  The minimum
    161 interarrival time is the minimum period of time which exists
    162 between successive iterations of the task.  For example, a
    163 sporadic task could be used to process the pressing of a fire
    164 button on a joystick.  The mechanical action of the fire button
    165 ensures a minimum time period between successive activations,
    166 but the missile must be launched by a hard deadline.
     137A periodic task is one which must be executed at a regular interval.  The
     138interval between successive iterations of the task is referred to as its
     139period.  Periodic tasks can be characterized by the length of their period and
     140execution time.  The period and execution time of a task can be used to
     141determine the processor utilization for that task.  Processor utilization is
     142the percentage of processor time used and can be calculated on a per-task or
     143system-wide basis.  Typically, the task's worst-case execution time will be
     144less than its period.  For example, a periodic task's requirements may state
     145that it should execute for 10 milliseconds every 100 milliseconds.  Although
     146the execution time may be the average, worst, or best case, the worst-case
     147execution time is more appropriate for use when analyzing system behavior under
     148transient overload conditions... index:: aperiodic task, definition
     149
     150In contrast, an aperiodic task executes at irregular intervals and has only a
     151soft deadline.  In other words, the deadlines for aperiodic tasks are not
     152rigid, but adequate response times are desirable.  For example, an aperiodic
     153task may process user input from a terminal.
     154
     155.. index:: sporadic task, definition
     156
     157Finally, a sporadic task is an aperiodic task with a hard deadline and minimum
     158interarrival time.  The minimum interarrival time is the minimum period of time
     159which exists between successive iterations of the task.  For example, a
     160sporadic task could be used to process the pressing of a fire button on a
     161joystick.  The mechanical action of the fire button ensures a minimum time
     162period between successive activations, but the missile must be launched by a
     163hard deadline.
    167164
    168165Rate Monotonic Scheduling Algorithm
     
    171168.. index:: RMS Algorithm, definition
    172169
    173 The Rate Monotonic Scheduling Algorithm (RMS) is
    174 important to real-time systems designers because it allows one
    175 to guarantee that a set of tasks is schedulable.  A set of tasks
    176 is said to be schedulable if all of the tasks can meet their
    177 deadlines.  RMS provides a set of rules which can be used to
    178 perform a guaranteed schedulability analysis for a task set.
    179 This analysis determines whether a task set is schedulable under
    180 worst-case conditions and emphasizes the predictability of the
    181 system's behavior.  It has been proven that:
    182 
    183 - *RMS is an optimal static priority algorithm for
    184   scheduling independent, preemptible, periodic tasks
    185   on a single processor.*
    186 
    187 RMS is optimal in the sense that if a set of tasks
    188 can be scheduled by any static priority algorithm, then RMS will
    189 be able to schedule that task set.  RMS bases it schedulability
    190 analysis on the processor utilization level below which all
    191 deadlines can be met.
    192 
    193 RMS calls for the static assignment of task
    194 priorities based upon their period.  The shorter a task's
    195 period, the higher its priority.  For example, a task with a 1
    196 millisecond period has higher priority than a task with a 100
    197 millisecond period.  If two tasks have the same period, then RMS
    198 does not distinguish between the tasks.  However, RTEMS
    199 specifies that when given tasks of equal priority, the task
    200 which has been ready longest will execute first.  RMS's priority
    201 assignment scheme does not provide one with exact numeric values
    202 for task priorities.  For example, consider the following task
    203 set and priority assignments:
     170The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems
     171designers because it allows one to guarantee that a set of tasks is
     172schedulable.  A set of tasks is said to be schedulable if all of the tasks can
     173meet their deadlines.  RMS provides a set of rules which can be used to perform
     174a guaranteed schedulability analysis for a task set.  This analysis determines
     175whether a task set is schedulable under worst-case conditions and emphasizes
     176the predictability of the system's behavior.  It has been proven that:
     177
     178.. sidebar:: *RMS*
     179
     180  RMS is an optimal static priority algorithm for scheduling independent,
     181  preemptible, periodic tasks on a single processor.
     182
     183RMS is optimal in the sense that if a set of tasks can be scheduled by any
     184static priority algorithm, then RMS will be able to schedule that task set.
     185RMS bases it schedulability analysis on the processor utilization level below
     186which all deadlines can be met.
     187
     188RMS calls for the static assignment of task priorities based upon their period.
     189The shorter a task's period, the higher its priority.  For example, a task with
     190a 1 millisecond period has higher priority than a task with a 100 millisecond
     191period.  If two tasks have the same period, then RMS does not distinguish
     192between the tasks.  However, RTEMS specifies that when given tasks of equal
     193priority, the task which has been ready longest will execute first.  RMS's
     194priority assignment scheme does not provide one with exact numeric values for
     195task priorities.  For example, consider the following task set and priority
     196assignments:
    204197
    205198+--------------------+---------------------+---------------------+
     
    216209+--------------------+---------------------+---------------------+
    217210
    218 RMS only calls for task 1 to have the lowest
    219 priority, task 4 to have the highest priority, and tasks 2 and 3
    220 to have an equal priority between that of tasks 1 and 4.  The
    221 actual RTEMS priorities assigned to the tasks must only adhere
    222 to those guidelines.
    223 
    224 Many applications have tasks with both hard and soft
    225 deadlines.  The tasks with hard deadlines are typically referred
    226 to as the critical task set, with the soft deadline tasks being
    227 the non-critical task set.  The critical task set can be
    228 scheduled using RMS, with the non-critical tasks not executing
    229 under transient overload, by simply assigning priorities such
    230 that the lowest priority critical task (i.e. longest period) has
    231 a higher priority than the highest priority non-critical task.
    232 Although RMS may be used to assign priorities to the
    233 non-critical tasks, it is not necessary.  In this instance,
     211RMS only calls for task 1 to have the lowest priority, task 4 to have the
     212highest priority, and tasks 2 and 3 to have an equal priority between that of
     213tasks 1 and 4.  The actual RTEMS priorities assigned to the tasks must only
     214adhere to those guidelines.
     215
     216Many applications have tasks with both hard and soft deadlines.  The tasks with
     217hard deadlines are typically referred to as the critical task set, with the
     218soft deadline tasks being the non-critical task set.  The critical task set can
     219be scheduled using RMS, with the non-critical tasks not executing under
     220transient overload, by simply assigning priorities such that the lowest
     221priority critical task (i.e. longest period) has a higher priority than the
     222highest priority non-critical task.  Although RMS may be used to assign
     223priorities to the non-critical tasks, it is not necessary.  In this instance,
    234224schedulability is only guaranteed for the critical task set.
    235225
     
    239229.. index:: RMS schedulability analysis
    240230
    241 RMS allows application designers to ensure that tasks
    242 can meet all deadlines, even under transient overload, without
    243 knowing exactly when any given task will execute by applying
    244 proven schedulability analysis rules.
     231RMS allows application designers to ensure that tasks can meet all deadlines,
     232even under transient overload, without knowing exactly when any given task will
     233execute by applying proven schedulability analysis rules.
    245234
    246235Assumptions
    247236~~~~~~~~~~~
    248237
    249 The schedulability analysis rules for RMS were
    250 developed based on the following assumptions:
    251 
    252 - The requests for all tasks for which hard deadlines
    253   exist are periodic, with a constant interval between requests.
    254 
    255 - Each task must complete before the next request for it
    256   occurs.
    257 
    258 - The tasks are independent in that a task does not depend
    259   on the initiation or completion of requests for other tasks.
    260 
    261 - The execution time for each task without preemption or
    262   interruption is constant and does not vary.
    263 
    264 - Any non-periodic tasks in the system are special.  These
    265   tasks displace periodic tasks while executing and do not have
    266   hard, critical deadlines.
    267 
    268 Once the basic schedulability analysis is understood,
    269 some of the above assumptions can be relaxed and the
    270 side-effects accounted for.
     238The schedulability analysis rules for RMS were developed based on the following
     239assumptions:
     240
     241- The requests for all tasks for which hard deadlines exist are periodic, with
     242  a constant interval between requests.
     243
     244- Each task must complete before the next request for it occurs.
     245
     246- The tasks are independent in that a task does not depend on the initiation or
     247  completion of requests for other tasks.
     248
     249- The execution time for each task without preemption or interruption is
     250  constant and does not vary.
     251
     252- Any non-periodic tasks in the system are special.  These tasks displace
     253  periodic tasks while executing and do not have hard, critical deadlines.
     254
     255Once the basic schedulability analysis is understood, some of the above
     256assumptions can be relaxed and the side-effects accounted for.
    271257
    272258Processor Utilization Rule
     
    274260.. index:: RMS Processor Utilization Rule
    275261
    276 The Processor Utilization Rule requires that
    277 processor utilization be calculated based upon the period and
    278 execution time of each task.  The fraction of processor time
    279 spent executing task index is Time(index) / Period(index).  The
    280 processor utilization can be calculated as follows:
     262The Processor Utilization Rule requires that processor utilization be
     263calculated based upon the period and execution time of each task.  The fraction
     264of processor time spent executing task index is ``Time(index) /
     265Period(index)``.  The processor utilization can be calculated as follows:
     266
    281267.. code:: c
    282268
     
    285271    Utilization = Utilization + (Time(index)/Period(index))
    286272
    287 To ensure schedulability even under transient
    288 overload, the processor utilization must adhere to the following
    289 rule:
     273To ensure schedulability even under transient overload, the processor
     274utilization must adhere to the following rule:
     275
    290276.. code:: c
    291277
    292278    Utilization = maximum_tasks * (2**(1/maximum_tasks) - 1)
    293279
    294 As the number of tasks increases, the above formula
    295 approaches ln(2) for a worst-case utilization factor of
    296 approximately 0.693.  Many tasks sets can be scheduled with a
    297 greater utilization factor.  In fact, the average processor
    298 utilization threshold for a randomly generated task set is
    299 approximately 0.88.
     280As the number of tasks increases, the above formula approaches ln(2) for a
     281worst-case utilization factor of approximately 0.693.  Many tasks sets can be
     282scheduled with a greater utilization factor.  In fact, the average processor
     283utilization threshold for a randomly generated task set is approximately 0.88.
    300284
    301285Processor Utilization Rule Example
    302286~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    303287
    304 This example illustrates the application of the
    305 Processor Utilization Rule to an application with three critical
    306 periodic tasks.  The following table details the RMS priority,
    307 period, execution time, and processor utilization for each task:
    308 
     288This example illustrates the application of the Processor Utilization Rule to
     289an application with three critical periodic tasks.  The following table details
     290the RMS priority, period, execution time, and processor utilization for each
     291task:
    309292
    310293+------------+----------+--------+-----------+-------------+
     
    319302+------------+----------+--------+-----------+-------------+
    320303
    321 The total processor utilization for this task set is
    322 0.73 which is below the upper bound of 3 * (2**(1/3) - 1), or
    323 0.779, imposed by the Processor Utilization Rule.  Therefore,
    324 this task set is guaranteed to be schedulable using RMS.
     304The total processor utilization for this task set is 0.73 which is below the
     305upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor
     306Utilization Rule.  Therefore, this task set is guaranteed to be schedulable
     307using RMS.
    325308
    326309First Deadline Rule
     
    328311.. index:: RMS First Deadline Rule
    329312
    330 If a given set of tasks do exceed the processor
    331 utilization upper limit imposed by the Processor Utilization
    332 Rule, they can still be guaranteed to meet all their deadlines
    333 by application of the First Deadline Rule.  This rule can be
     313If a given set of tasks do exceed the processor utilization upper limit imposed
     314by the Processor Utilization Rule, they can still be guaranteed to meet all
     315their deadlines by application of the First Deadline Rule.  This rule can be
    334316stated as follows:
    335317
    336 For a given set of independent periodic tasks, if
    337 each task meets its first deadline when all tasks are started at
    338 the same time, then the deadlines will always be met for any
    339 combination of start times.
    340 
    341 A key point with this rule is that ALL periodic tasks
    342 are assumed to start at the exact same instant in time.
    343 Although this assumption may seem to be invalid,  RTEMS makes it
    344 quite easy to ensure.  By having a non-preemptible user
    345 initialization task, all application tasks, regardless of
    346 priority, can be created and started before the initialization
    347 deletes itself.  This technique ensures that all tasks begin to
    348 compete for execution time at the same instant - when the user
    349 initialization task deletes itself.
     318For a given set of independent periodic tasks, if each task meets its first
     319deadline when all tasks are started at the same time, then the deadlines will
     320always be met for any combination of start times.
     321
     322A key point with this rule is that ALL periodic tasks are assumed to start at
     323the exact same instant in time.  Although this assumption may seem to be
     324invalid, RTEMS makes it quite easy to ensure.  By having a non-preemptible user
     325initialization task, all application tasks, regardless of priority, can be
     326created and started before the initialization deletes itself.  This technique
     327ensures that all tasks begin to compete for execution time at the same instant
     328- when the user initialization task deletes itself.
    350329
    351330First Deadline Rule Example
    352331~~~~~~~~~~~~~~~~~~~~~~~~~~~
    353332
    354 The First Deadline Rule can ensure schedulability
    355 even when the Processor Utilization Rule fails.  The example
    356 below is a modification of the Processor Utilization Rule
    357 example where task execution time has been increased from 15 to
    358 25 units.  The following table details the RMS priority, period,
    359 execution time, and processor utilization for each task:
    360 .. code:: c
     333The First Deadline Rule can ensure schedulability even when the Processor
     334Utilization Rule fails.  The example below is a modification of the Processor
     335Utilization Rule example where task execution time has been increased from 15
     336to 25 units.  The following table details the RMS priority, period, execution
     337time, and processor utilization for each task:
    361338
    362339+------------+----------+--------+-----------+-------------+
     
    371348+------------+----------+--------+-----------+-------------+
    372349
    373 The total processor utilization for the modified task
    374 set is 0.83 which is above the upper bound of 3 * (2**(1/3) - 1),
    375 or 0.779, imposed by the Processor Utilization Rule.  Therefore,
    376 this task set is not guaranteed to be schedulable using RMS.
    377 However, the First Deadline Rule can guarantee the
    378 schedulability of this task set.  This rule calls for one to
    379 examine each occurrence of deadline until either all tasks have
    380 met their deadline or one task failed to meet its first
    381 deadline.  The following table details the time of each deadline
    382 occurrence, the maximum number of times each task may have run,
    383 the total execution time, and whether all the deadlines have
    384 been met.
    385 .. code:: c
     350The total processor utilization for the modified task set is 0.83 which is
     351above the upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor
     352Utilization Rule.  Therefore, this task set is not guaranteed to be schedulable
     353using RMS.  However, the First Deadline Rule can guarantee the schedulability
     354of this task set.  This rule calls for one to examine each occurrence of
     355deadline until either all tasks have met their deadline or one task failed to
     356meet its first deadline.  The following table details the time of each deadline
     357occurrence, the maximum number of times each task may have run, the total
     358execution time, and whether all the deadlines have been met:
    386359
    387360+----------+------+------+------+----------------------+---------------+
     
    394367+----------+------+------+------+----------------------+---------------+
    395368
    396 The key to this analysis is to recognize when each
    397 task will execute.  For example at time 100, task 1 must have
    398 met its first deadline, but tasks 2 and 3 may also have begun
    399 execution.  In this example, at time 100 tasks 1 and 2 have
    400 completed execution and thus have met their first deadline.
    401 Tasks 1 and 2 have used (25 + 50) = 75 time units, leaving (100
    402 - 75) = 25 time units for task 3 to begin.  Because task 3 takes
    403 100 ticks to execute, it will not have completed execution at
    404 time 100.  Thus at time 100, all of the tasks except task 3 have
    405 met their first deadline.
    406 
    407 At time 200, task 1 must have met its second deadline
    408 and task 2 its first deadline.  As a result, of the first 200
    409 time units, task 1 uses (2 * 25) = 50 and task 2 uses 50,
    410 leaving (200 - 100) time units for task 3.  Task 3 requires 100
    411 time units to execute, thus it will have completed execution at
    412 time 200.  Thus, all of the tasks have met their first deadlines
    413 at time 200, and the task set is schedulable using the First
    414 Deadline Rule.
     369The key to this analysis is to recognize when each task will execute.  For
     370example at time 100, task 1 must have met its first deadline, but tasks 2 and 3
     371may also have begun execution.  In this example, at time 100 tasks 1 and 2 have
     372completed execution and thus have met their first deadline.  Tasks 1 and 2 have
     373used (25 + 50) = 75 time units, leaving (100 - 75) = 25 time units for task 3
     374to begin.  Because task 3 takes 100 ticks to execute, it will not have
     375completed execution at time 100.  Thus at time 100, all of the tasks except
     376task 3 have met their first deadline.
     377
     378At time 200, task 1 must have met its second deadline and task 2 its first
     379deadline.  As a result, of the first 200 time units, task 1 uses (2 * 25) = 50
     380and task 2 uses 50, leaving (200 - 100) time units for task 3.  Task 3 requires
     381100 time units to execute, thus it will have completed execution at time 200.
     382Thus, all of the tasks have met their first deadlines at time 200, and the task
     383set is schedulable using the First Deadline Rule.
    415384
    416385Relaxation of Assumptions
    417386~~~~~~~~~~~~~~~~~~~~~~~~~
    418387
    419 The assumptions used to develop the RMS
    420 schedulability rules are uncommon in most real-time systems.
    421 For example, it was assumed that tasks have constant unvarying
    422 execution time.  It is possible to relax this assumption, simply
    423 by using the worst-case execution time of each task.
    424 
    425 Another assumption is that the tasks are independent.
    426 This means that the tasks do not wait for one another or
    427 contend for resources.  This assumption can be relaxed by
    428 accounting for the amount of time a task spends waiting to
    429 acquire resources.  Similarly, each task's execution time must
    430 account for any I/O performed and any RTEMS directive calls.
    431 
    432 In addition, the assumptions did not account for the
    433 time spent executing interrupt service routines.  This can be
    434 accounted for by including all the processor utilization by
    435 interrupt service routines in the utilization calculation.
    436 Similarly, one should also account for the impact of delays in
    437 accessing local memory caused by direct memory access and other
    438 processors accessing local dual-ported memory.
    439 
    440 The assumption that nonperiodic tasks are used only
    441 for initialization or failure-recovery can be relaxed by placing
    442 all periodic tasks in the critical task set.  This task set can
    443 be scheduled and analyzed using RMS.  All nonperiodic tasks are
    444 placed in the non-critical task set.  Although the critical task
    445 set can be guaranteed to execute even under transient overload,
     388The assumptions used to develop the RMS schedulability rules are uncommon in
     389most real-time systems.  For example, it was assumed that tasks have constant
     390unvarying execution time.  It is possible to relax this assumption, simply by
     391using the worst-case execution time of each task.
     392
     393Another assumption is that the tasks are independent.  This means that the
     394tasks do not wait for one another or contend for resources.  This assumption
     395can be relaxed by accounting for the amount of time a task spends waiting to
     396acquire resources.  Similarly, each task's execution time must account for any
     397I/O performed and any RTEMS directive calls.
     398
     399In addition, the assumptions did not account for the time spent executing
     400interrupt service routines.  This can be accounted for by including all the
     401processor utilization by interrupt service routines in the utilization
     402calculation.  Similarly, one should also account for the impact of delays in
     403accessing local memory caused by direct memory access and other processors
     404accessing local dual-ported memory.
     405
     406The assumption that nonperiodic tasks are used only for initialization or
     407failure-recovery can be relaxed by placing all periodic tasks in the critical
     408task set.  This task set can be scheduled and analyzed using RMS.  All
     409nonperiodic tasks are placed in the non-critical task set.  Although the
     410critical task set can be guaranteed to execute even under transient overload,
    446411the non-critical task set is not guaranteed to execute.
    447412
    448 In conclusion, the application designer must be fully
    449 cognizant of the system and its run-time behavior when
    450 performing schedulability analysis for a system using RMS.
    451 Every hardware and software factor which impacts the execution
    452 time of each task must be accounted for in the schedulability
    453 analysis.
     413In conclusion, the application designer must be fully cognizant of the system
     414and its run-time behavior when performing schedulability analysis for a system
     415using RMS.  Every hardware and software factor which impacts the execution time
     416of each task must be accounted for in the schedulability analysis.
    454417
    455418Further Reading
    456419~~~~~~~~~~~~~~~
    457420
    458 For more information on Rate Monotonic Scheduling and
    459 its schedulability analysis, the reader is referred to the
    460 following:
    461 
    462 - *C. L. Liu and J. W. Layland. "Scheduling Algorithms for
    463   Multiprogramming in a Hard Real Time Environment." *Journal of
    464   the Association of Computing Machinery*. January 1973. pp. 46-61.*
    465 
    466 - *John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic
    467   Scheduling Algorithm: Exact Characterization and Average Case
    468   Behavior."  *IEEE Real-Time Systems Symposium*. 1989. pp. 166-171.*
    469 
    470 - *Lui Sha and John Goodenough. "Real-Time Scheduling
    471   theory and Ada."  *IEEE Computer*. April 1990. pp. 53-62.*
    472 
    473 - *Alan Burns. "Scheduling hard real-time systems: a
    474   review."  *Software Engineering Journal*. May 1991. pp. 116-128.*
     421For more information on Rate Monotonic Scheduling and its schedulability
     422analysis, the reader is referred to the following:
     423
     424- C. L. Liu and J. W. Layland. "Scheduling Algorithms for Multiprogramming in a
     425  Hard Real Time Environment." *Journal of the Association of Computing
     426  Machinery*. January 1973. pp. 46-61.
     427
     428- John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic Scheduling
     429  Algorithm: Exact Characterization and Average Case Behavior."  *IEEE
     430  Real-Time Systems Symposium*. 1989. pp. 166-171.
     431
     432- Lui Sha and John Goodenough. "Real-Time Scheduling theory and Ada."  *IEEE
     433  Computer*. April 1990. pp. 53-62.
     434
     435- Alan Burns. "Scheduling hard real-time systems: a review."  *Software
     436  Engineering Journal*. May 1991. pp. 116-128.
    475437
    476438Operations
     
    480442--------------------------------
    481443
    482 The ``rtems_rate_monotonic_create`` directive creates a rate
    483 monotonic period which is to be used by the calling task to
    484 delineate a period.  RTEMS allocates a Period Control Block
    485 (PCB) from the PCB free list.  This data structure is used by
    486 RTEMS to manage the newly created rate monotonic period.  RTEMS
    487 returns a unique period ID to the application which is used by
    488 other rate monotonic manager directives to access this rate
    489 monotonic period.
     444The ``rtems_rate_monotonic_create`` directive creates a rate monotonic period
     445which is to be used by the calling task to delineate a period.  RTEMS allocates
     446a Period Control Block (PCB) from the PCB free list.  This data structure is
     447used by RTEMS to manage the newly created rate monotonic period.  RTEMS returns
     448a unique period ID to the application which is used by other rate monotonic
     449manager directives to access this rate monotonic period.
    490450
    491451Manipulating a Period
    492452---------------------
    493453
    494 The ``rtems_rate_monotonic_period`` directive is used to
    495 establish and maintain periodic execution utilizing a previously
    496 created rate monotonic period.   Once initiated by the``rtems_rate_monotonic_period`` directive, the period is
    497 said to run until it either expires or is reinitiated.  The state of the rate
     454The ``rtems_rate_monotonic_period`` directive is used to establish and maintain
     455periodic execution utilizing a previously created rate monotonic period.  Once
     456initiated by the ``rtems_rate_monotonic_period`` directive, the period is said
     457to run until it either expires or is reinitiated.  The state of the rate
    498458monotonic period results in one of the following scenarios:
    499459
    500 - If the rate monotonic period is running, the calling
    501   task will be blocked for the remainder of the outstanding period
    502   and, upon completion of that period, the period will be
    503   reinitiated with the specified period.
    504 
    505 - If the rate monotonic period is not currently running
    506   and has not expired, it is initiated with a length of period
    507   ticks and the calling task returns immediately.
    508 
    509 - If the rate monotonic period has expired before the task
    510   invokes the ``rtems_rate_monotonic_period`` directive,
    511   the period will be initiated with a length of period ticks and the calling task
    512   returns immediately with a timeout error status.
     460- If the rate monotonic period is running, the calling task will be blocked for
     461  the remainder of the outstanding period and, upon completion of that period,
     462  the period will be reinitiated with the specified period.
     463
     464- If the rate monotonic period is not currently running and has not expired, it
     465  is initiated with a length of period ticks and the calling task returns
     466  immediately.
     467
     468- If the rate monotonic period has expired before the task invokes the
     469  ``rtems_rate_monotonic_period`` directive, the period will be initiated with
     470  a length of period ticks and the calling task returns immediately with a
     471  timeout error status.
    513472
    514473Obtaining the Status of a Period
    515474--------------------------------
    516475
    517 If the ``rtems_rate_monotonic_period`` directive is invoked
    518 with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current
    519 state of the specified rate monotonic period will be returned.  The following
    520 table details the relationship between the period's status and
    521 the directive status code returned by the``rtems_rate_monotonic_period``
    522 directive:
    523 
    524 - ``RTEMS_SUCCESSFUL`` - period is running
    525 
    526 - ``RTEMS_TIMEOUT`` - period has expired
    527 
    528 - ``RTEMS_NOT_DEFINED`` - period has never been initiated
    529 
    530 Obtaining the status of a rate monotonic period does
    531 not alter the state or length of that period.
     476If the ``rtems_rate_monotonic_period`` directive is invoked with a period of
     477``RTEMS_PERIOD_STATUS`` ticks, the current state of the specified rate
     478monotonic period will be returned.  The following table details the
     479relationship between the period's status and the directive status code returned
     480by the ``rtems_rate_monotonic_period`` directive:
     481
     482``RTEMS_SUCCESSFUL``
     483  period is running
     484
     485``RTEMS_TIMEOUT``
     486  period has expired
     487
     488``RTEMS_NOT_DEFINED``
     489  period has never been initiated
     490
     491Obtaining the status of a rate monotonic period does not alter the state or
     492length of that period.
    532493
    533494Canceling a Period
    534495------------------
    535496
    536 The ``rtems_rate_monotonic_cancel`` directive is used to stop
    537 the period maintained by the specified rate monotonic period.
    538 The period is stopped and the rate monotonic period can be
    539 reinitiated using the ``rtems_rate_monotonic_period`` directive.
     497The ``rtems_rate_monotonic_cancel`` directive is used to stop the period
     498maintained by the specified rate monotonic period.  The period is stopped and
     499the rate monotonic period can be reinitiated using the
     500``rtems_rate_monotonic_period`` directive.
    540501
    541502Deleting a Rate Monotonic Period
    542503--------------------------------
    543504
    544 The ``rtems_rate_monotonic_delete`` directive is used to delete
    545 a rate monotonic period.  If the period is running and has not
    546 expired, the period is automatically canceled.  The rate
    547 monotonic period's control block is returned to the PCB free
    548 list when it is deleted.  A rate monotonic period can be deleted
    549 by a task other than the task which created the period.
     505The ``rtems_rate_monotonic_delete`` directive is used to delete a rate
     506monotonic period.  If the period is running and has not expired, the period is
     507automatically canceled.  The rate monotonic period's control block is returned
     508to the PCB free list when it is deleted.  A rate monotonic period can be
     509deleted by a task other than the task which created the period.
    550510
    551511Examples
    552512--------
    553513
    554 The following sections illustrate common uses of rate
    555 monotonic periods to construct periodic tasks.
     514The following sections illustrate common uses of rate monotonic periods to
     515construct periodic tasks.
    556516
    557517Simple Periodic Task
    558518--------------------
    559519
    560 This example consists of a single periodic task
    561 which, after initialization, executes every 100 clock ticks.
    562 .. code:: c
     520This example consists of a single periodic task which, after initialization,
     521executes every 100 clock ticks.
     522
     523.. code-block:: c
     524    :linenos:
    563525
    564526    rtems_task Periodic_task(rtems_task_argument arg)
    565527    {
    566     rtems_name        name;
    567     rtems_id          period;
    568     rtems_status_code status;
    569     name = rtems_build_name( 'P', 'E', 'R', 'D' );
    570     status = rtems_rate_monotonic_create( name, &period );
    571     if ( status != RTEMS_STATUS_SUCCESSFUL ) {
    572     printf( "rtems_monotonic_create failed with status of %d.\\n", rc );
    573     exit( 1 );
     528        rtems_name        name;
     529        rtems_id          period;
     530        rtems_status_code status;
     531        name = rtems_build_name( 'P', 'E', 'R', 'D' );
     532        status = rtems_rate_monotonic_create( name, &period );
     533        if ( status != RTEMS_STATUS_SUCCESSFUL ) {
     534            printf( "rtems_monotonic_create failed with status of %d.\n", rc );
     535            exit( 1 );
     536        }
     537        while ( 1 ) {
     538            if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT )
     539                break;
     540            /* Perform some periodic actions */
     541        }
     542        /* missed period so delete period and SELF */
     543        status = rtems_rate_monotonic_delete( period );
     544        if ( status != RTEMS_STATUS_SUCCESSFUL ) {
     545            printf( "rtems_rate_monotonic_delete failed with status of %d.\n", status );
     546            exit( 1 );
     547        }
     548        status = rtems_task_delete( SELF );    /* should not return */
     549        printf( "rtems_task_delete returned with status of %d.\n", status );
     550        exit( 1 );
    574551    }
    575     while ( 1 ) {
    576     if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT )
    577     break;
    578     /* Perform some periodic actions \*/
    579     }
    580     /* missed period so delete period and SELF \*/
    581     status = rtems_rate_monotonic_delete( period );
    582     if ( status != RTEMS_STATUS_SUCCESSFUL ) {
    583     printf( "rtems_rate_monotonic_delete failed with status of %d.\\n", status );
    584     exit( 1 );
    585     }
    586     status = rtems_task_delete( SELF );    /* should not return \*/
    587     printf( "rtems_task_delete returned with status of %d.\\n", status );
    588     exit( 1 );
    589     }
    590 
    591 The above task creates a rate monotonic period as
    592 part of its initialization.  The first time the loop is
    593 executed, the ``rtems_rate_monotonic_period``
    594 directive will initiate the period for 100 ticks and return
    595 immediately.  Subsequent invocations of the``rtems_rate_monotonic_period`` directive will result
    596 in the task blocking for the remainder of the 100 tick period.
    597 If, for any reason, the body of the loop takes more than 100
    598 ticks to execute, the ``rtems_rate_monotonic_period``
    599 directive will return the ``RTEMS_TIMEOUT`` status.
    600 If the above task misses its deadline, it will delete the rate
     552
     553The above task creates a rate monotonic period as part of its initialization.
     554The first time the loop is executed, the ``rtems_rate_monotonic_period``
     555directive will initiate the period for 100 ticks and return immediately.
     556Subsequent invocations of the ``rtems_rate_monotonic_period`` directive will
     557result in the task blocking for the remainder of the 100 tick period.  If, for
     558any reason, the body of the loop takes more than 100 ticks to execute, the
     559``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT``
     560status.  If the above task misses its deadline, it will delete the rate
    601561monotonic period and itself.
    602562
     
    604564--------------------------
    605565
    606 This example consists of a single periodic task
    607 which, after initialization, performs two sets of actions every
    608 100 clock ticks.  The first set of actions is performed in the
    609 first forty clock ticks of every 100 clock ticks, while the
    610 second set of actions is performed between the fortieth and
    611 seventieth clock ticks.  The last thirty clock ticks are not
    612 used by this task.
    613 .. code:: c
     566This example consists of a single periodic task which, after initialization,
     567performs two sets of actions every 100 clock ticks.  The first set of actions
     568is performed in the first forty clock ticks of every 100 clock ticks, while the
     569second set of actions is performed between the fortieth and seventieth clock
     570ticks.  The last thirty clock ticks are not used by this task.
     571
     572.. code-block:: c
     573    :linenos:
    614574
    615575    rtems_task Periodic_task(rtems_task_argument arg)
    616576    {
    617     rtems_name        name_1, name_2;
    618     rtems_id          period_1, period_2;
    619     rtems_status_code status;
    620     name_1 = rtems_build_name( 'P', 'E', 'R', '1' );
    621     name_2 = rtems_build_name( 'P', 'E', 'R', '2' );
    622     (void ) rtems_rate_monotonic_create( name_1, &period_1 );
    623     (void ) rtems_rate_monotonic_create( name_2, &period_2 );
    624     while ( 1 ) {
    625     if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT )
    626     break;
    627     if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT )
    628     break;
    629     /*
    630     *  Perform first set of actions between clock
    631     *  ticks 0 and 39 of every 100 ticks.
    632     \*/
    633     if ( rtems_rate_monotonic_period( period_2, 30 ) == TIMEOUT )
    634     break;
    635     /*
    636     *  Perform second set of actions between clock 40 and 69
    637     *  of every 100 ticks.  THEN ...
    638     *
    639     *  Check to make sure we didn't miss the period_2 period.
    640     \*/
    641     if ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT )
    642     break;
    643     (void) rtems_rate_monotonic_cancel( period_2 );
     577        rtems_name        name_1, name_2;
     578        rtems_id          period_1, period_2;
     579        rtems_status_code status;
     580        name_1 = rtems_build_name( 'P', 'E', 'R', '1' );
     581        name_2 = rtems_build_name( 'P', 'E', 'R', '2' );
     582        (void ) rtems_rate_monotonic_create( name_1, &period_1 );
     583        (void ) rtems_rate_monotonic_create( name_2, &period_2 );
     584        while ( 1 ) {
     585            if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT )
     586                break;
     587            if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT )
     588            break;
     589            /*
     590             *  Perform first set of actions between clock
     591             *  ticks 0 and 39 of every 100 ticks.
     592             */
     593            if ( rtems_rate_monotonic_period( period_2, 30 ) == TIMEOUT )
     594                break;
     595            /*
     596             *  Perform second set of actions between clock 40 and 69
     597             *  of every 100 ticks.  THEN ...
     598             *
     599             *  Check to make sure we didn't miss the period_2 period.
     600             */
     601            if ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT )
     602                break;
     603            (void) rtems_rate_monotonic_cancel( period_2 );
     604        }
     605        /* missed period so delete period and SELF */
     606        (void ) rtems_rate_monotonic_delete( period_1 );
     607        (void ) rtems_rate_monotonic_delete( period_2 );
     608        (void ) task_delete( SELF );
    644609    }
    645     /* missed period so delete period and SELF \*/
    646     (void ) rtems_rate_monotonic_delete( period_1 );
    647     (void ) rtems_rate_monotonic_delete( period_2 );
    648     (void ) task_delete( SELF );
    649     }
    650 
    651 The above task creates two rate monotonic periods as
    652 part of its initialization.  The first time the loop is
    653 executed, the ``rtems_rate_monotonic_period``
    654 directive will initiate the period_1 period for 100 ticks
    655 and return immediately.  Subsequent invocations of the``rtems_rate_monotonic_period`` directive
    656 for period_1 will result in the task blocking for the remainder
    657 of the 100 tick period.  The period_2 period is used to control
    658 the execution time of the two sets of actions within each 100
    659 tick period established by period_1.  The``rtems_rate_monotonic_cancel( period_2 )``
    660 call is performed to ensure that the period_2 period
    661 does not expire while the task is blocked on the period_1
    662 period.  If this cancel operation were not performed, every time
    663 the ``rtems_rate_monotonic_period( period_2, 40 )``
    664 call is executed, except for the initial one, a directive status
    665 of ``RTEMS_TIMEOUT`` is returned.  It is important to
    666 note that every time this call is made, the period_2 period will be
    667 initiated immediately and the task will not block.
    668 
    669 If, for any reason, the task misses any deadline, the``rtems_rate_monotonic_period`` directive will
    670 return the ``RTEMS_TIMEOUT``
    671 directive status.  If the above task misses its deadline, it
    672 will delete the rate monotonic periods and itself.
     610
     611The above task creates two rate monotonic periods as part of its
     612initialization.  The first time the loop is executed, the
     613``rtems_rate_monotonic_period`` directive will initiate the period_1 period for
     614100 ticks and return immediately.  Subsequent invocations of the
     615``rtems_rate_monotonic_period`` directive for period_1 will result in the task
     616blocking for the remainder of the 100 tick period.  The period_2 period is used
     617to control the execution time of the two sets of actions within each 100 tick
     618period established by period_1.  The ``rtems_rate_monotonic_cancel( period_2
     619)`` call is performed to ensure that the period_2 period does not expire while
     620the task is blocked on the period_1 period.  If this cancel operation were not
     621performed, every time the ``rtems_rate_monotonic_period( period_2, 40 )`` call
     622is executed, except for the initial one, a directive status of
     623``RTEMS_TIMEOUT`` is returned.  It is important to note that every time this
     624call is made, the period_2 period will be initiated immediately and the task
     625will not block.
     626
     627If, for any reason, the task misses any deadline, the
     628``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT``
     629directive status.  If the above task misses its deadline, it will delete the
     630rate monotonic periods and itself.
    673631
    674632Directives
    675633==========
    676634
    677 This section details the rate monotonic manager's
    678 directives.  A subsection is dedicated to each of this manager's
    679 directives and describes the calling sequence, related
    680 constants, usage, and status codes.
     635This section details the rate monotonic manager's directives.  A subsection is
     636dedicated to each of this manager's directives and describes the calling
     637sequence, related constants, usage, and status codes.
     638
     639.. _rtems_rate_monotonic_create:
    681640
    682641RATE_MONOTONIC_CREATE - Create a rate monotonic period
     
    691650
    692651    rtems_status_code rtems_rate_monotonic_create(
    693     rtems_name  name,
    694     rtems_id   \*id
     652        rtems_name  name,
     653        rtems_id   *id
    695654    );
    696655
    697656**DIRECTIVE STATUS CODES:**
    698657
    699 ``RTEMS_SUCCESSFUL`` - rate monotonic period created successfully
    700 ``RTEMS_INVALID_NAME`` - invalid period name
    701 ``RTEMS_TOO_MANY`` - too many periods created
     658``RTEMS_SUCCESSFUL``
     659  rate monotonic period created successfully
     660
     661``RTEMS_INVALID_NAME``
     662  invalid period name
     663
     664``RTEMS_TOO_MANY``
     665  too many periods created
    702666
    703667**DESCRIPTION:**
    704668
    705 This directive creates a rate monotonic period.  The
    706 assigned rate monotonic id is returned in id.  This id is used
    707 to access the period with other rate monotonic manager
    708 directives.  For control and maintenance of the rate monotonic
    709 period, RTEMS allocates a PCB from the local PCB free pool and
     669This directive creates a rate monotonic period.  The assigned rate monotonic id
     670is returned in id.  This id is used to access the period with other rate
     671monotonic manager directives.  For control and maintenance of the rate
     672monotonic period, RTEMS allocates a PCB from the local PCB free pool and
    710673initializes it.
    711674
    712675**NOTES:**
    713676
    714 This directive will not cause the calling task to be
    715 preempted.
     677This directive will not cause the calling task to be preempted.
     678
     679.. _rtems_rate_monotonic_ident:
    716680
    717681RATE_MONOTONIC_IDENT - Get ID of a period
     
    727691
    728692    rtems_status_code rtems_rate_monotonic_ident(
    729     rtems_name  name,
    730     rtems_id   \*id
     693        rtems_name  name,
     694        rtems_id   *id
    731695    );
    732696
    733697**DIRECTIVE STATUS CODES:**
    734698
    735 ``RTEMS_SUCCESSFUL`` - period identified successfully
    736 ``RTEMS_INVALID_NAME`` - period name not found
     699``RTEMS_SUCCESSFUL``
     700  period identified successfully
     701
     702``RTEMS_INVALID_NAME``
     703  period name not found
    737704
    738705**DESCRIPTION:**
    739706
    740 This directive obtains the period id associated with
    741 the period name to be acquired.  If the period name is not
    742 unique, then the period id will match one of the periods with
    743 that name.  However, this period id is not guaranteed to
    744 correspond to the desired period.  The period id is used to
    745 access this period in other rate monotonic manager directives.
     707This directive obtains the period id associated with the period name to be
     708acquired.  If the period name is not unique, then the period id will match one
     709of the periods with that name.  However, this period id is not guaranteed to
     710correspond to the desired period.  The period id is used to access this period
     711in other rate monotonic manager directives.
    746712
    747713**NOTES:**
    748714
    749 This directive will not cause the running task to be
    750 preempted.
     715This directive will not cause the running task to be preempted.
     716
     717.. _rtems_rate_monotonic_cancel:
    751718
    752719RATE_MONOTONIC_CANCEL - Cancel a period
     
    761728
    762729    rtems_status_code rtems_rate_monotonic_cancel(
    763     rtems_id id
     730        rtems_id id
    764731    );
    765732
    766733**DIRECTIVE STATUS CODES:**
    767734
    768 ``RTEMS_SUCCESSFUL`` - period canceled successfully
    769 ``RTEMS_INVALID_ID`` - invalid rate monotonic period id
    770 ``RTEMS_NOT_OWNER_OF_RESOURCE`` - rate monotonic period not created by calling task
     735``RTEMS_SUCCESSFUL``
     736  period canceled successfully
     737
     738``RTEMS_INVALID_ID``
     739  invalid rate monotonic period id
     740
     741``RTEMS_NOT_OWNER_OF_RESOURCE``
     742  rate monotonic period not created by calling task
    771743
    772744**DESCRIPTION:**
    773745
    774 This directive cancels the rate monotonic period id.
    775 This period will be reinitiated by the next invocation of``rtems_rate_monotonic_period`` with id.
     746This directive cancels the rate monotonic period id.  This period will be
     747reinitiated by the next invocation of ``rtems_rate_monotonic_period`` with id.
    776748
    777749**NOTES:**
    778750
    779 This directive will not cause the running task to be
    780 preempted.
    781 
    782 The rate monotonic period specified by id must have
    783 been created by the calling task.
     751This directive will not cause the running task to be preempted.
     752
     753The rate monotonic period specified by id must have been created by the calling
     754task.
     755
     756.. _rtems_rate_monotonic_delete:
    784757
    785758RATE_MONOTONIC_DELETE - Delete a rate monotonic period
     
    794767
    795768    rtems_status_code rtems_rate_monotonic_delete(
    796     rtems_id id
     769        rtems_id id
    797770    );
    798771
    799772**DIRECTIVE STATUS CODES:**
    800773
    801 ``RTEMS_SUCCESSFUL`` - period deleted successfully
    802 ``RTEMS_INVALID_ID`` - invalid rate monotonic period id
     774``RTEMS_SUCCESSFUL``
     775  period deleted successfully
     776
     777``RTEMS_INVALID_ID``
     778  invalid rate monotonic period id
    803779
    804780**DESCRIPTION:**
    805781
    806 This directive deletes the rate monotonic period
    807 specified by id.  If the period is running, it is automatically
    808 canceled.  The PCB for the deleted period is reclaimed by RTEMS.
     782This directive deletes the rate monotonic period specified by id.  If the
     783period is running, it is automatically canceled.  The PCB for the deleted
     784period is reclaimed by RTEMS.
    809785
    810786**NOTES:**
    811787
    812 This directive will not cause the running task to be
    813 preempted.
    814 
    815 A rate monotonic period can be deleted by a task
    816 other than the task which created the period.
     788This directive will not cause the running task to be preempted.
     789
     790A rate monotonic period can be deleted by a task other than the task which
     791created the period.
     792
     793.. _rtems_rate_monotonic_period:
    817794
    818795RATE_MONOTONIC_PERIOD - Conclude current/Start next period
     
    829806
    830807    rtems_status_code rtems_rate_monotonic_period(
    831     rtems_id       id,
    832     rtems_interval length
     808        rtems_id       id,
     809        rtems_interval length
    833810    );
    834811
    835812**DIRECTIVE STATUS CODES:**
    836813
    837 ``RTEMS_SUCCESSFUL`` - period initiated successfully
    838 ``RTEMS_INVALID_ID`` - invalid rate monotonic period id
    839 ``RTEMS_NOT_OWNER_OF_RESOURCE`` - period not created by calling task
    840 ``RTEMS_NOT_DEFINED`` - period has never been initiated (only
    841 possible when period is set to PERIOD_STATUS)
    842 ``RTEMS_TIMEOUT`` - period has expired
     814``RTEMS_SUCCESSFUL``
     815  period initiated successfully
     816
     817``RTEMS_INVALID_ID``
     818  invalid rate monotonic period id
     819
     820``RTEMS_NOT_OWNER_OF_RESOURCE``
     821  period not created by calling task
     822
     823``RTEMS_NOT_DEFINED``
     824  period has never been initiated (only possible when period is set to
     825  PERIOD_STATUS)
     826
     827``RTEMS_TIMEOUT``
     828  period has expired
    843829
    844830**DESCRIPTION:**
    845831
    846 This directive initiates the rate monotonic period id
    847 with a length of period ticks.  If id is running, then the
    848 calling task will block for the remainder of the period before
    849 reinitiating the period with the specified period.  If id was
    850 not running (either expired or never initiated), the period is
    851 immediately initiated and the directive returns immediately.
    852 
    853 If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the
    854 current state of id will be returned.  The directive status
    855 indicates the current state of the period.  This does not alter
    856 the state or period of the period.
     832This directive initiates the rate monotonic period id with a length of period
     833ticks.  If id is running, then the calling task will block for the remainder of
     834the period before reinitiating the period with the specified period.  If id was
     835not running (either expired or never initiated), the period is immediately
     836initiated and the directive returns immediately.
     837
     838If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current state of
     839id will be returned.  The directive status indicates the current state of the
     840period.  This does not alter the state or period of the period.
    857841
    858842**NOTES:**
    859843
    860844This directive will not cause the running task to be preempted.
     845
     846.. _rtems_rate_monotonic_get_status:
    861847
    862848RATE_MONOTONIC_GET_STATUS - Obtain status from a period
     
    872858
    873859    rtems_status_code rtems_rate_monotonic_get_status(
    874     rtems_id                            id,
    875     rtems_rate_monotonic_period_status \*status
     860        rtems_id                            id,
     861        rtems_rate_monotonic_period_status \status
    876862    );
    877863
    878864**DIRECTIVE STATUS CODES:**
    879865
    880 ``RTEMS_SUCCESSFUL`` - period initiated successfully
    881 ``RTEMS_INVALID_ID`` - invalid rate monotonic period id
    882 ``RTEMS_INVALID_ADDRESS`` - invalid address of status
     866``RTEMS_SUCCESSFUL``
     867  period initiated successfully
     868
     869``RTEMS_INVALID_ID``
     870  invalid rate monotonic period id
     871
     872``RTEMS_INVALID_ADDRESS``
     873  invalid address of status
    883874
    884875**DESCRIPTION:**
    885876
    886 This directive returns status information associated with
    887 the rate monotonic period id in the following data structure:.. index:: rtems_rate_monotonic_period_status
     877This directive returns status information associated with the rate monotonic
     878period id in the following data structure:
     879
     880.. index:: rtems_rate_monotonic_period_status
    888881
    889882.. code:: c
    890883
    891884    typedef struct {
    892     rtems_id                              owner;
    893     rtems_rate_monotonic_period_states    state;
    894     rtems_rate_monotonic_period_time_t    since_last_period;
    895     rtems_thread_cpu_usage_t              executed_since_last_period;
     885        rtems_id                              owner;
     886        rtems_rate_monotonic_period_states    state;
     887        rtems_rate_monotonic_period_time_t    since_last_period;
     888        rtems_thread_cpu_usage_t              executed_since_last_period;
    896889    }  rtems_rate_monotonic_period_status;
    897890
    898 .. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS_ in front of it.
     891.. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it.
    899892
    900893A configure time option can be used to select whether the time information is
    901894given in ticks or seconds and nanoseconds.  The default is seconds and
    902 nanoseconds.  If the period's state is ``RATE_MONOTONIC_INACTIVE``, both
    903 time values will be set to 0.  Otherwise, both time values will contain
    904 time information since the last invocation of the``rtems_rate_monotonic_period`` directive.  More
    905 specifically, the ticks_since_last_period value contains the elapsed time
    906 which has occurred since the last invocation of the``rtems_rate_monotonic_period`` directive and the
    907 ticks_executed_since_last_period contains how much processor time the
    908 owning task has consumed since the invocation of the``rtems_rate_monotonic_period`` directive.
     895nanoseconds.  If the period's state is ``RATE_MONOTONIC_INACTIVE``, both time
     896values will be set to 0.  Otherwise, both time values will contain time
     897information since the last invocation of the ``rtems_rate_monotonic_period``
     898directive.  More specifically, the ticks_since_last_period value contains the
     899elapsed time which has occurred since the last invocation of the
     900``rtems_rate_monotonic_period`` directive and the
     901``ticks_executed_since_last_period`` contains how much processor time the
     902owning task has consumed since the invocation of the
     903``rtems_rate_monotonic_period`` directive.
    909904
    910905**NOTES:**
    911906
    912907This directive will not cause the running task to be preempted.
     908
     909.. _rtems_rate_monotonic_get_statistics:
    913910
    914911RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period
     
    924921
    925922    rtems_status_code rtems_rate_monotonic_get_statistics(
    926     rtems_id                                id,
    927     rtems_rate_monotonic_period_statistics \*statistics
     923        rtems_id                                id,
     924        rtems_rate_monotonic_period_statistics *statistics
    928925    );
    929926
    930927**DIRECTIVE STATUS CODES:**
    931928
    932 ``RTEMS_SUCCESSFUL`` - period initiated successfully
    933 ``RTEMS_INVALID_ID`` - invalid rate monotonic period id
    934 ``RTEMS_INVALID_ADDRESS`` - invalid address of statistics
     929``RTEMS_SUCCESSFUL``
     930  period initiated successfully
     931
     932``RTEMS_INVALID_ID``
     933  invalid rate monotonic period id
     934
     935``RTEMS_INVALID_ADDRESS``
     936  invalid address of statistics
    935937
    936938**DESCRIPTION:**
    937939
    938 This directive returns statistics information associated with
    939 the rate monotonic period id in the following data structure:.. index:: rtems_rate_monotonic_period_statistics
     940This directive returns statistics information associated with the rate
     941monotonic period id in the following data structure:
     942
     943.. index:: rtems_rate_monotonic_period_statistics
    940944
    941945.. code:: c
    942946
    943947    typedef struct {
    944     uint32_t     count;
    945     uint32_t     missed_count;
    946     #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS
    947     struct timespec min_cpu_time;
    948     struct timespec max_cpu_time;
    949     struct timespec total_cpu_time;
    950     #else
    951     uint32_t  min_cpu_time;
    952     uint32_t  max_cpu_time;
    953     uint32_t  total_cpu_time;
    954     #endif
    955     #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS
    956     struct timespec min_wall_time;
    957     struct timespec max_wall_time;
    958     struct timespec total_wall_time;
    959     #else
    960     uint32_t  min_wall_time;
    961     uint32_t  max_wall_time;
    962     uint32_t  total_wall_time;
    963     #endif
     948        uint32_t     count;
     949        uint32_t     missed_count;
     950        #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS
     951          struct timespec min_cpu_time;
     952          struct timespec max_cpu_time;
     953          struct timespec total_cpu_time;
     954        #else
     955          uint32_t  min_cpu_time;
     956          uint32_t  max_cpu_time;
     957          uint32_t  total_cpu_time;
     958        #endif
     959        #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS
     960          struct timespec min_wall_time;
     961          struct timespec max_wall_time;
     962          struct timespec total_wall_time;
     963        #else
     964         uint32_t  min_wall_time;
     965         uint32_t  max_wall_time;
     966         uint32_t  total_wall_time;
     967        #endif
    964968    }  rtems_rate_monotonic_period_statistics;
    965969
    966 This directive returns the current statistics information for
    967 the period instance assocaited with ``id``.  The information
    968 returned is indicated by the structure above.
     970This directive returns the current statistics information for the period
     971instance assocaited with ``id``.  The information returned is indicated by the
     972structure above.
    969973
    970974**NOTES:**
    971975
    972976This directive will not cause the running task to be preempted.
     977
     978.. _rtems_rate_monotonic_reset_statistics:
    973979
    974980RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period
     
    983989
    984990    rtems_status_code rtems_rate_monotonic_reset_statistics(
    985     rtems_id  id
     991        rtems_id  id
    986992    );
    987993
    988994**DIRECTIVE STATUS CODES:**
    989995
    990 ``RTEMS_SUCCESSFUL`` - period initiated successfully
    991 ``RTEMS_INVALID_ID`` - invalid rate monotonic period id
     996``RTEMS_SUCCESSFUL``
     997  period initiated successfully
     998
     999``RTEMS_INVALID_ID``
     1000  invalid rate monotonic period id
    9921001
    9931002**DESCRIPTION:**
    9941003
    995 This directive resets the statistics information associated with
    996 this rate monotonic period instance.
     1004This directive resets the statistics information associated with this rate
     1005monotonic period instance.
    9971006
    9981007**NOTES:**
    9991008
    10001009This directive will not cause the running task to be preempted.
     1010
     1011.. _rtems_rate_monotonic_reset_all_statistics:
    10011012
    10021013RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods
     
    10181029**DESCRIPTION:**
    10191030
    1020 This directive resets the statistics information associated with
    1021 all rate monotonic period instances.
     1031This directive resets the statistics information associated with all rate
     1032monotonic period instances.
    10221033
    10231034**NOTES:**
    10241035
    10251036This directive will not cause the running task to be preempted.
     1037
     1038.. _rtems_rate_monotonic_report_statistics:
    10261039
    10271040RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
     
    10441057**DESCRIPTION:**
    10451058
    1046 This directive prints a report on all active periods which have
    1047 executed at least one period. The following is an example of the
    1048 output generated by this directive... index:: rtems_rate_monotonic_period_statistics
     1059This directive prints a report on all active periods which have executed at
     1060least one period. The following is an example of the output generated by this
     1061directive.
     1062
     1063.. index:: rtems_rate_monotonic_period_statistics
    10491064
    10501065.. code:: c
     
    10611076
    10621077This directive will not cause the running task to be preempted.
    1063 
    1064 .. COMMENT: COPYRIGHT (c) 1988-2007.
    1065 
    1066 .. COMMENT: On-Line Applications Research Corporation (OAR).
    1067 
    1068 .. COMMENT: All rights reserved.
    1069 
  • c_user/rtems_data_types.rst

    r0f5ccd4 rb8d3f6b  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15RTEMS Data Types
    26################
     
    59============
    610
    7 This chapter contains a complete list of the RTEMS primitive
    8 data types in alphabetical order.  This is intended to be
    9 an overview and the user is encouraged to look at the appropriate
    10 chapters in the manual for more information about the
    11 usage of the various data types.
     11This chapter contains a complete list of the RTEMS primitive data types in
     12alphabetical order.  This is intended to be an overview and the user is
     13encouraged to look at the appropriate chapters in the manual for more
     14information about the usage of the various data types.
    1215
    1316List of Data Types
    1417==================
    1518
    16 The following is a complete list of the RTEMS primitive
    17 data types in alphabetical order:
    18 
    19 - .. index:: rtems_address
    20 
    21   ``rtems_address`` is the data type used to manage
    22   addresses.  It is equivalent to
    23   a "void \*" pointer.
    24 
    25 - .. index:: rtems_asr
    26 
    27   ``rtems_asr`` is the return type for an
    28   RTEMS ASR.
    29 
    30 - .. index:: rtems_asr_entry
    31 
    32   ``rtems_asr_entry`` is the address of
    33   the entry point to an RTEMS ASR.
    34 
    35 - .. index:: rtems_attribute
    36 
    37   ``rtems_attribute`` is the data type used
    38   to manage the attributes for RTEMS objects.  It is primarily
    39   used as an argument to object create routines to specify
     19The following is a complete list of the RTEMS primitive data types in
     20alphabetical order:
     21
     22.. index:: rtems_address
     23
     24``rtems_address``
     25  The data type used to manage addresses.  It is equivalent to a ``void *``
     26  pointer.
     27
     28.. index:: rtems_asr
     29
     30``rtems_asr``
     31  The return type for an RTEMS ASR.
     32
     33.. index:: rtems_asr_entry
     34
     35``rtems_asr_entry``
     36  The address of the entry point to an RTEMS ASR.
     37
     38 .. index:: rtems_attribute
     39
     40``rtems_attribute``
     41  The data type used to manage the attributes for RTEMS objects.  It is
     42  primarily used as an argument to object create routines to specify
    4043  characteristics of the new object.
    4144
    42 - .. index:: rtems_boolean
    43 
    44   ``rtems_boolean`` may only take on the
    45   values of ``TRUE`` and ``FALSE``.
    46   This type is deprecated. Use "bool" instead.
    47 
    48 - .. index:: rtems_context
    49 
    50   ``rtems_context`` is the CPU dependent
    51   data structure used to manage the integer and system
     45.. index:: rtems_boolean
     46
     47``rtems_boolean``
     48  May only take on the values of ``TRUE`` and ``FALSE``.  This type is
     49  deprecated. Use ``bool`` instead.
     50
     51.. index:: rtems_context
     52
     53``rtems_context``
     54  The CPU dependent data structure used to manage the integer and system
    5255  register portion of each task's context.
    5356
    54 - .. index:: rtems_context_fp
    55 
    56   ``rtems_context_fp`` is the CPU dependent
    57   data structure used to manage the floating point portion of
     57.. index:: rtems_context_fp
     58
     59``rtems_context_fp``
     60  The CPU dependent data structure used to manage the floating point portion of
    5861  each task's context.
    5962
    60 - .. index:: rtems_device_driver
    61 
    62   ``rtems_device_driver`` is the
    63   return type for a RTEMS device driver routine.
    64 
    65 - .. index:: rtems_device_driver_entry
    66 
    67   ``rtems_device_driver_entry`` is the
    68   entry point to a RTEMS device driver routine.
    69 
    70 - .. index:: rtems_device_major_number
    71 
    72   ``rtems_device_major_number`` is the
    73   data type used to manage device major numbers.
    74 
    75 - .. index:: rtems_device_minor_number
    76 
    77   ``rtems_device_minor_number`` is the
    78   data type used to manage device minor numbers.
    79 
    80 - .. index:: rtems_double
    81 
    82   ``rtems_double`` is the RTEMS data
    83   type that corresponds to double precision floating point
    84   on the target hardware.
    85   This type is deprecated. Use "double" instead.
    86 
    87 - .. index:: rtems_event_set
    88 
    89   ``rtems_event_set`` is the data
    90   type used to manage and manipulate RTEMS event sets
    91   with the Event Manager.
    92 
    93 - .. index:: rtems_extension
    94 
    95   ``rtems_extension`` is the return type
    96   for RTEMS user extension routines.
    97 
    98 - .. index:: rtems_fatal_extension
    99 
    100   ``rtems_fatal_extension`` is the
    101   entry point for a fatal error user extension handler routine.
    102 
    103 - .. index:: rtems_id
    104 
    105   ``rtems_id`` is the data type used
    106   to manage and manipulate RTEMS object IDs.
    107 
    108 - .. index:: rtems_interrupt_frame
    109 
    110   ``rtems_interrupt_frame`` is the
    111   data structure that defines the format of the interrupt
    112   stack frame as it appears to a user ISR.  This data
    113   structure may not be defined on all ports.
    114 
    115 - .. index:: rtems_interrupt_level
    116 
    117   ``rtems_interrupt_level`` is the
    118   data structure used with the ``rtems_interrupt_disable``,``rtems_interrupt_enable``, and``rtems_interrupt_flash`` routines.  This
    119   data type is CPU dependent and usually corresponds to
    120   the contents of the processor register containing
    121   the interrupt mask level.
    122 
    123 - .. index:: rtems_interval
    124 
    125   ``rtems_interval`` is the data
    126   type used to manage and manipulate time intervals.
    127   Intervals are non-negative integers used to measure
    128   the length of time in clock ticks.
    129 
    130 - .. index:: rtems_isr
    131 
    132   ``rtems_isr`` is the return type
    133   of a function implementing an RTEMS ISR.
    134 
    135 - .. index:: rtems_isr_entry
    136 
    137   ``rtems_isr_entry`` is the address of
    138   the entry point to an RTEMS ISR.  It is equivalent to the
     63.. index:: rtems_device_driver
     64
     65``rtems_device_driver``
     66  The return type for a RTEMS device driver routine.
     67
     68.. index:: rtems_device_driver_entry
     69
     70``rtems_device_driver_entry``
     71  The entry point to a RTEMS device driver routine.
     72
     73.. index:: rtems_device_major_number
     74
     75``rtems_device_major_number``
     76  The data type used to manage device major numbers.
     77
     78.. index:: rtems_device_minor_number
     79
     80``rtems_device_minor_number``
     81  The data type used to manage device minor numbers.
     82
     83.. index:: rtems_double
     84
     85``rtems_double``
     86  The RTEMS data type that corresponds to double precision floating point on
     87  the target hardware.  This type is deprecated. Use ``double`` instead.
     88
     89.. index:: rtems_event_set
     90
     91``rtems_event_set``
     92  The data type used to manage and manipulate RTEMS event sets with the Event
     93  Manager.
     94
     95.. index:: rtems_extension
     96
     97``rtems_extension``
     98  The return type for RTEMS user extension routines.
     99
     100.. index:: rtems_fatal_extension
     101
     102``rtems_fatal_extension``
     103
     104  The entry point for a fatal error user extension handler routine.
     105
     106.. index:: rtems_id
     107
     108``rtems_id``
     109  The data type used to manage and manipulate RTEMS object IDs.
     110
     111.. index:: rtems_interrupt_frame
     112
     113``rtems_interrupt_frame``
     114  The data structure that defines the format of the interrupt stack frame as it
     115  appears to a user ISR.  This data structure may not be defined on all ports.
     116
     117.. index:: rtems_interrupt_level
     118
     119``rtems_interrupt_level``
     120
     121  The data structure used with the ``rtems_interrupt_disable``,
     122  ``rtems_interrupt_enable``, and ``rtems_interrupt_flash`` routines.  This
     123  data type is CPU dependent and usually corresponds to the contents of the
     124  processor register containing the interrupt mask level.
     125
     126.. index:: rtems_interval
     127
     128``rtems_interval``
     129  The data type used to manage and manipulate time intervals.  Intervals are
     130  non-negative integers used to measure the length of time in clock ticks.
     131
     132.. index:: rtems_isr
     133
     134``rtems_isr``
     135  The return type of a function implementing an RTEMS ISR.
     136
     137.. index:: rtems_isr_entry
     138
     139``rtems_isr_entry``
     140  The address of the entry point to an RTEMS ISR.  It is equivalent to the
    139141  entry point of the function implementing the ISR.
    140142
    141 - .. index:: rtems_mp_packet_classes
    142 
    143   ``rtems_mp_packet_classes`` is the
    144   enumerated type which specifies the categories of
    145   multiprocessing messages.  For example, one of the
    146   classes is for messages that must be processed by
    147   the Task Manager.
    148 
    149 - .. index:: rtems_mode
    150 
    151   ``rtems_mode`` is the data type
    152   used to manage and dynamically manipulate the execution
    153   mode of an RTEMS task.
    154 
    155 - .. index:: rtems_mpci_entry
    156 
    157   ``rtems_mpci_entry`` is the return type
    158   of an RTEMS MPCI routine.
    159 
    160 - .. index:: rtems_mpci_get_packet_entry
    161 
    162   ``rtems_mpci_get_packet_entry`` is the address of
    163   the entry point to the get packet routine for an MPCI implementation.
    164 
    165 - .. index:: rtems_mpci_initialization_entry
    166 
    167   ``rtems_mpci_initialization_entry`` is the address of
    168   the entry point to the initialization routine for an MPCI implementation.
    169 
    170 - .. index:: rtems_mpci_receive_packet_entry
    171 
    172   ``rtems_mpci_receive_packet_entry`` is the address of
    173   the entry point to the receive packet routine for an MPCI implementation.
    174 
    175 - .. index:: rtems_mpci_return_packet_entry
    176 
    177   ``rtems_mpci_return_packet_entry`` is the address of
    178   the entry point to the return packet routine for an MPCI implementation.
    179 
    180 - .. index:: rtems_mpci_send_packet_entry
    181 
    182   ``rtems_mpci_send_packet_entry`` is the address of
    183   the entry point to the send packet routine for an MPCI implementation.
    184 
    185 - .. index:: rtems_mpci_table
    186 
    187   ``rtems_mpci_table`` is the data structure
    188   containing the configuration information for an MPCI.
    189 
    190 - .. index:: rtems_name
    191 
    192   ``rtems_name`` is the data type used to
    193   contain the name of a Classic API object.  It is an unsigned
    194   thirty-two bit integer which can be treated as a numeric
    195   value or initialized using ``rtems_build_name`` to
    196   contain four ASCII characters.
    197 
    198 - .. index:: rtems_option
    199 
    200   ``rtems_option`` is the data type
    201   used to specify which behavioral options the caller desires.
    202   It is commonly used with potentially blocking directives to specify
    203   whether the caller is willing to block or return immediately with an error
    204   indicating that the resource was not available.
    205 
    206 - .. index:: rtems_packet_prefix
    207 
    208   ``rtems_packet_prefix`` is the data structure
    209   that defines the first bytes in every packet sent between nodes
    210   in an RTEMS multiprocessor system.  It contains routing information
     143.. index:: rtems_mp_packet_classes
     144
     145``rtems_mp_packet_classes``
     146  The enumerated type which specifies the categories of multiprocessing
     147  messages.  For example, one of the classes is for messages that must be
     148  processed by the Task Manager.
     149
     150.. index:: rtems_mode
     151
     152``rtems_mode``
     153  The data type used to manage and dynamically manipulate the execution mode of
     154  an RTEMS task.
     155
     156.. index:: rtems_mpci_entry
     157
     158``rtems_mpci_entry``
     159  The return type of an RTEMS MPCI routine.
     160
     161.. index:: rtems_mpci_get_packet_entry
     162
     163``rtems_mpci_get_packet_entry``
     164  The address of the entry point to the get packet routine for an MPCI
     165  implementation.
     166
     167.. index:: rtems_mpci_initialization_entry
     168
     169``rtems_mpci_initialization_entry``
     170  The address of the entry point to the initialization routine for an MPCI
     171  implementation.
     172
     173.. index:: rtems_mpci_receive_packet_entry
     174
     175``rtems_mpci_receive_packet_entry``
     176  The address of the entry point to the receive packet routine for an MPCI
     177  implementation.
     178
     179.. index:: rtems_mpci_return_packet_entry
     180
     181``rtems_mpci_return_packet_entry``
     182  The address of the entry point to the return packet routine for an MPCI
     183  implementation.
     184
     185.. index:: rtems_mpci_send_packet_entry
     186
     187``rtems_mpci_send_packet_entry``
     188  The address of the entry point to the send packet routine for an MPCI
     189  implementation.
     190
     191.. index:: rtems_mpci_table
     192
     193``rtems_mpci_table``
     194  The data structure containing the configuration information for an MPCI.
     195
     196.. index:: rtems_name
     197
     198``rtems_name``
     199  The data type used to contain the name of a Classic API object.  It is an
     200  unsigned thirty-two bit integer which can be treated as a numeric value or
     201  initialized using ``rtems_build_name`` to contain four ASCII characters.
     202
     203.. index:: rtems_option
     204
     205``rtems_option``
     206  The data type used to specify which behavioral options the caller desires.
     207  It is commonly used with potentially blocking directives to specify whether
     208  the caller is willing to block or return immediately with an error indicating
     209  that the resource was not available.
     210
     211.. index:: rtems_packet_prefix
     212
     213``rtems_packet_prefix``
     214  The data structure that defines the first bytes in every packet sent between
     215  nodes in an RTEMS multiprocessor system.  It contains routing information
    211216  that is expected to be used by the MPCI layer.
    212217
    213 - .. index:: rtems_signal_set
    214 
    215   ``rtems_signal_set`` is the data
    216   type used to manage and manipulate RTEMS signal sets
    217   with the Signal Manager.
    218 
    219 - .. index:: int8_t
    220 
    221   ``int8_t`` is the C99 data type that corresponds to signed eight
    222   bit integers.  This data type is defined by RTEMS in a manner that
    223   ensures it is portable across different target processors.
    224 
    225 - .. index:: int16_t
    226 
    227   ``int16_t`` is the C99 data type that corresponds to signed
    228   sixteen bit integers.  This data type is defined by RTEMS in a manner
    229   that ensures it is portable across different target processors.
    230 
    231 - .. index:: int32_t
    232 
    233   ``int32_t`` is the C99 data type that corresponds to signed
    234   thirty-two bit integers.  This data type is defined by RTEMS in a manner
    235   that ensures it is portable across different target processors.
    236 
    237 - .. index:: int64_t
    238 
    239   ``int64_t`` is the C99 data type that corresponds to signed
    240   sixty-four bit integers.  This data type is defined by RTEMS in a manner
    241   that ensures it is portable across different target processors.
    242 
    243 - .. index:: rtems_single
    244 
    245   ``rtems_single`` is the RTEMS data
    246   type that corresponds to single precision floating point
    247   on the target hardware.
    248   This type is deprecated. Use "float" instead.
    249 
    250 - .. index:: rtems_status_codes
    251 
    252   ``rtems_status_codes`` is the return type for most
    253   RTEMS services.  This is an enumerated type of approximately twenty-five
    254   values.  In general, when a service returns a particular status code, it
    255   indicates that a very specific error condition has occurred.
    256 
    257 - .. index:: rtems_task
    258 
    259   ``rtems_task`` is the return type for an
    260   RTEMS Task.
    261 
    262 - .. index:: rtems_task_argument
    263 
    264   ``rtems_task_argument`` is the data
    265   type for the argument passed to each RTEMS task. In RTEMS 4.7
    266   and older, this is an unsigned thirty-two bit integer.  In
    267   RTEMS 4.8 and newer, this is based upon the C99 type ``uintptr_t``
    268   which is guaranteed to be an integer large enough to hold a
    269   pointer on the target architecture.
    270 
    271 - .. index:: rtems_task_begin_extension
    272 
    273   ``rtems_task_begin_extension`` is the
    274   entry point for a task beginning execution user extension handler routine.
    275 
    276 - .. index:: rtems_task_create_extension
    277 
    278   ``rtems_task_create_extension`` is the
    279   entry point for a task creation execution user extension handler routine.
    280 
    281 - .. index:: rtems_task_delete_extension
    282 
    283   ``rtems_task_delete_extension`` is the
    284   entry point for a task deletion user extension handler routine.
    285 
    286 - .. index:: rtems_task_entry
    287 
    288   ``rtems_task_entry`` is the address of
    289   the entry point to an RTEMS ASR.  It is equivalent to the
     218.. index:: rtems_signal_set
     219
     220``rtems_signal_set``
     221  The data type used to manage and manipulate RTEMS signal sets with the Signal
     222  Manager.
     223
     224.. index:: int8_t
     225
     226``int8_t``
     227  The C99 data type that corresponds to signed eight bit integers.  This data
     228  type is defined by RTEMS in a manner that ensures it is portable across
     229  different target processors.
     230
     231.. index:: int16_t
     232
     233``int16_t``
     234  The C99 data type that corresponds to signed sixteen bit integers.  This data
     235  type is defined by RTEMS in a manner that ensures it is portable across
     236  different target processors.
     237
     238.. index:: int32_t
     239
     240``int32_t``
     241  The C99 data type that corresponds to signed thirty-two bit integers.  This
     242  data type is defined by RTEMS in a manner that ensures it is portable across
     243  different target processors.
     244
     245.. index:: int64_t
     246
     247``int64_t``
     248  The C99 data type that corresponds to signed sixty-four bit integers.  This
     249  data type is defined by RTEMS in a manner that ensures it is portable across
     250  different target processors.
     251
     252.. index:: rtems_single
     253
     254``rtems_single``
     255  The RTEMS data type that corresponds to single precision floating point on
     256  the target hardware.  This type is deprecated. Use ``float`` instead.
     257
     258.. index:: rtems_status_codes
     259
     260``rtems_status_codes``
     261  The return type for most RTEMS services.  This is an enumerated type of
     262  approximately twenty-five values.  In general, when a service returns a
     263  particular status code, it indicates that a very specific error condition has
     264  occurred.
     265
     266.. index:: rtems_task
     267
     268``rtems_task``
     269  The return type for an RTEMS Task.
     270
     271.. index:: rtems_task_argument
     272
     273``rtems_task_argument``
     274  The data type for the argument passed to each RTEMS task. In RTEMS 4.7 and
     275  older, this is an unsigned thirty-two bit integer.  In RTEMS 4.8 and newer,
     276  this is based upon the C99 type ``uintptr_t`` which is guaranteed to be an
     277  integer large enough to hold a pointer on the target architecture.
     278
     279.. index:: rtems_task_begin_extension
     280
     281``rtems_task_begin_extension``
     282  The entry point for a task beginning execution user extension handler
     283  routine.
     284
     285.. index:: rtems_task_create_extension
     286
     287``rtems_task_create_extension``
     288  The entry point for a task creation execution user extension handler routine.
     289
     290.. index:: rtems_task_delete_extension
     291
     292``rtems_task_delete_extension``
     293  The entry point for a task deletion user extension handler routine.
     294
     295.. index:: rtems_task_entry
     296
     297``rtems_task_entry``
     298  The address of the entry point to an RTEMS ASR.  It is equivalent to the
    290299  entry point of the function implementing the ASR.
    291300
    292 - .. index:: rtems_task_exitted_extension
    293 
    294   ``rtems_task_exitted_extension`` is the
    295   entry point for a task exitted user extension handler routine.
    296 
    297 - .. index:: rtems_task_priority
    298 
    299   ``rtems_task_priority`` is the data type
    300   used to manage and manipulate task priorities.
    301 
    302 - .. index:: rtems_task_restart_extension
    303 
    304   ``rtems_task_restart_extension`` is the
    305   entry point for a task restart user extension handler routine.
    306 
    307 - .. index:: rtems_task_start_extension
    308 
    309   ``rtems_task_start_extension`` is the
    310   entry point for a task start user extension handler routine.
    311 
    312 - .. index:: rtems_task_switch_extension
    313 
    314   ``rtems_task_switch_extension`` is the
    315   entry point for a task context switch user extension handler routine.
    316 
    317 - .. index:: rtems_tcb
    318 
    319   ``rtems_tcb`` is the data structure associated
    320   with each task in an RTEMS system.
    321 
    322 - .. index:: rtems_time_of_day
    323 
    324   ``rtems_time_of_day`` is the data structure
    325   used to manage and manipulate calendar time in RTEMS.
    326 
    327 - .. index:: rtems_timer_service_routine
    328 
    329   ``rtems_timer_service_routine`` is the
    330   return type for an RTEMS Timer Service Routine.
    331 
    332 - .. index:: rtems_timer_service_routine_entry
    333 
    334   ``rtems_timer_service_routine_entry`` is the address of
    335   the entry point to an RTEMS TSR.  It is equivalent to the
     301.. index:: rtems_task_exitted_extension
     302
     303``rtems_task_exitted_extension``
     304  The entry point for a task exitted user extension handler routine.
     305
     306.. index:: rtems_task_priority
     307
     308``rtems_task_priority``
     309  The data type used to manage and manipulate task priorities.
     310
     311.. index:: rtems_task_restart_extension
     312
     313``rtems_task_restart_extension``
     314  The entry point for a task restart user extension handler routine.
     315
     316.. index:: rtems_task_start_extension
     317
     318``rtems_task_start_extension``
     319  The entry point for a task start user extension handler routine.
     320
     321.. index:: rtems_task_switch_extension
     322
     323``rtems_task_switch_extension``
     324  The entry point for a task context switch user extension handler routine.
     325
     326.. index:: rtems_tcb
     327
     328``rtems_tcb``
     329  The data structure associated with each task in an RTEMS system.
     330
     331.. index:: rtems_time_of_day
     332
     333``rtems_time_of_day``
     334  The data structure used to manage and manipulate calendar time in RTEMS.
     335
     336.. index:: rtems_timer_service_routine
     337
     338``rtems_timer_service_routine``
     339  The return type for an RTEMS Timer Service Routine.
     340
     341.. index:: rtems_timer_service_routine_entry
     342
     343``rtems_timer_service_routine_entry``
     344  The address of the entry point to an RTEMS TSR.  It is equivalent to the
    336345  entry point of the function implementing the TSR.
    337346
    338 - .. index:: rtems_vector_number
    339 
    340   ``rtems_vector_number`` is the data
    341   type used to manage and manipulate interrupt vector numbers.
    342 
    343 - .. index:: uint8_t
    344 
    345   ``uint8_t`` is the C99 data type that corresponds to unsigned
    346   eight bit integers.  This data type is defined by RTEMS in a manner that
    347   ensures it is portable across different target processors.
    348 
    349 - .. index:: uint16_t
    350 
    351   ``uint16_t`` is the C99 data type that corresponds to unsigned
    352   sixteen bit integers.  This data type is defined by RTEMS in a manner
    353   that ensures it is portable across different target processors.
    354 
    355 - .. index:: uint32_t
    356 
    357   ``uint32_t`` is the C99 data type that corresponds to unsigned
    358   thirty-two bit integers.  This data type is defined by RTEMS in a manner
    359   that ensures it is portable across different target processors.
    360 
    361 - .. index:: uint64_t
    362 
    363   ``uint64_t`` is the C99 data type that corresponds to unsigned
    364   sixty-four bit integers.  This data type is defined by RTEMS in a manner
    365   that ensures it is portable across different target processors.
    366 
    367 - .. index:: uintptr_t
    368 
    369   ``uintptr_t`` is the C99 data type that corresponds to the
    370   unsigned integer type that is of sufficient size to represent addresses
    371   as unsigned integers.  This data type is defined by RTEMS in a manner
    372   that ensures it is portable across different target processors.
    373 
    374 .. COMMENT: COPYRIGHT (c) 1988-2011.
    375 
    376 .. COMMENT: On-Line Applications Research Corporation (OAR).
    377 
    378 .. COMMENT: All rights reserved.
    379 
     347.. index:: rtems_vector_number
     348
     349``rtems_vector_number``
     350  The data type used to manage and manipulate interrupt vector numbers.
     351
     352.. index:: uint8_t
     353
     354``uint8_t``
     355  The C99 data type that corresponds to unsigned eight bit integers.  This data
     356  type is defined by RTEMS in a manner that ensures it is portable across
     357  different target processors.
     358
     359.. index:: uint16_t
     360
     361``uint16_t``
     362  The C99 data type that corresponds to unsigned sixteen bit integers.  This
     363  data type is defined by RTEMS in a manner that ensures it is portable across
     364  different target processors.
     365
     366.. index:: uint32_t
     367
     368``uint32_t``
     369  The C99 data type that corresponds to unsigned thirty-two bit integers.  This
     370  data type is defined by RTEMS in a manner that ensures it is portable across
     371  different target processors.
     372
     373.. index:: uint64_t
     374
     375``uint64_t``
     376  The C99 data type that corresponds to unsigned sixty-four bit integers.  This
     377  data type is defined by RTEMS in a manner that ensures it is portable across
     378  different target processors.
     379
     380.. index:: uintptr_t
     381
     382``uintptr_t``
     383  The C99 data type that corresponds to the unsigned integer type that is of
     384  sufficient size to represent addresses as unsigned integers.  This data type
     385  is defined by RTEMS in a manner that ensures it is portable across different
     386  target processors.
  • c_user/scheduling_concepts.rst

    r0f5ccd4 rb8d3f6b  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Scheduling Concepts
    26###################
     
    812============
    913
    10 The concept of scheduling in real-time systems dictates the ability to
    11 provide immediate response to specific external events, particularly
    12 the necessity of scheduling tasks to run within a specified time limit
    13 after the occurrence of an event.  For example, software embedded in
    14 life-support systems used to monitor hospital patients must take instant
    15 action if a change in the patient's status is detected.
     14The concept of scheduling in real-time systems dictates the ability to provide
     15immediate response to specific external events, particularly the necessity of
     16scheduling tasks to run within a specified time limit after the occurrence of
     17an event.  For example, software embedded in life-support systems used to
     18monitor hospital patients must take instant action if a change in the patient's
     19status is detected.
    1620
    1721The component of RTEMS responsible for providing this capability is
    18 appropriately called the scheduler.  The scheduler's sole purpose is
    19 to allocate the all important resource of processor time to the various
    20 tasks competing for attention.
     22appropriately called the scheduler.  The scheduler's sole purpose is to
     23allocate the all important resource of processor time to the various tasks
     24competing for attention.
    2125
    2226Scheduling Algorithms
     
    2529.. index:: scheduling algorithms
    2630
    27 RTEMS provides a plugin framework which allows it to support
    28 multiple scheduling algorithms. RTEMS now includes multiple
    29 scheduling algorithms in the SuperCore and the user can select which
    30 of these they wish to use in their application.  In addition,
    31 the user can implement their own scheduling algorithm and
    32 configure RTEMS to use it.
    33 
    34 Supporting multiple scheduling algorithms gives the end user the
    35 option to select the algorithm which is most appropriate to their use
    36 case. Most real-time operating systems schedule tasks using a priority
    37 based algorithm, possibly with preemption control.  The classic
    38 RTEMS scheduling algorithm which was the only algorithm available
    39 in RTEMS 4.10 and earlier, is a priority based scheduling algorithm.
    40 This scheduling algoritm is suitable for single core (e.g. non-SMP)
    41 systems and is now known as the *Deterministic Priority Scheduler*.
    42 Unless the user configures another scheduling algorithm, RTEMS will use
    43 this on single core systems.
     31RTEMS provides a plugin framework which allows it to support multiple
     32scheduling algorithms. RTEMS now includes multiple scheduling algorithms in the
     33SuperCore and the user can select which of these they wish to use in their
     34application.  In addition, the user can implement their own scheduling
     35algorithm and configure RTEMS to use it.
     36
     37Supporting multiple scheduling algorithms gives the end user the option to
     38select the algorithm which is most appropriate to their use case. Most
     39real-time operating systems schedule tasks using a priority based algorithm,
     40possibly with preemption control.  The classic RTEMS scheduling algorithm which
     41was the only algorithm available in RTEMS 4.10 and earlier, is a priority based
     42scheduling algorithm.  This scheduling algoritm is suitable for single core
     43(e.g. non-SMP) systems and is now known as the *Deterministic Priority
     44Scheduler*.  Unless the user configures another scheduling algorithm, RTEMS
     45will use this on single core systems.
    4446
    4547Priority Scheduling
     
    4749.. index:: priority scheduling
    4850
    49 When using priority based scheduling, RTEMS allocates the processor using
    50 a priority-based, preemptive algorithm augmented to provide round-robin
    51 characteristics within individual priority groups.  The goal of this
    52 algorithm is to guarantee that the task which is executing on the
    53 processor at any point in time is the one with the highest priority
    54 among all tasks in the ready state.
    55 
    56 When a task is added to the ready chain, it is placed behind all other
    57 tasks of the same priority.  This rule provides a round-robin within
    58 priority group scheduling characteristic.  This means that in a group of
    59 equal priority tasks, tasks will execute in the order they become ready
    60 or FIFO order.  Even though there are ways to manipulate and adjust task
    61 priorities, the most important rule to remember is:
    62 
    63 - *Priority based scheduling algorithms will always select the
    64   highest priority task that is ready to run when allocating the processor
    65   to a task.*
    66 
    67 Priority scheduling is the most commonly used scheduling algorithm.
    68 It should be used by applications in which multiple tasks contend for
    69 CPU time or other resources and there is a need to ensure certain tasks
    70 are given priority over other tasks.
     51When using priority based scheduling, RTEMS allocates the processor using a
     52priority-based, preemptive algorithm augmented to provide round-robin
     53characteristics within individual priority groups.  The goal of this algorithm
     54is to guarantee that the task which is executing on the processor at any point
     55in time is the one with the highest priority among all tasks in the ready
     56state.
     57
     58When a task is added to the ready chain, it is placed behind all other tasks of
     59the same priority.  This rule provides a round-robin within priority group
     60scheduling characteristic.  This means that in a group of equal priority tasks,
     61tasks will execute in the order they become ready or FIFO order.  Even though
     62there are ways to manipulate and adjust task priorities, the most important
     63rule to remember is:
     64
     65.. note::
     66
     67  Priority based scheduling algorithms will always select the highest priority
     68  task that is ready to run when allocating the processor to a task.
     69
     70Priority scheduling is the most commonly used scheduling algorithm.  It should
     71be used by applications in which multiple tasks contend for CPU time or other
     72resources and there is a need to ensure certain tasks are given priority over
     73other tasks.
    7174
    7275There are a few common methods of accomplishing the mechanics of this
    7376algorithm.  These ways involve a list or chain of tasks in the ready state.
    7477
    75 - The least efficient method is to randomly place tasks in the ready
    76   chain forcing the scheduler to scan the entire chain to determine which
    77   task receives the processor.
    78 
    79 - A more efficient method is to schedule the task by placing it
    80   in the proper place on the ready chain based on the designated scheduling
    81   criteria at the time it enters the ready state.  Thus, when the processor
    82   is free, the first task on the ready chain is allocated the processor.
    83 
    84 - Another mechanism is to maintain a list of FIFOs per priority.
    85   When a task is readied, it is placed on the rear of the FIFO for its
    86   priority.  This method is often used with a bitmap to assist in locating
    87   which FIFOs have ready tasks on them.
    88 
    89 RTEMS currently includes multiple priority based scheduling algorithms
    90 as well as other algorithms which incorporate deadline.  Each algorithm
    91 is discussed in the following sections.
     78- The least efficient method is to randomly place tasks in the ready chain
     79  forcing the scheduler to scan the entire chain to determine which task
     80  receives the processor.
     81
     82- A more efficient method is to schedule the task by placing it in the proper
     83  place on the ready chain based on the designated scheduling criteria at the
     84  time it enters the ready state.  Thus, when the processor is free, the first
     85  task on the ready chain is allocated the processor.
     86
     87- Another mechanism is to maintain a list of FIFOs per priority.  When a task
     88  is readied, it is placed on the rear of the FIFO for its priority.  This
     89  method is often used with a bitmap to assist in locating which FIFOs have
     90  ready tasks on them.
     91
     92RTEMS currently includes multiple priority based scheduling algorithms as well
     93as other algorithms which incorporate deadline.  Each algorithm is discussed in
     94the following sections.
    9295
    9396Deterministic Priority Scheduler
    9497--------------------------------
    9598
    96 This is the scheduler implementation which has always been in RTEMS.
    97 After the 4.10 release series, it was factored into pluggable scheduler
    98 selection.  It schedules tasks using a priority based algorithm which
    99 takes into account preemption.  It is implemented using an array of FIFOs
    100 with a FIFO per priority.  It maintains a bitmap which is used to track
    101