diff options
Diffstat (limited to 'c_user/chains.rst')
| -rw-r--r-- | c_user/chains.rst | 566 |
1 files changed, 359 insertions, 207 deletions
diff --git a/c_user/chains.rst b/c_user/chains.rst index 490d2b2..7cd18e5 100644 --- a/c_user/chains.rst +++ b/c_user/chains.rst @@ -1,3 +1,6 @@ +.. COMMENT: Copyright 2014 Gedare Bloom. +.. COMMENT: All rights reserved. + Chains ###### @@ -7,129 +10,122 @@ Introduction ============ The Chains API is an interface to the Super Core (score) chain -implementation. The Super Core uses chains for all list type -functions. This includes wait queues and task queues. The Chains API -provided by RTEMS is: - -- build_id +implementation. The Super Core uses chains for all list type functions. This +includes wait queues and task queues. The Chains API provided by RTEMS is: - ``rtems_chain_node`` - Chain node used in user objects - ``rtems_chain_control`` - Chain control node -- ``rtems_chain_initialize`` - initialize the chain with nodes - -- ``rtems_chain_initialize_empty`` - initialize the chain as empty +- rtems_chain_initialize_ - initialize the chain with nodes -- ``rtems_chain_is_null_node`` - Is the node NULL ? +- rtems_chain_initialize_empty_ - initialize the chain as empty -- ``rtems_chain_head`` - Return the chain's head +- rtems_chain_is_null_node_ - Is the node NULL ? -- ``rtems_chain_tail`` - Return the chain's tail +- rtems_chain_head_ - Return the chain's head -- ``rtems_chain_are_nodes_equal`` - Are the node's equal ? +- rtems_chain_tail_ - Return the chain's tail -- ``rtems_chain_is_empty`` - Is the chain empty ? +- rtems_chain_are_nodes_equal_ - Are the node's equal ? -- ``rtems_chain_is_first`` - Is the Node the first in the chain ? +- rtems_chain_is_empty_ - Is the chain empty ? -- ``rtems_chain_is_last`` - Is the Node the last in the chain ? +- rtems_chain_is_first_ - Is the Node the first in the chain ? -- ``rtems_chain_has_only_one_node`` - Does the node have one node ? +- rtems_chain_is_last_ - Is the Node the last in the chain ? -- ``rtems_chain_node_count_unprotected`` - Returns the node count of the chain (unprotected) +- rtems_chain_has_only_one_node_ - Does the node have one node ? -- ``rtems_chain_is_head`` - Is the node the head ? +- rtems_chain_node_count_unprotected_ - Returns the node count of the chain (unprotected) -- ``rtems_chain_is_tail`` - Is the node the tail ? +- rtems_chain_is_head_ - Is the node the head ? -- ``rtems_chain_extract`` - Extract the node from the chain +- rtems_chain_is_tail_ - Is the node the tail ? -- ``rtems_chain_extract_unprotected`` - Extract the node from the chain (unprotected) +- rtems_chain_extract_ - Extract the node from the chain -- ``rtems_chain_get`` - Return the first node on the chain +- rtems_chain_extract_unprotected_ - Extract the node from the chain (unprotected) -- ``rtems_chain_get_unprotected`` - Return the first node on the chain (unprotected) +- rtems_chain_get_ - Return the first node on the chain -- ``rtems_chain_get_first_unprotected`` - Get the first node on the chain (unprotected) +- rtems_chain_get_unprotected_ - Return the first node on the chain (unprotected) -- ``rtems_chain_insert`` - Insert the node into the chain +- rtems_chain_insert_ - Insert the node into the chain -- ``rtems_chain_insert_unprotected`` - Insert the node into the chain (unprotected) +- rtems_chain_insert_unprotected_ - Insert the node into the chain (unprotected) -- ``rtems_chain_append`` - Append the node to chain +- rtems_chain_append_ - Append the node to chain -- ``rtems_chain_append_unprotected`` - Append the node to chain (unprotected) +- rtems_chain_append_unprotected_ - Append the node to chain (unprotected) -- ``rtems_chain_prepend`` - Prepend the node to the end of the chain +- rtems_chain_prepend_ - Prepend the node to the end of the chain -- ``rtems_chain_prepend_unprotected`` - Prepend the node to chain (unprotected) +- rtems_chain_prepend_unprotected_ - Prepend the node to chain (unprotected) Background ========== -The Chains API maps to the Super Core Chains API. Chains are -implemented as a double linked list of nodes anchored to a control -node. The list starts at the control node and is terminated at the -control node. A node has previous and next pointers. Being a double -linked list nodes can be inserted and removed without the need to -travse the chain. +The Chains API maps to the Super Core Chains API. Chains are implemented as a +double linked list of nodes anchored to a control node. The list starts at the +control node and is terminated at the control node. A node has previous and +next pointers. Being a double linked list nodes can be inserted and removed +without the need to travse the chain. -Chains have a small memory footprint and can be used in interrupt -service routines and are thread safe in a multi-threaded -environment. The directives list which operations disable interrupts. +Chains have a small memory footprint and can be used in interrupt service +routines and are thread safe in a multi-threaded environment. The directives +list which operations disable interrupts. Chains are very useful in Board Support packages and applications. Nodes ----- -A chain is made up from nodes that orginate from a chain control -object. A node is of type ``rtems_chain_node``. The node -is designed to be part of a user data structure and a cast is used to -move from the node address to the user data structure address. For -example: -.. code:: c +A chain is made up from nodes that orginate from a chain control object. A node +is of type ``rtems_chain_node``. The node is designed to be part of a user data +structure and a cast is used to move from the node address to the user data +structure address. For example: + +.. code-block:: c typedef struct foo { - rtems_chain_node node; - int bar; + rtems_chain_node node; + int bar; } foo; -creates a type ``foo`` that can be placed on a chain. To get the -foo structure from the list you perform the following: -.. code:: c +creates a type ``foo`` that can be placed on a chain. To get the foo structure +from the list you perform the following: + +.. code-block:: c foo* get_foo(rtems_chain_control* control) { - return (foo*) rtems_chain_get(control); + return (foo*) rtems_chain_get(control); } -The node is placed at the start of the user's structure to allow the -node address on the chain to be easly cast to the user's structure -address. +The node is placed at the start of the user's structure to allow the node +address on the chain to be easly cast to the user's structure address. Controls -------- -A chain is anchored with a control object. Chain control provide the -user with access to the nodes on the chain. The control is head of the -node. +A chain is anchored with a control object. Chain control provide the user with +access to the nodes on the chain. The control is head of the node. -.. code:: c +.. code-block:: c - Control + [Control] first ------------------------> - permanent_null <--------------- NODE + permanent_null <--------------- [NODE] last -------------------------> -The implementation does not require special checks for manipulating -the first and last nodes on the chain. To accomplish this the``rtems_chain_control`` structure is treated as two -overlapping ``rtems_chain_node`` structures. The -permanent head of the chain overlays a node structure on the first and``permanent_null`` fields. The ``permanent_tail`` of the chain -overlays a node structure on the ``permanent_null`` and ``last`` -elements of the structure. +The implementation does not require special checks for manipulating the first +and last nodes on the chain. To accomplish this the ``rtems_chain_control`` +structure is treated as two overlapping ``rtems_chain_node`` structures. The +permanent head of the chain overlays a node structure on the first and +``permanent_null`` fields. The ``permanent_tail`` of the chain overlays a node +structure on the ``permanent_null`` and ``last`` elements of the structure. Operations ========== @@ -137,40 +133,42 @@ Operations Multi-threading --------------- -Chains are designed to be used in a multi-threading environment. The -directives list which operations mask interrupts. Chains supports -tasks and interrupt service routines appending and extracting nodes -with out the need for extra locks. Chains how-ever cannot insure the -integrity of a chain for all operations. This is the responsibility of -the user. For example an interrupt service routine extracting nodes -while a task is iterating over the chain can have unpredictable -results. +Chains are designed to be used in a multi-threading environment. The directives +list which operations mask interrupts. Chains supports tasks and interrupt +service routines appending and extracting nodes with out the need for extra +locks. Chains how-ever cannot insure the integrity of a chain for all +operations. This is the responsibility of the user. For example an interrupt +service routine extracting nodes while a task is iterating over the chain can +have unpredictable results. Creating a Chain ---------------- To create a chain you need to declare a chain control then add nodes to the control. Consider a user structure and chain control: -.. code:: c + +.. code-block:: c typedef struct foo { - rtems_chain_node node; - uint8_t char* data; + rtems_chain_node node; + uint8_t char* data; } foo; rtems_chain_control chain; Add nodes with the following code: -.. code:: c + +.. code-block:: c rtems_chain_initialize_empty (&chain); + for (i = 0; i < count; i++) { - foo* bar = malloc (sizeof (foo)); - if (!bar) - return -1; - bar->data = malloc (size); - rtems_chain_append (&chain, &bar->node); + foo* bar = malloc (sizeof (foo)); + if (!bar) + return -1; + bar->data = malloc (size); + rtems_chain_append (&chain, &bar->node); } The chain is initialized and the nodes allocated and appended to the @@ -180,31 +178,34 @@ Iterating a Chain ----------------- .. index:: chain iterate -Iterating a chain is a common function. The example shows how to -iterate the buffer pool chain created in the last section to find -buffers starting with a specific string. If the buffer is located it is -extracted from the chain and placed on another chain: -.. code:: c +Iterating a chain is a common function. The example shows how to iterate the +buffer pool chain created in the last section to find buffers starting with a +specific string. If the buffer is located it is extracted from the chain and +placed on another chain: + +.. code-block:: c void foobar (const char* match, - rtems_chain_control* chain, - rtems_chain_control* out) - { - rtems_chain_node* node; - foo* bar; - rtems_chain_initialize_empty (out); - node = chain->first; - while (!rtems_chain_is_tail (chain, node)) + rtems_chain_control* chain, + rtems_chain_control* out) { - bar = (foo*) node; - rtems_chain_node* next_node = node->next; - if (strcmp (match, bar->data) == 0) - { - rtems_chain_extract (node); - rtems_chain_append (out, node); - } - node = next_node; - } + rtems_chain_node* node; + foo* bar; + + rtems_chain_initialize_empty (out); + + node = chain->first; + while (!rtems_chain_is_tail (chain, node)) + { + bar = (foo*) node; + rtems_chain_node* next_node = node->next; + if (strcmp (match, bar->data) == 0) + { + rtems_chain_extract (node); + rtems_chain_append (out, node); + } + node = next_node; + } } Directives @@ -214,6 +215,8 @@ The section details the Chains directives. .. COMMENT: Initialize this Chain With Nodes +.. _rtems_chain_initialize: + Initialize Chain With Nodes --------------------------- .. index:: chain initialize @@ -222,13 +225,13 @@ Initialize Chain With Nodes .. index:: rtems_chain_initialize -.. code:: c +.. code-block:: c void rtems_chain_initialize( - rtems_chain_control \*the_chain, - void \*starting_address, - size_t number_nodes, - size_t node_size + rtems_chain_control *the_chain, + void *starting_address, + size_t number_nodes, + size_t node_size ) **RETURNS** @@ -237,10 +240,10 @@ Returns nothing. **DESCRIPTION:** -This function take in a pointer to a chain control and initializes it -to contain a set of chain nodes. The chain will contain ``number_nodes`` -chain nodes from the memory pointed to by ``start_address``. Each node -is assumed to be ``node_size`` bytes. +This function take in a pointer to a chain control and initializes it to +contain a set of chain nodes. The chain will contain ``number_nodes`` chain +nodes from the memory pointed to by ``start_address``. Each node is assumed to +be ``node_size`` bytes. **NOTES:** @@ -250,6 +253,8 @@ This call does NOT inititialize any user data on each node. .. COMMENT: Initialize this Chain as Empty +.. _rtems_chain_initialize_empty: + Initialize Empty ---------------- .. index:: chain initialize empty @@ -258,10 +263,10 @@ Initialize Empty .. index:: rtems_chain_initialize_empty -.. code:: c +.. code-block:: c void rtems_chain_initialize_empty( - rtems_chain_control \*the_chain + rtems_chain_control *the_chain ); **RETURNS** @@ -270,13 +275,14 @@ Returns nothing. **DESCRIPTION:** -This function take in a pointer to a chain control and initializes it -to empty. +This function take in a pointer to a chain control and initializes it to empty. **NOTES:** This call will discard any nodes on the chain. +.. _rtems_chain_is_null_node: + Is Null Node ? -------------- .. index:: chain is node null @@ -285,10 +291,10 @@ Is Null Node ? .. index:: rtems_chain_is_null_node -.. code:: c +.. code-block:: c bool rtems_chain_is_null_node( - const rtems_chain_node \*the_node + const rtems_chain_node *the_node ); **RETURNS** @@ -300,6 +306,8 @@ NULL. Tests the node to see if it is a NULL returning ``true`` if a null. +.. _rtems_chain_head: + Head ---- .. index:: chain get head @@ -308,10 +316,10 @@ Head .. index:: rtems_chain_head -.. code:: c +.. code-block:: c - rtems_chain_node \*rtems_chain_head( - rtems_chain_control \*the_chain + rtems_chain_node *rtems_chain_head( + rtems_chain_control *the_chain ) **RETURNS** @@ -322,6 +330,8 @@ Returns the permanent head node of the chain. This function returns a pointer to the first node on the chain. +.. _rtems_chain_tail: + Tail ---- .. index:: chain get tail @@ -330,10 +340,10 @@ Tail .. index:: rtems_chain_tail -.. code:: c +.. code-block:: c - rtems_chain_node \*rtems_chain_tail( - rtems_chain_control \*the_chain + rtems_chain_node *rtems_chain_tail( + rtems_chain_control *the_chain ); **RETURNS** @@ -344,6 +354,8 @@ Returns the permanent tail node of the chain. This function returns a pointer to the last node on the chain. +.. _rtems_chain_are_nodes_equal: + Are Two Nodes Equal ? --------------------- .. index:: chare are nodes equal @@ -352,22 +364,24 @@ Are Two Nodes Equal ? .. index:: rtems_chain_are_nodes_equal -.. code:: c +.. code-block:: c bool rtems_chain_are_nodes_equal( - const rtems_chain_node \*left, - const rtems_chain_node \*right + const rtems_chain_node *left, + const rtems_chain_node *right ); **RETURNS** -This function returns ``true`` if the left node and the right node are -equal, and ``false`` otherwise. +This function returns ``true`` if the left node and the right node are equal, +and ``false`` otherwise. **DESCRIPTION:** -This function returns ``true`` if the left node and the right node are -equal, and ``false`` otherwise. +This function returns ``true`` if the left node and the right node are equal, +and ``false`` otherwise. + +.. _rtems_chain_is_empty: Is the Chain Empty ------------------ @@ -377,10 +391,10 @@ Is the Chain Empty .. index:: rtems_chain_is_empty -.. code:: c +.. code-block:: c bool rtems_chain_is_empty( - rtems_chain_control \*the_chain + rtems_chain_control *the_chain ); **RETURNS** @@ -393,6 +407,8 @@ otherwise. This function returns ``true`` if there a no nodes on the chain and ``false`` otherwise. +.. _rtems_chain_is_first: + Is this the First Node on the Chain ? ------------------------------------- .. index:: chain is node the first @@ -401,21 +417,23 @@ Is this the First Node on the Chain ? .. index:: rtems_chain_is_first -.. code:: c +.. code-block:: c bool rtems_chain_is_first( - const rtems_chain_node \*the_node + const rtems_chain_node *the_node ); **RETURNS** -This function returns ``true`` if the node is the first node on a chain -and ``false`` otherwise. +This function returns ``true`` if the node is the first node on a chain and +``false`` otherwise. **DESCRIPTION:** -This function returns ``true`` if the node is the first node on a chain -and ``false`` otherwise. +This function returns ``true`` if the node is the first node on a chain and +``false`` otherwise. + +.. _rtems_chain_is_last: Is this the Last Node on the Chain ? ------------------------------------ @@ -425,19 +443,23 @@ Is this the Last Node on the Chain ? .. index:: rtems_chain_is_last -.. code:: c +.. code-block:: c bool rtems_chain_is_last( - const rtems_chain_node \*the_node + const rtems_chain_node *the_node ); **RETURNS** -This function returns ``true`` if the node is the last node on a chain and``false`` otherwise. +This function returns ``true`` if the node is the last node on a chain and +``false`` otherwise. **DESCRIPTION:** -This function returns ``true`` if the node is the last node on a chain and``false`` otherwise. +This function returns ``true`` if the node is the last node on a chain and +``false`` otherwise. + +.. _rtems_chain_has_only_one_node: Does this Chain have only One Node ? ------------------------------------ @@ -447,19 +469,23 @@ Does this Chain have only One Node ? .. index:: rtems_chain_has_only_one_node -.. code:: c +.. code-block:: c bool rtems_chain_has_only_one_node( - const rtems_chain_control \*the_chain + const rtems_chain_control *the_chain ); **RETURNS** -This function returns ``true`` if there is only one node on the chain and``false`` otherwise. +This function returns ``true`` if there is only one node on the chain and +``false`` otherwise. **DESCRIPTION:** -This function returns ``true`` if there is only one node on the chain and``false`` otherwise. +This function returns ``true`` if there is only one node on the chain and +``false`` otherwise. + +.. _rtems_chain_node_count_unprotected: Returns the node count of the chain (unprotected) ------------------------------------------------- @@ -469,10 +495,10 @@ Returns the node count of the chain (unprotected) .. index:: rtems_chain_node_count_unprotected -.. code:: c +.. code-block:: c size_t rtems_chain_node_count_unprotected( - const rtems_chain_control \*the_chain + const rtems_chain_control *the_chain ); **RETURNS** @@ -483,6 +509,8 @@ This function returns the node count of the chain. This function returns the node count of the chain. +.. _rtems_chain_is_head: + Is this Node the Chain Head ? ----------------------------- .. index:: chain is node the head @@ -491,20 +519,24 @@ Is this Node the Chain Head ? .. index:: rtems_chain_is_head -.. code:: c +.. code-block:: c bool rtems_chain_is_head( - rtems_chain_control \*the_chain, - rtems_const chain_node \*the_node + rtems_chain_control *the_chain, + rtems_const chain_node *the_node ); **RETURNS** -This function returns ``true`` if the node is the head of the chain and``false`` otherwise. +This function returns ``true`` if the node is the head of the chain and +``false`` otherwise. **DESCRIPTION:** -This function returns ``true`` if the node is the head of the chain and``false`` otherwise. +This function returns ``true`` if the node is the head of the chain and +``false`` otherwise. + +.. _rtems_chain_is_tail: Is this Node the Chain Tail ? ----------------------------- @@ -514,20 +546,24 @@ Is this Node the Chain Tail ? .. index:: rtems_chain_is_tail -.. code:: c +.. code-block:: c bool rtems_chain_is_tail( - rtems_chain_control \*the_chain, - const rtems_chain_node \*the_node + rtems_chain_control *the_chain, + const rtems_chain_node *the_node ) **RETURNS** -This function returns ``true`` if the node is the tail of the chain and``false`` otherwise. +This function returns ``true`` if the node is the tail of the chain and +``false`` otherwise. **DESCRIPTION:** -This function returns ``true`` if the node is the tail of the chain and``false`` otherwise. +This function returns ``true`` if the node is the tail of the chain and +``false`` otherwise. + +.. _rtems_chain_extract: Extract a Node -------------- @@ -537,10 +573,10 @@ Extract a Node .. index:: rtems_chain_extract -.. code:: c +.. code-block:: c void rtems_chain_extract( - rtems_chain_node \*the_node + rtems_chain_node *the_node ); **RETURNS** @@ -553,11 +589,40 @@ This routine extracts the node from the chain on which it resides. **NOTES:** -Interrupts are disabled while extracting the node to ensure the -atomicity of the operation. +Interrupts are disabled while extracting the node to ensure the atomicity of +the operation. + +Use rtems_chain_extract_unprotected_ to avoid disabling of interrupts. -Use ``rtems_chain_extract_unprotected()`` to avoid disabling of -interrupts. +.. _rtems_chain_extract_unprotected: + +Extract a Node (unprotected) +---------------------------- +.. index:: chain extract a node unprotected + +**CALLING SEQUENCE:** + +.. index:: rtems_chain_extract_unprotected + +.. code-block:: c + + void rtems_chain_extract_unprotected( + rtems_chain_node *the_node + ); + +**RETURNS** + +Returns nothing. + +**DESCRIPTION:** + +This routine extracts the node from the chain on which it resides. + +**NOTES:** + +The function does nothing to ensure the atomicity of the operation. + +.. _rtems_chain_get: Get the First Node ------------------ @@ -567,30 +632,30 @@ Get the First Node .. index:: rtems_chain_get -.. code:: c +.. code-block:: c - rtems_chain_node \*rtems_chain_get( - rtems_chain_control \*the_chain + rtems_chain_node *rtems_chain_get( + rtems_chain_control *the_chain ); **RETURNS** -Returns a pointer a node. If a node was removed, then a pointer to -that node is returned. If the chain was empty, then NULL is -returned. +Returns a pointer a node. If a node was removed, then a pointer to that node is +returned. If the chain was empty, then ``NULL`` is returned. **DESCRIPTION:** -This function removes the first node from the chain and returns a -pointer to that node. If the chain is empty, then NULL is returned. +This function removes the first node from the chain and returns a pointer to +that node. If the chain is empty, then ``NULL`` is returned. **NOTES:** -Interrupts are disabled while obtaining the node to ensure the -atomicity of the operation. +Interrupts are disabled while obtaining the node to ensure the atomicity of the +operation. -Use ``rtems_chain_get_unprotected()`` to avoid disabling of -interrupts. +Use ``rtems_chain_get_unprotected()`` to avoid disabling of interrupts. + +.. _rtems_chain_get_unprotected: Get the First Node (unprotected) -------------------------------- @@ -598,12 +663,12 @@ Get the First Node (unprotected) **CALLING SEQUENCE:** -.. index:: rtems_chain_get_first_unprotected +.. index:: rtems_chain_get_unprotected -.. code:: c +.. code-block:: c - rtems_chain_node \*rtems_chain_get_first_unprotected( - rtems_chain_control \*the_chain + rtems_chain_node *rtems_chain_get_unprotected( + rtems_chain_control *the_chain ); **RETURNS:** @@ -619,6 +684,8 @@ chain was empty, then the results are unpredictable. The function does nothing to ensure the atomicity of the operation. +.. _rtems_chain_insert: + Insert a Node ------------- .. index:: chain insert a node @@ -627,11 +694,11 @@ Insert a Node .. index:: rtems_chain_insert -.. code:: c +.. code-block:: c void rtems_chain_insert( - rtems_chain_node \*after_node, - rtems_chain_node \*the_node + rtems_chain_node *after_node, + rtems_chain_node *the_node ); **RETURNS** @@ -640,16 +707,47 @@ Returns nothing. **DESCRIPTION:** -This routine inserts a node on a chain immediately following the -specified node. +This routine inserts a node on a chain immediately following the specified +node. **NOTES:** -Interrupts are disabled during the insert to ensure the atomicity of -the operation. +Interrupts are disabled during the insert to ensure the atomicity of the +operation. -Use ``rtems_chain_insert_unprotected()`` to avoid disabling of -interrupts. +Use rtems_chain_insert_unprotected_ to avoid disabling of interrupts. + +.. _rtems_chain_insert_unprotected: + +Insert a Node (unprotected) +--------------------------- +.. index:: chain insert a node unprotected + +**CALLING SEQUENCE:** + +.. index:: rtems_chain_insert_unprotected + +.. code-block:: c + + void rtems_chain_insert_unprotected( + rtems_chain_node *after_node, + rtems_chain_node *the_node + ); + +**RETURNS** + +Returns nothing. + +**DESCRIPTION:** + +This routine inserts a node on a chain immediately following the specified +node. + +**NOTES:** + +The function does nothing to ensure the atomicity of the operation. + +.. _rtems_chain_append: Append a Node ------------- @@ -659,11 +757,11 @@ Append a Node .. index:: rtems_chain_append -.. code:: c +.. code-block:: c void rtems_chain_append( - rtems_chain_control \*the_chain, - rtems_chain_node \*the_node + rtems_chain_control *the_chain, + rtems_chain_node *the_node ); **RETURNS** @@ -676,11 +774,41 @@ This routine appends a node to the end of a chain. **NOTES:** -Interrupts are disabled during the append to ensure the atomicity of -the operation. +Interrupts are disabled during the append to ensure the atomicity of the +operation. -Use ``rtems_chain_append_unprotected()`` to avoid disabling of -interrupts. +Use rtems_chain_append_unprotected_ to avoid disabling of interrupts. + +.. _rtems_chain_append_unprotected: + +Append a Node (unprotected) +--------------------------- +.. index:: chain append a node unprotected + +**CALLING SEQUENCE:** + +.. index:: rtems_chain_append_unprotected + +.. code-block:: c + + void rtems_chain_append_unprotected( + rtems_chain_control *the_chain, + rtems_chain_node *the_node + ); + +**RETURNS** + +Returns nothing. + +**DESCRIPTION:** + +This routine appends a node to the end of a chain. + +**NOTES:** + +The function does nothing to ensure the atomicity of the operation. + +.. _rtems_chain_prepend: Prepend a Node -------------- @@ -690,11 +818,11 @@ Prepend a Node .. index:: rtems_chain_prepend -.. code:: c +.. code-block:: c void rtems_chain_prepend( - rtems_chain_control \*the_chain, - rtems_chain_node \*the_node + rtems_chain_control *the_chain, + rtems_chain_node *the_node ); **RETURNS** @@ -707,13 +835,37 @@ This routine prepends a node to the front of the chain. **NOTES:** -Interrupts are disabled during the prepend to ensure the atomicity of -the operation. +Interrupts are disabled during the prepend to ensure the atomicity of the +operation. -Use ``rtems_chain_prepend_unprotected()`` to avoid disabling of +Use rtems_chain_prepend_unprotected_ to avoid disabling of interrupts. -.. COMMENT: Copyright 2014 Gedare Bloom. +.. _rtems_chain_prepend_unprotected: -.. COMMENT: All rights reserved. +Prepend a Node (unprotected) +---------------------------- +.. index:: prepend node unprotected + +**CALLING SEQUENCE:** + +.. index:: rtems_chain_prepend_unprotected + +.. code-block:: c + + void rtems_chain_prepend_unprotected( + rtems_chain_control *the_chain, + rtems_chain_node *the_node + ); + +**RETURNS** + +Returns nothing. + +**DESCRIPTION:** + +This routine prepends a node to the front of the chain. + +**NOTES:** +The function does nothing to ensure the atomicity of the operation. |