Ticket #1340: pr1340.diff

cpukit/sapi/inline/rtems/chain.inl

@@ -37 +37 @@
 #include <rtems/score/chain.inl>
 
 /**
+ *  @brief Initialize a Chain Header
+ *
+ *  This routine initializes @a the_chain structure to manage the
+ *  contiguous array of @a number_nodes nodes which starts at
+ *  @a starting_address.  Each node is of @a node_size bytes.
+ *
+ *  @param[in] the_chain specifies the chain to initialize
+ *  @param[in] starting_address is the starting address of the array
+ *         of elements
+ *  @param[in] number_nodes is the number of nodes that will be in the chain
+ *  @param[in] node_size is the size of each node
+ */
+RTEMS_INLINE_ROUTINE void rtems_chain_initialize(
+  rtems_chain_control *the_chain,
+  void                *starting_address,
+  size_t               number_nodes,
+  size_t               node_size
+)
+{
+  _Chain_Initialize( the_chain, starting_address, number_nodes, node_size );
+}
+
+/**
  *  @brief Initialize this Chain as Empty
  *
  *  This routine initializes the specified chain to contain zero nodes.

doc/user/chains.t

@@ -21 +21 @@
 @c build_id
 @item @code{@value{DIRPREFIX}chain_node} - Chain node used in user objects
 @item @code{@value{DIRPREFIX}chain_control} - Chain control node
+@item @code{@value{DIRPREFIX}chain_initialize} - initialize the chain with nodes
 @item @code{@value{DIRPREFIX}chain_initialize_empty} - initialize the chain as empty
 @item @code{@value{DIRPREFIX}chain_is_null_node} - Is the node NULL ?
 @item @code{@value{DIRPREFIX}chain_head} - Return the chain's head
@@ -196 +197 @@
 The section details the Chains directives.
 
 @c
+@c Initialize this Chain With Nodes
+@c
+@page
+@subsection Initialize Chain With Nodes
+
+@cindex chain initialize
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@findex @value{DIRPREFIX}chain_initialize
+@example
+void @value{DIRPREFIX}chain_initialize(
+  @value{DIRPREFIX}chain_control *the_chain,
+  void                *starting_address,
+  size_t               number_nodes,
+  size_t               node_size
+)
+@end example
+@end ifset
+
+@subheading RETURNS
+
+Returns nothing.
+
+@subheading 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 @code{number_nodes}
+chain nodes from the memory pointed to by @code{start_address}.  Each node
+is assumed to be @code{node_size} bytes.
+
+@subheading NOTES:
+
+This call will discard any nodes on the chain.
+
+This call does NOT inititialize any user data on each node.
+
+@c
 @c Initialize this Chain as Empty
 @c
 @page
-@subsection Initialise Empty
+@subsection Initialize Empty
 
-@cindex chain initialise empty
+@cindex chain initialize empty
 
 @subheading CALLING SEQUENCE: