Changeset 0d86b71 in rtems-docs


Ignore:
Timestamp:
Feb 18, 2016, 4:29:28 AM (4 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, master
Children:
00d1a0a
Parents:
1762611
git-author:
Chris Johns <chrisj@…> (02/18/16 04:29:28)
git-committer:
Amar Takhar <verm@…> (05/03/16 00:51:26)
Message:

Clean up.

Location:
c_user
Files:
10 edited

Legend:

Unmodified
Added
Removed
  • c_user/chains.rst

    r1762611 r0d86b71  
     1.. COMMENT: Copyright 2014 Gedare Bloom.
     2.. COMMENT: All rights reserved.
     3
    14Chains
    25######
     
    811
    912The Chains API is an interface to the Super Core (score) chain
    10 implementation. The Super Core uses chains for all list type
    11 functions. This includes wait queues and task queues. The Chains API
    12 provided by RTEMS is:
    13 
    14 - build_id
     13implementation. The Super Core uses chains for all list type functions. This
     14includes wait queues and task queues. The Chains API provided by RTEMS is:
    1515
    1616- ``rtems_chain_node`` - Chain node used in user objects
     
    1818- ``rtems_chain_control`` - Chain control node
    1919
    20 - ``rtems_chain_initialize`` - initialize the chain with nodes
    21 
    22 - ``rtems_chain_initialize_empty`` - initialize the chain as empty
    23 
    24 - ``rtems_chain_is_null_node`` - Is the node NULL ?
    25 
    26 - ``rtems_chain_head`` - Return the chain's head
    27 
    28 - ``rtems_chain_tail`` - Return the chain's tail
    29 
    30 - ``rtems_chain_are_nodes_equal`` - Are the node's equal ?
    31 
    32 - ``rtems_chain_is_empty`` - Is the chain empty ?
    33 
    34 - ``rtems_chain_is_first`` - Is the Node the first in the chain ?
    35 
    36 - ``rtems_chain_is_last`` - Is the Node the last in the chain ?
    37 
    38 - ``rtems_chain_has_only_one_node`` - Does the node have one node ?
    39 
    40 - ``rtems_chain_node_count_unprotected`` - Returns the node count of the chain (unprotected)
    41 
    42 - ``rtems_chain_is_head`` - Is the node the head ?
    43 
    44 - ``rtems_chain_is_tail`` - Is the node the tail ?
    45 
    46 - ``rtems_chain_extract`` - Extract the node from the chain
    47 
    48 - ``rtems_chain_extract_unprotected`` - Extract the node from the chain (unprotected)
    49 
    50 - ``rtems_chain_get`` - Return the first node on the chain
    51 
    52 - ``rtems_chain_get_unprotected`` - Return the first node on the chain (unprotected)
    53 
    54 - ``rtems_chain_get_first_unprotected`` - Get the first node on the chain (unprotected)
    55 
    56 - ``rtems_chain_insert`` - Insert the node into the chain
    57 
    58 - ``rtems_chain_insert_unprotected`` - Insert the node into the chain (unprotected)
    59 
    60 - ``rtems_chain_append`` - Append the node to chain
    61 
    62 - ``rtems_chain_append_unprotected`` - Append the node to chain (unprotected)
    63 
    64 - ``rtems_chain_prepend`` - Prepend the node to the end of the chain
    65 
    66 - ``rtems_chain_prepend_unprotected`` - Prepend the node to chain (unprotected)
     20- rtems_chain_initialize_ - initialize the chain with nodes
     21
     22- rtems_chain_initialize_empty_ - initialize the chain as empty
     23
     24- rtems_chain_is_null_node_ - Is the node NULL ?
     25
     26- rtems_chain_head_ - Return the chain's head
     27
     28- rtems_chain_tail_ - Return the chain's tail
     29
     30- rtems_chain_are_nodes_equal_ - Are the node's equal ?
     31
     32- rtems_chain_is_empty_ - Is the chain empty ?
     33
     34- rtems_chain_is_first_ - Is the Node the first in the chain ?
     35
     36- rtems_chain_is_last_ - Is the Node the last in the chain ?
     37
     38- rtems_chain_has_only_one_node_ - Does the node have one node ?
     39
     40- rtems_chain_node_count_unprotected_ - Returns the node count of the chain (unprotected)
     41
     42- rtems_chain_is_head_ - Is the node the head ?
     43
     44- rtems_chain_is_tail_ - Is the node the tail ?
     45
     46- rtems_chain_extract_ - Extract the node from the chain
     47
     48- rtems_chain_extract_unprotected_ - Extract the node from the chain (unprotected)
     49
     50- rtems_chain_get_ - Return the first node on the chain
     51
     52- rtems_chain_get_unprotected_ - Return the first node on the chain (unprotected)
     53
     54- rtems_chain_insert_ - Insert the node into the chain
     55
     56- rtems_chain_insert_unprotected_ - Insert the node into the chain (unprotected)
     57
     58- rtems_chain_append_ - Append the node to chain
     59
     60- rtems_chain_append_unprotected_ - Append the node to chain (unprotected)
     61
     62- rtems_chain_prepend_ - Prepend the node to the end of the chain
     63
     64- rtems_chain_prepend_unprotected_ - Prepend the node to chain (unprotected)
    6765
    6866Background
    6967==========
    7068
    71 The Chains API maps to the Super Core Chains API. Chains are
    72 implemented as a double linked list of nodes anchored to a control
    73 node. The list starts at the control node and is terminated at the
    74 control node. A node has previous and next pointers. Being a double
    75 linked list nodes can be inserted and removed without the need to
    76 travse the chain.
    77 
    78 Chains have a small memory footprint and can be used in interrupt
    79 service routines and are thread safe in a multi-threaded
    80 environment. The directives list which operations disable interrupts.
     69The Chains API maps to the Super Core Chains API. Chains are implemented as a
     70double linked list of nodes anchored to a control node. The list starts at the
     71control node and is terminated at the control node. A node has previous and
     72next pointers. Being a double linked list nodes can be inserted and removed
     73without the need to travse the chain.
     74
     75Chains have a small memory footprint and can be used in interrupt service
     76routines and are thread safe in a multi-threaded environment. The directives
     77list which operations disable interrupts.
    8178
    8279Chains are very useful in Board Support packages and applications.
     
    8582-----
    8683
    87 A chain is made up from nodes that orginate from a chain control
    88 object. A node is of type ``rtems_chain_node``. The node
    89 is designed to be part of a user data structure and a cast is used to
    90 move from the node address to the user data structure address. For
    91 example:
    92 .. code:: c
     84A chain is made up from nodes that orginate from a chain control object. A node
     85is of type ``rtems_chain_node``. The node is designed to be part of a user data
     86structure and a cast is used to move from the node address to the user data
     87structure address. For example:
     88
     89.. code-block:: c
    9390
    9491    typedef struct foo
    9592    {
    96     rtems_chain_node node;
    97     int              bar;
     93        rtems_chain_node node;
     94        int              bar;
    9895    } foo;
    9996
    100 creates a type ``foo`` that can be placed on a chain. To get the
    101 foo structure from the list you perform the following:
    102 .. code:: c
     97creates a type ``foo`` that can be placed on a chain. To get the foo structure
     98from the list you perform the following:
     99
     100.. code-block:: c
    103101
    104102    foo* get_foo(rtems_chain_control* control)
    105103    {
    106     return (foo*) rtems_chain_get(control);
     104        return (foo*) rtems_chain_get(control);
    107105    }
    108106
    109 The node is placed at the start of the user's structure to allow the
    110 node address on the chain to be easly cast to the user's structure
    111 address.
     107The node is placed at the start of the user's structure to allow the node
     108address on the chain to be easly cast to the user's structure address.
    112109
    113110Controls
    114111--------
    115112
    116 A chain is anchored with a control object. Chain control provide the
    117 user with access to the nodes on the chain. The control is head of the
    118 node.
    119 
    120 .. code:: c
    121 
    122     Control
     113A chain is anchored with a control object. Chain control provide the user with
     114access to the nodes on the chain. The control is head of the node.
     115
     116.. code-block:: c
     117
     118    [Control]
    123119    first ------------------------>
    124     permanent_null <--------------- NODE
     120    permanent_null <--------------- [NODE]
    125121    last ------------------------->
    126122
    127 The implementation does not require special checks for manipulating
    128 the first and last nodes on the chain. To accomplish this the``rtems_chain_control`` structure is treated as two
    129 overlapping ``rtems_chain_node`` structures.  The
    130 permanent head of the chain overlays a node structure on the first and``permanent_null`` fields.  The ``permanent_tail`` of the chain
    131 overlays a node structure on the ``permanent_null`` and ``last``
    132 elements of the structure.
     123The implementation does not require special checks for manipulating the first
     124and last nodes on the chain. To accomplish this the ``rtems_chain_control``
     125structure is treated as two overlapping ``rtems_chain_node`` structures.  The
     126permanent head of the chain overlays a node structure on the first and
     127``permanent_null`` fields.  The ``permanent_tail`` of the chain overlays a node
     128structure on the ``permanent_null`` and ``last`` elements of the structure.
    133129
    134130Operations
     
    138134---------------
    139135
    140 Chains are designed to be used in a multi-threading environment. The
    141 directives list which operations mask interrupts. Chains supports
    142 tasks and interrupt service routines appending and extracting nodes
    143 with out the need for extra locks. Chains how-ever cannot insure the
    144 integrity of a chain for all operations. This is the responsibility of
    145 the user. For example an interrupt service routine extracting nodes
    146 while a task is iterating over the chain can have unpredictable
    147 results.
     136Chains are designed to be used in a multi-threading environment. The directives
     137list which operations mask interrupts. Chains supports tasks and interrupt
     138service routines appending and extracting nodes with out the need for extra
     139locks. Chains how-ever cannot insure the integrity of a chain for all
     140operations. This is the responsibility of the user. For example an interrupt
     141service routine extracting nodes while a task is iterating over the chain can
     142have unpredictable results.
    148143
    149144Creating a Chain
     
    152147To create a chain you need to declare a chain control then add nodes
    153148to the control. Consider a user structure and chain control:
    154 .. code:: c
     149
     150.. code-block:: c
    155151
    156152    typedef struct foo
    157153    {
    158     rtems_chain_node node;
    159     uint8_t char*    data;
     154        rtems_chain_node node;
     155        uint8_t char*    data;
    160156    } foo;
    161157    rtems_chain_control chain;
    162158
    163159Add nodes with the following code:
    164 .. code:: c
     160
     161.. code-block:: c
    165162
    166163    rtems_chain_initialize_empty (&chain);
     164
    167165    for (i = 0; i < count; i++)
    168166    {
    169     foo* bar = malloc (sizeof (foo));
    170     if (!bar)
    171     return -1;
    172     bar->data = malloc (size);
    173     rtems_chain_append (&chain, &bar->node);
     167        foo* bar = malloc (sizeof (foo));
     168        if (!bar)
     169            return -1;
     170        bar->data = malloc (size);
     171        rtems_chain_append (&chain, &bar->node);
    174172    }
    175173
     
    181179.. index:: chain iterate
    182180
    183 Iterating a chain is a common function. The example shows how to
    184 iterate the buffer pool chain created in the last section to find
    185 buffers starting with a specific string. If the buffer is located it is
    186 extracted from the chain and placed on another chain:
    187 .. code:: c
     181Iterating a chain is a common function. The example shows how to iterate the
     182buffer pool chain created in the last section to find buffers starting with a
     183specific string. If the buffer is located it is extracted from the chain and
     184placed on another chain:
     185
     186.. code-block:: c
    188187
    189188    void foobar (const char*          match,
    190     rtems_chain_control* chain,
    191     rtems_chain_control* out)
     189                 rtems_chain_control* chain,
     190                 rtems_chain_control* out)
    192191    {
    193     rtems_chain_node* node;
    194     foo*              bar;
    195     rtems_chain_initialize_empty (out);
    196     node = chain->first;
    197     while (!rtems_chain_is_tail (chain, node))
    198     {
    199     bar = (foo*) node;
    200     rtems_chain_node* next_node = node->next;
    201     if (strcmp (match, bar->data) == 0)
    202     {
    203     rtems_chain_extract (node);
    204     rtems_chain_append (out, node);
    205     }
    206     node = next_node;
    207     }
     192        rtems_chain_node* node;
     193        foo*              bar;
     194
     195        rtems_chain_initialize_empty (out);
     196
     197        node = chain->first;
     198        while (!rtems_chain_is_tail (chain, node))
     199        {
     200            bar = (foo*) node;
     201            rtems_chain_node* next_node = node->next;
     202            if (strcmp (match, bar->data) == 0)
     203            {
     204                rtems_chain_extract (node);
     205                rtems_chain_append (out, node);
     206            }
     207            node = next_node;
     208        }
    208209    }
    209210
     
    214215
    215216.. COMMENT: Initialize this Chain With Nodes
     217
     218.. _rtems_chain_initialize:
    216219
    217220Initialize Chain With Nodes
     
    223226.. index:: rtems_chain_initialize
    224227
    225 .. code:: c
     228.. code-block:: c
    226229
    227230    void rtems_chain_initialize(
    228     rtems_chain_control \*the_chain,
    229     void                \*starting_address,
    230     size_t               number_nodes,
    231     size_t               node_size
     231        rtems_chain_control *the_chain,
     232        void                *starting_address,
     233        size_t               number_nodes,
     234        size_t               node_size
    232235    )
    233236
     
    238241**DESCRIPTION:**
    239242
    240 This function take in a pointer to a chain control and initializes it
    241 to contain a set of chain nodes.  The chain will contain ``number_nodes``
    242 chain nodes from the memory pointed to by ``start_address``.  Each node
    243 is assumed to be ``node_size`` bytes.
     243This function take in a pointer to a chain control and initializes it to
     244contain a set of chain nodes.  The chain will contain ``number_nodes`` chain
     245nodes from the memory pointed to by ``start_address``.  Each node is assumed to
     246be ``node_size`` bytes.
    244247
    245248**NOTES:**
     
    250253
    251254.. COMMENT: Initialize this Chain as Empty
     255
     256.. _rtems_chain_initialize_empty:
    252257
    253258Initialize Empty
     
    259264.. index:: rtems_chain_initialize_empty
    260265
    261 .. code:: c
     266.. code-block:: c
    262267
    263268    void rtems_chain_initialize_empty(
    264     rtems_chain_control \*the_chain
    265     );
    266 
    267 **RETURNS**
    268 
    269 Returns nothing.
    270 
    271 **DESCRIPTION:**
    272 
    273 This function take in a pointer to a chain control and initializes it
    274 to empty.
     269        rtems_chain_control *the_chain
     270    );
     271
     272**RETURNS**
     273
     274Returns nothing.
     275
     276**DESCRIPTION:**
     277
     278This function take in a pointer to a chain control and initializes it to empty.
    275279
    276280**NOTES:**
    277281
    278282This call will discard any nodes on the chain.
     283
     284.. _rtems_chain_is_null_node:
    279285
    280286Is Null Node ?
     
    286292.. index:: rtems_chain_is_null_node
    287293
    288 .. code:: c
     294.. code-block:: c
    289295
    290296    bool rtems_chain_is_null_node(
    291     const rtems_chain_node \*the_node
     297        const rtems_chain_node *the_node
    292298    );
    293299
     
    300306
    301307Tests the node to see if it is a NULL returning ``true`` if a null.
     308
     309.. _rtems_chain_head:
    302310
    303311Head
     
    309317.. index:: rtems_chain_head
    310318
    311 .. code:: c
    312 
    313     rtems_chain_node \*rtems_chain_head(
    314     rtems_chain_control \*the_chain
     319.. code-block:: c
     320
     321    rtems_chain_node *rtems_chain_head(
     322        rtems_chain_control *the_chain
    315323    )
    316324
     
    322330
    323331This function returns a pointer to the first node on the chain.
     332
     333.. _rtems_chain_tail:
    324334
    325335Tail
     
    331341.. index:: rtems_chain_tail
    332342
    333 .. code:: c
    334 
    335     rtems_chain_node \*rtems_chain_tail(
    336     rtems_chain_control \*the_chain
     343.. code-block:: c
     344
     345    rtems_chain_node *rtems_chain_tail(
     346        rtems_chain_control *the_chain
    337347    );
    338348
     
    344354
    345355This function returns a pointer to the last node on the chain.
     356
     357.. _rtems_chain_are_nodes_equal:
    346358
    347359Are Two Nodes Equal ?
     
    353365.. index:: rtems_chain_are_nodes_equal
    354366
    355 .. code:: c
     367.. code-block:: c
    356368
    357369    bool rtems_chain_are_nodes_equal(
    358     const rtems_chain_node \*left,
    359     const rtems_chain_node \*right
    360     );
    361 
    362 **RETURNS**
    363 
    364 This function returns ``true`` if the left node and the right node are
    365 equal, and ``false`` otherwise.
    366 
    367 **DESCRIPTION:**
    368 
    369 This function returns ``true`` if the left node and the right node are
    370 equal, and ``false`` otherwise.
     370        const rtems_chain_node *left,
     371        const rtems_chain_node *right
     372    );
     373
     374**RETURNS**
     375
     376This function returns ``true`` if the left node and the right node are equal,
     377and ``false`` otherwise.
     378
     379**DESCRIPTION:**
     380
     381This function returns ``true`` if the left node and the right node are equal,
     382and ``false`` otherwise.
     383
     384.. _rtems_chain_is_empty:
    371385
    372386Is the Chain Empty
     
    378392.. index:: rtems_chain_is_empty
    379393
    380 .. code:: c
     394.. code-block:: c
    381395
    382396    bool rtems_chain_is_empty(
    383     rtems_chain_control \*the_chain
     397        rtems_chain_control *the_chain
    384398    );
    385399
     
    393407This function returns ``true`` if there a no nodes on the chain and ``false``
    394408otherwise.
     409
     410.. _rtems_chain_is_first:
    395411
    396412Is this the First Node on the Chain ?
     
    402418.. index:: rtems_chain_is_first
    403419
    404 .. code:: c
     420.. code-block:: c
    405421
    406422    bool rtems_chain_is_first(
    407     const rtems_chain_node \*the_node
    408     );
    409 
    410 **RETURNS**
    411 
    412 This function returns ``true`` if the node is the first node on a chain
    413 and ``false`` otherwise.
    414 
    415 **DESCRIPTION:**
    416 
    417 This function returns ``true`` if the node is the first node on a chain
    418 and ``false`` otherwise.
     423        const rtems_chain_node *the_node
     424    );
     425
     426**RETURNS**
     427
     428This function returns ``true`` if the node is the first node on a chain and
     429``false`` otherwise.
     430
     431**DESCRIPTION:**
     432
     433This function returns ``true`` if the node is the first node on a chain and
     434``false`` otherwise.
     435
     436.. _rtems_chain_is_last:
    419437
    420438Is this the Last Node on the Chain ?
     
    426444.. index:: rtems_chain_is_last
    427445
    428 .. code:: c
     446.. code-block:: c
    429447
    430448    bool rtems_chain_is_last(
    431     const rtems_chain_node \*the_node
    432     );
    433 
    434 **RETURNS**
    435 
    436 This function returns ``true`` if the node is the last node on a chain and``false`` otherwise.
    437 
    438 **DESCRIPTION:**
    439 
    440 This function returns ``true`` if the node is the last node on a chain and``false`` otherwise.
     449        const rtems_chain_node *the_node
     450    );
     451
     452**RETURNS**
     453
     454This function returns ``true`` if the node is the last node on a chain and
     455``false`` otherwise.
     456
     457**DESCRIPTION:**
     458
     459This function returns ``true`` if the node is the last node on a chain and
     460``false`` otherwise.
     461
     462.. _rtems_chain_has_only_one_node:
    441463
    442464Does this Chain have only One Node ?
     
    448470.. index:: rtems_chain_has_only_one_node
    449471
    450 .. code:: c
     472.. code-block:: c
    451473
    452474    bool rtems_chain_has_only_one_node(
    453     const rtems_chain_control \*the_chain
    454     );
    455 
    456 **RETURNS**
    457 
    458 This function returns ``true`` if there is only one node on the chain and``false`` otherwise.
    459 
    460 **DESCRIPTION:**
    461 
    462 This function returns ``true`` if there is only one node on the chain and``false`` otherwise.
     475        const rtems_chain_control *the_chain
     476    );
     477
     478**RETURNS**
     479
     480This function returns ``true`` if there is only one node on the chain and
     481``false`` otherwise.
     482
     483**DESCRIPTION:**
     484
     485This function returns ``true`` if there is only one node on the chain and
     486``false`` otherwise.
     487
     488.. _rtems_chain_node_count_unprotected:
    463489
    464490Returns the node count of the chain (unprotected)
     
    470496.. index:: rtems_chain_node_count_unprotected
    471497
    472 .. code:: c
     498.. code-block:: c
    473499
    474500    size_t rtems_chain_node_count_unprotected(
    475     const rtems_chain_control \*the_chain
     501        const rtems_chain_control *the_chain
    476502    );
    477503
     
    483509
    484510This function returns the node count of the chain.
     511
     512.. _rtems_chain_is_head:
    485513
    486514Is this Node the Chain Head ?
     
    492520.. index:: rtems_chain_is_head
    493521
    494 .. code:: c
     522.. code-block:: c
    495523
    496524    bool rtems_chain_is_head(
    497     rtems_chain_control    \*the_chain,
    498     rtems_const chain_node \*the_node
    499     );
    500 
    501 **RETURNS**
    502 
    503 This function returns ``true`` if the node is the head of the chain and``false`` otherwise.
    504 
    505 **DESCRIPTION:**
    506 
    507 This function returns ``true`` if the node is the head of the chain and``false`` otherwise.
     525        rtems_chain_control    *the_chain,
     526        rtems_const chain_node *the_node
     527    );
     528
     529**RETURNS**
     530
     531This function returns ``true`` if the node is the head of the chain and
     532``false`` otherwise.
     533
     534**DESCRIPTION:**
     535
     536This function returns ``true`` if the node is the head of the chain and
     537``false`` otherwise.
     538
     539.. _rtems_chain_is_tail:
    508540
    509541Is this Node the Chain Tail ?
     
    515547.. index:: rtems_chain_is_tail
    516548
    517 .. code:: c
     549.. code-block:: c
    518550
    519551    bool rtems_chain_is_tail(
    520     rtems_chain_control    \*the_chain,
    521     const rtems_chain_node \*the_node
     552        rtems_chain_control    *the_chain,
     553        const rtems_chain_node *the_node
    522554    )
    523555
    524556**RETURNS**
    525557
    526 This function returns ``true`` if the node is the tail of the chain and``false`` otherwise.
    527 
    528 **DESCRIPTION:**
    529 
    530 This function returns ``true`` if the node is the tail of the chain and``false`` otherwise.
     558This function returns ``true`` if the node is the tail of the chain and
     559``false`` otherwise.
     560
     561**DESCRIPTION:**
     562
     563This function returns ``true`` if the node is the tail of the chain and
     564``false`` otherwise.
     565
     566.. _rtems_chain_extract:
    531567
    532568Extract a Node
     
    538574.. index:: rtems_chain_extract
    539575
    540 .. code:: c
     576.. code-block:: c
    541577
    542578    void rtems_chain_extract(
    543     rtems_chain_node \*the_node
     579        rtems_chain_node *the_node
    544580    );
    545581
     
    554590**NOTES:**
    555591
    556 Interrupts are disabled while extracting the node to ensure the
    557 atomicity of the operation.
    558 
    559 Use ``rtems_chain_extract_unprotected()`` to avoid disabling of
    560 interrupts.
     592Interrupts are disabled while extracting the node to ensure the atomicity of
     593the operation.
     594
     595Use rtems_chain_extract_unprotected_ to avoid disabling of interrupts.
     596
     597.. _rtems_chain_extract_unprotected:
     598
     599Extract a Node (unprotected)
     600----------------------------
     601.. index:: chain extract a node unprotected
     602
     603**CALLING SEQUENCE:**
     604
     605.. index:: rtems_chain_extract_unprotected
     606
     607.. code-block:: c
     608
     609    void rtems_chain_extract_unprotected(
     610        rtems_chain_node *the_node
     611    );
     612
     613**RETURNS**
     614
     615Returns nothing.
     616
     617**DESCRIPTION:**
     618
     619This routine extracts the node from the chain on which it resides.
     620
     621**NOTES:**
     622
     623The function does nothing to ensure the atomicity of the operation.
     624
     625.. _rtems_chain_get:
    561626
    562627Get the First Node
     
    568633.. index:: rtems_chain_get
    569634
    570 .. code:: c
    571 
    572     rtems_chain_node \*rtems_chain_get(
    573     rtems_chain_control \*the_chain
    574     );
    575 
    576 **RETURNS**
    577 
    578 Returns a pointer a node. If a node was removed, then a pointer to
    579 that node is returned. If the chain was empty, then NULL is
    580 returned.
    581 
    582 **DESCRIPTION:**
    583 
    584 This function removes the first node from the chain and returns a
    585 pointer to that node.  If the chain is empty, then NULL is returned.
    586 
    587 **NOTES:**
    588 
    589 Interrupts are disabled while obtaining the node to ensure the
    590 atomicity of the operation.
    591 
    592 Use ``rtems_chain_get_unprotected()`` to avoid disabling of
    593 interrupts.
     635.. code-block:: c
     636
     637    rtems_chain_node *rtems_chain_get(
     638        rtems_chain_control *the_chain
     639    );
     640
     641**RETURNS**
     642
     643Returns a pointer a node. If a node was removed, then a pointer to that node is
     644returned. If the chain was empty, then ``NULL`` is returned.
     645
     646**DESCRIPTION:**
     647
     648This function removes the first node from the chain and returns a pointer to
     649that node.  If the chain is empty, then ``NULL`` is returned.
     650
     651**NOTES:**
     652
     653Interrupts are disabled while obtaining the node to ensure the atomicity of the
     654operation.
     655
     656Use ``rtems_chain_get_unprotected()`` to avoid disabling of interrupts.
     657
     658.. _rtems_chain_get_unprotected:
    594659
    595660Get the First Node (unprotected)
     
    599664**CALLING SEQUENCE:**
    600665
    601 .. index:: rtems_chain_get_first_unprotected
    602 
    603 .. code:: c
    604 
    605     rtems_chain_node \*rtems_chain_get_first_unprotected(
    606     rtems_chain_control \*the_chain
     666.. index:: rtems_chain_get_unprotected
     667
     668.. code-block:: c
     669
     670    rtems_chain_node *rtems_chain_get_unprotected(
     671        rtems_chain_control *the_chain
    607672    );
    608673
     
    619684
    620685The function does nothing to ensure the atomicity of the operation.
     686
     687.. _rtems_chain_insert:
    621688
    622689Insert a Node
     
    628695.. index:: rtems_chain_insert
    629696
    630 .. code:: c
     697.. code-block:: c
    631698
    632699    void rtems_chain_insert(
    633     rtems_chain_node \*after_node,
    634     rtems_chain_node \*the_node
    635     );
    636 
    637 **RETURNS**
    638 
    639 Returns nothing.
    640 
    641 **DESCRIPTION:**
    642 
    643 This routine inserts a node on a chain immediately following the
    644 specified node.
    645 
    646 **NOTES:**
    647 
    648 Interrupts are disabled during the insert to ensure the atomicity of
    649 the operation.
    650 
    651 Use ``rtems_chain_insert_unprotected()`` to avoid disabling of
    652 interrupts.
     700        rtems_chain_node *after_node,
     701        rtems_chain_node *the_node
     702    );
     703
     704**RETURNS**
     705
     706Returns nothing.
     707
     708**DESCRIPTION:**
     709
     710This routine inserts a node on a chain immediately following the specified
     711node.
     712
     713**NOTES:**
     714
     715Interrupts are disabled during the insert to ensure the atomicity of the
     716operation.
     717
     718Use rtems_chain_insert_unprotected_ to avoid disabling of interrupts.
     719
     720.. _rtems_chain_insert_unprotected:
     721
     722Insert a Node (unprotected)
     723---------------------------
     724.. index:: chain insert a node unprotected
     725
     726**CALLING SEQUENCE:**
     727
     728.. index:: rtems_chain_insert_unprotected
     729
     730.. code-block:: c
     731
     732    void rtems_chain_insert_unprotected(
     733        rtems_chain_node *after_node,
     734        rtems_chain_node *the_node
     735    );
     736
     737**RETURNS**
     738
     739Returns nothing.
     740
     741**DESCRIPTION:**
     742
     743This routine inserts a node on a chain immediately following the specified
     744node.
     745
     746**NOTES:**
     747
     748The function does nothing to ensure the atomicity of the operation.
     749
     750.. _rtems_chain_append:
    653751
    654752Append a Node
     
    660758.. index:: rtems_chain_append
    661759
    662 .. code:: c
     760.. code-block:: c
    663761
    664762    void rtems_chain_append(
    665     rtems_chain_control \*the_chain,
    666     rtems_chain_node    \*the_node
     763        rtems_chain_control *the_chain,
     764        rtems_chain_node    *the_node
    667765    );
    668766
     
    677775**NOTES:**
    678776
    679 Interrupts are disabled during the append to ensure the atomicity of
    680 the operation.
    681 
    682 Use ``rtems_chain_append_unprotected()`` to avoid disabling of
    683 interrupts.
     777Interrupts are disabled during the append to ensure the atomicity of the
     778operation.
     779
     780Use rtems_chain_append_unprotected_ to avoid disabling of interrupts.
     781
     782.. _rtems_chain_append_unprotected:
     783
     784Append a Node (unprotected)
     785---------------------------
     786.. index:: chain append a node unprotected
     787
     788**CALLING SEQUENCE:**
     789
     790.. index:: rtems_chain_append_unprotected
     791
     792.. code-block:: c
     793
     794    void rtems_chain_append_unprotected(
     795        rtems_chain_control *the_chain,
     796        rtems_chain_node    *the_node
     797    );
     798
     799**RETURNS**
     800
     801Returns nothing.
     802
     803**DESCRIPTION:**
     804
     805This routine appends a node to the end of a chain.
     806
     807**NOTES:**
     808
     809The function does nothing to ensure the atomicity of the operation.
     810
     811.. _rtems_chain_prepend:
    684812
    685813Prepend a Node
     
    691819.. index:: rtems_chain_prepend
    692820
    693 .. code:: c
     821.. code-block:: c
    694822
    695823    void rtems_chain_prepend(
    696     rtems_chain_control \*the_chain,
    697     rtems_chain_node    \*the_node
     824        rtems_chain_control *the_chain,
     825        rtems_chain_node    *the_node
    698826    );
    699827
     
    708836**NOTES:**
    709837
    710 Interrupts are disabled during the prepend to ensure the atomicity of
    711 the operation.
    712 
    713 Use ``rtems_chain_prepend_unprotected()`` to avoid disabling of
     838Interrupts are disabled during the prepend to ensure the atomicity of the
     839operation.
     840
     841Use rtems_chain_prepend_unprotected_ to avoid disabling of
    714842interrupts.
    715843
    716 .. COMMENT: Copyright 2014 Gedare Bloom.
    717 
    718 .. COMMENT: All rights reserved.
    719 
     844.. _rtems_chain_prepend_unprotected:
     845
     846Prepend a Node (unprotected)
     847----------------------------
     848.. index:: prepend node unprotected
     849
     850**CALLING SEQUENCE:**
     851
     852.. index:: rtems_chain_prepend_unprotected
     853
     854.. code-block:: c
     855
     856    void rtems_chain_prepend_unprotected(
     857        rtems_chain_control *the_chain,
     858        rtems_chain_node    *the_node
     859    );
     860
     861**RETURNS**
     862
     863Returns nothing.
     864
     865**DESCRIPTION:**
     866
     867This routine prepends a node to the front of the chain.
     868
     869**NOTES:**
     870
     871The function does nothing to ensure the atomicity of the operation.
  • c_user/constant_bandwidth_server.rst

    r1762611 r0d86b71  
     1.. COMMENT: COPYRIGHT (c) 1989-2011.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Constant Bandwidth Server Scheduler API
    26#######################################
     
    711============
    812
    9 Unlike simple schedulers, the Constant Bandwidth Server (CBS) requires
    10 a special API for tasks to indicate their scheduling parameters.
    11 The directives provided by the CBS API are:
    12 
    13 - ``rtems_cbs_initialize`` - Initialize the CBS library
    14 
    15 - ``rtems_cbs_cleanup`` - Cleanup the CBS library
    16 
    17 - ``rtems_cbs_create_server`` - Create a new bandwidth server
    18 
    19 - ``rtems_cbs_attach_thread`` - Attach a thread to server
    20 
    21 - ``rtems_cbs_detach_thread`` - Detach a thread from server
    22 
    23 - ``rtems_cbs_destroy_server`` - Destroy a bandwidth server
    24 
    25 - ``rtems_cbs_get_server_id`` - Get an ID of a server
    26 
    27 - ``rtems_cbs_get_parameters`` - Get scheduling parameters of a server
    28 
    29 - ``rtems_cbs_set_parameters`` - Set scheduling parameters of a server
    30 
    31 - ``rtems_cbs_get_execution_time`` - Get elapsed execution time
    32 
    33 - ``rtems_cbs_get_remaining_budget`` - Get remainig execution time
    34 
    35 - ``rtems_cbs_get_approved_budget`` - Get scheduler approved execution time
     13Unlike simple schedulers, the Constant Bandwidth Server (CBS) requires a
     14special API for tasks to indicate their scheduling parameters.  The directives
     15provided by the CBS API are:
     16
     17- rtems_cbs_initialize_ - Initialize the CBS library
     18
     19- rtems_cbs_cleanup_ - Cleanup the CBS library
     20
     21- rtems_cbs_create_server_ - Create a new bandwidth server
     22
     23- rtems_cbs_attach_thread_ - Attach a thread to server
     24
     25- rtems_cbs_detach_thread_ - Detach a thread from server
     26
     27- rtems_cbs_destroy_server_ - Destroy a bandwidth server
     28
     29- rtems_cbs_get_server_id_ - Get an ID of a server
     30
     31- rtems_cbs_get_parameters_ - Get scheduling parameters of a server
     32
     33- rtems_cbs_set_parameters_ - Set scheduling parameters of a server
     34
     35- rtems_cbs_get_execution_time_ - Get elapsed execution time
     36
     37- rtems_cbs_get_remaining_budget_ - Get remainig execution time
     38
     39- rtems_cbs_get_approved_budget_ - Get scheduler approved execution time
    3640
    3741Background
     
    4448.. index:: rtems_cbs_parameters
    4549
    46 The Constant Bandwidth Server API enables tasks to communicate with
    47 the scheduler and indicate its scheduling parameters. The scheduler
    48 has to be set up first (by defining ``CONFIGURE_SCHEDULER_CBS`` macro).
    49 
    50 The difference to a plain EDF is the presence of servers.
    51 It is a budget aware extention of the EDF scheduler, therefore, tasks
    52 attached to servers behave in a similar way as with EDF unless they
    53 exceed their budget.
    54 
    55 The intention of servers is reservation of a certain computation
    56 time (budget) of the processor for all subsequent periods. The structure``rtems_cbs_parameters`` determines the behavior of
    57 a server. It contains ``deadline`` which is equal to period,
    58 and ``budget`` which is the time the server is allowed to
    59 spend on CPU per each period. The ratio between those two parameters
    60 yields the maximum percentage of the CPU the server can use
    61 (bandwidth). Moreover, thanks to this limitation the overall
    62 utilization of CPU is under control, and the sum of bandwidths
    63 of all servers in the system yields the overall reserved portion
    64 of processor. The rest is still available for ordinary tasks that
    65 are not attached to any server.
    66 
    67 In order to make the server effective to the executing tasks,
    68 tasks have to be attached to the servers. The``rtems_cbs_server_id`` is a type denoting an id of a server
    69 and ``rtems_id`` a type for id of tasks.
     50The Constant Bandwidth Server API enables tasks to communicate with the
     51scheduler and indicate its scheduling parameters. The scheduler has to be set
     52up first (by defining ``CONFIGURE_SCHEDULER_CBS`` macro).
     53
     54The difference to a plain EDF is the presence of servers.  It is a budget aware
     55extention of the EDF scheduler, therefore, tasks attached to servers behave in
     56a similar way as with EDF unless they exceed their budget.
     57
     58The intention of servers is reservation of a certain computation time (budget)
     59of the processor for all subsequent periods. The structure
     60``rtems_cbs_parameters`` determines the behavior of a server. It contains
     61``deadline`` which is equal to period, and ``budget`` which is the time the
     62server is allowed to spend on CPU per each period. The ratio between those two
     63parameters yields the maximum percentage of the CPU the server can use
     64(bandwidth). Moreover, thanks to this limitation the overall utilization of CPU
     65is under control, and the sum of bandwidths of all servers in the system yields
     66the overall reserved portion of processor. The rest is still available for
     67ordinary tasks that are not attached to any server.
     68
     69In order to make the server effective to the executing tasks, tasks have to be
     70attached to the servers. The ``rtems_cbs_server_id`` is a type denoting an id
     71of a server and ``rtems_id`` a type for id of tasks.
    7072
    7173Handling Periodic Tasks
     
    7375.. index:: CBS periodic tasks
    7476
    75 Each task's execution begins with a default background priority
    76 (see the chapter Scheduling Concepts to understand the concept of
    77 priorities in EDF). Once you decide the tasks should start periodic
    78 execution, you have two possibilities. Either you use only the Rate
    79 Monotonic manager which takes care of periodic behavior, or you declare
    80 deadline and budget using the CBS API in which case these properties
    81 are constant for all subsequent periods, unless you change them using
    82 the CBS API again. Task now only has to indicate and end of
     77Each task's execution begins with a default background priority (see the
     78chapter Scheduling Concepts to understand the concept of priorities in
     79EDF). Once you decide the tasks should start periodic execution, you have two
     80possibilities. Either you use only the Rate Monotonic manager which takes care
     81of periodic behavior, or you declare deadline and budget using the CBS API in
     82which case these properties are constant for all subsequent periods, unless you
     83change them using the CBS API again. Task now only has to indicate and end of
    8384each period using ``rtems_rate_monotonic_period``.
    8485
     
    8788.. index:: CBS overrun handler
    8889
    89 In case tasks attached to servers are not aware of their execution time
    90 and happen to exceed it, the scheduler does not guarantee execution any
    91 more and pulls the priority of the task to background, which would
    92 possibly lead to immediate preemption (if there is at least one ready
    93 task with a higher pirority). However, the task is not blocked but a
    94 callback function is invoked. The callback function
    95 (``rtems_cbs_budget_overrun``) might be optionally registered upon
    96 a server creation (``rtems_cbs_create_server``).
     90In case tasks attached to servers are not aware of their execution time and
     91happen to exceed it, the scheduler does not guarantee execution any more and
     92pulls the priority of the task to background, which would possibly lead to
     93immediate preemption (if there is at least one ready task with a higher
     94pirority). However, the task is not blocked but a callback function is
     95invoked. The callback function (``rtems_cbs_budget_overrun``) might be
     96optionally registered upon a server creation (``rtems_cbs_create_server``).
    9797
    9898This enables the user to define what should happen in case of budget
    99 overrun. There is obviously no space for huge operations because the
    100 priority is down and not real time any more, however, you still can at
    101 least in release resources for other tasks, restart the task or log an
    102 error information. Since the routine is called directly from kernel,
    103 use ``printk()`` instead of ``printf()``.
    104 
    105 The calling convention of the callback function is:.. index:: rtems_asr
    106 
    107 .. code:: c
     99overrun. There is obviously no space for huge operations because the priority
     100is down and not real time any more, however, you still can at least in release
     101resources for other tasks, restart the task or log an error information. Since
     102the routine is called directly from kernel, use ``printk()`` instead of
     103``printf()``.
     104
     105The calling convention of the callback function is:
     106
     107.. index:: rtems_asr
     108
     109.. code-block:: c
    108110
    109111    void overrun_handler(
    110     rtems_cbs_server_id server_id
     112        rtems_cbs_server_id server_id
    111113    );
    112114
     
    119121- it_limitations
    120122
    121 - In the current implementation it is possible to attach only
    122   a single task to each server.
    123 
    124 - If you have a task attached to a server and you voluntatily
    125   block it in the beginning of its execution, its priority will be
    126   probably pulled to background upon unblock, thus not guaranteed
    127   deadline any more. This is because you are effectively raising
    128   computation time of the task. When unbocking, you should be always
    129   sure that the ratio between remaining computation time and remaining
    130   deadline is not higher that the utilization you have agreed with the
    131   scheduler.
     123- In the current implementation it is possible to attach only a single task to
     124  each server.
     125
     126- If you have a task attached to a server and you voluntatily block it in the
     127  beginning of its execution, its priority will be probably pulled to
     128  background upon unblock, thus not guaranteed deadline any more. This is
     129  because you are effectively raising computation time of the task. When
     130  unbocking, you should be always sure that the ratio between remaining
     131  computation time and remaining deadline is not higher that the utilization
     132  you have agreed with the scheduler.
    132133
    133134Operations
     
    137138-------------------
    138139
    139 The directive ``rtems_cbs_create_server`` is used to create a new
    140 server that is characterized by ``rtems_cbs_parameters``. You also
    141 might want to register the ``rtems_cbs_budget_overrun`` callback
    142 routine. After this step tasks can be attached to the server. The directive``rtems_cbs_set_parameters`` can change the scheduling parameters
    143 to avoid destroying and creating a new server again.
     140The directive ``rtems_cbs_create_server`` is used to create a new server that
     141is characterized by ``rtems_cbs_parameters``. You also might want to register
     142the ``rtems_cbs_budget_overrun`` callback routine. After this step tasks can be
     143attached to the server. The directive ``rtems_cbs_set_parameters`` can change
     144the scheduling parameters to avoid destroying and creating a new server again.
    144145
    145146Attaching Task to a Server
    146147--------------------------
    147148
    148 If a task is attached to a server using ``rtems_cbs_attach_thread``,
    149 the task's computation time per period is limited by the server and
    150 the deadline (period) of task is equal to deadline of the server which
    151 means if you conclude a period using ``rate_monotonic_period``,
    152 the length of next period is always determined by the server's property.
    153 
    154 The task has a guaranteed bandwidth given by the server but should not
    155 exceed it, otherwise the priority is pulled to background until the
    156 start of next period and the ``rtems_cbs_budget_overrun`` callback
    157 function is invoked.
    158 
    159 When attaching a task to server, the preemptability flag of the task
    160 is raised, otherwise it would not be possible to control the execution
    161 of the task.
     149If a task is attached to a server using ``rtems_cbs_attach_thread``, the task's
     150computation time per period is limited by the server and the deadline (period)
     151of task is equal to deadline of the server which means if you conclude a period
     152using ``rate_monotonic_period``, the length of next period is always determined
     153by the server's property.
     154
     155The task has a guaranteed bandwidth given by the server but should not exceed
     156it, otherwise the priority is pulled to background until the start of next
     157period and the ``rtems_cbs_budget_overrun`` callback function is invoked.
     158
     159When attaching a task to server, the preemptability flag of the task is raised,
     160otherwise it would not be possible to control the execution of the task.
    162161
    163162Detaching Task from a Server
    164163----------------------------
    165164
    166 The directive ``rtems_cbs_detach_thread`` is just an inverse
    167 operation to the previous one, the task continues its execution with
    168 the initial priority.
     165The directive ``rtems_cbs_detach_thread`` is just an inverse operation to the
     166previous one, the task continues its execution with the initial priority.
    169167
    170168Preemptability of the task is restored to the initial value.
     
    175173The following example presents a simple common use of the API.
    176174
    177 You can see the initialization and cleanup call here, if there are
    178 multiple tasks in the system, it is obvious that the initialization
    179 should be called before creating the task.
     175You can see the initialization and cleanup call here, if there are multiple
     176tasks in the system, it is obvious that the initialization should be called
     177before creating the task.
    180178
    181179Notice also that in this case we decided to register an overrun handler,
    182 instead of which there could be ``NULL``. This handler just prints
    183 a message to terminal, what else may be done here depends on a specific
    184 application.
    185 
    186 During the periodic execution, remaining budget should be watched
    187 to avoid overrun.
    188 .. code:: c
     180instead of which there could be ``NULL``. This handler just prints a message to
     181terminal, what else may be done here depends on a specific application.
     182
     183During the periodic execution, remaining budget should be watched to avoid
     184overrun.
     185
     186.. code-block:: c
    189187
    190188    void overrun_handler (
    191     rtems_cbs_server_id server_id
     189        rtems_cbs_server_id server_id
    192190    )
    193191    {
    194     printk( "Budget overrun, fixing the task\\n" );
    195     return;
     192        printk( "Budget overrun, fixing the task\\n" );
     193        return;
    196194    }
     195
    197196    rtems_task Tasks_Periodic(
    198     rtems_task_argument argument
     197        rtems_task_argument argument
    199198    )
    200199    {
    201     rtems_id          rmid;
    202     rtems_cbs_server_id server_id;
    203     rtems_cbs_parameters params;
    204     params.deadline = 10;
    205     params.budget = 4;
    206     rtems_cbs_initialize();
    207     rtems_cbs_create_server( &params, &overrun_handler, &server_id )
    208     rtems_cbs_attach_thread( server_id, SELF );
    209     rtems_rate_monotonic_create( argument, &rmid );
    210     while ( 1 ) {
    211     if (rtems_rate_monotonic_period(rmid, params.deadline)==RTEMS_TIMEOUT)
    212     break;
    213     /* Perform some periodic action \*/
    214     }
    215     rtems_rate_monotonic_delete( rmid );
    216     rtems_cbs_cleanup();
    217     exit( 1 );
     200        rtems_id             rmid;
     201        rtems_cbs_server_id  server_id;
     202        rtems_cbs_parameters params;
     203
     204        params.deadline = 10;
     205        params.budget = 4;
     206
     207        rtems_cbs_initialize();
     208        rtems_cbs_create_server( &params, &overrun_handler, &server_id )
     209        rtems_cbs_attach_thread( server_id, SELF );
     210        rtems_rate_monotonic_create( argument, &rmid );
     211
     212        while ( 1 ) {
     213            if (rtems_rate_monotonic_period(rmid, params.deadline) == RTEMS_TIMEOUT)
     214                break;
     215            /* Perform some periodic action \*/
     216        }
     217
     218        rtems_rate_monotonic_delete( rmid );
     219        rtems_cbs_cleanup();
     220        exit( 1 );
    218221    }
    219222
     
    221224==========
    222225
    223 This section details the Constant Bandwidth Server's directives.
    224 A subsection is dedicated to each of this manager's directives
    225 and describes the calling sequence, related constants, usage,
    226 and status codes.
     226This section details the Constant Bandwidth Server's directives.  A subsection
     227is dedicated to each of this manager's directives and describes the calling
     228sequence, related constants, usage, and status codes.
     229
     230.. _rtems_cbs_initialize:
    227231
    228232CBS_INITIALIZE - Initialize the CBS library
     
    234238.. index:: rtems_cbs_initialize
    235239
    236 .. code:: c
     240.. code-block:: c
    237241
    238242    int rtems_cbs_initialize( void );
     
    240244**DIRECTIVE STATUS CODES:**
    241245
    242 ``RTEMS_CBS_OK`` - successful initialization
    243 ``RTEMS_CBS_ERROR_NO_MEMORY`` - not enough memory for data
     246.. list-table::
     247 :class: rtems-table
     248
     249 * - ``RTEMS_CBS_OK``
     250   - successful initialization
     251 * - ``RTEMS_CBS_ERROR_NO_MEMORY``
     252   - not enough memory for data
    244253
    245254**DESCRIPTION:**
    246255
    247256This routine initializes the library in terms of allocating necessary memory
    248 for the servers. In case not enough memory is available in the system,``RTEMS_CBS_ERROR_NO_MEMORY`` is returned, otherwise``RTEMS_CBS_OK``.
    249 
    250 **NOTES:**
    251 
    252 Additional memory per each server is allocated upon invocation of``rtems_cbs_create_server``.
    253 
    254 Tasks in the system are not influenced, they still keep executing
    255 with their initial parameters.
     257for the servers. In case not enough memory is available in the system,
     258``RTEMS_CBS_ERROR_NO_MEMORY`` is returned, otherwise ``RTEMS_CBS_OK``.
     259
     260**NOTES:**
     261
     262Additional memory per each server is allocated upon invocation of
     263``rtems_cbs_create_server``.
     264
     265Tasks in the system are not influenced, they still keep executing with their
     266initial parameters.
     267
     268.. _rtems_cbs_cleanup:
    256269
    257270CBS_CLEANUP - Cleanup the CBS library
     
    263276.. index:: rtems_cbs_cleanup
    264277
    265 .. code:: c
     278.. code-block:: c
    266279
    267280    int rtems_cbs_cleanup( void );
     
    269282**DIRECTIVE STATUS CODES:**
    270283
    271 ``RTEMS_CBS_OK`` - always successful
    272 
    273 **DESCRIPTION:**
    274 
    275 This routine detaches all tasks from their servers, destroys all servers
    276 and returns memory back to the system.
     284.. list-table::
     285 :class: rtems-table
     286
     287 * - ``RTEMS_CBS_OK``
     288   - always successful
     289
     290**DESCRIPTION:**
     291
     292This routine detaches all tasks from their servers, destroys all servers and
     293returns memory back to the system.
    277294
    278295**NOTES:**
    279296
    280297All tasks continue executing with their initial priorities.
     298
     299.. _rtems_cbs_create_server:
    281300
    282301CBS_CREATE_SERVER - Create a new bandwidth server
     
    288307.. index:: rtems_cbs_create_server
    289308
    290 .. code:: c
     309.. code-block:: c
    291310
    292311    int rtems_cbs_create_server (
    293     rtems_cbs_parameters     \*params,
    294     rtems_cbs_budget_overrun  budget_overrun_callback,
    295     rtems_cbs_server_id      \*server_id
    296     );
    297 
    298 **DIRECTIVE STATUS CODES:**
    299 
    300 ``RTEMS_CBS_OK`` - successfully created
    301 ``RTEMS_CBS_ERROR_NO_MEMORY`` - not enough memory for data
    302 ``RTEMS_CBS_ERROR_FULL`` - maximum servers exceeded
    303 ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
    304 
    305 **DESCRIPTION:**
    306 
    307 This routine prepares an instance of a constant bandwidth server.
    308 The input parameter ``rtems_cbs_parameters`` specifies scheduling
    309 parameters of the server (period and budget). If these are not valid,``RTEMS_CBS_ERROR_INVALID_PARAMETER`` is returned.
    310 The ``budget_overrun_callback`` is an optional callback function, which is
    311 invoked in case the server's budget within one period is exceeded.
    312 Output parameter ``server_id`` becomes an id of the newly created server.
    313 If there is not enough memory, the ``RTEMS_CBS_ERROR_NO_MEMORY``
    314 is returned. If the maximum server count in the system is exceeded,``RTEMS_CBS_ERROR_FULL`` is returned.
     312        rtems_cbs_parameters     *params,
     313        rtems_cbs_budget_overrun  budget_overrun_callback,
     314        rtems_cbs_server_id      *server_id
     315    );
     316
     317**DIRECTIVE STATUS CODES:**
     318
     319.. list-table::
     320 :class: rtems-table
     321
     322 * - ``RTEMS_CBS_OK``
     323   - successfully created
     324 * - ``RTEMS_CBS_ERROR_NO_MEMORY``
     325   - not enough memory for data
     326 * - ``RTEMS_CBS_ERROR_FULL``
     327   - maximum servers exceeded
     328 * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
     329   - invalid input argument
     330
     331**DESCRIPTION:**
     332
     333This routine prepares an instance of a constant bandwidth server.  The input
     334parameter ``rtems_cbs_parameters`` specifies scheduling parameters of the
     335server (period and budget). If these are not valid,
     336``RTEMS_CBS_ERROR_INVALID_PARAMETER`` is returned.  The
     337``budget_overrun_callback`` is an optional callback function, which is invoked
     338in case the server's budget within one period is exceeded.  Output parameter
     339``server_id`` becomes an id of the newly created server.  If there is not
     340enough memory, the ``RTEMS_CBS_ERROR_NO_MEMORY`` is returned. If the maximum
     341server count in the system is exceeded, ``RTEMS_CBS_ERROR_FULL`` is returned.
    315342
    316343**NOTES:**
    317344
    318345No task execution is being influenced so far.
     346
     347.. _rtems_cbs_attach_thread:
    319348
    320349CBS_ATTACH_THREAD - Attach a thread to server
     
    326355.. index:: rtems_cbs_attach_thread
    327356
    328 .. code:: c
     357.. code-block:: c
    329358
    330359    int rtems_cbs_attach_thread (
    331     rtems_cbs_server_id server_id,
    332     rtems_id            task_id
    333     );
    334 
    335 **DIRECTIVE STATUS CODES:**
    336 
    337 ``RTEMS_CBS_OK`` - successfully attached
    338 ``RTEMS_CBS_ERROR_FULL`` - server maximum tasks exceeded
    339 ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
    340 ``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
    341 
    342 **DESCRIPTION:**
    343 
    344 Attaches a task (``task_id``) to a server (``server_id``).
    345 The server has to be previously created. Now, the task starts
    346 to be scheduled according to the server parameters and not
    347 using initial priority. This implementation allows only one task
    348 per server, if the user tries to bind another task to the same
     360        rtems_cbs_server_id server_id,
     361        rtems_id            task_id
     362    );
     363
     364**DIRECTIVE STATUS CODES:**
     365
     366.. list-table::
     367 :class: rtems-table
     368
     369 * - ``RTEMS_CBS_OK``
     370   - successfully attached
     371 * - ``RTEMS_CBS_ERROR_FULL``
     372   - server maximum tasks exceeded
     373 * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
     374   - invalid input argument
     375 * - ``RTEMS_CBS_ERROR_NOSERVER``
     376   - server is not valid
     377
     378**DESCRIPTION:**
     379
     380Attaches a task (``task_id``) to a server (``server_id``).  The server has to
     381be previously created. Now, the task starts to be scheduled according to the
     382server parameters and not using initial priority. This implementation allows
     383only one task per server, if the user tries to bind another task to the same
    349384server, ``RTEMS_CBS_ERROR_FULL`` is returned.
    350385
     
    352387
    353388Tasks attached to servers become preemptible.
     389
     390.. _rtems_cbs_detach_thread:
    354391
    355392CBS_DETACH_THREAD - Detach a thread from server
     
    361398.. index:: rtems_cbs_detach_thread
    362399
    363 .. code:: c
     400.. code-block:: c
    364401
    365402    int rtems_cbs_detach_thread (
    366     rtems_cbs_server_id server_id,
    367     rtems_id            task_id
    368     );
    369 
    370 **DIRECTIVE STATUS CODES:**
    371 
    372 ``RTEMS_CBS_OK`` - successfully detached
    373 ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
    374 ``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
    375 
    376 **DESCRIPTION:**
    377 
    378 This directive detaches a thread from server. The task continues its
    379 execution with initial priority.
     403        rtems_cbs_server_id server_id,
     404        rtems_id            task_id
     405    );
     406
     407**DIRECTIVE STATUS CODES:**
     408
     409.. list-table::
     410 :class: rtems-table
     411
     412 * - ``RTEMS_CBS_OK``
     413   - successfully detached
     414 * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
     415   - invalid input argument
     416 * - ``RTEMS_CBS_ERROR_NOSERVER``
     417   - server is not valid
     418
     419**DESCRIPTION:**
     420
     421This directive detaches a thread from server. The task continues its execution
     422with initial priority.
    380423
    381424**NOTES:**
    382425
    383426The server can be reused for any other task.
     427
     428.. _rtems_cbs_destroy_server:
    384429
    385430CBS_DESTROY_SERVER - Destroy a bandwidth server
     
    391436.. index:: rtems_cbs_destroy_server
    392437
    393 .. code:: c
     438.. code-block:: c
    394439
    395440    int rtems_cbs_destroy_server (
    396     rtems_cbs_server_id server_id
    397     );
    398 
    399 **DIRECTIVE STATUS CODES:**
    400 
    401 ``RTEMS_CBS_OK`` - successfully destroyed
    402 ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
    403 ``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
    404 
    405 **DESCRIPTION:**
    406 
    407 This directive destroys a server. If any task was attached to the server,
    408 the task is detached and continues its execution according to EDF rules
    409 with initial properties.
     441        rtems_cbs_server_id server_id
     442    );
     443
     444**DIRECTIVE STATUS CODES:**
     445
     446.. list-table::
     447 :class: rtems-table
     448
     449 * - ``RTEMS_CBS_OK``
     450   - successfully destroyed
     451 * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
     452   - invalid input argument
     453 * - ``RTEMS_CBS_ERROR_NOSERVER``
     454   - server is not valid
     455
     456**DESCRIPTION:**
     457
     458This directive destroys a server. If any task was attached to the server, the
     459task is detached and continues its execution according to EDF rules with
     460initial properties.
    410461
    411462**NOTES:**
    412463
    413464This again enables one more task to be created.
     465
     466.. _rtems_cbs_get_server_id:
    414467
    415468CBS_GET_SERVER_ID - Get an ID of a server
     
    421474.. index:: rtems_cbs_get_server_id
    422475
    423 .. code:: c
     476.. code-block:: c
    424477
    425478    int rtems_cbs_get_server_id (
    426     rtems_id             task_id,
    427     rtems_cbs_server_id \*server_id
    428     );
    429 
    430 **DIRECTIVE STATUS CODES:**
    431 
    432 ``RTEMS_CBS_OK`` - successful
    433 ``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
     479        rtems_id             task_id,
     480        rtems_cbs_server_id *server_id
     481    );
     482
     483**DIRECTIVE STATUS CODES:**
     484
     485.. list-table::
     486 :class: rtems-table
     487
     488 * - ``RTEMS_CBS_OK``
     489   - successful
     490 * - ``RTEMS_CBS_ERROR_NOSERVER``
     491   - server is not valid
    434492
    435493**DESCRIPTION:**
    436494
    437495This directive returns an id of server belonging to a given task.
     496
     497.. _rtems_cbs_get_parameters:
    438498
    439499CBS_GET_PARAMETERS - Get scheduling parameters of a server
     
    445505.. index:: rtems_cbs_get_parameters
    446506
    447 .. code:: c
     507.. code-block:: c
    448508
    449509    rtems_cbs_get_parameters (
    450     rtems_cbs_server_id   server_id,
    451     rtems_cbs_parameters \*params
    452     );
    453 
    454 **DIRECTIVE STATUS CODES:**
    455 
    456 ``RTEMS_CBS_OK`` - successful
    457 ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
    458 ``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
     510        rtems_cbs_server_id   server_id,
     511        rtems_cbs_parameters *params
     512    );
     513
     514**DIRECTIVE STATUS CODES:**
     515
     516.. list-table::
     517 :class: rtems-table
     518
     519 * - ``RTEMS_CBS_OK``
     520   - successful
     521 * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
     522   - invalid input argument
     523 * - ``RTEMS_CBS_ERROR_NOSERVER``
     524   - server is not valid
    459525
    460526**DESCRIPTION:**
     
    466532
    467533It makes no difference if any task is assigned or not.
     534
     535.. _rtems_cbs_set_parameters:
    468536
    469537CBS_SET_PARAMETERS - Set scheduling parameters
     
    475543.. index:: rtems_cbs_set_parameters
    476544
    477 .. code:: c
     545.. code-block:: c
    478546
    479547    int rtems_cbs_set_parameters (
    480     rtems_cbs_server_id   server_id,
    481     rtems_cbs_parameters \*params
    482     );
    483 
    484 **DIRECTIVE STATUS CODES:**
    485 
    486 ``RTEMS_CBS_OK`` - successful
    487 ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
    488 ``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
    489 
    490 **DESCRIPTION:**
    491 
    492 This directive sets new scheduling parameters to the server. This operation
    493 can be performed regardless of whether a task is assigned or not.
    494 If a task is assigned, the parameters become effective imediately, therefore it
    495 is recommended to apply the change between two subsequent periods.
     548        rtems_cbs_server_id   server_id,
     549        rtems_cbs_parameters *params
     550    );
     551
     552**DIRECTIVE STATUS CODES:**
     553
     554.. list-table::
     555 :class: rtems-table
     556
     557 * - ``RTEMS_CBS_OK``
     558   - successful
     559 * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
     560   - invalid input argument
     561 * - ``RTEMS_CBS_ERROR_NOSERVER``
     562   - server is not valid
     563
     564**DESCRIPTION:**
     565
     566This directive sets new scheduling parameters to the server. This operation can
     567be performed regardless of whether a task is assigned or not.  If a task is
     568assigned, the parameters become effective imediately, therefore it is
     569recommended to apply the change between two subsequent periods.
    496570
    497571**NOTES:**
    498572
    499573There is an upper limit on both period and budget equal to (2^31)-1 ticks.
     574
     575.. _rtems_cbs_get_execution_time:
    500576
    501577CBS_GET_EXECUTION_TIME - Get elapsed execution time
     
    507583.. index:: rtems_cbs_get_execution_time
    508584
    509 .. code:: c
     585.. code-block:: c
    510586
    511587    int rtems_cbs_get_execution_time (
    512     rtems_cbs_server_id    server_id,
    513     time_t                \*exec_time,
    514     time_t                \*abs_time
    515     );
    516 
    517 **DIRECTIVE STATUS CODES:**
    518 
    519 ``RTEMS_CBS_OK`` - successful
    520 ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
    521 ``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
    522 
    523 **DESCRIPTION:**
    524 
    525 This routine returns consumed execution time (``exec_time``) of a server
    526 during the current period.
     588        rtems_cbs_server_id    server_id,
     589        time_t                *exec_time,
     590        time_t                *abs_time
     591    );
     592
     593**DIRECTIVE STATUS CODES:**
     594
     595.. list-table::
     596 :class: rtems-table
     597
     598 * - ``RTEMS_CBS_OK``
     599   - successful
     600 * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
     601   - invalid input argument
     602 * - ``RTEMS_CBS_ERROR_NOSERVER``
     603   - server is not valid
     604
     605**DESCRIPTION:**
     606
     607This routine returns consumed execution time (``exec_time``) of a server during
     608the current period.
    527609
    528610**NOTES:**
    529611
    530612Absolute time (``abs_time``) not supported now.
     613
     614.. _rtems_cbs_get_remaining_budget:
    531615
    532616CBS_GET_REMAINING_BUDGET - Get remaining execution time
     
    538622.. index:: rtems_cbs_get_remaining_budget
    539623
    540 .. code:: c
     624.. code-block:: c
    541625
    542626    int rtems_cbs_get_remaining_budget (
    543     rtems_cbs_server_id  server_id,
    544     time_t              \*remaining_budget
    545     );
    546 
    547 **DIRECTIVE STATUS CODES:**
    548 
    549 ``RTEMS_CBS_OK`` - successful
    550 ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
    551 ``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
    552 
    553 **DESCRIPTION:**
    554 
    555 This directive returns remaining execution time of a given server for
    556 current period.
     627        rtems_cbs_server_id  server_id,
     628        time_t              *remaining_budget
     629    );
     630
     631**DIRECTIVE STATUS CODES:**
     632
     633.. list-table::
     634 :class: rtems-table
     635
     636 * - ``RTEMS_CBS_OK``
     637   - successful
     638 * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
     639   - invalid input argument
     640 * - ``RTEMS_CBS_ERROR_NOSERVER``
     641   - server is not valid
     642
     643**DESCRIPTION:**
     644
     645This directive returns remaining execution time of a given server for current
     646period.
    557647
    558648**NOTES:**
     
    560650If the execution time approaches zero, the assigned task should finish
    561651computations of the current period.
     652
     653.. _rtems_cbs_get_approved_budget:
    562654
    563655CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time
     
    569661.. index:: rtems_cbs_get_approved_budget
    570662
    571 .. code:: c
     663.. code-block:: c
    572664
    573665    int rtems_cbs_get_approved_budget (
    574     rtems_cbs_server_id  server_id,
    575     time_t              \*appr_budget
    576     );
    577 
    578 **DIRECTIVE STATUS CODES:**
    579 
    580 ``RTEMS_CBS_OK`` - successful
    581 ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument
    582 ``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid
     666        rtems_cbs_server_id  server_id,
     667        time_t              *appr_budget
     668    );
     669
     670**DIRECTIVE STATUS CODES:**
     671
     672.. list-table::
     673 :class: rtems-table
     674
     675 * - ``RTEMS_CBS_OK``
     676   - successful
     677 * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
     678   - invalid input argument
     679 * - ``RTEMS_CBS_ERROR_NOSERVER``
     680   - server is not valid
    583681
    584682**DESCRIPTION:**
    585683
    586684This directive returns server's approved budget for subsequent periods.
    587 
    588 .. COMMENT: COPYRIGHT (c) 1989-2011.
    589 
    590 .. COMMENT: On-Line Applications Research Corporation (OAR).
    591 
    592 .. COMMENT: All rights reserved.
    593 
  • c_user/cpu_usage_statistics.rst

    r1762611 r0d86b71  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15CPU Usage Statistics
    26####################
     
    59============
    610
    7 The CPU usage statistics manager is an RTEMS support
    8 component that provides a convenient way to manipulate
    9 the CPU usage information associated with each task
    10 The routines provided by the CPU usage statistics manager are:
     11The CPU usage statistics manager is an RTEMS support component that provides a
     12convenient way to manipulate the CPU usage information associated with each
     13task The routines provided by the CPU usage statistics manager are:
    1114
    12 - ``rtems_cpu_usage_report`` - Report CPU Usage Statistics
     15- rtems_cpu_usage_report_ - Report CPU Usage Statistics
    1316
    14 - ``rtems_cpu_usage_reset`` - Reset CPU Usage Statistics
     17- rtems_cpu_usage_reset_ - Reset CPU Usage Statistics
    1518
    1619Background
    1720==========
    1821
    19 When analyzing and debugging real-time applications, it is important
    20 to be able to know how much CPU time each task in the system consumes.
    21 This support component provides a mechanism to easily obtain this
    22 information with little burden placed on the target.
     22When analyzing and debugging real-time applications, it is important to be able
     23to know how much CPU time each task in the system consumes.  This support
     24component provides a mechanism to easily obtain this information with little
     25burden placed on the target.
    2326
    24 The raw data is gathered as part of performing a context switch.  RTEMS
    25 keeps track of how many clock ticks have occurred which the task being
    26 switched out has been executing.  If the task has been running less than
    27 1 clock tick, then for the purposes of the statistics, it is assumed to
    28 have executed 1 clock tick.  This results in some inaccuracy but the
    29 alternative is for the task to have appeared to execute 0 clock ticks.
     27The raw data is gathered as part of performing a context switch.  RTEMS keeps
     28track of how many clock ticks have occurred which the task being switched out
     29has been executing.  If the task has been running less than 1 clock tick, then
     30for the purposes of the statistics, it is assumed to have executed 1 clock
     31tick.  This results in some inaccuracy but the alternative is for the task to
     32have appeared to execute 0 clock ticks.
    3033
    31 RTEMS versions newer than the 4.7 release series, support the ability
    32 to obtain timestamps with nanosecond granularity if the BSP provides
    33 support.  It is a desirable enhancement to change the way the usage
    34 data is gathered to take advantage of this recently added capability.
    35 Please consider sponsoring the core RTEMS development team to add
    36 this capability.
     34RTEMS versions newer than the 4.7 release series, support the ability to obtain
     35timestamps with nanosecond granularity if the BSP provides support.  It is a
     36desirable enhancement to change the way the usage data is gathered to take
     37advantage of this recently added capability.  Please consider sponsoring the
     38core RTEMS development team to add this capability.
    3739
    3840Operations
     
    4244---------------------------
    4345
    44 The application may dynamically report the CPU usage for every
    45 task in the system by calling the``rtems_cpu_usage_report`` routine.
    46 This routine prints a table with the following information per task:
     46The application may dynamically report the CPU usage for every task in the
     47system by calling the ``rtems_cpu_usage_report`` routine.  This routine prints
     48a table with the following information per task:
    4749
    4850- task id
     
    5658The following is an example of the report generated:
    5759
     60.. code:: c
    5861
    59 +------------------------------------------------------------------------------+
    60 |CPU USAGE BY THREAD                                                           |
    61 +-----------+----------------------------------------+-------------------------+
    62 |ID         | NAME                                   | SECONDS       | PERCENT |
    63 +-----------+----------------------------------------+---------------+---------+
    64 |0x04010001 | IDLE                                   |             0 |   0.000 |
    65 +-----------+----------------------------------------+---------------+---------+
    66 |0x08010002 | TA1                                    |          1203 |   0.748 |
    67 +-----------+----------------------------------------+---------------+---------+
    68 |0x08010003 | TA2                                    |           203 |   0.126 |
    69 +-----------+----------------------------------------+---------------+---------+
    70 |0x08010004 | TA3                                    |           202 |   0.126 |
    71 +-----------+----------------------------------------+---------------+---------+
    72 |TICKS SINCE LAST SYSTEM RESET:                                           1600 |
    73 |TOTAL UNITS:                                                             1608 |
    74 +------------------------------------------------------------------------------+
     62 +------------------------------------------------------------------------------+
     63 |CPU USAGE BY THREAD                                                           |
     64 +-----------+----------------------------------------+-------------------------+
     65 |ID         | NAME                                   | SECONDS       | PERCENT |
     66 +-----------+----------------------------------------+---------------+---------+
     67 |0x04010001 | IDLE                                   |             0 |   0.000 |
     68 +-----------+----------------------------------------+---------------+---------+
     69 |0x08010002 | TA1                                    |          1203 |   0.748 |
     70 +-----------+----------------------------------------+---------------+---------+
     71 |0x08010003 | TA2                                    |           203 |   0.126 |
     72 +-----------+----------------------------------------+---------------+---------+
     73 |0x08010004 | TA3                                    |           202 |   0.126 |
     74 +-----------+----------------------------------------+---------------+---------+
     75 |TICKS SINCE LAST SYSTEM RESET:                                           1600 |
     76 |TOTAL UNITS:                                                             1608 |
     77 +------------------------------------------------------------------------------+
    7578
    76 Notice that the "TOTAL UNITS" is greater than the ticks per reset.
    77 This is an artifact of the way in which RTEMS keeps track of CPU
    78 usage.  When a task is context switched into the CPU, the number
    79 of clock ticks it has executed is incremented.  While the task
    80 is executing, this number is incremented on each clock tick.
    81 Otherwise, if a task begins and completes execution between
    82 successive clock ticks, there would be no way to tell that it
    83 executed at all.
     79Notice that the ``TOTAL UNITS`` is greater than the ticks per reset.  This is
     80an artifact of the way in which RTEMS keeps track of CPU usage.  When a task is
     81context switched into the CPU, the number of clock ticks it has executed is
     82incremented.  While the task is executing, this number is incremented on each
     83clock tick.  Otherwise, if a task begins and completes execution between
     84successive clock ticks, there would be no way to tell that it executed at all.
    8485
    85 Another thing to keep in mind when looking at idle time, is that
    86 many systems - especially during debug - have a task providing
    87 some type of debug interface.  It is usually fine to think of the
    88 total idle time as being the sum of the IDLE task and a debug
    89 task that will not be included in a production build of an application.
     86Another thing to keep in mind when looking at idle time, is that many systems -
     87especially during debug - have a task providing some type of debug interface.
     88It is usually fine to think of the total idle time as being the sum of the
     89``IDLE`` task and a debug task that will not be included in a production build
     90of an application.
    9091
    9192Reset CPU Usage Statistics
    9293--------------------------
    9394
    94 Invoking the ``rtems_cpu_usage_reset`` routine resets
    95 the CPU usage statistics for all tasks in the system.
     95Invoking the ``rtems_cpu_usage_reset`` routine resets the CPU usage statistics
     96for all tasks in the system.
    9697
    9798Directives
    9899==========
    99100
    100 This section details the CPU usage statistics manager's directives.
    101 A subsection is dedicated to each of this manager's directives
    102 and describes the calling sequence, related constants, usage,
    103 and status codes.
     101This section details the CPU usage statistics manager's directives.  A
     102subsection is dedicated to each of this manager's directives and describes the
     103calling sequence, related constants, usage, and status codes.
     104
     105.. _rtems_cpu_usage_report:
    104106
    105107cpu_usage_report - Report CPU Usage Statistics
     
    112114    void rtems_cpu_usage_report( void );
    113115
    114 **STATUS CODES: NONE**
     116**STATUS CODES:**
     117
     118NONE
    115119
    116120**DESCRIPTION:**
    117121
    118 This routine prints out a table detailing the CPU usage statistics for
    119 all tasks in the system.
     122This routine prints out a table detailing the CPU usage statistics for all
     123tasks in the system.
    120124
    121125**NOTES:**
    122126
    123127The table is printed using the ``printk`` routine.
     128
     129.. _rtems_cpu_usage_reset:
    124130
    125131cpu_usage_reset - Reset CPU Usage Statistics
     
    132138    void rtems_cpu_usage_reset( void );
    133139
    134 **STATUS CODES: NONE**
     140**STATUS CODES:**
     141
     142NONE
    135143
    136144**DESCRIPTION:**
    137145
    138 This routine re-initializes the CPU usage statistics for all tasks
    139 in the system to their initial state.  The initial state is that
    140 a task has not executed and thus has consumed no CPU time.
    141 default state which is when zero period executions have occurred.
     146This routine re-initializes the CPU usage statistics for all tasks in the
     147system to their initial state.  The initial state is that a task has not
     148executed and thus has consumed no CPU time.  default state which is when zero
     149period executions have occurred.
    142150
    143151**NOTES:**
    144152
    145153NONE
    146 
    147 .. COMMENT: COPYRIGHT (c) 1988-2008.
    148 
    149 .. COMMENT: On-Line Applications Research Corporation (OAR).
    150 
    151 .. COMMENT: All rights reserved.
    152 
  • c_user/directive_status_codes.rst

    r1762611 r0d86b71  
     1.. COMMENT: Copyright 2015 embedded brains GmbH
     2.. COMMENT: All rights reserved.
     3
    14Directive Status Codes
    25######################
     
    58============
    69
    7 *``RTEMS_SUCCESSFUL`` - successful completion*
     10The directive status code directives are:
    811
    9 *``RTEMS_TASK_EXITTED`` - returned from a task*
    10 
    11 *``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured*
    12 
    13 *``RTEMS_INVALID_NAME`` - invalid object name*
    14 
    15 *``RTEMS_INVALID_ID`` - invalid object id*
    16 
    17 *``RTEMS_TOO_MANY`` - too many*
    18 
    19 *``RTEMS_TIMEOUT`` - timed out waiting*
    20 
    21 *``RTEMS_OBJECT_WAS_DELETED`` - object was deleted while waiting*
    22 
    23 *``RTEMS_INVALID_SIZE`` - invalid specified size*
    24 
    25 *``RTEMS_INVALID_ADDRESS`` - invalid address specified*
    26 
    27 *``RTEMS_INVALID_NUMBER`` - number was invalid*
    28 
    29 *``RTEMS_NOT_DEFINED`` - item not initialized*
    30 
    31 *``RTEMS_RESOURCE_IN_USE`` - resources outstanding*
    32 
    33 *``RTEMS_UNSATISFIED`` - request not satisfied*
    34 
    35 *``RTEMS_INCORRECT_STATE`` - task is in wrong state*
    36 
    37 *``RTEMS_ALREADY_SUSPENDED`` - task already in state*
    38 
    39 *``RTEMS_ILLEGAL_ON_SELF`` - illegal for calling task*
    40 
    41 *``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - illegal for remote object*
    42 
    43 *``RTEMS_CALLED_FROM_ISR`` - invalid environment*
    44 
    45 *``RTEMS_INVALID_PRIORITY`` - invalid task priority*
    46 
    47 *``RTEMS_INVALID_CLOCK`` - invalid time buffer*
    48 
    49 *``RTEMS_INVALID_NODE`` - invalid node id*
    50 
    51 *``RTEMS_NOT_CONFIGURED`` - directive not configured*
    52 
    53 *``RTEMS_NOT_OWNER_OF_RESOURCE`` - not owner of resource*
    54 
    55 *``RTEMS_NOT_IMPLEMENTED`` - directive not implemented*
    56 
    57 *``RTEMS_INTERNAL_ERROR`` - RTEMS inconsistency detected*
    58 
    59 *``RTEMS_NO_MEMORY`` - could not get enough memory*
     12- rtems_status_text_ - Return the name for the status code
    6013
    6114Directives
    6215==========
     16
     17The directives are:
     18
     19.. list-table::
     20 :class: rtems-table
     21
     22 * - ``RTEMS_SUCCESSFUL``
     23   - successful completion
     24 * - ``RTEMS_TASK_EXITTED``
     25   - returned from a task
     26 * - ``RTEMS_MP_NOT_CONFIGURED``
     27   - multiprocessing not configured
     28 * - ``RTEMS_INVALID_NAME``
     29   - invalid object name
     30 * - ``RTEMS_INVALID_ID``
     31   - invalid object id
     32 * - ``RTEMS_TOO_MANY``
     33   - too many
     34 * - ``RTEMS_TIMEOUT``
     35   - timed out waiting
     36 * - ``RTEMS_OBJECT_WAS_DELETED``
     37   - object was deleted while waiting
     38 * - ``RTEMS_INVALID_SIZE``
     39   - invalid specified size
     40 * - ``RTEMS_INVALID_ADDRESS``
     41   - invalid address specified
     42 * - ``RTEMS_INVALID_NUMBER``
     43   - number was invalid
     44 * - ``RTEMS_NOT_DEFINED``
     45   - item not initialized
     46 * - ``RTEMS_RESOURCE_IN_USE``
     47   - resources outstanding
     48 * - ``RTEMS_UNSATISFIED``
     49   - request not satisfied
     50 * - ``RTEMS_INCORRECT_STATE``
     51   - task is in wrong state
     52 * - ``RTEMS_ALREADY_SUSPENDED``
     53   - task already in state
     54 * - ``RTEMS_ILLEGAL_ON_SELF``
     55   - illegal for calling task
     56 * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
     57   - illegal for remote object
     58 * - ``RTEMS_CALLED_FROM_ISR``
     59   - invalid environment
     60 * - ``RTEMS_INVALID_PRIORITY``
     61   - invalid task priority
     62 * - ``RTEMS_INVALID_CLOCK``
     63   - invalid time buffer
     64 * - ``RTEMS_INVALID_NODE``
     65   - invalid node id
     66 * - ``RTEMS_NOT_CONFIGURED``
     67   - directive not configured
     68 * - ``RTEMS_NOT_OWNER_OF_RESOURCE``
     69   - not owner of resource
     70 * - ``RTEMS_NOT_IMPLEMENTED``
     71   - directive not implemented
     72 * - ``RTEMS_INTERNAL_ERROR``
     73   - RTEMS inconsistency detected
     74 * - ``RTEMS_NO_MEMORY``
     75   - could not get enough memory
     76
     77.. _rtems_status_text:
    6378
    6479STATUS_TEXT - Returns the enumeration name for a status code
     
    6984.. index:: rtems_status_text
    7085
    71 .. code:: c
     86.. code-block:: c
    7287
    73     const char \*rtems_status_text(
    74     rtems_status_code code
     88    const char *rtems_status_text(
     89        rtems_status_code code
    7590    );
    7691
     
    8297
    8398Returns the enumeration name for the specified status code.
    84 
    85 .. COMMENT: Copyright 2015 embedded brains GmbH
    86 
    87 .. COMMENT: All rights reserved.
    88 
  • c_user/example_application.rst

    r1762611 r0d86b71  
     1.. COMMENT: COPYRIGHT (c) 1989-2011.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Example Application
    26###################
    37
    4 .. code:: c
     8.. code-block:: c
     9    :linenos:
    510
    611    /*
     
    914    *  Information using confdef.h and contains two tasks:
    1015    *  a user initialization task and a simple task.
    11     \*/
     16    */
     17
    1218    #include <rtems.h>
     19
    1320    rtems_task user_application(rtems_task_argument argument);
     21
    1422    rtems_task init_task(
    15     rtems_task_argument ignored
     23        rtems_task_argument ignored
    1624    )
    1725    {
    18     rtems_id          tid;
    19     rtems_status_code status;
    20     rtems_name        name;
    21     name = rtems_build_name( 'A', 'P', 'P', '1' )
    22     status = rtems_task_create(
    23     name, 1, RTEMS_MINIMUM_STACK_SIZE,
    24     RTEMS_NO_PREEMPT, RTEMS_FLOATING_POINT, &tid
    25     );
    26     if ( status != RTEMS_STATUS_SUCCESSFUL ) {
    27     printf( "rtems_task_create failed with status of %d.\\n", status );
    28     exit( 1 );
     26        rtems_id          tid;
     27        rtems_status_code status;
     28        rtems_name        name;
     29
     30        name = rtems_build_name( 'A', 'P', 'P', '1' )
     31
     32        status = rtems_task_create(
     33            name, 1, RTEMS_MINIMUM_STACK_SIZE,
     34            RTEMS_NO_PREEMPT, RTEMS_FLOATING_POINT, &tid
     35        );
     36        if ( status != RTEMS_STATUS_SUCCESSFUL ) {
     37            printf( "rtems_task_create failed with status of %d.\n", status );
     38            exit( 1 );
     39        }
     40
     41        status = rtems_task_start( tid, user_application, 0 );
     42        if ( status != RTEMS_STATUS_SUCCESSFUL ) {
     43            printf( "rtems_task_start failed with status of %d.\n", status );
     44            exit( 1 );
     45        }
     46
     47        status = rtems_task_delete( SELF );    /* should not return */
     48
     49        printf( "rtems_task_delete returned with status of %d.\n", status );
     50        exit( 1 );
    2951    }
    30     status = rtems_task_start( tid, user_application, 0 );
    31     if ( status != RTEMS_STATUS_SUCCESSFUL ) {
    32     printf( "rtems_task_start failed with status of %d.\\n", status );
    33     exit( 1 );
    34     }
    35     status = rtems_task_delete( SELF );    /* should not return \*/
    36     printf( "rtems_task_delete returned with status of %d.\\n", status );
    37     exit( 1 );
    38     }
     52
    3953    rtems_task user_application(rtems_task_argument argument)
    4054    {
    41     /* application specific initialization goes here \*/
    42     while ( 1 )  {              /* infinite loop \*/
    43     /*  APPLICATION CODE GOES HERE
    44     *
    45     *  This code will typically include at least one
    46     *  directive which causes the calling task to
    47     *  give up the processor.
    48     \*/
     55        /* application specific initialization goes here */
     56        while ( 1 )  {              /* infinite loop */
     57            /*  APPLICATION CODE GOES HERE
     58             *
     59             *  This code will typically include at least one
     60             *  directive which causes the calling task to
     61             *  give up the processor.
     62             */
     63        }
    4964    }
    50     }
    51     /* The Console Driver supplies Standard I/O. \*/
     65
     66    /* The Console Driver supplies Standard I/O. */
    5267    #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
    53     /* The Clock Driver supplies the clock tick. \*/
     68    /* The Clock Driver supplies the clock tick. */
    5469    #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
    5570    #define CONFIGURE_MAXIMUM_TASKS 2
     
    5873    #define CONFIGURE_INIT
    5974    #include <rtems/confdefs.h>
    60 
    61 .. COMMENT: COPYRIGHT (c) 1989-2011.
    62 
    63 .. COMMENT: On-Line Applications Research Corporation (OAR).
    64 
    65 .. COMMENT: All rights reserved.
    66 
  • c_user/linker_sets.rst

    r1762611 r0d86b71  
     1.. COMMENT: COPYRIGHT (c) 1989-2014.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Linker Sets
    26###########
     
    812
    913Linker sets are a flexible means to create arrays of items out of a set of
    10 object files at link-time.  For example its possible to define an item *I*
    11 of type *T* in object file *A* and an item *J* of type *T*
    12 in object file *B* to be a member of a linker set *S*.  The linker
    13 will then collect these two items *I* and *J* and place them in
    14 consecutive memory locations, so that they can be accessed like a normal array
    15 defined in one object file.  The size of a linker set is defined by its begin
    16 and end markers.  A linker set may be empty.  It should only contain items of
    17 the same type.
     14object files at link-time.  For example its possible to define an item *I* of
     15type *T* in object file *A* and an item *J* of type *T* in object file *B* to
     16be a member of a linker set *S*.  The linker will then collect these two items
     17*I* and *J* and place them in consecutive memory locations, so that they can be
     18accessed like a normal array defined in one object file.  The size of a linker
     19set is defined by its begin and end markers.  A linker set may be empty.  It
     20should only contain items of the same type.
    1821
    1922The following macros are provided to create, populate and use linker sets.
    2023
    21 - ``RTEMS_LINKER_SET_BEGIN`` - Designator of the linker set begin marker
    22 
    23 - ``RTEMS_LINKER_SET_END`` - Designator of the linker set end marker
    24 
    25 - ``RTEMS_LINKER_SET_SIZE`` - The linker set size in characters
    26 
    27 - ``RTEMS_LINKER_ROSET_DECLARE`` - Declares a read-only linker set
    28 
    29 - ``RTEMS_LINKER_ROSET`` - Defines a read-only linker set
    30 
    31 - ``RTEMS_LINKER_ROSET_ITEM_DECLARE`` - Declares a read-only linker set item
    32 
    33 - ``RTEMS_LINKER_ROSET_ITEM_REFERENCE`` - References a read-only linker set item
    34 
    35 - ``RTEMS_LINKER_ROSET_ITEM`` - Defines a read-only linker set item
    36 
    37 - ``RTEMS_LINKER_ROSET_ITEM_ORDERED`` - Defines an ordered read-only linker set item
    38 
    39 - ``RTEMS_LINKER_RWSET_DECLARE`` - Declares a read-write linker set
    40 
    41 - ``RTEMS_LINKER_RWSET`` - Defines a read-write linker set
    42 
    43 - ``RTEMS_LINKER_RWSET_ITEM_DECLARE`` - Declares a read-write linker set item
    44 
    45 - ``RTEMS_LINKER_RWSET_ITEM_REFERENCE`` - References a read-write linker set item
    46 
    47 - ``RTEMS_LINKER_RWSET_ITEM`` - Defines a read-write linker set item
    48 
    49 - ``RTEMS_LINKER_RWSET_ITEM_ORDERED`` - Defines an ordered read-write linker set item
     24- RTEMS_LINKER_SET_BEGIN_ - Designator of the linker set begin marker
     25
     26- RTEMS_LINKER_SET_END_ - Designator of the linker set end marker
     27
     28- RTEMS_LINKER_SET_SIZE_ - The linker set size in characters
     29
     30- RTEMS_LINKER_ROSET_DECLARE_ - Declares a read-only linker set
     31
     32- RTEMS_LINKER_ROSET_ - Defines a read-only linker set
     33
     34- RTEMS_LINKER_ROSET_ITEM_DECLARE_ - Declares a read-only linker set item
     35
     36- RTEMS_LINKER_ROSET_ITEM_REFERENCE_ - References a read-only linker set item
     37
     38- RTEMS_LINKER_ROSET_ITEM_ - Defines a read-only linker set item
     39
     40- RTEMS_LINKER_ROSET_ITEM_ORDERED_ - Defines an ordered read-only linker set item
     41
     42- RTEMS_LINKER_RWSET_DECLARE_ - Declares a read-write linker set
     43
     44- RTEMS_LINKER_RWSET_ - Defines a read-write linker set
     45
     46- RTEMS_LINKER_RWSET_ITEM_DECLARE_ - Declares a read-write linker set item
     47
     48- RTEMS_LINKER_RWSET_ITEM_REFERENCE_ - References a read-write linker set item
     49
     50- RTEMS_LINKER_RWSET_ITEM_ - Defines a read-write linker set item
     51
     52- RTEMS_LINKER_RWSET_ITEM_ORDERED_ - Defines an ordered read-write linker set item
    5053
    5154Background
     
    5760linker set consists of
    5861
    59 - dedicated input sections for the linker (e.g. ``.ctors`` and``.ctors.*`` in the case of global constructors),
     62- dedicated input sections for the linker (e.g. ``.ctors`` and ``.ctors.*`` in
     63  the case of global constructors),
    6064
    6165- a begin marker (e.g. provided by ``crtbegin.o``, and
     
    7074In the linker command file of the GNU linker we need the following output
    7175section descriptions.
    72 .. code:: c
    73 
    74     /* To be placed in a read-only memory region \*/
     76
     77.. code-block:: c
     78
     79    /* To be placed in a read-only memory region */
    7580    .rtemsroset : {
    76     KEEP (\*(SORT(.rtemsroset.*)))
     81        KEEP (\*(SORT(.rtemsroset.*)))
    7782    }
    78     /* To be placed in a read-write memory region \*/
     83    /* To be placed in a read-write memory region */
    7984    .rtemsrwset : {
    80     KEEP (\*(SORT(.rtemsrwset.*)))
     85        KEEP (\*(SORT(.rtemsrwset.*)))
    8186    }
    8287
    83 The ``KEEP()`` ensures that a garbage collection by the linker will not
    84 discard the content of this section.  This would normally be the case since the
    85 linker set items are not referenced directly.  The ``SORT()`` directive
    86 sorts the input sections lexicographically.  Please note the lexicographical
    87 order of the ``.begin``, ``.content`` and ``.end`` section name parts
    88 in the RTEMS linker sets macros which ensures that the position of the begin
    89 and end markers are right.
     88The ``KEEP()`` ensures that a garbage collection by the linker will not discard
     89the content of this section.  This would normally be the case since the linker
     90set items are not referenced directly.  The ``SORT()`` directive sorts the
     91input sections lexicographically.  Please note the lexicographical order of the
     92``.begin``, ``.content`` and ``.end`` section name parts in the RTEMS linker
     93sets macros which ensures that the position of the begin and end markers are
     94right.
    9095
    9196So, what is the benefit of using linker sets to initialize modules?  It can be
    9297used to initialize and include only those RTEMS managers and other components
    9398which are used by the application.  For example, in case an application uses
    94 message queues, it must call ``rtems_message_queue_create()``.  In the
    95 module implementing this function, we can place a linker set item and register
    96 the message queue handler constructor.  Otherwise, in case the application does
    97 not use message queues, there will be no reference to the``rtems_message_queue_create()`` function and the constructor is not
     99message queues, it must call ``rtems_message_queue_create()``.  In the module
     100implementing this function, we can place a linker set item and register the
     101message queue handler constructor.  Otherwise, in case the application does not
     102use message queues, there will be no reference to the
     103``rtems_message_queue_create()`` function and the constructor is not
    98104registered, thus nothing of the message queue handler will be in the final
    99105executable.
     
    104110==========
    105111
     112.. _RTEMS_LINKER_SET_BEGIN:
     113
    106114RTEMS_LINKER_SET_BEGIN - Designator of the linker set begin marker
    107115------------------------------------------------------------------
     
    111119.. index:: RTEMS_LINKER_SET_BEGIN
    112120
    113 .. code:: c
    114 
    115     volatile type \*begin = RTEMS_LINKER_SET_BEGIN( set );
     121.. code-block:: c
     122
     123    volatile type *begin = RTEMS_LINKER_SET_BEGIN( set );
    116124
    117125**DESCRIPTION:**
     
    122130linker set is empty, if and only if the begin and end markers have the same
    123131address.
     132
    124133The ``set`` parameter itself must be a valid C designator on which no macro
    125134expansion is performed.  It uniquely identifies the linker set.
    126135
     136.. _RTEMS_LINKER_SET_END:
     137
    127138RTEMS_LINKER_SET_END - Designator of the linker set end marker
    128139--------------------------------------------------------------
     
    132143.. index:: RTEMS_LINKER_SET_END
    133144
    134 .. code:: c
    135 
    136     volatile type \*end = RTEMS_LINKER_SET_END( set );
     145.. code-block:: c
     146
     147    volatile type *end = RTEMS_LINKER_SET_END( set );
    137148
    138149**DESCRIPTION:**
    139150
    140151This macro generates the designator of the end marker of the linker set
    141 identified by ``set``.  The item at the end marker address is not a member
    142 of the linker set.  The ``set`` parameter itself must be a valid C designator on which no macro
    143 expansion is performed.  It uniquely identifies the linker set.
     152identified by ``set``.  The item at the end marker address is not a member of
     153the linker set.  The ``set`` parameter itself must be a valid C designator on
     154which no macro expansion is performed.  It uniquely identifies the linker set.
     155
     156.. _RTEMS_LINKER_SET_SIZE:
    144157
    145158RTEMS_LINKER_SET_SIZE - The linker set size in characters
     
    150163.. index:: RTEMS_LINKER_SET_SIZE
    151164
    152 .. code:: c
     165.. code-block:: c
    153166
    154167    size_t size = RTEMS_LINKER_SET_SIZE( set );
     
    157170
    158171This macro returns the size of the linker set identified by ``set`` in
    159 characters.  The ``set`` parameter itself must be a valid C designator on which no macro
    160 expansion is performed.  It uniquely identifies the linker set.
     172characters.  The ``set`` parameter itself must be a valid C designator on which
     173no macro expansion is performed.  It uniquely identifies the linker set.
     174
     175.. _RTEMS_LINKER_ROSET_DECLARE:
    161176
    162177RTEMS_LINKER_ROSET_DECLARE - Declares a read-only linker set
     
    167182.. index:: RTEMS_LINKER_ROSET_DECLARE
    168183
    169 .. code:: c
     184.. code-block:: c
    170185
    171186    RTEMS_LINKER_ROSET_DECLARE( set, type );
     
    174189
    175190This macro generates declarations for the begin and end markers of a read-only
    176 linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    177 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    178 must be the same for all macro invocations of a particular linker set.
     191linker set identified by ``set``.  The ``set`` parameter itself must be a valid
     192C designator on which no macro expansion is performed.  It uniquely identifies
     193the linker set. The ``type`` parameter defines the type of the linker set
     194items.  The type must be the same for all macro invocations of a particular
     195linker set.
     196
     197.. _RTEMS_LINKER_ROSET:
    179198
    180199RTEMS_LINKER_ROSET - Defines a read-only linker set
     
    185204.. index:: RTEMS_LINKER_ROSET
    186205
    187 .. code:: c
     206.. code-block:: c
    188207
    189208    RTEMS_LINKER_ROSET( set, type );
     
    192211
    193212This macro generates definitions for the begin and end markers of a read-only
    194 linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    195 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    196 must be the same for all macro invocations of a particular linker set.
     213linker set identified by ``set``.  The ``set`` parameter itself must be a valid
     214C designator on which no macro expansion is performed.  It uniquely identifies
     215the linker set. The ``type`` parameter defines the type of the linker set
     216items.  The type must be the same for all macro invocations of a particular
     217linker set.
     218
     219.. _RTEMS_LINKER_ROSET_ITEM_DECLARE:
    197220
    198221RTEMS_LINKER_ROSET_ITEM_DECLARE - Declares a read-only linker set item
     
    203226.. index:: RTEMS_LINKER_ROSET_ITEM_DECLARE
    204227
    205 .. code:: c
     228.. code-block:: c
    206229
    207230    RTEMS_LINKER_ROSET_ITEM_DECLARE( set, type, item );
     
    210233
    211234This macro generates a declaration of an item contained in the read-only linker
    212 set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    213 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    214 must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
    215 expansion is performed.  It uniquely identifies an item in the linker set.
     235set identified by ``set``.  The ``set`` parameter itself must be a valid C
     236designator on which no macro expansion is performed.  It uniquely identifies
     237the linker set. The ``type`` parameter defines the type of the linker set
     238items.  The type must be the same for all macro invocations of a particular
     239linker set. The ``item`` parameter itself must be a valid C designator on which
     240no macro expansion is performed.  It uniquely identifies an item in the linker
     241set.
     242
     243.. _RTEMS_LINKER_ROSET_ITEM_REFERENCE:
    216244
    217245RTEMS_LINKER_ROSET_ITEM_REFERENCE - References a read-only linker set item
     
    222250.. index:: RTEMS_LINKER_ROSET_ITEM_REFERENCE
    223251
    224 .. code:: c
     252.. code-block:: c
    225253
    226254    RTEMS_LINKER_ROSET_ITEM_REFERENCE( set, type, item );
     
    228256**DESCRIPTION:**
    229257
    230 This macro generates a reference to an item contained in the read-only linker set
    231 identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    232 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    233 must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
    234 expansion is performed.  It uniquely identifies an item in the linker set.
     258This macro generates a reference to an item contained in the read-only linker
     259set identified by ``set``.  The ``set`` parameter itself must be a valid C
     260designator on which no macro expansion is performed.  It uniquely identifies
     261the linker set. The ``type`` parameter defines the type of the linker set
     262items.  The type must be the same for all macro invocations of a particular
     263linker set. The ``item`` parameter itself must be a valid C designator on which
     264no macro expansion is performed.  It uniquely identifies an item in the linker
     265set.
     266
     267.. _RTEMS_LINKER_ROSET_ITEM:
    235268
    236269RTEMS_LINKER_ROSET_ITEM - Defines a read-only linker set item
     
    241274.. index:: RTEMS_LINKER_ROSET_ITEM
    242275
    243 .. code:: c
     276.. code-block:: c
    244277
    245278    RTEMS_LINKER_ROSET_ITEM( set, type, item );
     
    247280**DESCRIPTION:**
    248281
    249 This macro generates a definition of an item contained in the read-only linker set
    250 identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    251 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    252 must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
    253 expansion is performed.  It uniquely identifies an item in the linker set.
     282This macro generates a definition of an item contained in the read-only linker
     283set identified by ``set``.  The ``set`` parameter itself must be a valid C
     284designator on which no macro expansion is performed.  It uniquely identifies
     285the linker set. The ``type`` parameter defines the type of the linker set
     286items.  The type must be the same for all macro invocations of a particular
     287linker set. The ``item`` parameter itself must be a valid C designator on which
     288no macro expansion is performed.  It uniquely identifies an item in the linker
     289set.
     290
     291.. _RTEMS_LINKER_ROSET_ITEM_ORDERED:
    254292
    255293RTEMS_LINKER_ROSET_ITEM_ORDERED - Defines an ordered read-only linker set item
     
    260298.. index:: RTEMS_LINKER_ROSET_ITEM_ORDERED
    261299
    262 .. code:: c
     300.. code-block:: c
    263301
    264302    RTEMS_LINKER_ROSET_ITEM_ORDERED( set, type, item, order );
     
    267305
    268306This macro generates a definition of an ordered item contained in the read-only
    269 linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    270 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    271 must be the same for all macro invocations of a particular linker set.
    272 The ``item`` parameter itself must be a valid C designator on which no macro
    273 expansion is performed.  It uniquely identifies an item in the linker set. The ``order`` parameter must be a valid linker input section name part on
    274 which macro expansion is performed.  The items are lexicographically ordered
    275 according to the ``order`` parameter within a linker set.  Ordered items are
    276 placed before unordered items in the linker set.
     307linker set identified by ``set``.  The ``set`` parameter itself must be a valid
     308C designator on which no macro expansion is performed.  It uniquely identifies
     309the linker set. The ``type`` parameter defines the type of the linker set
     310items.  The type must be the same for all macro invocations of a particular
     311linker set.  The ``item`` parameter itself must be a valid C designator on
     312which no macro expansion is performed.  It uniquely identifies an item in the
     313linker set. The ``order`` parameter must be a valid linker input section name
     314part on which macro expansion is performed.  The items are lexicographically
     315ordered according to the ``order`` parameter within a linker set.  Ordered
     316items are placed before unordered items in the linker set.
    277317
    278318**NOTES:**
     
    281321following construct in macros defining items for a particular linker set (see
    282322enum in ``XYZ_ITEM()``).
    283 .. code:: c
     323
     324.. code-block:: c
    284325
    285326    #include <rtems/linkersets.h>
     327
    286328    typedef struct {
    287     int foo;
     329        int foo;
    288330    } xyz_item;
    289     /* The XYZ-order defines \*/
     331
     332    /* The XYZ-order defines */
    290333    #define XYZ_ORDER_FIRST 0x00001000
    291334    #define XYZ_ORDER_AND_SO_ON 0x00002000
    292     /* Defines an ordered XYZ-item \*/
    293     #define XYZ_ITEM( item, order ) \\
    294     enum { xyz_##item = order - order }; \\
    295     RTEMS_LINKER_ROSET_ITEM_ORDERED( \\
    296     xyz, const xyz_item \*, item, order \\
    297     ) = { &item }
    298     /* Example item \*/
     335
     336    /* Defines an ordered XYZ-item */
     337    #define XYZ_ITEM( item, order ) \
     338                enum { xyz_##item = order - order }; \
     339                RTEMS_LINKER_ROSET_ITEM_ORDERED( \
     340                    xyz, const xyz_item *, item, order \
     341                ) = { &item }
     342
     343    /* Example item */
    299344    static const xyz_item some_item = { 123 };
    300345    XYZ_ITEM( some_item, XYZ_ORDER_FIRST );
    301346
     347.. _RTEMS_LINKER_RWSET_DECLARE:
     348
    302349RTEMS_LINKER_RWSET_DECLARE - Declares a read-write linker set
    303350-------------------------------------------------------------
     
    307354.. index:: RTEMS_LINKER_RWSET_DECLARE
    308355
    309 .. code:: c
     356.. code-block:: c
    310357
    311358    RTEMS_LINKER_RWSET_DECLARE( set, type );
     
    314361
    315362This macro generates declarations for the begin and end markers of a read-write
    316 linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    317 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    318 must be the same for all macro invocations of a particular linker set.
     363linker set identified by ``set``.  The ``set`` parameter itself must be a valid
     364C designator on which no macro expansion is performed.  It uniquely identifies
     365the linker set. The ``type`` parameter defines the type of the linker set
     366items.  The type must be the same for all macro invocations of a particular
     367linker set.
     368
     369.. _RTEMS_LINKER_RWSET:
    319370
    320371RTEMS_LINKER_RWSET - Defines a read-write linker set
     
    325376.. index:: RTEMS_LINKER_RWSET
    326377
    327 .. code:: c
     378.. code-block:: c
    328379
    329380    RTEMS_LINKER_RWSET( set, type );
     
    332383
    333384This macro generates definitions for the begin and end markers of a read-write
    334 linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    335 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    336 must be the same for all macro invocations of a particular linker set.
     385linker set identified by ``set``.  The ``set`` parameter itself must be a valid
     386C designator on which no macro expansion is performed.  It uniquely identifies
     387the linker set. The ``type`` parameter defines the type of the linker set
     388items.  The type must be the same for all macro invocations of a particular
     389linker set.
     390
     391.. _RTEMS_LINKER_RWSET_ITEM_DECLARE:
    337392
    338393RTEMS_LINKER_RWSET_ITEM_DECLARE - Declares a read-write linker set item
     
    343398.. index:: RTEMS_LINKER_RWSET_ITEM_DECLARE
    344399
    345 .. code:: c
     400.. code-block:: c
    346401
    347402    RTEMS_LINKER_RWSET_ITEM_DECLARE( set, type, item );
     
    349404**DESCRIPTION:**
    350405
    351 This macro generates a declaration of an item contained in the read-write linker
    352 set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    353 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    354 must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
    355 expansion is performed.  It uniquely identifies an item in the linker set.
     406This macro generates a declaration of an item contained in the read-write
     407linker set identified by ``set``.  The ``set`` parameter itself must be a valid
     408C designator on which no macro expansion is performed.  It uniquely identifies
     409the linker set. The ``type`` parameter defines the type of the linker set
     410items.  The type must be the same for all macro invocations of a particular
     411linker set. The ``item`` parameter itself must be a valid C designator on which
     412no macro expansion is performed.  It uniquely identifies an item in the linker
     413set.
     414
     415.. _RTEMS_LINKER_RWSET_ITEM_REFERENCE:
    356416
    357417RTEMS_LINKER_RWSET_ITEM_REFERENCE - References a read-write linker set item
     
    362422.. index:: RTEMS_LINKER_RWSET_ITEM_REFERENCE
    363423
    364 .. code:: c
     424.. code-block:: c
    365425
    366426    RTEMS_LINKER_RWSET_ITEM_REFERENCE( set, type, item );
     
    368428**DESCRIPTION:**
    369429
    370 This macro generates a reference to an item contained in the read-write linker set
    371 identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    372 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    373 must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
    374 expansion is performed.  It uniquely identifies an item in the linker set.
     430This macro generates a reference to an item contained in the read-write linker
     431set identified by ``set``.  The ``set`` parameter itself must be a valid C
     432designator on which no macro expansion is performed.  It uniquely identifies
     433the linker set. The ``type`` parameter defines the type of the linker set
     434items.  The type must be the same for all macro invocations of a particular
     435linker set. The ``item`` parameter itself must be a valid C designator on which
     436no macro expansion is performed.  It uniquely identifies an item in the linker
     437set.
     438
     439.. _RTEMS_LINKER_RWSET_ITEM:
    375440
    376441RTEMS_LINKER_RWSET_ITEM - Defines a read-write linker set item
     
    381446.. index:: RTEMS_LINKER_RWSET_ITEM
    382447
    383 .. code:: c
     448.. code-block:: c
    384449
    385450    RTEMS_LINKER_RWSET_ITEM( set, type, item );
     
    387452**DESCRIPTION:**
    388453
    389 This macro generates a definition of an item contained in the read-write linker set
    390 identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    391 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    392 must be the same for all macro invocations of a particular linker set. The ``item`` parameter itself must be a valid C designator on which no macro
    393 expansion is performed.  It uniquely identifies an item in the linker set.
     454This macro generates a definition of an item contained in the read-write linker
     455set identified by ``set``.  The ``set`` parameter itself must be a valid C
     456designator on which no macro expansion is performed.  It uniquely identifies
     457the linker set. The ``type`` parameter defines the type of the linker set
     458items.  The type must be the same for all macro invocations of a particular
     459linker set. The ``item`` parameter itself must be a valid C designator on which
     460no macro expansion is performed.  It uniquely identifies an item in the linker
     461set.
     462
     463.. _RTEMS_LINKER_RWSET_ITEM_ORDERED:
    394464
    395465RTEMS_LINKER_RWSET_ITEM_ORDERED - Defines an ordered read-write linker set item
     
    400470.. index:: RTEMS_LINKER_RWSET_ITEM_ORDERED
    401471
    402 .. code:: c
     472.. code-block:: c
    403473
    404474    RTEMS_LINKER_RWSET_ITEM_ORDERED( set, type, item, order );
     
    406476**DESCRIPTION:**
    407477
    408 This macro generates a definition of an ordered item contained in the read-write
    409 linker set identified by ``set``.  The ``set`` parameter itself must be a valid C designator on which no macro
    410 expansion is performed.  It uniquely identifies the linker set. The ``type`` parameter defines the type of the linker set items.  The type
    411 must be the same for all macro invocations of a particular linker set.
    412 The ``item`` parameter itself must be a valid C designator on which no macro
    413 expansion is performed.  It uniquely identifies an item in the linker set. The ``order`` parameter must be a valid linker input section name part on
    414 which macro expansion is performed.  The items are lexicographically ordered
    415 according to the ``order`` parameter within a linker set.  Ordered items are
    416 placed before unordered items in the linker set.
     478This macro generates a definition of an ordered item contained in the
     479read-write linker set identified by ``set``.  The ``set`` parameter itself must
     480be a valid C designator on which no macro expansion is performed.  It uniquely
     481identifies the linker set. The ``type`` parameter defines the type of the
     482linker set items.  The type must be the same for all macro invocations of a
     483particular linker set.  The ``item`` parameter itself must be a valid C
     484designator on which no macro expansion is performed.  It uniquely identifies an
     485item in the linker set. The ``order`` parameter must be a valid linker input
     486section name part on which macro expansion is performed.  The items are
     487lexicographically ordered according to the ``order`` parameter within a linker
     488set.  Ordered items are placed before unordered items in the linker set.
    417489
    418490**NOTES:**
     
    421493following construct in macros defining items for a particular linker set (see
    422494enum in ``XYZ_ITEM()``).
    423 .. code:: c
     495
     496.. code-block:: c
    424497
    425498    #include <rtems/linkersets.h>
     499
    426500    typedef struct {
    427     int foo;
     501        int foo;
    428502    } xyz_item;
    429     /* The XYZ-order defines \*/
     503
     504    /* The XYZ-order defines */
    430505    #define XYZ_ORDER_FIRST 0x00001000
    431506    #define XYZ_ORDER_AND_SO_ON 0x00002000
    432     /* Defines an ordered XYZ-item \*/
    433     #define XYZ_ITEM( item, order ) \\
    434     enum { xyz_##item = order - order }; \\
    435     RTEMS_LINKER_RWSET_ITEM_ORDERED( \\
    436     xyz, const xyz_item \*, item, order \\
    437     ) = { &item }
    438     /* Example item \*/
     507
     508    /* Defines an ordered XYZ-item */
     509    #define XYZ_ITEM( item, order ) \
     510                enum { xyz_##item = order - order }; \
     511                RTEMS_LINKER_RWSET_ITEM_ORDERED( \
     512                    xyz, const xyz_item \*, item, order \
     513                ) = { &item }
     514    /* Example item */
    439515    static const xyz_item some_item = { 123 };
    440516    XYZ_ITEM( some_item, XYZ_ORDER_FIRST );
    441 
    442 .. COMMENT: COPYRIGHT (c) 1989-2014.
    443 
    444 .. COMMENT: On-Line Applications Research Corporation (OAR).
    445 
    446 .. COMMENT: All rights reserved.
    447 
  • c_user/object_services.rst

    r1762611 r0d86b71  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Object Services
    26###############
     
    711============
    812
    9 RTEMS provides a collection of services to assist in the
    10 management and usage of the objects created and utilized
    11 via other managers.  These services assist in the
    12 manipulation of RTEMS objects independent of the API used
    13 to create them.  The object related services provided by
    14 RTEMS are:
     13RTEMS provides a collection of services to assist in the management and usage
     14of the objects created and utilized via other managers.  These services assist
     15in the manipulation of RTEMS objects independent of the API used to create
     16them.  The object related services provided by RTEMS are:
    1517
    1618- build_id
    1719
    18 - ``rtems_build_name`` - build object name from characters
    19 
    20 - ``rtems_object_get_classic_name`` - lookup name from Id
    21 
    22 - ``rtems_object_get_name`` - obtain object name as string
    23 
    24 - ``rtems_object_set_name`` - set object name
    25 
    26 - ``rtems_object_id_get_api`` - obtain API from Id
    27 
    28 - ``rtems_object_id_get_class`` - obtain class from Id
    29 
    30 - ``rtems_object_id_get_node`` - obtain node from Id
    31 
    32 - ``rtems_object_id_get_index`` - obtain index from Id
    33 
    34 - ``rtems_build_id`` - build object id from components
    35 
    36 - ``rtems_object_id_api_minimum`` - obtain minimum API value
    37 
    38 - ``rtems_object_id_api_maximum`` - obtain maximum API value
    39 
    40 - ``rtems_object_id_api_minimum_class`` - obtain minimum class value
    41 
    42 - ``rtems_object_id_api_maximum_class`` - obtain maximum class value
    43 
    44 - ``rtems_object_get_api_name`` - obtain API name
    45 
    46 - ``rtems_object_get_api_class_name`` - obtain class name
    47 
    48 - ``rtems_object_get_class_information`` - obtain class information
     20- rtems_build_name_ - build object name from characters
     21
     22- rtems_object_get_classic_name_ - lookup name from Id
     23
     24- rtems_object_get_name_ - obtain object name as string
     25
     26- rtems_object_set_name_ - set object name
     27
     28- rtems_object_id_get_api_ - obtain API from Id
     29
     30- rtems_object_id_get_class_ - obtain class from Id
     31
     32- rtems_object_id_get_node_ - obtain node from Id
     33
     34- rtems_object_id_get_index_ - obtain index from Id
     35
     36- rtems_build_id_ - build object id from components
     37
     38- rtems_object_id_api_minimum_ - obtain minimum API value
     39
     40- rtems_object_id_api_maximum_ - obtain maximum API value
     41
     42- rtems_object_id_api_minimum_class_ - obtain minimum class value
     43
     44- rtems_object_id_api_maximum_class_ - obtain maximum class value
     45
     46- rtems_object_get_api_name_ - obtain API name
     47
     48- rtems_object_get_api_class_name_ - obtain class name
     49
     50- rtems_object_get_class_information_ - obtain class information
    4951
    5052Background
     
    5456----
    5557
    56 RTEMS implements multiple APIs including an Internal API,
    57 the Classic API, and the POSIX API.  These
    58 APIs share the common foundation of SuperCore objects and
    59 thus share object management code. This includes a common
    60 scheme for object Ids and for managing object names whether
    61 those names be in the thirty-two bit form used by the Classic
    62 API or C strings.
    63 
    64 The object Id contains a field indicating the API that
    65 an object instance is associated with.  This field
    66 holds a numerically small non-zero integer.
     58RTEMS implements multiple APIs including an Internal API, the Classic API, and
     59the POSIX API.  These APIs share the common foundation of SuperCore objects and
     60thus share object management code. This includes a common scheme for object Ids
     61and for managing object names whether those names be in the thirty-two bit form
     62used by the Classic API or C strings.
     63
     64The object Id contains a field indicating the API that an object instance is
     65associated with.  This field holds a numerically small non-zero integer.
    6766
    6867Object Classes
    6968--------------
    7069
    71 Each API consists of a collection of managers.  Each manager
    72 is responsible for instances of a particular object class.
    73 Classic API Tasks and POSIX Mutexes example classes.
    74 
    75 The object Id contains a field indicating the class that
    76 an object instance is associated with.  This field
    77 holds a numerically small non-zero integer.  In all APIs,
    78 a class value of one is reserved for tasks or threads.
     70Each API consists of a collection of managers.  Each manager is responsible for
     71instances of a particular object class.  Classic API Tasks and POSIX Mutexes
     72example classes.
     73
     74The object Id contains a field indicating the class that an object instance is
     75associated with.  This field holds a numerically small non-zero integer.  In
     76all APIs, a class value of one is reserved for tasks or threads.
    7977
    8078Object Names
    8179------------
    8280
    83 Every RTEMS object which has an Id may also have a
    84 name associated with it.  Depending on the API, names
    85 may be either thirty-two bit integers as in the Classic
    86 API or strings as in the POSIX API.
    87 
    88 Some objects have Ids but do not have a defined way to associate
    89 a name with them.  For example, POSIX threads have
    90 Ids but per POSIX do not have names. In RTEMS, objects
    91 not defined to have thirty-two bit names may have string
    92 names assigned to them via the ``rtems_object_set_name``
    93 service.  The original impetus in providing this service
    94 was so the normally anonymous POSIX threads could have
    95 a user defined name in CPU Usage Reports.
     81Every RTEMS object which has an Id may also have a name associated with it.
     82Depending on the API, names may be either thirty-two bit integers as in the
     83Classic API or strings as in the POSIX API.
     84
     85Some objects have Ids but do not have a defined way to associate a name with
     86them.  For example, POSIX threads have Ids but per POSIX do not have names. In
     87RTEMS, objects not defined to have thirty-two bit names may have string names
     88assigned to them via the ``rtems_object_set_name`` service.  The original
     89impetus in providing this service was so the normally anonymous POSIX threads
     90could have a user defined name in CPU Usage Reports.
    9691
    9792Operations
     
    10196----------------------------------------
    10297
    103 Services are provided to decompose an object Id into its
    104 subordinate components. The following services are used
    105 to do this:
     98Services are provided to decompose an object Id into its subordinate
     99components. The following services are used to do this:
    106100
    107101- ``rtems_object_id_get_api``
     
    113107- ``rtems_object_id_get_index``
    114108
    115 The following C language example illustrates the
    116 decomposition of an Id and printing the values.
     109The following C language example illustrates the decomposition of an Id and
     110printing the values.
     111
    117112.. code:: c
    118113
    119114    void printObjectId(rtems_id id)
    120115    {
    121     printf(
    122     "API=%d Class=%d Node=%d Index=%d\\n",
    123     rtems_object_id_get_api(id),
    124     rtems_object_id_get_class(id),
    125     rtems_object_id_get_node(id),
    126     rtems_object_id_get_index(id)
    127     );
     116        printf(
     117            "API=%d Class=%d Node=%d Index=%d\n",
     118            rtems_object_id_get_api(id),
     119            rtems_object_id_get_class(id),
     120            rtems_object_id_get_node(id),
     121            rtems_object_id_get_index(id)
     122        );
    128123    }
    129124
    130125This prints the components of the Ids as integers.
    131126
    132 It is also possible to construct an arbitrary Id using
    133 the ``rtems_build_id`` service.  The following
    134 C language example illustrates how to construct the
     127It is also possible to construct an arbitrary Id using the ``rtems_build_id``
     128service.  The following C language example illustrates how to construct the
    135129"next Id."
     130
    136131.. code:: c
    137132
    138133    rtems_id nextObjectId(rtems_id id)
    139134    {
    140     return rtems_build_id(
    141     rtems_object_id_get_api(id),
    142     rtems_object_id_get_class(id),
    143     rtems_object_id_get_node(id),
    144     rtems_object_id_get_index(id) + 1
    145     );
     135        return rtems_build_id(
     136                    rtems_object_id_get_api(id),
     137                    rtems_object_id_get_class(id),
     138                    rtems_object_id_get_node(id),
     139                    rtems_object_id_get_index(id) + 1
     140               );
    146141    }
    147142
     
    152147---------------------
    153148
    154 RTEMS also provides services to associate the API and Class
    155 portions of an Object Id with strings.  This allows the
    156 application developer to provide more information about
    157 an object in diagnostic messages.
    158 
    159 In the following C language example, an Id is decomposed into
    160 its constituent parts and "pretty-printed."
     149RTEMS also provides services to associate the API and Class portions of an
     150Object Id with strings.  This allows the application developer to provide more
     151information about an object in diagnostic messages.
     152
     153In the following C language example, an Id is decomposed into its constituent
     154parts and "pretty-printed."
     155
    161156.. code:: c
    162157
    163158    void prettyPrintObjectId(rtems_id id)
    164159    {
    165     int tmpAPI, tmpClass;
    166     tmpAPI   = rtems_object_id_get_api(id),
    167     tmpClass = rtems_object_id_get_class(id),
    168     printf(
    169     "API=%s Class=%s Node=%d Index=%d\\n",
    170     rtems_object_get_api_name(tmpAPI),
    171     rtems_object_get_api_class_name(tmpAPI, tmpClass),
    172     rtems_object_id_get_node(id),
    173     rtems_object_id_get_index(id)
    174     );
     160        int tmpAPI, tmpClass;
     161
     162        tmpAPI   = rtems_object_id_get_api(id),
     163        tmpClass = rtems_object_id_get_class(id),
     164
     165        printf(
     166            "API=%s Class=%s Node=%d Index=%d\n",
     167            rtems_object_get_api_name(tmpAPI),
     168            rtems_object_get_api_class_name(tmpAPI, tmpClass),
     169            rtems_object_id_get_node(id),
     170            rtems_object_id_get_index(id)
     171        );
    175172    }
    176173
    177174Directives
    178175==========
     176
     177.. _rtems_build_name:
    179178
    180179BUILD_NAME - Build object name from characters
     
    189188
    190189    rtems_name rtems_build_name(
    191     uint8_t c1,
    192     uint8_t c2,
    193     uint8_t c3,
    194     uint8_t c4
     190        uint8_t c1,
     191        uint8_t c2,
     192        uint8_t c3,
     193        uint8_t c4
    195194    );
    196195
     
    201200**DESCRIPTION:**
    202201
    203 This service takes the four characters provided as arguments
    204 and constructs a thirty-two bit object name with ``c1``
    205 in the most significant byte and ``c4`` in the least
    206 significant byte.
    207 
    208 **NOTES:**
    209 
    210 This directive is strictly local and does not impact task scheduling.
     202This service takes the four characters provided as arguments and constructs a
     203thirty-two bit object name with ``c1`` in the most significant byte and ``c4``
     204in the least significant byte.
     205
     206**NOTES:**
     207
     208This directive is strictly local and does not impact task scheduling.
     209
     210.. _rtems_object_get_classic_name:
    211211
    212212OBJECT_GET_CLASSIC_NAME - Lookup name from id
     
    217217**CALLING SEQUENCE:**
    218218
    219 .. index:: rtems_build_name
     219.. index:: rtems_object_get_classic_name
    220220
    221221.. code:: c
    222222
    223223    rtems_status_code rtems_object_get_classic_name(
    224     rtems_id      id,
    225     rtems_name   \*name
    226     );
    227 
    228 **DIRECTIVE STATUS CODES**
    229 
    230 ``RTEMS_SUCCESSFUL`` - name looked up successfully
    231 ``RTEMS_INVALID_ADDRESS`` - invalid name pointer
    232 ``RTEMS_INVALID_ID`` - invalid object id
    233 
    234 **DESCRIPTION:**
    235 
    236 This service looks up the name for the object ``id`` specified
    237 and, if found, places the result in ``*name``.
    238 
    239 **NOTES:**
    240 
    241 This directive is strictly local and does not impact task scheduling.
     224        rtems_id      id,
     225        rtems_name   *name
     226    );
     227
     228**DIRECTIVE STATUS CODES**
     229
     230.. list-table::
     231 :class: rtems-table
     232
     233 * - ``RTEMS_SUCCESSFUL``
     234   - name looked up successfully
     235 * - ``RTEMS_INVALID_ADDRESS``
     236   - invalid name pointer
     237 * - ``RTEMS_INVALID_ID``
     238   - invalid object id
     239
     240**DESCRIPTION:**
     241
     242This service looks up the name for the object ``id`` specified and, if found,
     243places the result in ``*name``.
     244
     245**NOTES:**
     246
     247This directive is strictly local and does not impact task scheduling.
     248
     249.. _rtems_object_get_name:
    242250
    243251OBJECT_GET_NAME - Obtain object name as string
     
    252260.. code:: c
    253261
    254     char \*rtems_object_get_name(
    255     rtems_id       id,
    256     size_t         length,
    257     char          \*name
    258     );
    259 
    260 **DIRECTIVE STATUS CODES**
    261 
    262 Returns a pointer to the name if successful or ``NULL``
    263 otherwise.
    264 
    265 **DESCRIPTION:**
    266 
    267 This service looks up the name of the object specified by``id`` and places it in the memory pointed to by ``name``.
    268 Every attempt is made to return name as a printable string even
    269 if the object has the Classic API thirty-two bit style name.
    270 
    271 **NOTES:**
    272 
    273 This directive is strictly local and does not impact task scheduling.
     262    char* rtems_object_get_name(
     263        rtems_id       id,
     264        size_t         length,
     265        char          *name
     266    );
     267
     268**DIRECTIVE STATUS CODES**
     269
     270Returns a pointer to the name if successful or ``NULL`` otherwise.
     271
     272**DESCRIPTION:**
     273
     274This service looks up the name of the object specified by ``id`` and places it
     275in the memory pointed to by ``name``.  Every attempt is made to return name as
     276a printable string even if the object has the Classic API thirty-two bit style
     277name.
     278
     279**NOTES:**
     280
     281This directive is strictly local and does not impact task scheduling.
     282
     283.. _rtems_object_set_name:
    274284
    275285OBJECT_SET_NAME - Set object name
     
    284294
    285295    rtems_status_code rtems_object_set_name(
    286     rtems_id       id,
    287     const char    \*name
    288     );
    289 
    290 **DIRECTIVE STATUS CODES**
    291 
    292 ``RTEMS_SUCCESSFUL`` - name looked up successfully
    293 ``RTEMS_INVALID_ADDRESS`` - invalid name pointer
    294 ``RTEMS_INVALID_ID`` - invalid object id
    295 
    296 **DESCRIPTION:**
    297 
    298 This service sets the name of ``id`` to that specified
    299 by the string located at ``name``.
    300 
    301 **NOTES:**
    302 
    303 This directive is strictly local and does not impact task scheduling.
    304 
    305 If the object specified by ``id`` is of a class that
    306 has a string name, this method will free the existing
    307 name to the RTEMS Workspace and allocate enough memory
     296        rtems_id       id,
     297        const char    *name
     298    );
     299
     300**DIRECTIVE STATUS CODES**
     301
     302.. list-table::
     303 :class: rtems-table
     304
     305 * - ``RTEMS_SUCCESSFUL``
     306   - name looked up successfully
     307 * - ``RTEMS_INVALID_ADDRESS``
     308   - invalid name pointer
     309 * - ``RTEMS_INVALID_ID``
     310   - invalid object id
     311
     312**DESCRIPTION:**
     313
     314This service sets the name of ``id`` to that specified by the string located at
     315``name``.
     316
     317**NOTES:**
     318
     319This directive is strictly local and does not impact task scheduling.
     320
     321If the object specified by ``id`` is of a class that has a string name, this
     322method will free the existing name to the RTEMS Workspace and allocate enough
     323memory from the RTEMS Workspace to make a copy of the string located at
     324``name``.
     325
     326If the object specified by ``id`` is of a class that has a thirty-two bit
     327integer style name, then the first four characters in ``*name`` will be used to
     328construct the name.  name to the RTEMS Workspace and allocate enough memory
    308329from the RTEMS Workspace to make a copy of the string
    309 located at ``name``.
    310 
    311 If the object specified by ``id`` is of a class that
    312 has a thirty-two bit integer style name, then the first
    313 four characters in ``*name`` will be used to construct
    314 the name.
    315 name to the RTEMS Workspace and allocate enough memory
    316 from the RTEMS Workspace to make a copy of the string
     330
     331.. _rtems_object_id_get_api:
    317332
    318333OBJECT_ID_GET_API - Obtain API from Id
     
    327342
    328343    int rtems_object_id_get_api(
    329     rtems_id id
     344        rtems_id id
    330345    );
    331346
     
    343358
    344359This directive does NOT validate the ``id`` provided.
     360
     361.. _rtems_object_id_get_class:
    345362
    346363OBJECT_ID_GET_CLASS - Obtain Class from Id
     
    355372
    356373    int rtems_object_id_get_class(
    357     rtems_id id
     374        rtems_id id
    358375    );
    359376
     
    371388
    372389This directive does NOT validate the ``id`` provided.
     390
     391.. _rtems_object_id_get_node:
    373392
    374393OBJECT_ID_GET_NODE - Obtain Node from Id
     
    383402
    384403    int rtems_object_id_get_node(
    385     rtems_id id
     404        rtems_id id
    386405    );
    387406
     
    399418
    400419This directive does NOT validate the ``id`` provided.
     420
     421.. _rtems_object_id_get_index:
    401422
    402423OBJECT_ID_GET_INDEX - Obtain Index from Id
     
    411432
    412433    int rtems_object_id_get_index(
    413     rtems_id id
     434        rtems_id id
    414435    );
    415436
     
    427448
    428449This directive does NOT validate the ``id`` provided.
     450
     451.. _rtems_build_id:
    429452
    430453BUILD_ID - Build Object Id From Components
     
    439462
    440463    rtems_id rtems_build_id(
    441     int the_api,
    442     int the_class,
    443     int the_node,
    444     int the_index
     464        int the_api,
     465        int the_class,
     466        int the_node,
     467        int the_index
    445468    );
    446469
     
    451474**DESCRIPTION:**
    452475
    453 This service constructs an object Id from the provided``the_api``, ``the_class``, ``the_node``, and ``the_index``.
    454 
    455 **NOTES:**
    456 
    457 This directive is strictly local and does not impact task scheduling.
    458 
    459 This directive does NOT validate the arguments provided
    460 or the Object id returned.
     476This service constructs an object Id from the provided ``the_api``,
     477``the_class``, ``the_node``, and ``the_index``.
     478
     479**NOTES:**
     480
     481This directive is strictly local and does not impact task scheduling.
     482
     483This directive does NOT validate the arguments provided or the Object id
     484returned.
     485
     486.. _rtems_object_id_api_minimum:
    461487
    462488OBJECT_ID_API_MINIMUM - Obtain Minimum API Value
     
    478504**DESCRIPTION:**
    479505
    480 This service returns the minimum valid for the API portion of
    481 an object Id.
    482 
    483 **NOTES:**
    484 
    485 This directive is strictly local and does not impact task scheduling.
     506This service returns the minimum valid for the API portion of an object Id.
     507
     508**NOTES:**
     509
     510This directive is strictly local and does not impact task scheduling.
     511
     512.. _rtems_object_id_api_maximum:
    486513
    487514OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value
     
    503530**DESCRIPTION:**
    504531
    505 This service returns the maximum valid for the API portion of
    506 an object Id.
    507 
    508 **NOTES:**
    509 
    510 This directive is strictly local and does not impact task scheduling.
     532This service returns the maximum valid for the API portion of an object Id.
     533
     534**NOTES:**
     535
     536This directive is strictly local and does not impact task scheduling.
     537
     538.. _rtems_object_api_minimum_class:
    511539
    512540OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value
     
    521549
    522550    int rtems_object_api_minimum_class(
    523     int api
     551        int api
    524552    );
    525553
     
    528556If ``api`` is not valid, -1 is returned.
    529557
    530 If successful, this service returns the minimum valid for the class
    531 portion of an object Id for the specified ``api``.
    532 
    533 **DESCRIPTION:**
    534 
    535 This service returns the minimum valid for the class portion of
     558If successful, this service returns the minimum valid for the class portion of
    536559an object Id for the specified ``api``.
    537560
    538 **NOTES:**
    539 
    540 This directive is strictly local and does not impact task scheduling.
     561**DESCRIPTION:**
     562
     563This service returns the minimum valid for the class portion of an object Id
     564for the specified ``api``.
     565
     566**NOTES:**
     567
     568This directive is strictly local and does not impact task scheduling.
     569
     570.. _rtems_object_api_maximum_class:
    541571
    542572OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value
     
    551581
    552582    int rtems_object_api_maximum_class(
    553     int api
     583        int api
    554584    );
    555585
     
    558588If ``api`` is not valid, -1 is returned.
    559589
    560 If successful, this service returns the maximum valid for the class
    561 portion of an object Id for the specified ``api``.
    562 
    563 **DESCRIPTION:**
    564 
    565 This service returns the maximum valid for the class portion of
     590If successful, this service returns the maximum valid for the class portion of
    566591an object Id for the specified ``api``.
    567592
    568 **NOTES:**
    569 
    570 This directive is strictly local and does not impact task scheduling.
     593**DESCRIPTION:**
     594
     595This service returns the maximum valid for the class portion of an object Id
     596for the specified ``api``.
     597
     598**NOTES:**
     599
     600This directive is strictly local and does not impact task scheduling.
     601
     602.. _rtems_object_get_api_name:
    571603
    572604OBJECT_GET_API_NAME - Obtain API Name
     
    580612.. code:: c
    581613
    582     const char \*rtems_object_get_api_name(
    583     int api
     614    const char* rtems_object_get_api_name(
     615        int api
    584616    );
    585617
     
    588620If ``api`` is not valid, the string ``"BAD API"`` is returned.
    589621
    590 If successful, this service returns a pointer to a string
    591 containing the name of the specified ``api``.
     622If successful, this service returns a pointer to a string containing the name
     623of the specified ``api``.
    592624
    593625**DESCRIPTION:**
     
    599631This directive is strictly local and does not impact task scheduling.
    600632
    601 The string returned is from constant space.  Do not modify
    602 or free it.
     633The string returned is from constant space.  Do not modify or free it.
     634
     635.. _rtems_object_get_api_class_name:
    603636
    604637OBJECT_GET_API_CLASS_NAME - Obtain Class Name
     
    612645.. code:: c
    613646
    614     const char \*rtems_object_get_api_class_name(
    615     int the_api,
    616     int the_class
     647    const char *rtems_object_get_api_class_name(
     648        int the_api,
     649        int the_class
    617650    );
    618651
     
    623656If ``the_class`` is not valid, the string ``"BAD CLASS"`` is returned.
    624657
    625 If successful, this service returns a pointer to a string
    626 containing the name of the specified ``the_api``/``the_class`` pair.
    627 
    628 **DESCRIPTION:**
    629 
    630 This service returns the name of the object class indicated by the
    631 specified ``the_api`` and ``the_class``.
    632 
    633 **NOTES:**
    634 
    635 This directive is strictly local and does not impact task scheduling.
    636 
    637 The string returned is from constant space.  Do not modify
    638 or free it.
     658If successful, this service returns a pointer to a string containing the name
     659of the specified ``the_api`` / ``the_class`` pair.
     660
     661**DESCRIPTION:**
     662
     663This service returns the name of the object class indicated by the specified
     664``the_api`` and ``the_class``.
     665
     666**NOTES:**
     667
     668This directive is strictly local and does not impact task scheduling.
     669
     670The string returned is from constant space.  Do not modify or free it.
    639671
    640672OBJECT_GET_CLASS_INFORMATION - Obtain Class Information
     
    649681
    650682    rtems_status_code rtems_object_get_class_information(
    651     int                                 the_api,
    652     int                                 the_class,
    653     rtems_object_api_class_information \*info
    654     );
    655 
    656 **DIRECTIVE STATUS CODES**
    657 
    658 ``RTEMS_SUCCESSFUL`` - information obtained successfully
    659 ``RTEMS_INVALID_ADDRESS`` - ``info`` is NULL
    660 ``RTEMS_INVALID_NUMBER`` - invalid ``api`` or ``the_class``
    661 
    662 If successful, the structure located at ``info`` will be filled
    663 in with information about the specified ``api``/``the_class`` pairing.
     683        int                                 the_api,
     684        int                                 the_class,
     685        rtems_object_api_class_information *info
     686    );
     687
     688**DIRECTIVE STATUS CODES**
     689
     690.. list-table::
     691 :class: rtems-table
     692
     693 * - ``RTEMS_SUCCESSFUL``
     694   - information obtained successfully
     695 * - ``RTEMS_INVALID_ADDRESS``
     696   - ``info`` is NULL
     697 * - ``RTEMS_INVALID_NUMBER``
     698   - invalid ``api`` or ``the_class``
     699
     700If successful, the structure located at ``info`` will be filled in with
     701information about the specified ``api`` / ``the_class`` pairing.
    664702
    665703**DESCRIPTION:**
    666704
    667705This service returns information about the object class indicated by the
    668 specified ``api`` and ``the_class``. This structure is defined as
    669 follows:
     706specified ``api`` and ``the_class``. This structure is defined as follows:
     707
    670708.. code:: c
    671709
    672710    typedef struct {
    673     rtems_id  minimum_id;
    674     rtems_id  maximum_id;
    675     int       maximum;
    676     bool      auto_extend;
    677     int       unallocated;
     711        rtems_id  minimum_id;
     712        rtems_id  maximum_id;
     713        int       maximum;
     714        bool      auto_extend;
     715        int       unallocated;
    678716    } rtems_object_api_class_information;
    679717
     
    681719
    682720This directive is strictly local and does not impact task scheduling.
    683 
    684 .. COMMENT: COPYRIGHT (c) 1988-2008.
    685 
    686 .. COMMENT: On-Line Applications Research Corporation (OAR).
    687 
    688 .. COMMENT: All rights reserved.
    689 
  • c_user/red_black_trees.rst

    r1762611 r0d86b71  
     1.. COMMENT: COPYRIGHT (c) 1988-2012.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Red-Black Trees
    26###############
     
    1115tree is needed, including dynamic priority thread queues and non-contiguous
    1216heap memory. The Red-Black Tree API provided by RTEMS is:
    13 
    14 - build_id
    1517
    1618- ``rtems_rtems_rbtree_node`` - Red-Black Tree node embedded in another struct
     
    8284-----
    8385
    84 A red-black tree is made up from nodes that orginate from a red-black tree control
    85 object. A node is of type ``rtems_rtems_rbtree_node``. The node
    86 is designed to be part of a user data structure. To obtain the encapsulating
    87 structure users can use the ``RTEMS_CONTAINER_OF`` macro.
    88 The node can be placed anywhere within the user's structure and the macro will
    89 calculate the structure's address from the node's address.
     86A red-black tree is made up from nodes that orginate from a red-black tree
     87control object. A node is of type ``rtems_rtems_rbtree_node``. The node is
     88designed to be part of a user data structure. To obtain the encapsulating
     89structure users can use the ``RTEMS_CONTAINER_OF`` macro.  The node can be
     90placed anywhere within the user's structure and the macro will calculate the
     91structure's address from the node's address.
    9092
    9193Controls
     
    9597provide the user with access to the nodes on the red-black tree.  The
    9698implementation does not require special checks for manipulating the root of the
    97 red-black tree. To accomplish this the``rtems_rtems_rbtree_control`` structure is treated as a``rtems_rtems_rbtree_node`` structure with a ``NULL`` parent
     99red-black tree. To accomplish this the ``rtems_rtems_rbtree_control`` structure
     100is treated as a ``rtems_rtems_rbtree_node`` structure with a ``NULL`` parent
    98101and left child pointing to the root.
    99102
     
    101104==========
    102105
    103 Examples for using the red-black trees
    104 can be found in the testsuites/sptests/sprbtree01/init.c file.
     106Examples for using the red-black trees can be found in the
     107``testsuites/sptests/sprbtree01/init.c`` file.
    105108
    106109Directives
     
    111114.. index:: rbtree doc
    112115
    113 Source documentation for the Red-Black Tree API can be found in the
    114 generated Doxygen output for cpukit/sapi.
    115 
    116 .. COMMENT: COPYRIGHT (c) 1988-2012.
    117 
    118 .. COMMENT: On-Line Applications Research Corporation (OAR).
    119 
    120 .. COMMENT: All rights reserved.
    121 
     116Source documentation for the Red-Black Tree API can be found in the generated
     117Doxygen output for ``cpukit/sapi``.
  • c_user/stack_bounds_checker.rst

    r1762611 r0d86b71  
     1.. COMMENT: COPYRIGHT (c) 1988-2008.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Stack Bounds Checker
    26####################
    37
     8.. index:: stack
     9
    410Introduction
    511============
    612
    7 The stack bounds checker is an RTEMS support component that determines
    8 if a task has overrun its run-time stack.  The routines provided
    9 by the stack bounds checker manager are:
    10 
    11 - ``rtems_stack_checker_is_blown`` - Has the Current Task Blown its Stack
    12 
    13 - ``rtems_stack_checker_report_usage`` - Report Task Stack Usage
     13The stack bounds checker is an RTEMS support component that determines if a
     14task has overrun its run-time stack.  The routines provided by the stack bounds
     15checker manager are:
     16
     17- rtems_stack_checker_is_blown_ - Has the Current Task Blown its Stack
     18
     19- rtems_stack_checker_report_usage_ - Report Task Stack Usage
    1420
    1521Background
     
    1925----------
    2026
    21 Each task in a system has a fixed size stack associated with it.  This
    22 stack is allocated when the task is created.  As the task executes, the
    23 stack is used to contain parameters, return addresses, saved registers,
    24 and local variables.  The amount of stack space required by a task
    25 is dependent on the exact set of routines used.  The peak stack usage
    26 reflects the worst case of subroutine pushing information on the stack.
    27 For example, if a subroutine allocates a local buffer of 1024 bytes, then
    28 this data must be accounted for in the stack of every task that invokes that
    29 routine.
     27Each task in a system has a fixed size stack associated with it.  This stack is
     28allocated when the task is created.  As the task executes, the stack is used to
     29contain parameters, return addresses, saved registers, and local variables.
     30The amount of stack space required by a task is dependent on the exact set of
     31routines used.  The peak stack usage reflects the worst case of subroutine
     32pushing information on the stack.  For example, if a subroutine allocates a
     33local buffer of 1024 bytes, then this data must be accounted for in the stack
     34of every task that invokes that routine.
    3035
    3136Recursive routines make calculating peak stack usage difficult, if not
    32 impossible.  Each call to the recursive routine consumes *n* bytes
    33 of stack space.  If the routine recursives 1000 times, then ``1000 * *n*`` bytes of stack space are required.
     37impossible.  Each call to the recursive routine consumes *n* bytes of stack
     38space.  If the routine recursives 1000 times, then ``1000 * n`` bytes of
     39stack space are required.
    3440
    3541Execution
    3642---------
    3743
    38 The stack bounds checker operates as a set of task extensions.  At
    39 task creation time, the task's stack is filled with a pattern to
    40 indicate the stack is unused.  As the task executes, it will overwrite
    41 this pattern in memory.  At each task switch, the stack bounds checker's
    42 task switch extension is executed.  This extension checks that:
    43 
    44 - the last ``n`` bytes of the task's stack have
    45   not been overwritten.  If this pattern has been damaged, it
    46   indicates that at some point since this task was context
    47   switch to the CPU, it has used too much stack space.
    48 
    49 - the current stack pointer of the task is not within
    50   the address range allocated for use as the task's stack.
    51 
    52 If either of these conditions is detected, then a blown stack
    53 error is reported using the ``printk`` routine.
     44The stack bounds checker operates as a set of task extensions.  At task
     45creation time, the task's stack is filled with a pattern to indicate the stack
     46is unused.  As the task executes, it will overwrite this pattern in memory.  At
     47each task switch, the stack bounds checker's task switch extension is executed.
     48This extension checks that:
     49
     50- the last ``n`` bytes of the task's stack have not been overwritten.  If this
     51  pattern has been damaged, it indicates that at some point since this task was
     52  context switch to the CPU, it has used too much stack space.
     53
     54- the current stack pointer of the task is not within the address range
     55  allocated for use as the task's stack.
     56
     57If either of these conditions is detected, then a blown stack error is reported
     58using the ``printk`` routine.
    5459
    5560The number of bytes checked for an overwrite is processor family dependent.
    5661The minimum stack frame per subroutine call varies widely between processor
    57 families.  On CISC families like the Motorola MC68xxx and Intel ix86, all
    58 that is needed is a return address.  On more complex RISC processors,
    59 the minimum stack frame per subroutine call may include space to save
    60 a significant number of registers.
    61 
    62 Another processor dependent feature that must be taken into account by
    63 the stack bounds checker is the direction that the stack grows.  On some
    64 processor families, the stack grows up or to higher addresses as the
    65 task executes.  On other families, it grows down to lower addresses.  The
    66 stack bounds checker implementation uses the stack description definitions
    67 provided by every RTEMS port to get for this information.
     62families.  On CISC families like the Motorola MC68xxx and Intel ix86, all that
     63is needed is a return address.  On more complex RISC processors, the minimum
     64stack frame per subroutine call may include space to save a significant number
     65of registers.
     66
     67Another processor dependent feature that must be taken into account by the
     68stack bounds checker is the direction that the stack grows.  On some processor
     69families, the stack grows up or to higher addresses as the task executes.  On
     70other families, it grows down to lower addresses.  The stack bounds checker
     71implementation uses the stack description definitions provided by every RTEMS
     72port to get for this information.
    6873
    6974Operations
     
    7378-------------------------------------
    7479
    75 The stack checker is initialized automatically when its task
    76 create extension runs for the first time.
    77 
    78 The application must include the stack bounds checker extension set
    79 in its set of Initial Extensions.  This set of extensions is
    80 defined as ``STACK_CHECKER_EXTENSION``.  If using ``<rtems/confdefs.h>``
    81 for Configuration Table generation, then all that is necessary is
    82 to define the macro ``CONFIGURE_STACK_CHECKER_ENABLED`` before including``<rtems/confdefs.h>`` as shown below:
     80The stack checker is initialized automatically when its task create extension
     81runs for the first time.
     82
     83The application must include the stack bounds checker extension set in its set
     84of Initial Extensions.  This set of extensions is defined as
     85``STACK_CHECKER_EXTENSION``.  If using ``<rtems/confdefs.h>`` for Configuration
     86Table generation, then all that is necessary is to define the macro
     87``CONFIGURE_STACK_CHECKER_ENABLED`` before including ``<rtems/confdefs.h>`` as
     88shown below:
     89
    8390.. code:: c
    8491
     
    9097-----------------------------
    9198
    92 The application may check whether the stack pointer of currently
    93 executing task is within proper bounds at any time by calling
    94 the ``rtems_stack_checker_is_blown`` method.  This
    95 method return ``FALSE`` if the task is operating within its
    96 stack bounds and has not damaged its pattern area.
     99The application may check whether the stack pointer of currently executing task
     100is within proper bounds at any time by calling the
     101``rtems_stack_checker_is_blown`` method.  This method return ``FALSE`` if the
     102task is operating within its stack bounds and has not damaged its pattern area.
    97103
    98104Reporting Task Stack Usage
    99105--------------------------
    100106
    101 The application may dynamically report the stack usage for every task
    102 in the system by calling the``rtems_stack_checker_report_usage`` routine.
    103 This routine prints a table with the peak usage and stack size of
    104 every task in the system.  The following is an example of the
    105 report generated:
     107The application may dynamically report the stack usage for every task in the
     108system by calling the ``rtems_stack_checker_report_usage`` routine.  This
     109routine prints a table with the peak usage and stack size of every task in the
     110system.  The following is an example of the report generated:
     111
    106112.. code:: c
    107113
     
    113119    0xffffffff  INTR  0x003ecfc0  0x003effbf      12160        128
    114120
    115 Notice the last time.  The task id is 0xffffffff and its name is "INTR".
     121Notice the last line.  The task id is ``0xffffffff`` and its name is ``INTR``.
    116122This is not actually a task, it is the interrupt stack.
    117123
     
    119125-------------------------------
    120126
    121 When the stack bounds checker determines that a stack overflow has occurred,
    122 it will attempt to print a message using ``printk`` identifying the
    123 task and then shut the system down.  If the stack overflow has caused
    124 corruption, then it is possible that the message cannot be printed.
     127When the stack bounds checker determines that a stack overflow has occurred, it
     128will attempt to print a message using ``printk`` identifying the task and then
     129shut the system down.  If the stack overflow has caused corruption, then it is
     130possible that the message cannot be printed.
    125131
    126132The following is an example of the output generated:
     133
    127134.. code:: c
    128135
     
    131138    Damaged pattern begins at 0x003e5758 and is 128 bytes long
    132139
    133 The above includes the task id and a pointer to the task control block as
    134 well as enough information so one can look at the task's stack and
    135 see what was happening.
     140The above includes the task id and a pointer to the task control block as well
     141as enough information so one can look at the task's stack and see what was
     142happening.
    136143
    137144Routines
    138145========
    139146
    140 This section details the stack bounds checker's routines.
    141 A subsection is dedicated to each of routines
    142 and describes the calling sequence, related constants, usage,
    143 and status codes.
     147This section details the stack bounds checker's routines.  A subsection is
     148dedicated to each of routines and describes the calling sequence, related
     149constants, usage, and status codes.
    144150
    145151.. COMMENT: rtems_stack_checker_is_blown
     152
     153.. _rtems_stack_checker_is_blown:
    146154
    147155STACK_CHECKER_IS_BLOWN - Has Current Task Blown Its Stack
     
    156164**STATUS CODES:**
    157165
    158 ``TRUE`` - Stack is operating within its stack limits
    159 ``FALSE`` - Current stack pointer is outside allocated area
     166.. list-table::
     167 :class: rtems-table
     168
     169 * - ``TRUE``
     170   - Stack is operating within its stack limits
     171 * - ``FALSE``
     172   - Current stack pointer is outside allocated area
    160173
    161174**DESCRIPTION:**
    162175
    163 This method is used to determine if the current stack pointer
    164 of the currently executing task is within bounds.
     176This method is used to determine if the current stack pointer of the currently
     177executing task is within bounds.
    165178
    166179**NOTES:**
    167180
    168 This method checks the current stack pointer against
    169 the high and low addresses of the stack memory allocated when
    170 the task was created and it looks for damage to the high water
    171 mark pattern for the worst case usage of the task being called.
     181This method checks the current stack pointer against the high and low addresses
     182of the stack memory allocated when the task was created and it looks for damage
     183to the high water mark pattern for the worst case usage of the task being
     184called.
     185
     186.. _rtems_stack_checker_report_usage:
    172187
    173188STACK_CHECKER_REPORT_USAGE - Report Task Stack Usage
     
    180195    void rtems_stack_checker_report_usage( void );
    181196
    182 **STATUS CODES: NONE**
     197**STATUS CODES:**
     198
     199NONE
    183200
    184201**DESCRIPTION:**
     
    190207
    191208NONE
    192 
    193 .. COMMENT: COPYRIGHT (c) 1988-2007.
    194 
    195 .. COMMENT: On-Line Applications Research Corporation (OAR).
    196 
    197 .. COMMENT: All rights reserved.
    198 
  • c_user/timespec_helpers.rst

    r1762611 r0d86b71  
     1.. COMMENT: COPYRIGHT (c) 2011.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Timespec Helpers
    26################
     
    1014The directives provided by the timespec helpers manager are:
    1115
    12 - ``rtems_timespec_set`` - Set timespec's value
    13 
    14 - ``rtems_timespec_zero`` - Zero timespec's value
    15 
    16 - ``rtems_timespec_is_valid`` - Check if timespec is valid
    17 
    18 - ``rtems_timespec_add_to`` - Add two timespecs
    19 
    20 - ``rtems_timespec_subtract`` - Subtract two timespecs
    21 
    22 - ``rtems_timespec_divide`` - Divide two timespecs
    23 
    24 - ``rtems_timespec_divide_by_integer`` - Divide timespec by integer
    25 
    26 - ``rtems_timespec_less_than`` - Less than operator
    27 
    28 - ``rtems_timespec_greater_than`` - Greater than operator
    29 
    30 - ``rtems_timespec_equal_to`` - Check if two timespecs are equal
    31 
    32 - ``rtems_timespec_get_seconds`` - Obtain seconds portion of timespec
    33 
    34 - ``rtems_timespec_get_nanoseconds`` - Obtain nanoseconds portion of timespec
    35 
    36 - ``rtems_timespec_to_ticks`` - Convert timespec to number of ticks
    37 
    38 - ``rtems_timespec_from_ticks`` - Convert ticks to timespec
     16- rtems_timespec_set_ - Set timespec's value
     17
     18- rtems_timespec_zero_ - Zero timespec's value
     19
     20- rtems_timespec_is_valid_ - Check if timespec is valid
     21
     22- rtems_timespec_add_to_ - Add two timespecs
     23
     24- rtems_timespec_subtract_ - Subtract two timespecs
     25
     26- rtems_timespec_divide_ - Divide two timespecs
     27
     28- rtems_timespec_divide_by_integer_ - Divide timespec by integer
     29
     30- rtems_timespec_less_than_ - Less than operator
     31
     32- rtems_timespec_greater_than_ - Greater than operator
     33
     34- rtems_timespec_equal_to_ - Check if two timespecs are equal
     35
     36- rtems_timespec_get_seconds_ - Obtain seconds portion of timespec
     37
     38- rtems_timespec_get_nanoseconds_ - Obtain nanoseconds portion of timespec
     39
     40- rtems_timespec_to_ticks_ - Convert timespec to number of ticks
     41
     42- rtems_timespec_from_ticks_ - Convert ticks to timespec
    3943
    4044Background
     
    4448------------------------
    4549
    46 Time can be stored in many ways. One of them is the ``struct timespec``
    47 format which is a structure that consists of the fields ``tv_sec``
    48 to represent seconds and ``tv_nsec`` to represent nanoseconds.  The``struct timeval`` structure is simular and consists of seconds (stored
    49 in ``tv_sec``) and microseconds (stored in ``tv_usec``). Either``struct timespec`` or ``struct timeval`` can be used to represent
    50 elapsed time, time of executing some operations, or time of day.
     50Time can be stored in many ways. One of them is the ``struct timespec`` format
     51which is a structure that consists of the fields ``tv_sec`` to represent
     52seconds and ``tv_nsec`` to represent nanoseconds.  The``struct timeval``
     53structure is simular and consists of seconds (stored in ``tv_sec``) and
     54microseconds (stored in ``tv_usec``). Either``struct timespec`` or ``struct
     55timeval`` can be used to represent elapsed time, time of executing some
     56operations, or time of day.
    5157
    5258Operations
     
    5662-----------------------------
    5763
    58 A user may write a specific time by passing the desired seconds and
    59 nanoseconds values and the destination ``struct timespec`` using the``rtems_timespec_set`` directive.
     64A user may write a specific time by passing the desired seconds and nanoseconds
     65values and the destination ``struct timespec`` using the ``rtems_timespec_set``
     66directive.
    6067
    6168The ``rtems_timespec_zero`` directive is used to zero the seconds
    6269and nanoseconds portions of a ``struct timespec`` instance.
    6370
    64 Users may obtain the seconds or nanoseconds portions of a ``struct
    65 timespec`` instance with the ``rtems_timespec_get_seconds`` or``rtems_timespec_get_nanoseconds`` methods, respectively.
     71Users may obtain the seconds or nanoseconds portions of a ``struct timespec``
     72instance with the ``rtems_timespec_get_seconds`` or
     73``rtems_timespec_get_nanoseconds`` methods, respectively.
    6674
    6775Timespec Math
    6876-------------
    6977
    70 A user can perform multiple operations on ``struct timespec``
    71 instances. The helpers in this manager assist in adding, subtracting, and
    72 performing divison on ``struct timespec`` instances.
    73 
    74 - Adding two ``struct timespec`` can be done using the``rtems_timespec_add_to`` directive. This directive is used mainly
    75   to calculate total amount of time consumed by multiple operations.
    76 
    77 - The ``rtems_timespec_subtract`` is used to subtract two``struct timespecs`` instances and determine the elapsed time between
    78   those two points in time.
    79 
    80 - The ``rtems_timespec_divide`` is used to use to divide one``struct timespec`` instance by another. This calculates the percentage
    81   with a precision to three decimal points.
    82 
    83 - The ``rtems_timespec_divide_by_integer`` is used to divide a``struct timespec`` instance by an integer. It is commonly used in
    84   benchmark calculations to dividing duration by the number of iterations
    85   performed.
     78A user can perform multiple operations on ``struct timespec`` instances. The
     79helpers in this manager assist in adding, subtracting, and performing divison
     80on ``struct timespec`` instances.
     81
     82- Adding two ``struct timespec`` can be done using the
     83  ``rtems_timespec_add_to`` directive. This directive is used mainly to
     84  calculate total amount of time consumed by multiple operations.
     85
     86- The ``rtems_timespec_subtract`` is used to subtract two ``struct timespecs``
     87  instances and determine the elapsed time between those two points in time.
     88
     89- The ``rtems_timespec_divide`` is used to use to divide one ``struct
     90  timespec`` instance by another. This calculates the percentage with a
     91  precision to three decimal points.
     92
     93- The ``rtems_timespec_divide_by_integer`` is used to divide a ``struct
     94  timespec`` instance by an integer. It is commonly used in benchmark
     95  calculations to dividing duration by the number of iterations performed.
    8696
    8797Comparing struct timespec Instances
    8898-----------------------------------
    8999
    90 A user can compare two ``struct timespec`` instances using the``rtems_timespec_less_than``, ``rtems_timespec_greater_than``
    91 or ``rtems_timespec_equal_to`` routines.
     100A user can compare two ``struct timespec`` instances using the
     101``rtems_timespec_less_than``, ``rtems_timespec_greater_than`` or
     102``rtems_timespec_equal_to`` routines.
    92103
    93104Conversions and Validity Check
    94105------------------------------
    95106
    96 Conversion to and from clock ticks may be performed by using the``rtems_timespec_to_ticks`` and ``rtems_timespec_from_ticks``
    97 directives.
    98 
    99 User can also check validity of timespec with``rtems_timespec_is_valid`` routine.
     107Conversion to and from clock ticks may be performed by using the
     108``rtems_timespec_to_ticks`` and ``rtems_timespec_from_ticks`` directives.
     109
     110User can also check validity of timespec with ``rtems_timespec_is_valid``
     111routine.
    100112
    101113Directives
    102114==========
    103115
    104 This section details the Timespec Helpers manager's directives.
    105 A subsection is dedicated to each of this manager's directives
    106 and describes the calling sequence, related constants, usage,
    107 and status codes.
     116This section details the Timespec Helpers manager's directives.  A subsection
     117is dedicated to each of this manager's directives and describes the calling
     118sequence, related constants, usage, and status codes.
     119
     120.. _rtems_timespec_set:
    108121
    109122TIMESPEC_SET - Set struct timespec Instance
    110123-------------------------------------------
    111 
    112 **CALLING SEQUENCE:**
    113 
    114 .. code:: c
     124.. index:: set struct timespec instance
     125
     126**CALLING SEQUENCE:**
     127
     128.. index:: rtems_timespec_set
     129
     130.. code-block:: c
    115131
    116132    void rtems_timespec_set(
    117     struct timespec \*time,
    118     time_t           seconds,
    119     uint32_t         nanoseconds
    120     );
    121 
    122 .. index:: rtems_timespec_set
    123 
    124 **STATUS CODES:**
    125 
    126 NONE
    127 
    128 **DESCRIPTION:**
    129 
    130 This directive sets the ``struct timespec`` ``time`` value to the
    131 desired ``seconds`` and ``nanoseconds`` values.
    132 
    133 **NOTES:**
    134 
    135 This method does NOT check if ``nanoseconds`` is less than the
    136 maximum number of nanoseconds in a second.
     133        struct timespec *time,
     134        time_t           seconds,
     135        uint32_t         nanoseconds
     136    );
     137
     138**STATUS CODES:**
     139
     140NONE
     141
     142**DESCRIPTION:**
     143
     144This directive sets the ``struct timespec`` *time* to the desired ``seconds``
     145and ``nanoseconds`` values.
     146
     147**NOTES:**
     148
     149This method does NOT check if ``nanoseconds`` is less than the maximum number
     150of nanoseconds in a second.
     151
     152.. _rtems_timespec_zero:
    137153
    138154TIMESPEC_ZERO - Zero struct timespec Instance
     
    141157**CALLING SEQUENCE:**
    142158
    143 .. code:: c
     159.. index:: rtems_timespec_zero
     160
     161.. code-block:: c
    144162
    145163    void rtems_timespec_zero(
    146     struct timespec \*time
    147     );
    148 
    149 .. index:: rtems_timespec_zero
    150 
    151 **STATUS CODES:**
    152 
    153 NONE
    154 
    155 **DESCRIPTION:**
    156 
    157 This routine sets the contents of the ``struct timespec`` instance``time`` to zero.
    158 
    159 **NOTES:**
    160 
    161 NONE
     164        struct timespec *time
     165    );
     166
     167**STATUS CODES:**
     168
     169NONE
     170
     171**DESCRIPTION:**
     172
     173This routine sets the contents of the ``struct timespec`` instance ``time`` to
     174zero.
     175
     176**NOTES:**
     177
     178NONE
     179
     180.. _rtems_timespec_is_valid:
    162181
    163182TIMESPEC_IS_VALID - Check validity of a struct timespec instance
     
    166185**CALLING SEQUENCE:**
    167186
    168 .. code:: c
     187.. index:: rtems_timespec_is_valid
     188
     189.. code-block:: c
    169190
    170191    bool rtems_timespec_is_valid(
    171     const struct timespec \*time
    172     );
    173 
    174 .. index:: rtems_timespec_is_valid
    175 
    176 **STATUS CODES:**
    177 
    178 This method returns ``true`` if the instance is valid, and ``false``
    179 otherwise.
    180 
    181 **DESCRIPTION:**
    182 
    183 This routine check validity of a ``struct timespec`` instance. It
    184 checks if the nanoseconds portion of the ``struct timespec`` instanceis
    185 in allowed range (less than the maximum number of nanoseconds per second).
    186 
    187 **NOTES:**
     192        const struct timespec *time
     193    );
     194
     195**STATUS CODES:**
     196
     197This method returns ``true`` if the instance is valid, and ``false`` otherwise.
     198
     199**DESCRIPTION:**
     200
     201This routine check validity of a ``struct timespec`` instance. It checks if the
     202nanoseconds portion of the ``struct timespec`` instanceis in allowed range
     203(less than the maximum number of nanoseconds per second).
     204
     205**NOTES:**
     206
     207.. _rtems_timespec_add_to:
    188208
    189209TIMESPEC_ADD_TO - Add Two struct timespec Instances
     
    192212**CALLING SEQUENCE:**
    193213
    194 .. code:: c
     214.. index:: rtems_timespec_add_to
     215
     216.. code-block:: c
    195217
    196218    uint32_t rtems_timespec_add_to(
    197     struct timespec       \*time,
    198     const struct timespec \*add
    199     );
    200 
    201 .. index:: rtems_timespec_add_to
     219        struct timespec       *time,
     220        const struct timespec *add
     221    );
    202222
    203223**STATUS CODES:**
     
    207227**DESCRIPTION:**
    208228
    209 This routine adds two ``struct timespec`` instances. The second argument is added to the first. The parameter ``time`` is the base time to which the ``add`` parameter is added.
    210 
    211 **NOTES:**
    212 
    213 NONE
     229This routine adds two ``struct timespec`` instances. The second argument is
     230added to the first. The parameter ``time`` is the base time to which the
     231``add`` parameter is added.
     232
     233**NOTES:**
     234
     235NONE
     236
     237.. _rtems_timespec_subtract:
    214238
    215239TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances
     
    218242**CALLING SEQUENCE:**
    219243
    220 .. code:: c
     244.. index:: rtems_timespec_subtract
     245
     246.. code-block:: c
    221247
    222248    void rtems_timespec_subtract(
    223     const struct timespec \*start,
    224     const struct timespec \*end,
    225     struct timespec       \*result
    226     );
    227 
    228 .. index:: rtems_timespec_subtract
    229 
    230 **STATUS CODES:**
    231 
    232 NONE
    233 
    234 **DESCRIPTION:**
    235 
    236 This routine subtracts ``start`` from ``end`` saves the difference
    237 in ``result``. The primary use of this directive is to calculate
    238 elapsed time.
    239 
    240 **NOTES:**
    241 
    242 It is possible to subtract when ``end`` is less than ``start``
    243 and it produce negative ``result``. When doing this you should be
    244 careful and remember that only the seconds portion of a ``struct
    245 timespec`` instance is signed, which means that nanoseconds portion is
    246 always increasing. Due to that when your timespec has seconds = -1 and
    247 nanoseconds=500,000,000 it means that result is -0.5 second, NOT the
    248 expected -1.5!
     249        const struct timespec *start,
     250        const struct timespec *end,
     251        struct timespec       *result
     252    );
     253
     254**STATUS CODES:**
     255
     256NONE
     257
     258**DESCRIPTION:**
     259
     260This routine subtracts ``start`` from ``end`` saves the difference in
     261``result``. The primary use of this directive is to calculate elapsed time.
     262
     263**NOTES:**
     264
     265It is possible to subtract when ``end`` is less than ``start`` and it produce
     266negative ``result``. When doing this you should be careful and remember that
     267only the seconds portion of a ``struct timespec`` instance is signed, which
     268means that nanoseconds portion is always increasing. Due to that when your
     269timespec has seconds = -1 and nanoseconds = 500,000,000 it means that result is
     270-0.5 second, NOT the expected -1.5!
     271
     272.. _rtems_timespec_divide:
    249273
    250274TIMESPEC_DIVIDE - Divide Two struct timespec Instances
     
    253277**CALLING SEQUENCE:**
    254278
    255 .. code:: c
     279.. index:: rtems_timespec_divide
     280
     281.. code-block:: c
    256282
    257283    void rtems_timespec_divide(
    258     const struct timespec \*lhs,
    259     const struct timespec \*rhs,
    260     uint32_t              \*ival_percentage,
    261     uint32_t              \*fval_percentage
    262     );
    263 
    264 .. index:: rtems_timespec_divide
    265 
    266 **STATUS CODES:**
    267 
    268 NONE
    269 
    270 **DESCRIPTION:**
    271 
    272 This routine divides the ``struct timespec`` instance ``lhs`` by
    273 the ``struct timespec`` instance ``rhs``. The result is returned
    274 in the ``ival_percentage`` and ``fval_percentage``, representing
    275 the integer and fractional results of the division respectively.
    276 
    277 The ``ival_percentage`` is integer value of calculated percentage and ``fval_percentage`` is fractional part of calculated percentage.
     284        const struct timespec *lhs,
     285        const struct timespec *rhs,
     286        uint32_t              *ival_percentage,
     287        uint32_t              *fval_percentage
     288    );
     289
     290**STATUS CODES:**
     291
     292NONE
     293
     294**DESCRIPTION:**
     295
     296This routine divides the ``struct timespec`` instance ``lhs`` by the ``struct
     297timespec`` instance ``rhs``. The result is returned in the ``ival_percentage``
     298and ``fval_percentage``, representing the integer and fractional results of the
     299division respectively.
     300
     301The ``ival_percentage`` is integer value of calculated percentage and
     302``fval_percentage`` is fractional part of calculated percentage.
    278303
    279304**NOTES:**
     
    281306The intended use is calculating percentges to three decimal points.
    282307
    283 When dividing by zero, this routine return both ``ival_percentage``
    284 and ``fval_percentage`` equal zero.
     308When dividing by zero, this routine return both ``ival_percentage`` and
     309``fval_percentage`` equal zero.
    285310
    286311The division is performed using exclusively integer operations.
     312
     313.. _rtems_timespec_divide_by_integer:
    287314
    288315TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer
     
    291318**CALLING SEQUENCE:**
    292319
    293 .. code:: c
     320.. index:: rtems_timespec_divide_by_integer
     321
     322.. code-block:: c
    294323
    295324    int rtems_timespec_divide_by_integer(
    296     const struct timespec \*time,
    297     uint32_t               iterations,
    298     struct timespec       \*result
    299     );
    300 
    301 .. index:: rtems_timespec_divide_by_integer
    302 
    303 **STATUS CODES:**
    304 
    305 NONE
    306 
    307 **DESCRIPTION:**
    308 
    309 This routine divides the ``struct timespec`` instance ``time`` by the integer value ``iterations``.
    310 The result is saved in ``result``.
    311 
    312 **NOTES:**
    313 
    314 The expected use is to assist in benchmark calculations where you
    315 typically divide a duration (``time``) by a number of iterations what
    316 gives average time.
     325        const struct timespec *time,
     326        uint32_t               iterations,
     327        struct timespec       *result
     328    );
     329
     330**STATUS CODES:**
     331
     332NONE
     333
     334**DESCRIPTION:**
     335
     336This routine divides the ``struct timespec`` instance ``time`` by the integer
     337value ``iterations``.  The result is saved in ``result``.
     338
     339**NOTES:**
     340
     341The expected use is to assist in benchmark calculations where you typically
     342divide a duration (``time``) by a number of iterations what gives average time.
     343
     344.. _rtems_timespec_less_than:
    317345
    318346TIMESPEC_LESS_THAN - Less than operator
     
    321349**CALLING SEQUENCE:**
    322350
    323 .. code:: c
     351.. index:: rtems_timespec_less_than
     352
     353.. code-block:: c
    324354
    325355    bool rtems_timespec_less_than(
    326     const struct timespec \*lhs,
    327     const struct timespec \*rhs
    328     );
    329 
    330 .. index:: rtems_timespec_less_than
    331 
    332 **STATUS CODES:**
    333 
    334 This method returns ``struct true`` if ``lhs`` is less than``rhs`` and ``struct false`` otherwise.
    335 
    336 **DESCRIPTION:**
    337 
    338 This method is the less than operator for ``struct timespec`` instances. The first parameter is the left hand side and the second is the right hand side of the comparison.
    339 
    340 **NOTES:**
    341 
    342 NONE
     356        const struct timespec *lhs,
     357        const struct timespec *rhs
     358    );
     359
     360**STATUS CODES:**
     361
     362This method returns ``struct true`` if ``lhs`` is less than``rhs`` and ``struct
     363false`` otherwise.
     364
     365**DESCRIPTION:**
     366
     367This method is the less than operator for ``struct timespec`` instances. The
     368first parameter is the left hand side and the second is the right hand side of
     369the comparison.
     370
     371**NOTES:**
     372
     373NONE
     374
     375.. _rtems_timespec_greater_than:
    343376
    344377TIMESPEC_GREATER_THAN - Greater than operator
     
    347380**CALLING SEQUENCE:**
    348381
    349 .. code:: c
     382.. index:: rtems_timespec_greater_than
     383
     384.. code-block:: c
    350385
    351386    bool rtems_timespec_greater_than(
    352     const struct timespec \*_lhs,
    353     const struct timespec \*_rhs
    354     );
    355 
    356 .. index:: rtems_timespec_greater_than
    357 
    358 **STATUS CODES:**
    359 
    360 This method returns ``struct true`` if ``lhs`` is greater than``rhs`` and ``struct false`` otherwise.
     387        const struct timespec *_lhs,
     388        const struct timespec *_rhs
     389    );
     390
     391**STATUS CODES:**
     392
     393This method returns ``struct true`` if ``lhs`` is greater than``rhs`` and
     394``struct false`` otherwise.
    361395
    362396**DESCRIPTION:**
     
    367401
    368402NONE
     403
     404.. _rtems_timespec_equal_to:
    369405
    370406TIMESPEC_EQUAL_TO - Check equality of timespecs
     
    373409**CALLING SEQUENCE:**
    374410
    375 .. code:: c
     411.. index:: rtems_timespec_equal_to
     412
     413.. code-block:: c
    376414
    377415    bool rtems_timespec_equal_to(
    378     const struct timespec \*lhs,
    379     const struct timespec \*rhs
    380     );
    381 
    382 .. index:: rtems_timespec_equal_to
    383 
    384 **STATUS CODES:**
    385 
    386 This method returns ``struct true`` if ``lhs`` is equal to``rhs`` and ``struct false`` otherwise.
     416        const struct timespec *lhs,
     417        const struct timespec *rhs
     418    );
     419
     420**STATUS CODES:**
     421
     422This method returns ``struct true`` if ``lhs`` is equal to``rhs`` and ``struct
     423false`` otherwise.
    387424
    388425**DESCRIPTION:**
     
    393430
    394431NONE
     432
     433.. _rtems_timespec_get_seconds:
    395434
    396435TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance
     
    399438**CALLING SEQUENCE:**
    400439
    401 .. code:: c
     440.. index:: rtems_timespec_get_seconds
     441
     442.. code-block:: c
    402443
    403444    time_t rtems_timespec_get_seconds(
    404     struct timespec \*time
    405     );
    406 
    407 .. index:: rtems_timespec_get_seconds
    408 
    409 **STATUS CODES:**
    410 
    411 This method returns the seconds portion of the specified ``struct
    412 timespec`` instance.
    413 
    414 **DESCRIPTION:**
    415 
    416 This method returns the seconds portion of the specified ``struct timespec`` instance ``time``.
    417 
    418 **NOTES:**
    419 
    420 NONE
     445        struct timespec *time
     446    );
     447
     448**STATUS CODES:**
     449
     450This method returns the seconds portion of the specified ``struct timespec``
     451instance.
     452
     453**DESCRIPTION:**
     454
     455This method returns the seconds portion of the specified ``struct timespec``
     456instance ``time``.
     457
     458**NOTES:**
     459
     460NONE
     461
     462.. _rtems_timespec_get_nanoseconds:
    421463
    422464TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance
     
    425467**CALLING SEQUENCE:**
    426468
    427 .. code:: c
     469.. index:: rtems_timespec_get_nanoseconds
     470
     471.. code-block:: c
    428472
    429473    uint32_t rtems_timespec_get_nanoseconds(
    430     struct timespec \*_time
    431     );
    432 
    433 .. index:: rtems_timespec_get_nanoseconds
     474        struct timespec *_time
     475    );
    434476
    435477**STATUS CODES:**
     
    440482**DESCRIPTION:**
    441483
    442 This method returns the nanoseconds portion of the specified timespec
    443 which is pointed by ``_time``.
    444 
    445 **NOTES:**
     484This method returns the nanoseconds portion of the specified timespec which is
     485pointed by ``_time``.
     486
     487**NOTES:**
     488
     489.. _rtems_timespec_to_ticks:
    446490
    447491TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks
     
    450494**CALLING SEQUENCE:**
    451495
    452 .. code:: c
     496.. index:: rtems_timespec_to_ticks
     497
     498.. code-block:: c
    453499
    454500    uint32_t rtems_timespec_to_ticks(
    455     const struct timespec \*time
    456     );
    457 
    458 .. index:: rtems_timespec_to_ticks
     501        const struct timespec *time
     502    );
    459503
    460504**STATUS CODES:**
     
    464508**DESCRIPTION:**
    465509
    466 This directive converts the ``time`` timespec to the corresponding number of clock ticks.
    467 
    468 **NOTES:**
    469 
    470 NONE
     510This directive converts the ``time`` timespec to the corresponding number of
     511clock ticks.
     512
     513**NOTES:**
     514
     515NONE
     516
     517.. _rtems_timespec_from_ticks:
    471518
    472519TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation
     
    475522**CALLING SEQUENCE:**
    476523
    477 .. code:: c
     524.. index:: rtems_timespec_from_ticks
     525
     526.. code-block:: c
    478527
    479528    void rtems_timespec_from_ticks(
    480     uint32_t         ticks,
    481     struct timespec \*time
     529        uint32_t         ticks,
     530        struct timespec *time
    482531    );
    483532
     
    490539**DESCRIPTION:**
    491540
    492 This routine converts the ``ticks`` to the corresponding ``struct timespec`` representation and stores it in ``time``.
    493 
    494 **NOTES:**
    495 
    496 NONE
    497 
    498 .. COMMENT: COPYRIGHT (c) 2011.
    499 
    500 .. COMMENT: On-Line Applications Research Corporation (OAR).
    501 
    502 .. COMMENT: All rights reserved.
    503 
     541This routine converts the ``ticks`` to the corresponding ``struct timespec``
     542representation and stores it in ``time``.
     543
     544**NOTES:**
     545
     546NONE
Note: See TracChangeset for help on using the changeset viewer.