Changeset 8d87f4d in rtems-docs


Ignore:
Timestamp:
Jan 17, 2016, 3:48:37 PM (4 years ago)
Author:
Amar Takhar <amar@…>
Branches:
4.11, master
Children:
4783b0d
Parents:
7d8260a
git-author:
Amar Takhar <amar@…> (01/17/16 15:48:37)
git-committer:
Amar Takhar <verm@…> (05/03/16 00:51:23)
Message:

Fix markup.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • ada_user/ada_user.rst

    r7d8260a r8d87f4d  
    587587RTEMS requires RAM to manage each instance of an RTEMS object
    588588that is created.  Thus the more RTEMS objects an application
    589 needs, the more memory that must be reserved.  See:ref:`Configuring a System <Configuring-a-System>` for more details.
     589needs, the more memory that must be reserved.  See `Configuring a System`_ for more details.
    590590
    591591RTEMS utilizes memory for both code and data space.
     
    785785
    786786Chapter 30:
    787     Constant Bandwidth Server Scheduler API::
     787    Constant Bandwidth Server Scheduler API.
    788788
    789789Chapter 31:
     
    10821082The data type ``rtems.time_of_day`` is used to specify
    10831083calendar time in RTEMS services.
    1084 See :ref:`Time and Date Data Structures <Clock-Manager-Time-and-Date-Data-Structures>`... index:: rtems_time_of_day
     1084See `Time and Date Data Structures`_
     1085
     1086... index:: rtems_time_of_day
    10851087
    10861088Obviously, the directives which use intervals or wall
     
    11451147
    11461148- .. index:: rtems_address
     1149
    11471150  ``rtems.address`` is the data type used to manage
    11481151  addresses.  It is equivalent to
     
    11501153
    11511154- .. index:: rtems_asr
     1155
    11521156  ``rtems.asr`` is the return type for an
    11531157  RTEMS ASR.
    11541158
    11551159- .. index:: rtems_asr_entry
     1160
    11561161  ``rtems.asr_entry`` is the address of
    11571162  the entry point to an RTEMS ASR.
    11581163
    11591164- .. index:: rtems_attribute
     1165
    11601166  ``rtems.attribute`` is the data type used
    11611167  to manage the attributes for RTEMS objects.  It is primarily
     
    11641170
    11651171- .. index:: rtems_boolean
     1172
    11661173  ``rtems.boolean`` may only take on the
    11671174  values of ``TRUE`` and ``FALSE``.
     
    11691176
    11701177- .. index:: rtems_context
     1178
    11711179  ``rtems.context`` is the CPU dependent
    11721180  data structure used to manage the integer and system
     
    11741182
    11751183- .. index:: rtems_context_fp
     1184
    11761185  ``rtems.context_fp`` is the CPU dependent
    11771186  data structure used to manage the floating point portion of
     
    11791188
    11801189- .. index:: rtems_device_driver
     1190
    11811191  ``rtems.device_driver`` is the
    11821192  return type for a RTEMS device driver routine.
    11831193
    11841194- .. index:: rtems_device_driver_entry
     1195
    11851196  ``rtems.device_driver_entry`` is the
    11861197  entry point to a RTEMS device driver routine.
    11871198
    11881199- .. index:: rtems_device_major_number
     1200
    11891201  ``rtems.device_major_number`` is the
    11901202  data type used to manage device major numbers.
    11911203
    11921204- .. index:: rtems_device_minor_number
     1205
    11931206  ``rtems.device_minor_number`` is the
    11941207  data type used to manage device minor numbers.
    11951208
    11961209- .. index:: rtems_double
     1210
    11971211  ``rtems.double`` is the RTEMS data
    11981212  type that corresponds to double precision floating point
     
    12011215
    12021216- .. index:: rtems_event_set
     1217
    12031218  ``rtems.event_set`` is the data
    12041219  type used to manage and manipulate RTEMS event sets
     
    12061221
    12071222- .. index:: rtems_extension
     1223
    12081224  ``rtems.extension`` is the return type
    12091225  for RTEMS user extension routines.
    12101226
    12111227- .. index:: rtems_fatal_extension
     1228
    12121229  ``rtems.fatal_extension`` is the
    12131230  entry point for a fatal error user extension handler routine.
    12141231
    12151232- .. index:: rtems_id
     1233
    12161234  ``rtems.id`` is the data type used
    12171235  to manage and manipulate RTEMS object IDs.
    12181236
    12191237- .. index:: rtems_interrupt_frame
     1238
    12201239  ``rtems.interrupt_frame`` is the
    12211240  data structure that defines the format of the interrupt
     
    12241243
    12251244- .. index:: rtems_interrupt_level
     1245
    12261246  ``rtems.interrupt_level`` is the
    12271247  data structure used with the ``rtems.interrupt_disable``,``rtems.interrupt_enable``, and``rtems.interrupt_flash`` routines.  This
     
    12311251
    12321252- .. index:: rtems_interval
     1253
    12331254  ``rtems.interval`` is the data
    12341255  type used to manage and manipulate time intervals.
     
    12371258
    12381259- .. index:: rtems_isr
     1260
    12391261  ``rtems.isr`` is the return type
    12401262  of a function implementing an RTEMS ISR.
    12411263
    12421264- .. index:: rtems_isr_entry
     1265
    12431266  ``rtems.isr_entry`` is the address of
    12441267  the entry point to an RTEMS ISR.  It is equivalent to the
     
    12461269
    12471270- .. index:: rtems_mp_packet_classes
     1271
    12481272  ``rtems.mp_packet_classes`` is the
    12491273  enumerated type which specifies the categories of
     
    12531277
    12541278- .. index:: rtems_mode
     1279
    12551280  ``rtems.mode`` is the data type
    12561281  used to manage and dynamically manipulate the execution
     
    12581283
    12591284- .. index:: rtems_mpci_entry
     1285
    12601286  ``rtems.mpci_entry`` is the return type
    12611287  of an RTEMS MPCI routine.
    12621288
    12631289- .. index:: rtems_mpci_get_packet_entry
     1290
    12641291  ``rtems.mpci_get_packet_entry`` is the address of
    12651292  the entry point to the get packet routine for an MPCI implementation.
    12661293
    12671294- .. index:: rtems_mpci_initialization_entry
     1295
    12681296  ``rtems.mpci_initialization_entry`` is the address of
    12691297  the entry point to the initialization routine for an MPCI implementation.
    12701298
    12711299- .. index:: rtems_mpci_receive_packet_entry
     1300
    12721301  ``rtems.mpci_receive_packet_entry`` is the address of
    12731302  the entry point to the receive packet routine for an MPCI implementation.
    12741303
    12751304- .. index:: rtems_mpci_return_packet_entry
     1305
    12761306  ``rtems.mpci_return_packet_entry`` is the address of
    12771307  the entry point to the return packet routine for an MPCI implementation.
    12781308
    12791309- .. index:: rtems_mpci_send_packet_entry
     1310
    12801311  ``rtems.mpci_send_packet_entry`` is the address of
    12811312  the entry point to the send packet routine for an MPCI implementation.
    12821313
    12831314- .. index:: rtems_mpci_table
     1315
    12841316  ``rtems.mpci_table`` is the data structure
    12851317  containing the configuration information for an MPCI.
    12861318
    12871319- .. index:: rtems_name
     1320
    12881321  ``rtems.name`` is the data type used to
    12891322  contain the name of a Classic API object.  It is an unsigned
     
    12931326
    12941327- .. index:: rtems_option
     1328
    12951329  ``rtems.option`` is the data type
    12961330  used to specify which behavioral options the caller desires.
     
    13001334
    13011335- .. index:: rtems_packet_prefix
     1336
    13021337  ``rtems.packet_prefix`` is the data structure
    13031338  that defines the first bytes in every packet sent between nodes
     
    13061341
    13071342- .. index:: rtems_signal_set
     1343
    13081344  ``rtems.signal_set`` is the data
    13091345  type used to manage and manipulate RTEMS signal sets
     
    13111347
    13121348- .. index:: int8_t
     1349
    13131350  ``int8_t`` is the C99 data type that corresponds to signed eight
    13141351  bit integers.  This data type is defined by RTEMS in a manner that
     
    13161353
    13171354- .. index:: int16_t
     1355
    13181356  ``int16_t`` is the C99 data type that corresponds to signed
    13191357  sixteen bit integers.  This data type is defined by RTEMS in a manner
     
    13211359
    13221360- .. index:: int32_t
     1361
    13231362  ``int32_t`` is the C99 data type that corresponds to signed
    13241363  thirty-two bit integers.  This data type is defined by RTEMS in a manner
     
    13261365
    13271366- .. index:: int64_t
     1367
    13281368  ``int64_t`` is the C99 data type that corresponds to signed
    13291369  sixty-four bit integers.  This data type is defined by RTEMS in a manner
     
    13311371
    13321372- .. index:: rtems_single
     1373
    13331374  ``rtems.single`` is the RTEMS data
    13341375  type that corresponds to single precision floating point
     
    13371378
    13381379- .. index:: rtems_status_codes
     1380
    13391381  ``rtems.status_codes`` is the return type for most
    13401382  RTEMS services.  This is an enumerated type of approximately twenty-five
     
    13431385
    13441386- .. index:: rtems_task
     1387
    13451388  ``rtems.task`` is the return type for an
    13461389  RTEMS Task.
    13471390
    13481391- .. index:: rtems_task_argument
     1392
    13491393  ``rtems.task_argument`` is the data
    13501394  type for the argument passed to each RTEMS task. In RTEMS 4.7
     
    13551399
    13561400- .. index:: rtems_task_begin_extension
     1401
    13571402  ``rtems.task_begin_extension`` is the
    13581403  entry point for a task beginning execution user extension handler routine.
    13591404
    13601405- .. index:: rtems_task_create_extension
     1406
    13611407  ``rtems.task_create_extension`` is the
    13621408  entry point for a task creation execution user extension handler routine.
    13631409
    13641410- .. index:: rtems_task_delete_extension
     1411
    13651412  ``rtems.task_delete_extension`` is the
    13661413  entry point for a task deletion user extension handler routine.
    13671414
    13681415- .. index:: rtems_task_entry
     1416
    13691417  ``rtems.task_entry`` is the address of
    13701418  the entry point to an RTEMS ASR.  It is equivalent to the
     
    13721420
    13731421- .. index:: rtems_task_exitted_extension
     1422
    13741423  ``rtems.task_exitted_extension`` is the
    13751424  entry point for a task exitted user extension handler routine.
    13761425
    13771426- .. index:: rtems_task_priority
     1427
    13781428  ``rtems.task_priority`` is the data type
    13791429  used to manage and manipulate task priorities.
    13801430
    13811431- .. index:: rtems_task_restart_extension
     1432
    13821433  ``rtems.task_restart_extension`` is the
    13831434  entry point for a task restart user extension handler routine.
    13841435
    13851436- .. index:: rtems_task_start_extension
     1437
    13861438  ``rtems.task_start_extension`` is the
    13871439  entry point for a task start user extension handler routine.
    13881440
    13891441- .. index:: rtems_task_switch_extension
     1442
    13901443  ``rtems.task_switch_extension`` is the
    13911444  entry point for a task context switch user extension handler routine.
    13921445
    13931446- .. index:: rtems_tcb
     1447
    13941448  ``rtems.tcb`` is the data structure associated
    13951449  with each task in an RTEMS system.
    13961450
    13971451- .. index:: rtems_time_of_day
     1452
    13981453  ``rtems.time_of_day`` is the data structure
    13991454  used to manage and manipulate calendar time in RTEMS.
    14001455
    14011456- .. index:: rtems_timer_service_routine
     1457
    14021458  ``rtems.timer_service_routine`` is the
    14031459  return type for an RTEMS Timer Service Routine.
    14041460
    14051461- .. index:: rtems_timer_service_routine_entry
     1462
    14061463  ``rtems.timer_service_routine_entry`` is the address of
    14071464  the entry point to an RTEMS TSR.  It is equivalent to the
     
    14091466
    14101467- .. index:: rtems_vector_number
     1468
    14111469  ``rtems.vector_number`` is the data
    14121470  type used to manage and manipulate interrupt vector numbers.
    14131471
    14141472- .. index:: uint8_t
     1473
    14151474  ``uint8_t`` is the C99 data type that corresponds to unsigned
    14161475  eight bit integers.  This data type is defined by RTEMS in a manner that
     
    14181477
    14191478- .. index:: uint16_t
     1479
    14201480  ``uint16_t`` is the C99 data type that corresponds to unsigned
    14211481  sixteen bit integers.  This data type is defined by RTEMS in a manner
     
    14231483
    14241484- .. index:: uint32_t
     1485
    14251486  ``uint32_t`` is the C99 data type that corresponds to unsigned
    14261487  thirty-two bit integers.  This data type is defined by RTEMS in a manner
     
    14281489
    14291490- .. index:: uint64_t
     1491
    14301492  ``uint64_t`` is the C99 data type that corresponds to unsigned
    14311493  sixty-four bit integers.  This data type is defined by RTEMS in a manner
     
    14331495
    14341496- .. index:: uintptr_t
     1497
    14351498  ``uintptr_t`` is the C99 data type that corresponds to the
    14361499  unsigned integer type that is of sufficient size to represent addresses
     
    15591622
    15601623A discussion of RTEMS actions when a fatal error occurs
    1561 may be found :ref:`Fatal Error Manager Announcing a Fatal Error <Fatal-Error-Manager-Announcing-a-Fatal-Error>`.
     1624may be found `Announcing a Fatal Error`_
    15621625
    15631626Operations
     
    15841647The ``rtems.initialize_executive`` directive uses a system
    15851648initialization linker set to initialize only those parts of the overall RTEMS
    1586 feature set that is necessary for a particular application.  See :ref:`Linker
    1587 Sets <Linker-Sets>`.  Each RTEMS feature used the application may optionally register an
     1649feature set that is necessary for a particular application.  See `Linker Sets`_. 
     1650Each RTEMS feature used the application may optionally register an
    15881651initialization handler.  The system initialization API is available via``#included <rtems/sysinit.h>``.
    15891652
     
    16391702the contents of the Configuration Table.  For more information
    16401703regarding the format and contents of this table, please refer
    1641 to the chapter :ref:`Configuring a System <Configuring-a-System>`.
     1704to the chapter `Configuring a System`_.
    16421705
    16431706The final action in the initialization sequence is the
     
    37563819specified by the user in the Configuration Table.
    37573820
    3758 .. _Clock-Manager-Time-and-Date-Data-Structures:
    37593821
    37603822Time and Date Data Structures
     
    50615123from executing by lower priority tasks.
    50625124
    5063 .. _Semaphore-Manager-Priority-Inheritance:
    50645125
    50655126Priority Inheritance
     
    51385199releases ALL of the binary semaphores it holds will its priority
    51395200be restored to the normal value.
    5140 
    5141 .. _Semaphore-Manager-Multiprocessor-Resource-Sharing-Protocol:
    51425201
    51435202Multiprocessor Resource Sharing Protocol
     
    66816740
    66826741- Target Task is Blocked Waiting for Events
    6683   - - If the waiting task’s input event condition is
     6742
     6743  - If the waiting task’s input event condition is
    66846744    satisfied, then the task is made ready for execution.
    6685   - - If the waiting task’s input event condition is not
     6745
     6746  - If the waiting task’s input event condition is not
    66866747    satisfied, then the event set is posted but left pending and the
    66876748    task remains blocked.
    66886749
    66896750- Target Task is Not Waiting for Events
    6690   - - The event set is posted and left pending.
     6751
     6752  - The event set is posted and left pending.
    66916753
    66926754Receiving an Event Set
     
    90809142==========
    90819143
    9082 .. _Fatal-Error-Manager-Announcing-a-Fatal-Error:
    90839144
    90849145Announcing a Fatal Error
     
    92999360priorities, the most important rule to remember is:
    93009361
    9301 - ```` *Priority based scheduling algorithms will always select the
     9362- *Priority based scheduling algorithms will always select the
    93029363  highest priority task that is ready to run when allocating the processor
    93039364  to a task.*
     
    99079968system’s behavior.  It has been proven that:
    99089969
    9909 - ```` *RMS is an optimal static priority algorithm for
     9970- *RMS is an optimal static priority algorithm for
    99109971  scheduling independent, preemptible, periodic tasks
    99119972  on a single processor.*
     
    99279988assignment scheme does not provide one with exact numeric values
    99289989for task priorities.  For example, consider the following task
    9929 set and priority assignments:
    9930 .. code:: c
    9931 
    9932     +--------------------+---------------------+---------------------+
    9933     |        Task        |       Period        |      Priority       |
    9934     |                    |  (in milliseconds)  |                     |
    9935     +--------------------+---------------------+---------------------+
    9936     |         1          |         100         |         Low         |
    9937     +--------------------+---------------------+---------------------+
    9938     |         2          |          50         |       Medium        |
    9939     +--------------------+---------------------+---------------------+
    9940     |         3          |          50         |       Medium        |
    9941     +--------------------+---------------------+---------------------+
    9942     |         4          |          25         |        High         |
    9943     +--------------------+---------------------+---------------------+
     9990set and priority assignments.
     9991
     9992+--------------------+---------------------+---------------------+
     9993| Task               | Period              | Priority            |
     9994|                    | (in milliseconds)   |                     |
     9995+====================+=====================+=====================+
     9996|         1          |         100         |         Low         |
     9997+--------------------+---------------------+---------------------+
     9998|         2          |          50         |       Medium        |
     9999+--------------------+---------------------+---------------------+
     10000|         3          |          50         |       Medium        |
     10001+--------------------+---------------------+---------------------+
     10002|         4          |          25         |        High         |
     10003+--------------------+---------------------+---------------------+
    994410004
    994510005RMS only calls for task 1 to have the lowest
     
    1003210092Processor Utilization Rule to an application with three critical
    1003310093periodic tasks.  The following table details the RMS priority,
    10034 period, execution time, and processor utilization for each task:
    10035 .. code:: c
    10036 
    10037     +------------+----------+--------+-----------+-------------+
    10038     |    Task    |   RMS    | Period | Execution |  Processor  |
    10039     |            | Priority |        |   Time    | Utilization |
    10040     +------------+----------+--------+-----------+-------------+
    10041     |     1      |   High   |  100   |    15     |    0.15     |
    10042     +------------+----------+--------+-----------+-------------+
    10043     |     2      |  Medium  |  200   |    50     |    0.25     |
    10044     +------------+----------+--------+-----------+-------------+
    10045     |     3      |   Low    |  300   |   100     |    0.33     |
    10046     +------------+----------+--------+-----------+-------------+
     10094period, execution time, and processor utilization for each task.
     10095
     10096+------------+----------+--------+-----------+-------------+
     10097| Tas   k    | RMS      | Period | Execution | Processor   |
     10098|            | Priority |        | Time      | Utilization |
     10099+============+==========+========+===========+=============+
     10100|     1      |   High   |  100   |    15     |    0.15     |
     10101+------------+----------+--------+-----------+-------------+
     10102|     2      |  Medium  |  200   |    50     |    0.25     |
     10103+------------+----------+--------+-----------+-------------+
     10104|     3      |   Low    |  300   |   100     |    0.33     |
     10105+------------+----------+--------+-----------+-------------+
    1004710106
    1004810107The total processor utilization for this task set is
     
    100851014425 units.  The following table details the RMS priority, period,
    1008610145execution time, and processor utilization for each task:
    10087 .. code:: c
    10088 
    10089     +------------+----------+--------+-----------+-------------+
    10090     |    Task    |   RMS    | Period | Execution |  Processor  |
    10091     |            | Priority |        |   Time    | Utilization |
    10092     +------------+----------+--------+-----------+-------------+
    10093     |     1      |   High   |  100   |    25     |    0.25     |
    10094     +------------+----------+--------+-----------+-------------+
    10095     |     2      |  Medium  |  200   |    50     |    0.25     |
    10096     +------------+----------+--------+-----------+-------------+
    10097     |     3      |   Low    |  300   |   100     |    0.33     |
    10098     +------------+----------+--------+-----------+-------------+
     10146
     10147
     10148+------------+----------+--------+-----------+-------------+
     10149| Task       | RMS      | Period | Execution | Processor   |
     10150|            | Priority |        | Time      | Utilization |
     10151+============+==========+========+===========+=============+
     10152|     1      |   High   |  100   |    25     |    0.25     |
     10153+------------+----------+--------+-----------+-------------+
     10154|     2      |  Medium  |  200   |    50     |    0.25     |
     10155+------------+----------+--------+-----------+-------------+
     10156|     3      |   Low    |  300   |   100     |    0.33     |
     10157+------------+----------+--------+-----------+-------------+
    1009910158
    1010010159The total processor utilization for the modified task
     
    1011010169the total execution time, and whether all the deadlines have
    1011110170been met.
    10112 .. code:: c
    10113 
    10114     +----------+------+------+------+----------------------+---------------+
    10115     | Deadline | Task | Task | Task |        Total         | All Deadlines |
    10116     |   Time   |  1   |  2   |  3   |    Execution Time    |     Met?      |
    10117     +----------+------+------+------+----------------------+---------------+
    10118     |   100    |  1   |  1   |  1   |  25 + 50 + 100 = 175 |      NO       |
    10119     +----------+------+------+------+----------------------+---------------+
    10120     |   200    |  2   |  1   |  1   |  50 + 50 + 100 = 200 |     YES       |
    10121     +----------+------+------+------+----------------------+---------------+
     10171
     10172+----------+------+------+------+----------------------+---------------+
     10173| Deadline | Task | Task | Task | Total                | All Deadlines |
     10174| Time     | 1    | 2    | 3    | Execution Time       | Met?          |
     10175+==========+======+======+======+======================+===============+
     10176|   100    |  1   |  1   |  1   |  25 + 50 + 100 = 175 |      NO       |
     10177+----------+------+------+------+----------------------+---------------+
     10178|   200    |  2   |  1   |  1   |  50 + 50 + 100 = 200 |     YES       |
     10179+----------+------+------+------+----------------------+---------------+
    1012210180
    1012310181The key to this analysis is to recognize when each
     
    1018710245following:
    1018810246
    10189 - ```` *C. L. Liu and J. W. Layland. "Scheduling Algorithms for
     10247- *C. L. Liu and J. W. Layland. "Scheduling Algorithms for
    1019010248  Multiprogramming in a Hard Real Time Environment." *Journal of
    1019110249  the Association of Computing Machinery*. January 1973. pp. 46-61.*
    1019210250
    10193 - ```` *John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic
     10251- *John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic
    1019410252  Scheduling Algorithm: Exact Characterization and Average Case
    1019510253  Behavior."  *IEEE Real-Time Systems Symposium*. 1989. pp. 166-171.*
    1019610254
    10197 - ```` *Lui Sha and John Goodenough. "Real-Time Scheduling
     10255- *Lui Sha and John Goodenough. "Real-Time Scheduling
    1019810256  Theory and Ada."  *IEEE Computer*. April 1990. pp. 53-62.*
    1019910257
    10200 - ```` *Alan Burns. "Scheduling hard real-time systems: a
     10258- *Alan Burns. "Scheduling hard real-time systems: a
    1020110259  review."  *Software Engineering Journal*. May 1991. pp. 116-128.*
    1020210260
     
    1062510683time values will be set to 0.  Otherwise, both time values will contain
    1062610684time information since the last invocation of the``rtems.rate_monotonic_period`` directive.  More
    10627 specifically, the (ticks_)since_last_period value contains the elapsed time
     10685specifically, the ticks_since_last_period value contains the elapsed time
    1062810686which has occurred since the last invocation of the``rtems.rate_monotonic_period`` directive and the
    10629 (ticks_)executed_since_last_period contains how much processor time the
     10687ticks_executed_since_last_period contains how much processor time the
    1063010688owning task has consumed since the invocation of the``rtems.rate_monotonic_period`` directive.
    1063110689
     
    1136011418device.
    1136111419
    11362 For more information on user extensions, refer to the:ref:`User Extensions Manager <User-Extensions-Manager>` chapter.
     11420For more information on user extensions, refer to the `User Extensions Manager`_ chapter.
    1136311421
    1136411422Multiprocessor Communications Interface (MPCI)
     
    1145211510
    1145311511.. COMMENT: All rights reserved.
    11454 
    11455 .. _User-Extensions-Manager:
    1145611512
    1145711513User Extensions Manager
     
    1204312099.. COMMENT: Device Driver Table, Init task table, etc.?
    1204412100
    12045 .. _Configuring-a-System:
    1204612101
    1204712102Configuring a System
     
    1211212167.. COMMENT: === Sizing the RTEMS Workspace ===
    1211312168
    12114 .. _Configuring-a-System-Sizing-the-RTEMS-Workspace:
    1211512169
    1211612170Sizing the RTEMS Workspace
     
    1212912183includes the amount of memory that will be allocated for internal use
    1213012184by RTEMS. The automatic calculation may underestimate the workspace
    12131 size truly needed by the application, in which case one can use the``CONFIGURE_MEMORY_OVERHEAD`` macro to add a value to the estimate. See:ref:`Configuring a System Specify Memory Overhead <Configuring-a-System-Specify-Memory-Overhead>` for more details.
     12185size truly needed by the application, in which case one can use the``CONFIGURE_MEMORY_OVERHEAD`` macro to add a value to the estimate. See `Specify Memory Overhead`_ for more details.
    1213212186
    1213312187The memory area for the RTEMS Workspace is determined by the BSP.  In case the
     
    1214912203space from inside the RTEMS Workspace.
    1215012204
    12151 See :ref:`Configuring a System Unlimited Objects <Configuring-a-System-Unlimited-Objects>` for more details about
     12205See `Unlimited Objects`_ for more details about
    1215212206the second way, which allows for dynamic allocation of objects and
    1215312207therefore does not provide determinism.  This mode is useful mostly for
     
    1222012274- RANGE:
    1222112275  The range depends on the Data Type of the macro.
     12276
    1222212277  - − If the data type is of type task priority, then its value should
    1222312278    be an integer in the range of 1 to 255.
     12279
    1222412280  - − If the data type is an integer, then it can have numbers, characters
    1222512281    (in case the value is defined using another macro) and arithmetic operations
    1222612282    (+, -, \*, /).
     12283
    1222712284  - − If the data type is a function pointer the first character
    1222812285    should be an alphabet or an underscore. The rest of the string
    1222912286    can be alphanumeric.
     12287
    1223012288  - − If the data type is RTEMS Attributes or RTEMS Mode then
    1223112289    the string should be alphanumeric.
     12290
    1223212291  - − If the data type is RTEMS NAME then the value should be
    1223312292    an integer>=0 or RTEMS_BUILD_NAME( ’U’, ’I’, ’1’, ’ ’ )
     
    1223612295  The default value should be in the following formats-
    1223712296  Please note that the ’.’ (full stop) is necessary.
     12297
    1223812298  - − In case the value is not defined then:
    1223912299    This is not defined by default.
     12300
    1224012301  - − If we know the default value then:
    1224112302    The default value is XXX.
     12303
    1224212304  - − If the default value is BSP Specific then:
    1224312305    This option is BSP specific.
     
    1233412396.. COMMENT: === Unlimited Objects ===
    1233512397
    12336 .. _Configuring-a-System-Unlimited-Objects:
    1233712398
    1233812399Unlimited Objects
     
    1234112402In real-time embedded systems the RAM is normally a limited, critical
    1234212403resource and dynamic allocation is avoided as much as possible to
    12343 ensure predictable, deterministic execution times. For such cases, see:ref:`Configuring a System Sizing the RTEMS Workspace <Configuring-a-System-Sizing-the-RTEMS-Workspace>` for an overview
     12404ensure predictable, deterministic execution times. For such cases, see `Sizing the RTEMS Workspace`_ for an overview
    1234412405of how to tune the size of the workspace.  Frequently when users are
    1234512406porting software to RTEMS the precise resource requirements of the
     
    1241012471
    1241112472Due to the memory requirements of unlimited objects it is strongly recommended
    12412 to use them only in combination with the unified work areas. See:ref:`Configuring a System Separate or Unified Work Areas <Configuring-a-System-Separate-or-Unified-Work-Areas>` for more information
     12473to use them only in combination with the unified work areas. See `Separate or Unified Work Areas`_ for more information
    1241312474on unified work areas.
    1241412475
     
    1257012631for tasks assume that each task has a minimum stack size and
    1257112632has floating point support enabled.  The configuration parameter``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify task stack
    12572 requirements *ABOVE* the minimum size required.  See:ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
     12633requirements *ABOVE* the minimum size required.  See `Reserve Task/Thread Stack Memory Above Minimum`_
    1257312634for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
    1257412635
     
    1298313044If the stack size specified is greater than the configured minimum,
    1298413045it must be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``.
    12985 See :ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
     13046See `Reserve Task/Thread Stack Memory Above Minimum`_
    1298613047for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
    1298713048
     
    1316513226has floating point support enabled.  The configuration parameter``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify thread stack
    1316613227requirements *ABOVE* the minimum size required.
    13167 See :ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
     13228See `Reserve Task/Thread Stack Memory Above Minimum`_
    1316813229for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
    1316913230
     
    1358413645If the stack size specified is greater than the configured minimum,
    1358513646it must be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``.
    13586 See :ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
     13647See `Reserve Task/Thread Stack Memory Above Minimum`_
    1358713648for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
    1358813649
     
    1362513686.. COMMENT: === CONFIGURE_UNIFIED_WORK_AREAS ===
    1362613687
    13627 .. _Configuring-a-System-Separate-or-Unified-Work-Areas:
    1362813688
    1362913689Separate or Unified Work Areas
     
    1386913929.. COMMENT: === CONFIGURE_EXTRA_TASK_STACKS ===
    1387013930
    13871 .. _Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum:
    1387213931
    1387313932Reserve Task/Thread Stack Memory Above Minimum
     
    1420714266.. COMMENT: === CONFIGURE_MEMORY_OVERHEAD ===
    1420814267
    14209 .. _Configuring-a-System-Specify-Memory-Overhead:
    1421014268
    1421114269Specify Memory Overhead
     
    1592115979
    1592215980.. COMMENT: === Configuring Clustered Schedulers ===
    15923 
    15924 .. _Configuring-a-System-Configuring-Clustered-Schedulers:
    1592515981
    1592615982Configuring Clustered Schedulers
     
    1609316149.. COMMENT: === CONFIGURE_SMP_APPLICATION ===
    1609416150
    16095 .. _Configuring-a-System-Enable-SMP-Support-for-Applications:
    1609616151
    1609716152Enable SMP Support for Applications
     
    1692416979ways depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined:
    1692516980
    16926 - .. index:: PCI_LIB_AUTO
    16927   ``PCI_LIB_AUTO`` is used to enable the PCI auto configuration
    16928   software. PCI will be automatically probed, PCI buses enumerated, all
    16929   devices and bridges will be initialized using Plug & Play software
    16930   routines. The PCI device tree will be populated based on the PCI devices
    16931   found in the system, PCI devices will be configured by allocating address
    16932   region resources automatically in PCI space according to the BSP or host
    16933   bridge driver set up.
    16934 
    16935 - .. index:: PCI_LIB_READ
    16936   ``PCI_LIB_READ`` is used to enable the PCI read configuration
    16937   software. The current PCI configuration is read to create the RAM
    16938   representation (the PCI device tree) of the PCI devices present. PCI devices
    16939   are assumed to already have been initialized and PCI buses enumerated, it is
    16940   therefore required that a BIOS or a boot loader has set up configuration space
    16941   prior to booting into RTEMS.
    16942 
    16943 - .. index:: PCI_LIB_STATIC
    16944   ``PCI_LIB_STATIC`` is used to enable the PCI static configuration
    16945   software. The user provides a PCI tree with information how all PCI devices
    16946   are to be configured at compile time by linking in a custom``struct pci_bus pci_hb`` tree. The static PCI library will not probe PCI
    16947   for devices, instead it will assume that all devices defined by the user are
    16948   present, it will enumerate the PCI buses and configure all PCI devices in
    16949   static configuration accordingly. Since probe and allocation software is not
    16950   needed the startup is faster, has smaller footprint and does not require
    16951   dynamic memory allocation.
    16952 
    16953 - .. index:: PCI_LIB_PERIPHERAL
    16954   ``PCI_LIB_PERIPHERAL`` is used to enable the PCI peripheral
    16955   configuration. It is similar to ``PCI_LIB_STATIC``, but it will never write
    16956   the configuration to the PCI devices since PCI peripherals are not allowed to
    16957   access PCI configuration space.
     16981.. index:: PCI_LIB_AUTO
     16982
     16983``PCI_LIB_AUTO`` is used to enable the PCI auto configuration
     16984software. PCI will be automatically probed, PCI buses enumerated, all
     16985devices and bridges will be initialized using Plug & Play software
     16986routines. The PCI device tree will be populated based on the PCI devices
     16987found in the system, PCI devices will be configured by allocating address
     16988region resources automatically in PCI space according to the BSP or host
     16989bridge driver set up.
     16990
     16991.. index:: PCI_LIB_READ
     16992
     16993``PCI_LIB_READ`` is used to enable the PCI read configuration
     16994software. The current PCI configuration is read to create the RAM
     16995representation (the PCI device tree) of the PCI devices present. PCI devices
     16996are assumed to already have been initialized and PCI buses enumerated, it is
     16997therefore required that a BIOS or a boot loader has set up configuration space
     16998prior to booting into RTEMS.
     16999
     17000.. index:: PCI_LIB_STATIC
     17001
     17002``PCI_LIB_STATIC`` is used to enable the PCI static configuration
     17003software. The user provides a PCI tree with information how all PCI devices
     17004are to be configured at compile time by linking in a custom``struct pci_bus pci_hb`` tree. The static PCI library will not probe PCI
     17005for devices, instead it will assume that all devices defined by the user are
     17006present, it will enumerate the PCI buses and configure all PCI devices in
     17007static configuration accordingly. Since probe and allocation software is not
     17008needed the startup is faster, has smaller footprint and does not require
     17009dynamic memory allocation.
     17010
     17011.. index:: PCI_LIB_PERIPHERAL
     17012
     17013``PCI_LIB_PERIPHERAL`` is used to enable the PCI peripheral
     17014configuration. It is similar to ``PCI_LIB_STATIC``, but it will never write
     17015the configuration to the PCI devices since PCI peripherals are not allowed to
     17016access PCI configuration space.
    1695817017
    1695917018Note that selecting PCI_LIB_STATIC or PCI_LIB_PERIPHERAL but not defining``pci_hb`` will reuslt in link errors. Note also that in these modes
     
    1763117690
    1763217691It must be explicitly enabled via the ``--enable-smp`` configure command
    17633 line option.  To enable SMP in the application configuration see:ref:`Configuring a System Enable SMP Support for Applications <Configuring-a-System-Enable-SMP-Support-for-Applications>`.  The default
     17692line option.  To enable SMP in the application configuration see `Enable SMP Support for Applications`_.  The default
    1763417693scheduler for SMP applications supports up to 32 processors and is a global
    17635 fixed priority scheduler, see also :ref:`Configuring a System Configuring
    17636 Clustered Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.  For example applications see:file:`testsuites/smptests`.
     17694fixed priority scheduler, see also `Configuring Clustered Schedulers`_.  For example applications see:file:`testsuites/smptests`.
    1763717695
    1763817696*WARNING: The SMP support in RTEMS is work in progress.  Before you
     
    1780617864- message queues,
    1780717865
    17808 - semaphores using the :ref:`Semaphore Manager Priority Inheritance <Semaphore-Manager-Priority-Inheritance>`
     17866- semaphores using the `Priority Inheritance`_
    1780917867  protocol (priority boosting), and
    1781017868
    17811 - semaphores using the :ref:`Semaphore Manager Multiprocessor Resource
    17812   Sharing Protocol <Semaphore-Manager-Multiprocessor-Resource-Sharing-Protocol>` (MrsP).
     17869- semaphores using the `Multiprocessor Resource Sharing Protocol`_ (MrsP).
    1781317870
    1781417871The clustered scheduling approach enables separation of functions with
     
    1781717874inter-cluster synchronization primitives are used.  This is work in progress.
    1781817875
    17819 For the configuration of clustered schedulers see :ref:`Configuring a System
    17820 Configuring Clustered Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.
    17821 
    17822 To set the scheduler of a task see :ref:`Symmetric Multiprocessing Services
    17823 SCHEDULER_IDENT - Get ID of a scheduler <Symmetric-Multiprocessing-Services-SCHEDULER_005fIDENT-_002d-Get-ID-of-a-scheduler>` and :ref:`Symmetric Multiprocessing
    17824 Services TASK_SET_SCHEDULER - Set scheduler of a task <Symmetric-Multiprocessing-Services-TASK_005fSET_005fSCHEDULER-_002d-Set-scheduler-of-a-task>`.
     17876For the configuration of clustered schedulers see `Configuring Clustered Schedulers`_.
     17877
     17878To set the scheduler of a task see `SCHEDULER_IDENT - Get ID of a scheduler`_
     17879 and `TASK_SET_SCHEDULER - Set scheduler of a task`_.
    1782517880
    1782617881Task Priority Queues
     
    1830718362.. COMMENT: rtems_scheduler_ident
    1830818363
    18309 .. _Symmetric-Multiprocessing-Services-SCHEDULER_005fIDENT-_002d-Get-ID-of-a-scheduler:
    1831018364
    1831118365SCHEDULER_IDENT - Get ID of a scheduler
     
    1832518379
    1832618380Identifies a scheduler by its name.  The scheduler name is determined by the
    18327 scheduler configuration.  See :ref:`Configuring a System Configuring Clustered
    18328 Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.
     18381scheduler configuration.  See `Configuring Clustered Schedulers`_.
    1832918382
    1833018383**NOTES:**
     
    1838018433.. COMMENT: rtems_task_set_scheduler
    1838118434
    18382 .. _Symmetric-Multiprocessing-Services-TASK_005fSET_005fSCHEDULER-_002d-Set-scheduler-of-a-task:
    1838318435
    1838418436TASK_SET_SCHEDULER - Set scheduler of a task
     
    1880918861given to the functions is not the PCI I/O addresses, the caller must have
    1881018862translated PCI I/O addresses (available in the PCI BARs) into a BSP or host
    18811 driver custom address, see :ref:`PCI Library Access functions <PCI-Library-Access-functions>` for how
     18863driver custom address, see `Access functions`_ for how
    1881218864addresses are translated.
     18865
    1881318866.. code:: c
    1881418867
     
    1884718900is required, pci_ld_le16 != ld_le16 on big endian PCI buses.
    1884818901
    18849 .. _PCI-Library-Access-functions:
    1885018902
    1885118903Access functions
     
    1891318965when including bsp.h.
    1891418966
    18915 PCI device drivers may use the pci_interrupt_ routines in order to call the
     18967PCI device drivers may use the pci_interrupt_* routines in order to call the
    1891618968BSP specific functions in a platform independent way. The PCI interrupt
    1891718969interface has been made similar to the RTEMS IRQ extension so that a BSP can
     
    1896319015Recursive routines make calculating peak stack usage difficult, if not
    1896419016impossible.  Each call to the recursive routine consumes *n* bytes
    18965 of stack space.  If the routine recursives 1000 times, then``1000 * *n*`` bytes of stack space are required.
     19017of stack space.  If the routine recursives 1000 times, then ``1000 * *n*`` bytes of stack space are required.
    1896619018
    1896719019Execution
     
    1918419236- percentage of time consumed by this task
    1918519237
    19186 The following is an example of the report generated:
    19187 .. code:: c
    19188 
    19189     -------------------------------------------------------------------------------
    19190     CPU USAGE BY THREAD
    19191     ------------+----------------------------------------+---------------+---------
    19192     ID         | NAME                                   | SECONDS       | PERCENT
    19193     ------------+----------------------------------------+---------------+---------
    19194     0x04010001 | IDLE                                   |             0 |   0.000
    19195     0x08010002 | TA1                                    |          1203 |   0.748
    19196     0x08010003 | TA2                                    |           203 |   0.126
    19197     0x08010004 | TA3                                    |           202 |   0.126
    19198     ------------+----------------------------------------+---------------+---------
    19199     TICKS SINCE LAST SYSTEM RESET:                                           1600
    19200     TOTAL UNITS:                                                             1608
    19201     -------------------------------------------------------------------------------
     19238The following is an example of the report generated.
     19239
     19240
     19241+------------------------------------------------------------------------------+
     19242|CPU USAGE BY THREAD                                                           |
     19243+-----------+----------------------------------------+-------------------------+
     19244|ID         | NAME                                   | SECONDS       | PERCENT |
     19245+-----------+----------------------------------------+---------------+---------+
     19246|0x04010001 | IDLE                                   |             0 |   0.000 |
     19247+-----------+----------------------------------------+---------------+---------+
     19248|0x08010002 | TA1                                    |          1203 |   0.748 |
     19249+-----------+----------------------------------------+---------------+---------+
     19250|0x08010003 | TA2                                    |           203 |   0.126 |
     19251+-----------+----------------------------------------+---------------+---------+
     19252|0x08010004 | TA3                                    |           202 |   0.126 |
     19253+-----------+----------------------------------------+---------------+---------+
     19254|TICKS SINCE LAST SYSTEM RESET:                                           1600 |
     19255|TOTAL UNITS:                                                             1608 |
     19256+------------------------------------------------------------------------------+
    1920219257
    1920319258Notice that the "TOTAL UNITS" is greater than the ticks per reset.
     
    1992819983follows:
    1992919984
    19930 .. code:: c
    1993119985
    1993219986**NOTES:**
     
    2158821642.. COMMENT: All rights reserved.
    2158921643
    21590 .. _Linker-Sets:
    2159121644
    2159221645Linker Sets
     
    2269722750    context to store its internal state.  Each processor in the system is owned by
    2269822751    at most one scheduler instance.  The processor to scheduler instance assignment
    22699     is determined at application configuration time.  See :ref:`Configuring a System
    22700     Configuring Clustered Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.
     22752    is determined at application configuration time.  See `Configuring Clustered Schedulers`_.
    2270122753
    2270222754:dfn:`segments`
Note: See TracChangeset for help on using the changeset viewer.