[baff4da] | 1 | /** |
---|
[11874561] | 2 | * @file rtems/score/chain.h |
---|
[ac7d5ef0] | 3 | * |
---|
| 4 | * This include file contains all the constants and structures associated |
---|
[baff4da] | 5 | * with the Doubly-Linked Chain Handler. |
---|
| 6 | */ |
---|
| 7 | |
---|
| 8 | /* |
---|
| 9 | * COPYRIGHT (c) 1989-2004. |
---|
[ac7d5ef0] | 10 | * On-Line Applications Research Corporation (OAR). |
---|
| 11 | * |
---|
[98e4ebf5] | 12 | * The license and distribution terms for this file may be |
---|
| 13 | * found in the file LICENSE in this distribution or at |
---|
[dd687d97] | 14 | * http://www.rtems.com/license/LICENSE. |
---|
[ac7d5ef0] | 15 | * |
---|
| 16 | * $Id$ |
---|
| 17 | */ |
---|
| 18 | |
---|
| 19 | #ifndef __RTEMS_CHAIN_h |
---|
| 20 | #define __RTEMS_CHAIN_h |
---|
| 21 | |
---|
[baff4da] | 22 | /** |
---|
| 23 | * @defgroup ScoreChain Chain Handler |
---|
| 24 | * |
---|
| 25 | * The Chain Handler contains XXX |
---|
| 26 | */ |
---|
| 27 | /**@{*/ |
---|
| 28 | |
---|
[ac7d5ef0] | 29 | #ifdef __cplusplus |
---|
| 30 | extern "C" { |
---|
| 31 | #endif |
---|
| 32 | |
---|
[5e9b32b] | 33 | #include <rtems/score/address.h> |
---|
[ac7d5ef0] | 34 | |
---|
[baff4da] | 35 | /** |
---|
| 36 | * @typedef Chain_Node |
---|
| 37 | * |
---|
| 38 | * This type definition promotes the name for the Chain Node used by |
---|
| 39 | * all RTEMS code. It is a separate type definition because a forward |
---|
| 40 | * reference is required to define it. |
---|
| 41 | */ |
---|
| 42 | typedef struct Chain_Node_struct Chain_Node; |
---|
| 43 | |
---|
| 44 | /** |
---|
| 45 | * @struct Chain_Node_struct |
---|
| 46 | * |
---|
[ac7d5ef0] | 47 | * This is used to manage each element (node) which is placed |
---|
| 48 | * on a chain. |
---|
| 49 | * |
---|
[baff4da] | 50 | * @note Typically, a more complicated structure will use the |
---|
| 51 | * chain package. The more complicated structure will |
---|
| 52 | * include a chain node as the first element in its |
---|
| 53 | * control structure. It will then call the chain package |
---|
| 54 | * with a pointer to that node element. The node pointer |
---|
| 55 | * and the higher level structure start at the same address |
---|
| 56 | * so the user can cast the pointers back and forth. |
---|
[ac7d5ef0] | 57 | * |
---|
| 58 | */ |
---|
| 59 | struct Chain_Node_struct { |
---|
[baff4da] | 60 | /** This points to the node after to this one on this chain. */ |
---|
[ac7d5ef0] | 61 | Chain_Node *next; |
---|
[baff4da] | 62 | /** This points to the node immediate prior to this one on this chain. */ |
---|
[ac7d5ef0] | 63 | Chain_Node *previous; |
---|
| 64 | }; |
---|
| 65 | |
---|
[baff4da] | 66 | /** |
---|
| 67 | * @struct Chain_Control |
---|
| 68 | * |
---|
| 69 | * This is used to manage a chain. A chain consists of a doubly |
---|
| 70 | * linked list of zero or more nodes. |
---|
| 71 | * |
---|
| 72 | * @note This implementation does not require special checks for |
---|
| 73 | * manipulating the first and last elements on the chain. |
---|
| 74 | * To accomplish this the @a Chain_Control structure is |
---|
| 75 | * treated as two overlapping @ref Chain_Node structures. |
---|
| 76 | * The permanent head of the chain overlays a node structure on the |
---|
| 77 | * @a first and @a permanent_null fields. The permanent tail |
---|
| 78 | * of the chain overlays a node structure on the |
---|
| 79 | * @a permanent_null and @a last elements of the structure. |
---|
[ac7d5ef0] | 80 | * |
---|
| 81 | */ |
---|
| 82 | typedef struct { |
---|
[baff4da] | 83 | /** This points to the first node on this chain. */ |
---|
[ac7d5ef0] | 84 | Chain_Node *first; |
---|
[baff4da] | 85 | /** This field is always 0. */ |
---|
[ac7d5ef0] | 86 | Chain_Node *permanent_null; |
---|
[baff4da] | 87 | /** This points to the last node on this chain. */ |
---|
[ac7d5ef0] | 88 | Chain_Node *last; |
---|
| 89 | } Chain_Control; |
---|
| 90 | |
---|
[baff4da] | 91 | /** |
---|
| 92 | * @brief Initialize a Chain Header |
---|
[ac7d5ef0] | 93 | * |
---|
[baff4da] | 94 | * This routine initializes @a the_chain structure to manage the |
---|
| 95 | * contiguous array of @a number_nodes nodes which starts at |
---|
| 96 | * @a starting_address. Each node is of @a node_size bytes. |
---|
[ac7d5ef0] | 97 | * |
---|
[baff4da] | 98 | * @param the_chain (in) specifies the chain to initialize |
---|
| 99 | * @param starting_address (in) is the starting address of the array |
---|
| 100 | * of elements |
---|
| 101 | * @param number_nodes (in) is the numebr of nodes that will be in the chain |
---|
| 102 | * @param node_size (in) is the size of each node |
---|
[ac7d5ef0] | 103 | */ |
---|
| 104 | void _Chain_Initialize( |
---|
| 105 | Chain_Control *the_chain, |
---|
| 106 | void *starting_address, |
---|
[9c8195a] | 107 | uint32_t number_nodes, |
---|
| 108 | uint32_t node_size |
---|
[ac7d5ef0] | 109 | ); |
---|
| 110 | |
---|
[8af72be] | 111 | #ifndef RTEMS_INLINES |
---|
[baff4da] | 112 | /** |
---|
| 113 | * @brief Get the first node (do not disable interrupts) |
---|
| 114 | * |
---|
| 115 | * This method attempts to obtain the first node from \a the_chain. |
---|
| 116 | * |
---|
| 117 | * @param the_chain (in) points to the chain to operate upon |
---|
| 118 | * @return If successful, a chain node is returned. Otherwise, NULL |
---|
| 119 | * is returned. |
---|
| 120 | */ |
---|
[f4d52cd7] | 121 | Chain_Node *_Chain_Get_first_unprotected( |
---|
| 122 | Chain_Control *the_chain |
---|
| 123 | ); |
---|
| 124 | #endif |
---|
| 125 | |
---|
[baff4da] | 126 | /** |
---|
| 127 | * @brief Extract the specified node from a chain |
---|
[ac7d5ef0] | 128 | * |
---|
[baff4da] | 129 | * This routine extracts \a the_node from the chain on which it resides. |
---|
[ac7d5ef0] | 130 | * It disables interrupts to insure the atomicity of the |
---|
| 131 | * extract operation. |
---|
| 132 | * |
---|
[baff4da] | 133 | * @arg the_node specifies the node to extract |
---|
[ac7d5ef0] | 134 | */ |
---|
| 135 | void _Chain_Extract( |
---|
| 136 | Chain_Node *the_node |
---|
| 137 | ); |
---|
| 138 | |
---|
[baff4da] | 139 | /** |
---|
| 140 | * @brief Obtain the first node on a chain |
---|
[ac7d5ef0] | 141 | * |
---|
[baff4da] | 142 | * This function removes the first node from \a the_chain and returns |
---|
| 143 | * a pointer to that node. If \a the_chain is empty, then NULL is returned. |
---|
[ac7d5ef0] | 144 | * |
---|
[baff4da] | 145 | * @note It disables interrupts to insure the atomicity of the |
---|
[ac7d5ef0] | 146 | * get operation. |
---|
| 147 | */ |
---|
| 148 | Chain_Node *_Chain_Get( |
---|
| 149 | Chain_Control *the_chain |
---|
| 150 | ); |
---|
| 151 | |
---|
[baff4da] | 152 | /** |
---|
| 153 | * @brief Insert a node on a chain |
---|
[ac7d5ef0] | 154 | * |
---|
[baff4da] | 155 | * This routine inserts \a the_node on a chain immediately following |
---|
| 156 | * \a after_node. |
---|
[ac7d5ef0] | 157 | * |
---|
[baff4da] | 158 | * @note It disables interrupts to insure the atomicity |
---|
[ac7d5ef0] | 159 | * of the extract operation. |
---|
| 160 | */ |
---|
| 161 | void _Chain_Insert( |
---|
| 162 | Chain_Node *after_node, |
---|
| 163 | Chain_Node *the_node |
---|
| 164 | ); |
---|
| 165 | |
---|
[baff4da] | 166 | /** |
---|
| 167 | * @brief Append a node on the end of a chain |
---|
[ac7d5ef0] | 168 | * |
---|
[baff4da] | 169 | * This routine appends \a the_node onto the end of \a the_chain. |
---|
[ac7d5ef0] | 170 | * |
---|
[baff4da] | 171 | * @note It disables interrupts to insure the atomicity of the |
---|
[ac7d5ef0] | 172 | * append operation. |
---|
| 173 | */ |
---|
| 174 | void _Chain_Append( |
---|
| 175 | Chain_Control *the_chain, |
---|
| 176 | Chain_Node *the_node |
---|
| 177 | ); |
---|
| 178 | |
---|
[1a8fde6c] | 179 | #ifndef __RTEMS_APPLICATION__ |
---|
[5e9b32b] | 180 | #include <rtems/score/chain.inl> |
---|
[1a8fde6c] | 181 | #endif |
---|
[ac7d5ef0] | 182 | |
---|
| 183 | #ifdef __cplusplus |
---|
| 184 | } |
---|
| 185 | #endif |
---|
| 186 | |
---|
[baff4da] | 187 | /**@}*/ |
---|
| 188 | |
---|
[ac7d5ef0] | 189 | #endif |
---|
| 190 | /* end of include file */ |
---|