diff --git a/platform/linux-generic/include/api/odp_buffer.h b/platform/linux-generic/include/api/odp_buffer.h
index 289e0eb..4adf6b6 100644
--- a/platform/linux-generic/include/api/odp_buffer.h
+++ b/platform/linux-generic/include/api/odp_buffer.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2013, Linaro Limited
+/* Copyright (c) 2013-2014, Linaro Limited
  * All rights reserved.
  *
  * SPDX-License-Identifier:     BSD-3-Clause
@@ -8,7 +8,88 @@
 /**
  * @file
  *
- * ODP buffer descriptor
+ * @par Buffer
+ * A buffer is an element of a buffer pool used for storing
+ * information. Buffers are referenced by an abstract handle of type
+ * odp_buffer_t. Buffers have associated buffer types that describe
+ * their intended use and the type of meta data that is associated
+ * with them. Buffers of a specific type may be referenced for
+ * processing by cores or by offload engines. Buffers are also
+ * transmitted via queues from one processing element to another.
+ *
+ * @par Buffer Types
+ * An ODP buffer type is identified by the
+ * odp_buffer_type_e enum. It defines the semantics that are to be
+ * attached to the buffer and defines the type of meta data that is
+ * associated with it. ODP implementations MUST support the following
+ * buffer types:
+ *
+ * - ODP_BUFFER_TYPE_RAW
+ * This is the “basic” buffer type
+ * which simply consists of a single fixed-sized block of contiguous
+ * memory. Buffers of this type do not support user meta data and the
+ * only built-in meta data supported for this type of buffer are those
+ * that are statically computable, such as pool and size. This type of
+ * buffer is entirely under application control and most of the buffer
+ * APIs defined in this document are not available. APIs for this
+ * type of buffer are described in this document.
+ *
+ * - ODP_BUFFER_TYPE_PACKET
+ * This buffer type is suitable for receiving,
+ * processing, and transmitting network packet data. Included in this
+ * type is a rich set of primitives for manipulating buffer aggregates
+ * and for storing system and user meta data. APIs for this type of
+ * buffer are described here and in the ODP Packet Management Design
+ * document.
+ *
+ * - ODP_BUFFER_TYPE_TIMEOUT
+ * This buffer type is suitable for
+ * representing timer timeout events. Does not support buffer
+ * aggregation but does support user meta data. APIs for this type of
+ * buffer are described here and in the ODP Timer Management Design
+ * document.
+ *
+ * - ODP_BUFFER_TYPE_ANY
+ * A “universal” buffer type capable of
+ * storing information needed for any other buffer type. It is not
+ * intended to be used directly, but exists for possible
+ * implementation convenience.
+ *
+ * @par Meta Data
+ * Meta Data is additional information relating to a
+ * buffer that is distinct from the application data normally held in
+ * the buffer. Implementations MAY choose to implement meta data as
+ * contiguous with a buffer (e.g., in an implementation-managed prefix
+ * area of the buffer) or in a physically separate meta data area
+ * efficiently accessible by the implementation using the same
+ * identifier as the buffer itself. ODP applications MUST NOT make
+ * assumptions about the addressability relationship between a buffer
+ * and its associated meta data, or between meta data items.
+ * Application use of meta data MUST only be via accessor functions.
+ *
+ * @par Note on OPTIONAL APIs
+ * Every conforming ODP implementation MUST
+ * provide implementations for each API described here. if an API is
+ * designated as OPTIONAL, this means that it is acceptable for an
+ * implementation to do nothing except return
+ * ODP_FUNCTION_NOT_AVAILABLE in response to this call. Note that this
+ * may limit the range of ODP applications supported by a given
+ * implementation since applications needing the functionality of the
+ * optional API will likely choose to deploy on other ODP platforms.
+ *
+ * @par
+ * APIs are designated as OPTIONAL under two conditions:
+ *
+ * -# The API is expected to be difficult to provide efficiently on all
+ *  platforms.
+ *
+ * -# A significant number of ODP applications are expected to exist
+ *  that will not need or use this API.
+ *
+ * @par
+ * Under these circumstances, an API is designated as OPTIONAL to
+ * permit ODP implementations to be conformant while still expecting
+ * to be able to run a significant number of ODP applications.
  */
 
 #ifndef ODP_BUFFER_H_
@@ -21,10 +102,9 @@ extern "C" {
 
 #include <odp_std_types.h>
 
-
 /** @defgroup odp_buffer ODP BUFFER
- *  Operations on a buffer.
- *  @{
+ *
+ * @{
  */
 
 /**
@@ -32,62 +112,478 @@ extern "C" {
  */
 typedef uint32_t odp_buffer_t;
 
-#define ODP_BUFFER_INVALID (0xffffffff) /**< Invalid buffer */
+/**
+ * ODP buffer segment
+ */
+typedef uint32_t odp_buffer_segment_t;
+
+/**
+ * ODP Buffer pool
+ */
+typedef uint32_t odp_buffer_pool_t;
+
+/**
+ * ODP buffer type
+ */
+typedef enum odp_buffer_type {
+	ODP_BUFER_TYPE_INVALID  = -1, /**< Buffer type invalid */
+	ODP_BUFFER_TYPE_ANY     = 0,  /**< Buffer type can hold any other
+					 buffer type */
+	ODP_BUFFER_TYPE_RAW     = 1,  /**< Raw buffer,
+					 no additional metadata */
+	ODP_BUFFER_TYPE_PACKET  = 2,  /**< Packet buffer */
+	ODP_BUFFER_TYPE_TIMEOUT = 3,  /**< Timeout buffer */
+} odp_buffer_type_e;
 
+/**
+ * ODP buffer options
+ *
+ * @note These options are additive so an application can simply
+ * specify a buf_opts by ORing together the options needed. Note that
+ * buffer pool options are themselves OPTIONAL and a given
+ * implementation MAY fail the buffer pool creation request with an
+ * appropriate errno if the requested option is not supported by the
+ * underlying ODP implementation, with the exception that UNSEGMENTED
+ * pools MUST be supported for non-packet types and for packet types
+ * as long as the requested size is less than the
+ * implementation-defined native packet segment size.
+ *
+ * Use ODP_BUFFER_OPTS_NONE to specify default buffer pool options
+ * with no additions. The ODP_BUFFER_OPTS_UNSEGMENTED option
+ * specifies that the buffer pool should be unsegmented.
+ *
+ * @par Segmented vs. Unsegmented Buffer Pools
+ * By default, the buffers
+ * in ODP buffer pools are logical buffers that support transparent
+ * segmentation managed by ODP on behalf of the application and have a
+ * rich set of associated semantics as described here.
+ * ODP_BUFFER_OPTS_UNSEGMENTED indicates that the buf_size specified
+ * for the pool should be regarded as a fixed buffer size for all pool
+ * elements and that segmentation support is not needed for the pool.
+ * This MAY result in greater efficiency on some implementations. For
+ * packet processing, a typical use of unsegmented pools would be in
+ * conjunction with classification rules that sort packets into
+ * different pools based on their lengths, thus ensuring that each
+ * packet occupies a single segment within an appropriately-sized
+ * buffer.
+ */
+ typedef enum odp_buffer_opts {
+	 ODP_BUFFER_OPTS_NONE,        /**< Default, no buffer options */
+	 ODP_BUFFER_OPTS_UNSEGMENTED, /**< Reqest this pool contain unsegmented
+                                           buffers */
+ } odp_buffer_opts_e;
+
+/**
+ * Error returns
+ */
+#define ODP_BUFFER_INVALID (odp_buffer_t)(-1)
 
 /**
  * Buffer start address
  *
- * @param buf      Buffer handle
+ * @param[in] buf  Buffer handle
  *
  * @return Buffer start address
  */
 void *odp_buffer_addr(odp_buffer_t buf);
 
 /**
- * Buffer maximum data size
+ * Buffer application data size
+ *
+ * @param[in] buf  Buffer handle
  *
- * @param buf      Buffer handle
+ * @return Buffer application data size
  *
- * @return Buffer maximum data size
+ * @note The size returned by this rouine is the size of the
+ * application data contained within the buffer and does not include
+ * any inplementation-defined overhead to support meta data, etc. ODP
+ * does not define APIs for determining the amount of storage that is
+ * physically allocated by an implementation to support ODP buffers.
  */
 size_t odp_buffer_size(odp_buffer_t buf);
 
 /**
  * Buffer type
  *
- * @param buf      Buffer handle
+ * @param[in] buf    Buffer handle
  *
  * @return Buffer type
  */
-int odp_buffer_type(odp_buffer_t buf);
+odp_buffer_type_e odp_buffer_type(odp_buffer_t buf);
 
-#define ODP_BUFFER_TYPE_INVALID (-1) /**< Buffer type invalid */
-#define ODP_BUFFER_TYPE_ANY       0  /**< Buffer that can hold any other
-					  buffer type */
-#define ODP_BUFFER_TYPE_RAW       1  /**< Raw buffer, no additional metadata */
-#define ODP_BUFFER_TYPE_PACKET    2  /**< Packet buffer */
-#define ODP_BUFFER_TYPE_TIMEOUT   3  /**< Timeout buffer */
+/**
+ * Get address and size of user meta data for buffer
+ *
+ * @param[in]  buf        Buffer handle
+ * @param[out] udata_size Number of bytes of user meta data available
+ *                        at the returned address
+ * @return                Address of the user meta data for this buffer
+ *                        or NULL if the buffer has no user meta data.
+ */
+void *odp_buffer_udata(odp_buffer_t buf, size_t *udata_size);
 
+/**
+ * Get address of user meta data for buffer
+ *
+ * @param[in] buf         Buffer handle
+ *
+ * @return                Address of the user meta data for this buffer
+ *                        or NULL if the buffer has no user meta data.
+ *
+ * @note This is a "fastpath" version of odp_buffer_udata() since it
+ * omits returning the size of the user meta data area. Callers are
+ * expected to know and honor this limit nonetheless.
+ */
+void *odp_buffer_udata_addr(odp_buffer_t buf);
 
 /**
  * Tests if buffer is valid
  *
- * @param buf      Buffer handle
+ * @param[in] buf    Buffer handle
  *
  * @return 1 if valid, otherwise 0
+ *
+ * @note Since buffer operations typically occur in fastpath sections
+ * of applications, by default most ODP APIs assume that valid buffer
+ * handles are passed to them and results are undefined if this
+ * assumption is not met. This routine exists to enable an
+ * application to request explicit validation of a buffer handle. It
+ * is understood that the performance of this operation MAY vary
+ * considerably on a per-implementation basis.
  */
 int odp_buffer_is_valid(odp_buffer_t buf);
 
 /**
+ * Tests if buffer is segmented
+ *
+ * @param[in] buf    Buffer handle
+ *
+ * @return 1 if buffer has more then one segment, otherwise 0
+ *
+ * @note This routine behaves identically to the test
+ * odp_buffer_segment_count() > 1, but is potentially more efficient
+ * and represents the preferred method of determining a buffer's
+ * segmentation status.
+ */
+int odp_buffer_is_segmented(odp_buffer_t buf);
+
+/**
  * Print buffer metadata to STDOUT
  *
- * @param buf      Buffer handle
+ * @param[in] buf    Buffer handle
  *
+ * @note This routine is intended for diagnostic use and prints
+ * implementation-defined information concerning the buffer to the ODP
+ * LOG. It's provision is OPTIONAL.
  */
 void odp_buffer_print(odp_buffer_t buf);
 
 /**
+ * Get count of number of segments in a buffer
+ *
+ * @param[in] buf    Buffer handle
+ *
+ * @return           Count of the number of segments in buf
+ */
+size_t odp_buffer_segment_count(odp_buffer_t buf);
+
+/**
+ * Get the segment identifier for a buffer segment by index
+ *
+ * @param[in] buf    Buffer handle
+ * @param[in] ndx    Segment index of segment of interest
+ *
+ * @return           Segment handle or ODP_SEGMENT_INVALID if the
+ *                   supplied ndx is out of range.
+ */
+odp_buffer_segment_t odp_buffer_segment_by_index(odp_buffer_t buf, size_t ndx);
+
+/**
+ * Get the next segment handle for a buffer segment
+ *
+ * @param[in] buf    Buffer handle
+ * @param[in] seg    Segment identifier of the previous segment
+ *
+ * @return           Segment identifier of next segment or ODP_SEGMENT_INVALID
+ *
+ * @note This routine returns the identifier (odp_buffer_segment_t) of
+ * the next buffer segment in a buffer aggregate. The input
+ * specifies the buffer and the previous segment identifier. There are
+ * three use cases for this routine:
+ * @par
+ * -# If the input seg is ODP_SEGMENT_START then the segment identifier returned
+ * is that of the first segment in the buffer. ODP_SEGMENT_NULL MAY be used
+ * as a synonym for ODP_SEGMENT_START for symmetry if desired.
+ *
+ * -# If the input seg is not the last segment in the buffer then the
+ * segment handle of the next segment following seg is returned.
+ *
+ * -# If the input seg is the segment identifier of the last segment in
+ * the buffer then ODP_SEGMENT_NULL is returned.
+ *
+ */
+odp_buffer_segment_t odp_buffer_segment_next(odp_buffer_t buf,
+					     odp_buffer_segment_t seg);
+
+/**
+ * Get addressability for a specified buffer segment
+ *
+ * @param[in] buf     Buffer handle
+ * @param[in] seg     Segment handle of the segment to be mapped
+ * @param[in] seglen  Returned number of bytes in this buffer segment
+ *                    available at the returned address
+ *
+ * @return            Segment start address or NULL
+ *
+ * @note This routine is used to obtain addressability to a segment within
+ * a buffer aggregate at a specified segment identifier. The returned seglen
+ * indicates the number of bytes addressable at the returned address.
+ */
+void *odp_buffer_segment_map(odp_buffer_t buf, odp_buffer_segment_t seg,
+			     size_t *seglen);
+
+/**
+ * Unmap a buffer segment
+ *
+ * @param[in] seg     Buffer segment handle
+ *
+ * @note This routine is used to unmap a buffer segment previously
+ *  mapped by odp_buffer_segment_map(). Following this call,
+ *  applications MUST NOT attempt to reference the segment via any
+ *  pointer returned from a previous odp_buffer_segment_map() call
+ *  referring to it. It is intended to allow certain NUMA
+ *  architectures to better manage the coherency of mapped segments.
+ *  For non-NUMA architectures this routine will be a no-op. Note
+ *  that implementations SHOULD implicitly unmap all buffer segments
+ *  whenever a buffer is added to a queue as this indicates that the
+ *  caller is relinquishing control of the buffer.
+ */
+void odp_buffer_segment_unmap(odp_buffer_segment_t seg);
+
+/**
+ * Get start address for a specified buffer offset
+ *
+ * @param[in]  buf     Buffer handle
+ * @param[in]  offset  Byte offset within the buffer to be addressed
+ * @param[out] seglen  Returned number of bytes in this buffer
+ *                     segment available at returned address
+ *
+ * @return             Offset start address or NULL
+ *
+ * @note This routine is used to obtain addressability to a segment
+ * within a buffer at a specified byte offset. Note that because the
+ * offset is independent of any implementation-defined physical
+ * segmentation the returned seglen may be “short” and will range from
+ * 1 to whatever physical segment size is used by the underlying
+ * implementation.
+ */
+void *odp_buffer_offset_map(odp_buffer_t buf, size_t offset,
+                            size_t *seglen);
+
+/**
+ * Unmap a buffer segment by offset
+ *
+ * @param[in] buf    Buffer handle
+ * @param[in] offset Buffer offset
+ *
+ * @note This routine is used to unmap a buffer segment previously
+ * mapped by odp_buffer_offset_map(). Following this call
+ * the application MUST NOT attempt to reference the segment via any
+ * pointer returned by a prior odp_buffer_offset_map() call relating
+ * to this offset. It is intended to allow certain NUMA architectures
+ * to better manage the coherency of mapped segments. For non-NUMA
+ * architectures this routine will be a no-op. Note that
+ * implementations SHOULD implicitly unmap all buffer segments
+ * whenever a buffer is added to a queue as this indicates that the
+ * caller is relinquishing control of the buffer.
+ */
+void odp_buffer_offset_unmap(odp_buffer_t buf, size_t offset);
+
+/**
+ * Split a buffer into two buffers at a specified split point
+ *
+ * @param[in] buf    Handle of buffer to split
+ * @param[in] offset Byte offset within buf to split buffer
+ *
+ * @return           Buffer handle of the created split buffer
+ *
+ * @note This routine splits a buffer into two buffers at the
+ * specified byte offset. The odp_buffer_t returned by the function
+ * is the handle of the new buffer created at the split point. If the
+ * original buffer was allocated from a buffer pool then the split is
+ * allocated from the same pool. If the original buffer was size
+ * bytes in length then upon return the original buffer is of size
+ * offset while the split buffer is of size (size-offset).
+ *
+ * @par
+ * This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns ODP_BUFFER_INVALID with an errno of
+ * ODP_FUNCTION_NOT_AVAILABLE.
+ *
+ * @par
+ * Upon return from this function, the system meta data for both
+ * buffers has been updated appropriately by the call since system
+ * meta data maintenance is the responsibility of the ODP
+ * implementation. Any required updates to the user meta data is the
+ * responsibility of the caller.
+ */
+odp_buffer_t odp_buffer_split(odp_buffer_t buf, size_t offset);
+
+/**
+ * Join two buffers into a single buffer
+ *
+ * @param[in] buf1  Buffer handle of first buffer to join
+ * @param[in] buf2  Buffer handle of second buffer to join
+ *
+ * @return          Buffer handle of the joined buffer
+ *
+ * @note This routine joins two buffers into a single buffer. Both
+ * buf1 and buf2 MUST be from the same buffer pool and the resulting
+ * joined buffer will be an element of that same pool. The
+ * application MUST NOT assume that either buf1 or buf2 survive the
+ * join or that the returned joined buffer is contiguous with or
+ * otherwise related to the input buffers. An implementation SHOULD
+ * free either or both input buffers if they are not reused as part of
+ * the construction of the returned joined buffer. If the join cannot
+ * be performed (e.g., if the two input buffers are not from the same
+ * buffer pool, insufficient space in the target buffer pool, etc.)
+ * then ODP_BUFFER_INVALID SHOULD be returned to indicate that the
+ * operation could not be performed, and an appropriate errno set. In
+ * such case the input buffers MUST NOT be freed as part of the failed
+ * join attempt and should be unchanged from their input values and
+ * content.
+ *
+ * @par The result of odp_buffer_join() is the logical concatenation
+ * of the two buffers using an implementation-defined buffer
+ * aggregation mechanism. The application data contents of the
+ * returned buffer is identical to that of the two joined input
+ * buffers however certain associated meta data (e.g., information
+ * about the buffer size) will likely differ.
+ *
+ * @par If user meta data is present in the buffer pool containing the
+ * input buffers, then the user meta data associated with the returned
+ * buffer MUST be copied by this routine from the source buf1.
+ *
+ * @par This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a routine matching that simply
+ * returns ODP_BUFFER_INVALID with an errno of
+ * ODP_FUNCTION_NOT_AVAILABLE.
+ */
+odp_buffer_t odp_buffer_join(odp_buffer_t buf1, odp_buffer_t buf2);
+
+/**
+ * Trim a buffer at a specified trim point
+ *
+ * @param[in] buf    buffer handle of buffer to trim
+ * @param[in] offset byte offset within buf to trim
+ *
+ * @return           Handle of the trimmed buffer or ODP_BUFFER_INVALID
+ *                   if the operation was not performed
+ *
+ * @note This routine discards bytes from the end of a buffer. It is
+ * logically equivalent to a split followed by a free of the split
+ * portion of the input buffer. The input offset must be less than or
+ * equal to the odp_buffer_size() of the input buffer. Upon
+ * successful return the odp_buffer_size() routine would now return
+ * offset as the size of the trimmed buffer. Note that the returned
+ * odp_buffer_t may not necessarily be the same as the input
+ * odp_buffer_t. The caller should use the returned value when
+ * referencing the trimmed buffer instead of the original in case they
+ * are different.
+ *
+ * @par If the input buf contains user meta data, then this data MUST
+ * be copied to the returned buffer if needed by the API
+ * implementation.
+ *
+ * @par This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns ODP_BUFFER_INVALID with an errno of
+ * ODP_FUNCTION_NOT_AVAILABLE.
+ */
+odp_buffer_t odp_buffer_trim(odp_buffer_t buf, size_t offset);
+
+/**
+ * Extend a buffer for a specified number of bytes
+ *
+ * @param[in] buf  buffer handle of buffer to expand
+ * @param[in] ext  size, in bytes, of the extent to add to the
+ *                 existing buffer.
+ *
+ * @return         Handle of the extended buffer or ODP_BUFFER_INVALID
+ *                 if the operation was not performed
+ *
+ * @note This routine extends a buffer by increasing its size by ext
+ * bytes. It is logically equivalent to an odp_buffer_join() of a
+ * buffer of size ext to the original buffer. Upon successful return
+ * the odp_buffer_size() routine would now return size+ext as the size
+ * of the extended buffer.
+ *
+ * @par Note that the returned odp_buffer_t may not necessarily be the
+ * same as the input odp_buffer_t. The caller should use the returned
+ * value when referencing the extended buffer instead of the original
+ * in case they are different. If the input buf contains user meta
+ * data, then this data MUST be copied to the returned buffer if
+ * needed by the API implementation.
+ *
+ * @par This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns ODP_BUFFER_INVALID with an errno of
+ * ODP_FUNCTION_NOT_AVAILABLE.
+ */
+odp_buffer_t odp_buffer_extend(odp_buffer_t buf, size_t ext);
+
+/**
+ * Clone a buffer, returning an exact copy of it
+ *
+ * @param[in] buf  buffer handle of buffer to duplicate
+ *
+ * @return         Handle of the duplicated buffer or ODP_BUFFER_INVALID
+ *                 if the operation was not performed
+ *
+ * @note This routine allows an ODP buffer to be cloned in an
+ * implementation-defined manner. The application data contents of
+ * the returned odp_buffer_t is an exact copy of the application data
+ * of the input buffer. The implementation MAY perform this operation
+ * via reference counts, resegmentation, or any other technique it
+ * wishes to employ. The cloned buffer is an element of the same
+ * buffer pool as the input buf. If the input buf contains user meta
+ * data, then this data MUST be copied to the returned buffer by the
+ * ODP implementation.
+ *
+ * @par This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns ODP_BUFFER_INVALID with an errno of
+ * ODP_FUNCTION_NOT_AVAILABLE.
+ */
+odp_buffer_t odp_buffer_clone(odp_buffer_t buf);
+
+/**
+ * Copy a buffer, returning an exact copy of it
+ *
+ * @param[in] buf  buffer handle of buffer to copy
+ * @param[in] pool buffer pool to contain the copied buffer
+ *
+ * @return         Handle of the copied buffer or ODP_BUFFER_INVALID
+ *                 if the operation was not performed
+ *
+ * @note This routine allows an ODP buffer to be copied in an
+ * implementation-defined manner to a specified buffer pool. The
+ * specified pool may or may not be different from the source buffer’s
+ * pool. The application data contents of the returned odp_buffer_t
+ * is an exact separate copy of the application data of the input
+ * buffer. If the input buf contains user meta data, then this data
+ * MUST be copied to the returned buffer by the ODP implementation.
+ *
+ * @par This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns ODP_BUFFER_INVALID with an errno of
+ * ODP_FUNCTION_NOT_AVAILABLE.
+ */
+odp_buffer_t odp_buffer_copy(odp_buffer_t buf, odp_buffer_pool_t pool);
+
+
+/**
  * @}
  */
 
diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h b/platform/linux-generic/include/api/odp_buffer_pool.h
index d04abf0..a9861be 100644
--- a/platform/linux-generic/include/api/odp_buffer_pool.h
+++ b/platform/linux-generic/include/api/odp_buffer_pool.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2013, Linaro Limited
+/* Copyright (c) 2013-2014, Linaro Limited
  * All rights reserved.
  *
  * SPDX-License-Identifier:     BSD-3-Clause
@@ -8,7 +8,44 @@
 /**
  * @file
  *
- * ODP buffer pool
+ * @par Buffer Pools
+ * Buffers are elements of buffer pools that represent an equivalence
+ * class of buffer objects that are managed by a buffer pool manager.
+ * ODP implementations MAY support buffer pool managers implemented in
+ * hardware, software, or a combination of the two. An ODP
+ * implementation MUST support at least one buffer pool and MAY
+ * support as many as it wishes. The implementation MAY support one
+ * or more predefined buffer pools that are not explicitly allocated
+ * by an ODP application. It SHOULD also support application creation
+ * of buffer pools via the odp_buffer_pool_create() API, however it
+ * MAY restrict the types of buffers that can be so created.
+ *
+ * @par
+ * Buffer pools are represented by the abstract type odp_buffer_pool_t
+ * that is returned by buffer pool creation and lookup/enumeration
+ * routines. Applications refer to buffer pools via a name of
+ * implementation-defined maximum length that MUST be a minimummap of
+ * eight characters in length and MAY be longer. It is RECOMMENDED
+ * that 32 character buffer pool names be supported to provide
+ * application naming flexibility. The supported maximum length of
+ * buffer pool names is exposed via the ODP_BUFFER_POOL_NAME_LEN
+ * predefined implementation limit.
+ *
+ * @par Segmented vs. Unsegmented Buffer Pools
+ * By default, the buffers in
+ * ODP buffer pools are logical buffers that support transparent
+ * segmentation managed by ODP on behalf of the application and have a
+ * rich set of associated semantics as described here.
+ * ODP_BUFFER_OPTS_UNSEGMENTED indicates that the buf_size specified
+ * for the pool should be regarded as a fixed buffer size for all pool
+ * elements and that segmentation support is not needed for the pool.
+ * This MAY result in greater efficiency on some implementations. For
+ * packet processing, a typical use of unsegmented pools would be in
+ * conjunction with classification rules that sort packets into
+ * different pools based on their lengths, thus ensuring that each
+ * packet occupies a single segment within an appropriately-sized
+ * buffer.
+ *
  */
 
 #ifndef ODP_BUFFER_POOL_H_
@@ -35,42 +72,217 @@ extern "C" {
 #define ODP_BUFFER_POOL_INVALID   0
 
 /** ODP buffer pool */
-typedef uint32_t odp_buffer_pool_t;
+// typedef uint32_t odp_buffer_pool_t;
+
+/**
+ * Buffer initialization routine prototype
+ *
+ * @note Routines of this type MAY be passed as part of the
+ * odp_buffer_pool_init_t structure to be called whenever a
+ * buffer is allocated to initialize the user meta data
+ * associated with that buffer.
+ */
+typedef void (odp_buf_init_t)(odp_buffer_t buf, void *buf_init_arg);
+
+/**
+ * Buffer pool parameters
+ *
+ * @param[in] buf_num    Number of buffers that pool should contain
+ * @param[in] buf_size   Size of application data in each buffer
+ * @param[in] buf_type   Buffer type
+ * @param[in] buf_opts   Buffer options
+ */
+typedef struct odp_buffer_pool_param_t {
+        size_t buf_num;             /**< Number of buffers in this pool */
+	size_t buf_size;            /**< Application data size of each buffer */
+	odp_buffer_type_e buf_type; /**< Buffer type */
+	odp_buffer_opts_e buf_opts; /**< Buffer options */
+} odp_buffer_pool_param_t;          /**< Type of buffer pool parameter struct */
 
+/**
+ * Buffer pool initialization parameters
+ *
+ * @param[in] udata_size     Size of the user meta data for each buffer
+ * @param[in] buf_init       Function pointer to be called to initialize the
+ *                           user meta data for each buffer in the pool.
+ * @param[in] buf_init_arg   Argument to be passed to buf_init().
+ *
+ */
+typedef struct odp_buffer_pool_init_t {
+        size_t udata_size;         /**< Size of user meta dat for each buffer */
+        odp_buf_init_t *buf_init;  /**< Buffer initialization routine to use */
+        void *buf_init_arg;        /**< Argument to be passed to buf_init() */
+} odp_buffer_pool_init_t;          /**< Type of buffer initialization struct */
 
 /**
  * Create a buffer pool
  *
- * @param name      Name of the pool (max ODP_BUFFER_POOL_NAME_LEN - 1 chars)
- * @param base_addr Pool base address
- * @param size      Pool size in bytes
- * @param buf_size  Buffer size in bytes
- * @param buf_align Minimum buffer alignment
- * @param buf_type  Buffer type
+ * @param[in] name           Name of the pool
+ *                           (max ODP_BUFFER_POOL_NAME_LEN - 1 chars)
+ *
+ * @param[in] params         Parameters controlling the creation of this
+ *                           buffer pool
+ *
+ * @param[in] init_params    Parameters controlling the initialization of
+ *                           this buffer pool
  *
- * @return Buffer pool handle
+ * @return Buffer pool handle or ODP_BUFFER_POOL_NULL with errno set
+ *
+ * @note This routine is used to create a buffer pool. It takes three
+ * arguments: the name of the pool to be created, a parameter
+ * structure that controls the pool creation, and an optional
+ * parameter that controls pool initialization. In the creation
+ * parameter structure, the application specifies the number of
+ * buffers that the pool should contain as well as the application
+ * data size for each buffer in the pool, the type of buffers it
+ * should contain, and their associated options. In the
+ * initialization parameters, the application specifies the size of
+ * the user meta data that should be associated with each buffer in
+ * the pool. If no user meta data is required, the init_params SHOULD
+ * be specified as NULL. If user meta data is requested, then
+ * udata_size SHOULD be set to the requested size of the per-buffer
+ * user meta data. Also specified is the address of an
+ * application-provided buffer initialization routine to be called for
+ * each buffer in the pool at the time the pool is initialized, or
+ * when the buffer is allocated. If no application buffer
+ * initialization is needed, then buf_init and buf_init_arg SHOULD be
+ * set to NULL.
  */
 odp_buffer_pool_t odp_buffer_pool_create(const char *name,
-					 void *base_addr, uint64_t size,
-					 size_t buf_size, size_t buf_align,
-					 int buf_type);
-
+                                         odp_buffer_pool_param_t *params,
+                                         odp_buffer_pool_init_t *init_params);
 
 /**
  * Find a buffer pool by name
  *
- * @param name      Name of the pool
+ * @param[in] name  Name of the pool
  *
  * @return Buffer pool handle, or ODP_BUFFER_POOL_INVALID if not found.
  */
 odp_buffer_pool_t odp_buffer_pool_lookup(const char *name);
 
+/**
+ * Get the next buffer pool from its predecessor
+ *
+ * @param[in]  pool       Buffer pool handle
+ * @param[out] name       Name of the pool
+ *                        (max ODP_BUFFER_POOL_NAME_LEN - 1 chars)
+ * @param[out] udata_size Size of user meta data used by this pool.
+ * @param[out] params     Output structure for pool parameters
+ * @param[out] predef     Predefined (1) or Created (0).
+ *
+ * @return                Buffer pool handle
+ *
+ * @note This routine returns the abstract identifier
+ * (odp_buffer_pool_t) of a buffer pool and is used to obtain the list
+ * of all buffer pools. In this manner an application can discover
+ * both application created and implementation predefined buffer pools
+ * and their characteristics. The input specifies the previous buffer
+ * pool identifier. There are three use cases for this
+ * routine:
+ *
+ * -# If the input pool is ODP_BUFFER_POOL_START then the buffer pool handle
+ * returned is that of the first buffer pool in the list.
+ * ODP_BUFFER_POOL_NULL MAY be used as a synonym for ODP_BUFFER_POOL_START
+ * if desired.
+ *
+ * -# If the input pool is not the last element in the buffer pool list
+ * then the buffer pool handle of the next buffer pool following  pool is
+ * returned.
+ *
+ * -# If the input pool is the buffer pool handle of the last buffer pool
+ * in the list then ODP_BUFFER_POOL_NULL is returned.
+ *
+ * Returned with the buffer pool handle is the name of the pool as
+ * well as its dimensions, type of buffers it contains, and a flag
+ * that says whether the pool is predefined or was created by the
+ * application. Note that the buf_size reported for a buffer pool is
+ * simply the declared expected size of the buffers in the pool and
+ * serves only to estimate the total amount of application data that
+ * can be stored in the pool. Actual sizes of individual buffers
+ * within the pool are dynamic and variable since physical buffer
+ * segments MAY be aggregated to create buffers of arbitrary size (up
+ * to the pool memory limits). Note that for predefined buffer pools,
+ * some implementations MAY return the physical segment counts and
+ * sizes used to construct the pool as output of this routine.
+ */
+odp_buffer_pool_t odp_buffer_pool_next(odp_buffer_pool_t pool,
+                                       char *name, size_t *udata_size,
+                                       odp_buffer_pool_param_t *params,
+                                       int *predef);
+
+/**
+ * Get the high/low watermarks for a buffer pool
+ *
+ * @param[in]  pool     Handle of the buffer pool
+ * @param[out] high_wm  The high water mark of the designated buffer pool
+ * @param[out] low_wm   The low water mark of the designated buffer pool
+ *
+ * @return Success or ODP_BUFFER_POOL_INVALID if pool is unknown
+ *                 or ODP_BUFFER_POOL_NO_WATERMARKS if no watermarks
+ *                 are associated with this buffer pool.
+ *
+ * @note This routine gets the high/low watermarks associated with a
+ * given buffer pool. If the buffer pool does not have or support
+ * watermarks then an error will be returned and both high_wm and
+ * low_wm will be unchanged.
+ *
+ * @par
+ * It is RECOMMENDED that buffer pools of all types support the setting
+ * and getting of watermarks for use in flow control processing.
+ * Watermarks are designed to trigger flow control actions based on
+ * utilization levels of a buffer pool. When the number of free
+ * buffers in the buffer pool hits the configured low watermark for
+ * the pool, the pool asserts a low watermark condition and an
+ * implementation-defined action in response to this condition is
+ * triggered. Once in a low watermark state, the condition is
+ * maintained until the number of free buffers reaches the configured
+ * high watermark. At this point the low watermark condition is
+ * deasserted and normal pool processing resumes. Having separate
+ * high and low watermarks permits configurable hysteresis to avoid
+ * jitter in handling transient buffer shortages in the pool.
+ *
+ * @par
+ * In general, two types of actions are common. The first is to
+ * control Random Early Detection (RED) or Weighted RED (WRED)
+ * processing for the pool, while the second is to control IEEE
+ * 802.1Qbb priority-based flow control (PFC) processing for so-called
+ * “lossless Ethernet” support. The use of watermarks for flow
+ * control processing is most often used for pools containing packets
+ * and this is discussed in further detail in the Class of Service
+ * (CoS) ODP Classification APIs.
+ *
+ */
+int odp_buffer_pool_watermarks(odp_buffer_pool_t pool,
+                               size_t *high_wm, size_t *low_wm);
+
+/**
+ * Set the high/low watermarks for a buffer pool
+ *
+ * @param[in] pool      Handle of the buffer pool
+ * @param[in] high_wm   The high water mark of the designated buffer pool
+ * @param[in] low_wm    The low water mark of the designated buffer pool
+ *
+ * @return Success or ODP_BUFFER_POOL_INVALID if pool is unknown
+ *                 or ODP_BUFFER_POOL_NO_WATERMARKS if no watermarks
+ *                 are associated with this buffer pool.
+ *
+ * @note This routine sets the high/low watermarks associated with a
+ * specified buffer pool. If the buffer pool does not support
+ * watermarks then errno ODP_BUFFER_POOL_NO_WATERMARKS is set and no
+ * function is performed.
+ */
+int odp_buffer_pool_set_watermarks(odp_buffer_pool_t pool,
+                                   size_t high_wm, size_t low_wm);
 
 /**
  * Print buffer pool info
  *
- * @param pool      Pool handle
+ * @param[in] pool   Pool handle
  *
+ * @note This is a diagnostic routine that prints statistics regarding
+ * the specified buffer pool to the ODP LOG. This routine is OPTIONAL
+ * and if present its output is implementation-defined.
  */
 void odp_buffer_pool_print(odp_buffer_pool_t pool);
 
diff --git a/platform/linux-generic/include/api/odp_packet.h b/platform/linux-generic/include/api/odp_packet.h
index 688e047..9e8410b 100644
--- a/platform/linux-generic/include/api/odp_packet.h
+++ b/platform/linux-generic/include/api/odp_packet.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2013, Linaro Limited
+/* Copyright (c) 2013-2014, Linaro Limited
  * All rights reserved.
  *
  * SPDX-License-Identifier:     BSD-3-Clause
@@ -8,7 +8,261 @@
 /**
  * @file
  *
- * ODP packet descriptor
+ * @par ODP Packet Management APIs
+ * Described here are the fundamental
+ * concepts and supporting APIs of the ODP Packet Management routines.
+ * All conforming ODP implementations MUST provide these data types
+ * and APIs. Latitude in how routines MAY be implemented are noted
+ * when applicable.
+ *
+ * @par Inherited and New Concepts
+ * As a type of buffer, packets are
+ * allocated from its containing buffer pool created via
+ * odp_buffer_pool_create() with a buffer type of
+ * ODP_BUFFER_TYPE_PACKET. Packets are referenced by an abstract
+ * odp_packet_t handle defined by each implementation.
+ *
+ * @par
+ * Packet objects are normally created at ingress when they arrive
+ * at a source odp_pktio_t and are received by an application either
+ * directly or (more typically) via a scheduled receive queue. They
+ * MAY be implicitly freed when they are transmitted to an output
+ * odp_pktio_t via an associated transmit queue, or freed directly via
+ * the odp_packet_free() API.
+ *
+ * @par
+ * Packets contain additional system meta data beyond those found
+ * in buffers that is populated by the parse function of the ODP
+ * classifier. See below for a discussion of this meta data and the
+ * accessor functions provided for application reference to them.
+ *
+ * @par
+ * Occasionally an application may originate a packet itself,
+ * either de novo or by deriving it from an existing packet, and APIs
+ * are provided to assist in these cases as well. Application-created
+ * packets can be recycled back through a loopback interface to reparse
+ * and reclassify them, or the application can explicitly re-invoke the
+ * parser or do its own parsing as desired. This can also occur as a
+ * result of packet decryption or decapsulation when dealing with
+ * ingress tunnels. See the ODP classification design document for
+ * further details. Additionally, the meta data set as a result of
+ * parsing MAY be directly set by the application as needed.
+ *
+ * @par Packet Structure and Concepts
+ * A packet consists of a sequence
+ * of octets conforming to an architected format, such as Ethernet,
+ * that can be received and transmitted via the ODP pktio abstraction.
+ * Packets have a length, which is the number of bytes in the packet.
+ * Packet data in ODP is referenced to via offsets since these reflect
+ * the logical contents and structure of a packet independent of how
+ * particular ODP implementations store that data.
+ *
+ * @par
+ * These concepts are shown in the following diagram:
+ *
+ * @image html packet.png "ODP Packet Structure" width=\textwidth
+ * @image latex packet.eps "ODP Packet Structure" width=\textwidth
+ *
+ * @par
+ * Packet data consists of zero or more headers, followed by 0 or
+ * more bytes of payload, followed by zero or more trailers.
+ *
+ * @par
+ * Packet Segments and Addressing Network SoCs use various
+ * methods and techniques to store and process packets efficiently.
+ * These vary considerably from platform to platform, so to ensure
+ * portability across them ODP adopts certain conventions for
+ * referencing packets.
+ *
+ * @par
+ * ODP APIs use a handle of type odp_packet_t to refer to packet
+ * objects. Associated with packets are various bits of system meta
+ * data that describe the packet. By referring to the meta data, ODP
+ * applications accelerate packet processing by minimizing the need to
+ * examine packet data. This is because the packet meta data is
+ * populated by parsing and classification functions that are coupled
+ * to ingress processing that occur prior to a packet being presented
+ * to the application via the ODP scheduler.
+ *
+ * @par
+ * When an ODP implementation needs to examine the contents of a
+ * packet, it requests addressability to it via a mapping API that
+ * makes the packet (or a contiguously addressable segment of it)
+ * available for coherent access by the application. While ODP
+ * applications MAY request that packets be stored in unsegmented
+ * buffer pools, not all platforms supporting ODP are able to provide
+ * contiguity guarantees for packets and as a result such requests may
+ * either fail or else result in degraded performance compared to
+ * native operation.
+ *
+ * @par
+ * Instead, ODP applications SHOULD assume that the underlying
+ * implementation stores packets in segments of implementation-defined
+ * and managed size. These represent the contiguously addressable
+ * portions of a packet that the application may refer to via normal
+ * memory accesses. ODP provides APIs that allow applications to
+ * operate on packet segments in an efficient and portable manner as
+ * needed. By combining these with the meta data provided for
+ * packets, ODP applications can operate in a fully
+ * platform-independent manner while still achieving optimal
+ * performance across the range of platforms that support ODP.
+ *
+ * @par
+ * The use of segments for packet addressing and their
+ * relationship to meta data is shown in this diagram:
+ *
+ * @image html segments.png "ODP Packet Segmentation Structure" width=\textwidth
+ * @image latex segments.eps "ODP Packet Segmentation Structure" width=\textwidth
+ *
+ * @par
+ * The packet meta data is set during parsing and identifies the
+ * starting offsets of the various headers contained in the packet.
+ * The packet itself is physically stored as a sequence of segments
+ * that are managed by the ODP implementation. Segment 0 is the first
+ * segment of the packet and is where the packet’s headroom and
+ * headers typically reside. Depending on the length of the packet,
+ * additional segments may be part of the packet and contain the
+ * remaining packet payload and tailroom. The application need not
+ * concern itself with segments except that when the application
+ * requires addressability to a packet it understands that
+ * addressability is provided on a per-segment basis. So, for
+ * example, if the application makes a call like
+ * odp_packet_payload_map() to obtain addressability to the packet
+ * payload, the returned seglen from that call is the number of bytes
+ * from the start of the payload that are contiguously addressable to
+ * the application from the returned payload address. This is because
+ * the following byte occupies a different segment that may be stored
+ * elsewhere. To obtain access to those bytes, the application simply
+ * requests addressability to that offset and it will be able to
+ * address the payload bytes that occupy segment 1, etc. Note that
+ * the returned seglen for any mapping call is always the lesser of
+ * the remaining packet length and the size of its containing segment.
+ * So a mapping request for segment 2, for example, would return a
+ * seglen that extends only to the end of the packet since the
+ * remaining bytes are part of the tailroom reserved for the packet
+ * and are not usable by the application until made available to it by
+ * an appropriate API call.
+ *
+ * @par Headroom and Tailroom
+ * Because data plane applications will
+ * often manipulate packets by adding or removing headers and/or
+ * trailers, ODP implementations MUST support the concepts of headroom
+ * and tailroom for packets. How implementations choose to support
+ * these concepts is unspecified by ODP.
+ *
+ * @par
+ * Headroom is an area that logically prepends the start of a
+ * packet and is reserved for the insertion of additional header
+ * information to the front of a packet. Typical use of headroom
+ * might be packet encapsulation as part of tunnel operations.
+ * Tailroom is a similar area that logically follows a packet reserved
+ * for the insertion of trailer information at the end of a packet.
+ * Typical use of tailroom might be in payload manipulation or in
+ * additional checksum insertion. The idea behind headroom and
+ * tailroom is to support efficient manipulation of packet headers
+ * and/or trailers by preallocating buffer space and/or meta data to
+ * support the insertion of packet headers and/or trailers while
+ * avoiding the overhead of more general split/join buffer operations.
+ *
+ * @par
+ * Note that not every application or communication protocol will
+ * need these and ODP implementations MAY impose restrictions or
+ * modifications on when and how these capabilities are used. For
+ * example, headroom MAY indicate the byte offset into a packet buffer
+ * at which packet data is received from an associated odp_pktio_t.
+ * An implementation MAY add to the requested headroom or tailroom for
+ * implementation-defined alignment or other reasons. Note also that
+ * implementations MUST NOT assume that headroom and/or tailroom is
+ * necessarily contiguous with any other segment of the packet unless
+ * the underlying buffer pool the packet has been allocated from has
+ * been explicitly defined as unsegmented. See the ODP Buffer API
+ * design for discussion of segmented vs. unsegmented buffers and
+ * their implementation models. This convention is observed
+ * automatically because every mapping call returns a corresponding
+ * seglen that tells the application the number of bytes it may
+ * reference from the address returned by that call. Applications
+ * MUST observe these limits to avoid programming errors and
+ * portability issues.
+ *
+ * @par Packet Parsing and Inflags
+ * ODP packets are intended to be
+ * processed by the ODP Classifier upon receipt. As part of its
+ * processing, the classifier parses information from the packet
+ * headers and makes this information available as system meta data so
+ * that applications using ODP do not have to reference packets or
+ * their headers directly for most processing. The set of headers
+ * supported by the ODP parse functions MUST include at minimum the
+ * following:
+ *
+ * - Layer 2: ARP, SNAP (recognition), VLAN (C-Tag and S-Tag)
+ * - Layer 3: IPv4, IPv6
+ * - Layer 4: TCP, UDP, ICMP, ICMPv6, IPsec (ESP and AH)
+ *
+ * @par
+ * Other protocols MAY be supported, however ODP v1.0 does not
+ * define APIs for referencing them.
+ *
+ * @par
+ * Parsing results are stored as meta data associated with the
+ * packet. These include various precomputed offsets used for direct
+ * access to parsed headers as well as indicators of packet contents
+ * that are collectively referred to as inflags. Inflags are packet
+ * meta data that may be inspected or set via accessor functions as
+ * described below. Setters are provided to enable applications that
+ * create or modify packet headers to update these attributes
+ * efficiently. Applications that use them take responsibility for
+ * ensuring that the results are consistent. ODP itself does not
+ * validate an inflag setter to ensure that it reflects actual packet
+ * contents. Applications that wish this additional assurance should
+ * request an explicit packet reparse.
+ *
+ * @par Packet Outflags
+ * Packet transmission options are controlled by
+ * packet meta data collectively referred to as outflags. An
+ * application sets these to request various services related to
+ * packet transmission.
+ *
+ * @par
+ * Note: The outflags controlling checksum offload processing are
+ * overrides. That is, they have no effect unless they are set
+ * explicitly by the application. By default, checksum offloads are
+ * controlled by the corresponding settings of the odp_pktio_t through
+ * which a packet is transmitted. The purpose of these bits is to
+ * permit this offload processing to be overridden on a per-packet
+ * basis. Note that not every implementation may support such
+ * override capabilities, which is why the setters here return a
+ * success/failure indicator.
+ *
+ * @par Packet Headroom and Tailroom Routines
+ * Data plane applications frequently manipulate the headers and trailers
+ * associated with packets. These operations involve either stripping
+ * headers or trailers from packets or inserting new headers or
+ * trailers onto them. To enable this manipulation, ODP provides the
+ * notion of headroom and tailroom, as well as a set of APIs that
+ * enable their efficient manipulation.
+ *
+ * @par
+ * Headroom is a set of bytes that logically precede the start of
+ * a packet, enabling additional headers to be created that become
+ * part of the packet. Similarly, tailroom is a set of bytes that
+ * logically follow the end of a packet, enabling additional payload
+ * and/or trailers to be created that become part of the packet. Both
+ * headroom and tailroom are meta data associated with packets, and
+ * are assigned at packet creation.
+ *
+ * @par
+ * Packet headroom and tailroom is manipulated by the following
+ * routines that MUST be provided by conforming ODP implementations.
+ * These operations define push and pull operations. The convention
+ * is that push operations move away from packet data while pull
+ * operations move towards packet data. Alternately, push operations
+ * add to packet data, while pull operations remove packet data.
+ *
+ * @par These concepts are shown as operations on the packet diagram
+ * we saw previously:
+ *
+ * @image html hrtr.png "Headroom and Tailroom Manipulation" width=\textwidth
+ * @image latex hrtr.eps "Headroom and Tailroom Manipulation" width=\textwidth
  */
 
 #ifndef ODP_PACKET_H_
@@ -21,7 +275,7 @@ extern "C" {
 #include <odp_buffer.h>
 
 /** @defgroup odp_packet ODP PACKET
- *  Operations on a packet.
+ *
  *  @{
  */
 
@@ -31,7 +285,7 @@ extern "C" {
 typedef odp_buffer_t odp_packet_t;
 
 /** Invalid packet */
-#define ODP_PACKET_INVALID ODP_BUFFER_INVALID
+#define ODP_PACKET_INVALID (odp_packet_t)(-1)
 
 /** Invalid offset */
 #define ODP_PACKET_OFFSET_INVALID ((uint32_t)-1)
@@ -40,411 +294,2012 @@ typedef odp_buffer_t odp_packet_t;
 /**
  * ODP packet segment handle
  */
-typedef int odp_packet_seg_t;
+typedef uint32_t odp_packet_segment_t;
 
 /** Invalid packet segment */
-#define ODP_PACKET_SEG_INVALID -1
+#define ODP_PACKET_SEGMENT_INVALID (odp_packet_segment_t)(-1)
+
+/**
+ * Convert a buffer handle to a packet handle
+ *
+ * @param[in] buf  Buffer handle
+ *
+ * @return Packet handle
+ *
+ * @note This routine converts a buffer handle to a packet handle.
+ * Only meaningful if buffer is of type ODP_BUFFER_TYPE_PACKET.
+ * Results are undefined otherwise.
+ */
+odp_packet_t odp_packet_from_buffer(odp_buffer_t buf);
+
+/**
+ * Convert a packet handle to a buffer handle
+ *
+ * @param[in] pkt  Packet handle
+ *
+ * @return Buffer handle
+ *
+ * @note This routine converts a packet handle to a buffer handle.
+ * This routine always succeeds (assuming pkt is a valid packet
+ * handle) since all packets are buffers.
+ */
+odp_buffer_t odp_packet_to_buffer(odp_packet_t pkt);
+
+/**
+ * Get the headroom for a packet buffer pool
+ *
+ * @param[in] pool      Handle of the buffer pool
+ *
+ * @return              The headroom for the pool. If the pool is invalid,
+ *                      returns -1 and errno set to ODP_BUFFER_POOL_INVALID.
+ */
+size_t odp_buffer_pool_headroom(odp_buffer_pool_t pool);
+
+/**
+ * Set the headroom for a packet buffer pool
+ *
+ * @param[in] pool      Handle of the buffer pool
+ * @param[in] hr        The headroom for the pool
+ *
+ * @return              0 on Success or -1 on error. For errors, errno set to
+ *                      ODP_BUFFER_POOL_INVALID if pool is unknown
+ *                      or ODP_INVALID_RANGE if hr exceeds
+ *                      ODP_PACKET_MAX_HEADROOM
+ *
+ * @note This routine sets the default headroom associated with
+ * buffers allocated from this packet pool. Note that headroom is a
+ * per-packet attribute. The headroom associated with the buffer pool
+ * is the default headroom to assign to a packet allocated from this
+ * buffer pool by the odp_packet_alloc() routine By contrast, the
+ * odp_cos_set_headroom() classification API sets the default headroom
+ * to assign to a packet by the classifier for packets matching a
+ * particular Class of Service (CoS). The allowable range of
+ * supported headroom sizes is subject to the ODP_PACKET_MAX_HEADROOM
+ * limit defined by the implementation. The valid range for hr is
+ * 0..ODP_PACKET_MAX_HEADROOM.
+ *
+ * @par
+ * Note also that if the buffer is unsegmented, the specified
+ * headroom will subtract from the preallocated segments that comprise
+ * the pool. Applications need to take this into account when sizing
+ * unsegmented buffer pools.
+ *
+ * @par
+ * Specifying a new headroom for an existing buffer pool does not
+ * affect the headroom associated with existing buffers. The buffer
+ * pool headroom setting only affects new buffers allocated from the
+ * pool.
+ */
+int odp_buffer_pool_set_headroom(odp_buffer_pool_t pool, size_t hr);
+
+/**
+ * Get the tailroom for a packet buffer pool
+ *
+ * @param[in] pool      Handle of the buffer pool
+ *
+ * @return              The tailroom for the pool. If the pool is invalid,
+ *                      returns -1 and errno set to ODP_BUFFER_POOL_INVALID.
+ */
+size_t odp_buffer_pool_tailroom(odp_buffer_pool_t pool);
+
+/**
+ * Set the tailroom for a packet buffer pool
+ *
+ * @param[in] pool      Handle of the buffer pool
+ * @param[in] tr        The tailroom for the pool
+ *
+ * @return              0 on Success or -1 on error. For errors, errno set to
+ *                      ODP_BUFFER_POOL_INVALID if pool is unknown
+ *                      or ODP_INVALID_RANGE if hr exceeds
+ *                      ODP_PACKET_MAX_TAILROOM
+ *
+ * @note This routine sets the tailroom associated with buffers
+ * allocated from a packet pool. The allowable range of supported
+ * tailroom sizes is subject to the ODP_PACKET_MAX_TAILROOM limit
+ * defined by the implementation. The valid range for tr is
+ * 0..ODP_PACKET_MAX_TAILROOM.
+ *
+ * @par
+ * Note also that if the buffer is unsegmented, the specified
+ * tailroom will subtract from the preallocated segments that comprise
+ * the pool. Applications need to take this into account when sizing
+ * unsegmented buffer pools.
+ *
+ * @par
+ * Specifying a new tailroom for an existing buffer pool does not
+ * affect the tailroom associated with existing buffers. The buffer
+ * pool tailroom setting only affects new buffers allocated from the
+ * pool.
+ */
+int odp_buffer_pool_set_tailroom(odp_buffer_pool_t pool, size_t tr);
 
 /**
- * ODP packet segment info
+ * Packet alloc
+ *
+ * @param[in] pool    Pool handle for a pool of type ODP_BUFFER_TYPE_PACKET
+ *
+ * @return Packet handle or ODP_PACKET_INVALID
+ *
+ * @note This routine is used to allocate a packet from a buffer pool
+ * of type ODP_BUFFER_TYPE_PACKET. The returned odp_packet_t is an
+ * opaque handle for the packet that can be used in further calls to
+ * manipulate the allocated packet. The value ODP_PACKET_INVALID is
+ * returned if the request cannot be satisfied. The length of the
+ * allocated packet is set to 0.
+ *
+ * @par
+ * If non-persistent user meta data is associated with the
+ * underlying buffer that contains the packet, the buf_init() routine
+ * specified as part of the containing buffer pool will be called as
+ * part of buffer allocation to enable the application to initialize
+ * the user meta data associated with it.
  */
-typedef struct odp_packet_seg_info_t {
-	void   *addr;      /**< Segment start address */
-	size_t  size;      /**< Segment maximum data size */
-	void   *data;      /**< Segment data address */
-	size_t  data_len;  /**< Segment data length */
-} odp_packet_seg_info_t;
+odp_packet_t odp_packet_alloc(odp_buffer_pool_t pool);
 
+/**
+ * Allocate a packet from a buffer pool of a specified length
+ *
+ * @param[in] pool  Pool handle
+ * @param[in] len   Length of packet requested
+ *
+ * @return          Packet handle or ODP_PACKET_INVALID
+ *
+ * @note This routine is used to allocate a packet of a given length
+ * from a packet buffer pool. The returned odp_packet_t is an opaque
+ * handle for the packet that can be used in further calls to
+ * manipulate the allocated packet. The returned buffer is
+ * initialized as an ODP packet and with the length set to the
+ * requested len. The caller will then initialize the packet with
+ * headers and payload as needed. This call itself does not
+ * initialize packet contents or the meta data that would be present
+ * following a packet parse.
+ */
+odp_packet_t odp_packet_alloc_len(odp_buffer_pool_t pool, size_t len);
 
 /**
- * Initialize the packet
+ * Packet free
  *
- * Needs to be called if the user allocates a packet buffer, i.e. the packet
- * has not been received from I/O through ODP.
+ * @param[in] pkt     Handle of the packet to be freed
  *
- * @param pkt  Packet handle
+ * @note This routine is used to return a packet back to its
+ * containing buffer pool. Results are undefined if an application
+ * attempts to reference a packet after it is freed.
+ */
+void odp_packet_free(odp_packet_t pkt);
+
+/**
+ * Initialize a packet
+ *
+ * @param[in] pkt     Handle of the packet to be initialized
+ *
+ * @note This routine is called following packet allocation to
+ * initialize the packet meta data and internal structure to support
+ * packet operations. Note that this function is performed whenever a
+ * packet is allocated so it would only be used if an application
+ * wished to re-initialize a packet to permit it to discard whatever
+ * previous contents existed and start a fresh packet without having
+ * to free and re-allocate the packet. Re-initializing a packet
+ * resets its headroom and tailroom to their default values (from the
+ * containing packet pool) and sets the packet length to 0.
  */
 void odp_packet_init(odp_packet_t pkt);
 
 /**
- * Convert a buffer handle to a packet handle
+ * Obtain buffer pool handle of a packet
  *
- * @param buf  Buffer handle
+ * @param[in] pkt   Packet handle
  *
- * @return Packet handle
+ * @return Buffer pool the packet was allocated from
+ *
+ * @note This routine is an accessor function that returns the handle
+ * of the buffer pool containing the referenced packet.
  */
-odp_packet_t odp_packet_from_buffer(odp_buffer_t buf);
+odp_buffer_pool_t odp_packet_pool(odp_packet_t pkt);
 
 /**
- * Convert a packet handle to a buffer handle
+ * Get the headroom available for a packet
  *
- * @param pkt  Packet handle
+ * @param[in] pkt   Packet handle
  *
- * @return Buffer handle
+ * @return Headroom available for this packet, in bytes.
+ *
+ * @note This routine returns the current headroom available for a
+ * buffer. The initial value for this is taken either from the
+ * containing buffer pool (for explicit packet allocation) or from the
+ * Class of Service (CoS) on packet reception. It is adjusted
+ * dynamically by the odp_packet_push_head() and
+ * odp_packet_pull_head() routines.
  */
-odp_buffer_t odp_packet_to_buffer(odp_packet_t pkt);
+size_t odp_packet_headroom(odp_packet_t pkt);
 
 /**
- * Set the packet length
+ * Get the tailroom available for a packet
+ *
+ * @param[in] pkt   Packet handle
  *
- * @param pkt  Packet handle
- * @param len  Length of packet in bytes
+ * @return Tailroom available for this packet, in bytes.
+ *
+ * @note This routine returns the current tailroom available for a
+ * buffer. The initial value for this is taken either from the
+ * containing buffer pool. It is adjusted dynamically by the
+ * odp_packet_push_tail() and odp_packet_pull_tail() routines.
  */
-void odp_packet_set_len(odp_packet_t pkt, size_t len);
+size_t odp_packet_tailroom(odp_packet_t pkt);
 
 /**
- * Get the packet length
+ * Get packet length
  *
- * @param pkt  Packet handle
+ * @param[in] pkt  Packet handle
  *
  * @return   Packet length in bytes
+ *
+ * @note This routine is an accessor function that returns the length
+ * (in bytes) of a packet. This is the total number of octets that
+ * would transmit for the packet, not including the Ethernet Frame
+ * Check Sequence (FCS), and includes all packet headers as well as
+ * payload. Results are undefined if the supplied pkt does not
+ * specify a valid packet. Note that packet length will change in
+ * response to headroom/tailroom and/or split/join operations. As a
+ * result, this attribute does not have a setter accessor function.
  */
 size_t odp_packet_get_len(odp_packet_t pkt);
 
 /**
- * Set packet user context
+ * Get address and size of user meta data associated with a packet
+ *
+ * @param[in]  pkt        Packet handle
+ * @param[out] udata_size Number of bytes of user meta data available
+ *                        at the returned address
  *
- * @param buf      Packet handle
- * @param ctx      User context
+ * @return                Address of the user meta data for this packet
+ *                        or NULL if the buffer has no user meta data.
  *
+ * @note This routine returns the address of the user meta data
+ * associated with an ODP packet. This enables the caller to read or
+ * write the user meta data associated with the buffer. The caller
+ * MUST honor the returned udata_size in referencing this storage.
  */
-void odp_packet_set_ctx(odp_packet_t buf, const void *ctx);
+void *odp_packet_udata(odp_packet_t pkt, size_t *udata_size);
 
 /**
- * Get packet user context
+ * Get address of user meta data associated with a packet
  *
- * @param buf      Packet handle
+ * @param[in] pkt         Packet handle
  *
- * @return User context
+ * @return                Address of the user meta data for this packet
+ *                        or NULL if the buffer has no user meta data.
+ *
+ * @note This routine returns the address of the user meta data
+ * associated with an ODP packet. This enables the caller to read or
+ * write the user meta data associated with the packet. This routine
+ * is intended as a fast-path version of odp_packet_udata() for
+ * callers that only require the address of the user meta data area
+ * associated with the packet. This routine assumes that the caller
+ * already knows and will honor the size limits of this area.
  */
-void *odp_packet_get_ctx(odp_packet_t buf);
+void *odp_packet_udata_addr(odp_packet_t pkt);
 
 /**
- * Packet buffer start address
+ * Tests if packet is segmented
  *
- * Returns a pointer to the start of the packet buffer. The address is not
- * necessarily the same as packet data address. E.g. on a received Ethernet
- * frame, the protocol header may start 2 or 6 bytes within the buffer to
- * ensure 32 or 64-bit alignment of the IP header.
+ * @param[in] pkt  Packet handle
  *
- * Use odp_packet_l2(pkt) to get the start address of a received valid frame
- * or odp_packet_data(pkt) to get the current packet data address.
+ * @return         1 if packet has more than one segment, otherwise 0
  *
- * @param pkt  Packet handle
+ * @note This routine tests whether a packet is segmented. Logically
+ * equivalent to testing whether odp_packet_segment_count(pkt) > 1,
+ * but may be more efficient in some implementations.
+ */
+int odp_packet_is_segmented(odp_packet_t pkt);
+
+/**
+ * Print packet metadata to ODP Log
  *
- * @return  Pointer to the start of the packet buffer
+ * @param[in] pkt  Packet handle
  *
- * @see odp_packet_l2(), odp_packet_data()
+ * @note This routine is used for debug purposes to print the metadata
+ * associated with a packet to the ODP log. This routine is OPTIONAL
+ * and MAY be treated as a no-op if the function is not available or
+ * if the supplied odp_packet_t is not valid.
+ */
+void odp_packet_print(odp_packet_t pkt);
+
+/**
+ * Parse a packet and set its meta data.
+ *
+ * @param[in] pkt Packet handle of packet to be parsed
+ *
+ * @return 1 if packet has any parse errors, 0 otherwise
+ *
+ * @note This routine requests that the specified packet by parsed and
+ * the meta data associated with it be set. The return value
+ * indicates whether the parse was successful or if any parse errors
+ * were encountered. The intent of this routine is to allow
+ * applications that construct or modify packets to force an
+ * implementation-provided re-parse to set the relevant packet meta
+ * data. As an alternative, the application is free to set these
+ * individually as it desires with appropriate setter functions,
+ * however in this case it is the application’s responsibility to
+ * ensure that they are set consistently as no error checking is
+ * performed by the setters. Calling odp_packet_parse(), by contrast,
+ * guarantees that they will be set properly to reflect the actual
+ * contents of the packet.
  */
-uint8_t *odp_packet_addr(odp_packet_t pkt);
+int odp_packet_parse(odp_packet_t pkt);
 
 /**
- * Packet data address
+ * Check for packet errors
  *
- * Returns the current packet data address. When a packet is received from
- * packet input, the data address points to the first byte of the packet.
+ * Checks all error flags at once.
  *
- * @param pkt  Packet handle
+ * @param[in] pkt   Packet handle
  *
- * @return  Pointer to the packet data
+ * @return 1 if packet has errors, 0 otherwise
  *
- * @see odp_packet_l2(), odp_packet_addr()
+ * @note This routine is a summary routine that says whether the
+ * referenced packet contains any errors. If odp_packet_error() is 0
+ * then the packet is well-formed.
  */
-uint8_t *odp_packet_data(odp_packet_t pkt);
+int odp_packet_error(odp_packet_t pkt);
 
 /**
- * Get pointer to the start of the L2 frame
+ * Control indication of packet error.
  *
- * The L2 frame header address is not necessarily the same as the address of the
- * packet buffer, see odp_packet_addr()
+ * @param[in] pkt Packet handle
+ * @param[in] val Value to set for this bit (0 or 1).
+ *
+ * @note This routine is used to set the error flag for a packet.
+ * Note that while error is a summary bit, at present ODP does not
+ * define any error detail bits.
+ */
+void odp_packet_set_error(odp_packet_t pkt, int val);
+
+/**
+ * Examine packet reference count
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return reference count of the packet
+ *
+ * @note This routine examines the reference count associated with a
+ * packet. The reference count is used to control when a packet is
+ * freed. When initially allocated, the refcount for a packet is set
+ * to 1. When a packet is transmitted its refcount is decremented and
+ * if the refcount is 0 then the packet is freed by the transmit
+ * function of the odp_pktio_t that transmits it. If the refcount is
+ * greater than zero then the packet is not freed and instead is
+ * returned to the application for further processing. Note that a
+ * packet refcount is an unsigned integer and can never be less than
+ * 0.
+ */
+unsigned int odp_packet_refcount(odp_packet_t pkt);
+
+/**
+ * Increment a packet’s refcount.
  *
- * @param pkt  Packet handle
+ * @param[in] pkt Packet handle
+ * @param[in] val Value to increment refcount by
  *
- * @return  Pointer to L2 header or NULL if not found
+ * @return The packet refcount following increment
  *
- * @see odp_packet_addr(), odp_packet_data()
+ * @note This routine is used to increment the refcount for a packet
+ * by a specified amount.
  */
-uint8_t *odp_packet_l2(odp_packet_t pkt);
+unsigned int odp_packet_incr_refcount(odp_packet_t pkt, unsigned int val);
 
 /**
- * Return the byte offset from the packet buffer to the L2 frame
+ * Decrement a packet’s refcount.
+ *
+ * @param[in] pkt Packet handle
+ * @param[in] val Value to decrement refcount by
  *
- * @param pkt  Packet handle
+ * @return The packet refcount following decrement
  *
- * @return  L2 byte offset or ODP_PACKET_OFFSET_INVALID if not found
+ * @note This routine is used to decrement the refcount for a packet
+ * by a specified amount. The refcount will never be decremented
+ * below 0 regardless of the specified val.
  */
-size_t odp_packet_l2_offset(odp_packet_t pkt);
+unsigned int odp_packet_decr_refcount(odp_packet_t pkt, unsigned int val);
 
 /**
- * Set the byte offset to the L2 frame
+ * Check for L2 header, e.g., Ethernet
  *
- * @param pkt     Packet handle
- * @param offset  L2 byte offset
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains a valid & known L2 header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * a valid Layer 2 header.
  */
-void odp_packet_set_l2_offset(odp_packet_t pkt, size_t offset);
+int odp_packet_inflag_l2(odp_packet_t pkt);
 
+/**
+ * Control indication of Layer 2 presence.
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @param val[in] 1 if packet contains a valid & known L2 header, 0 otherwise
+ *
+ * @note This routine sets whether the referenced packet contains a
+ * valid Layer 2 header.
+ */
+void odp_packet_set_inflag_l2(odp_packet_t pkt, int val);
 
 /**
- * Get pointer to the start of the L3 packet
+ * Check for L3 header, e.g. IPv4, IPv6
  *
- * @param pkt  Packet handle
+ * @param[in] pkt Packet handle
  *
- * @return  Pointer to L3 packet or NULL if not found
+ * @return 1 if packet contains a valid & known L3 header, 0 otherwise
  *
+ * @note This routine indicates whether the referenced packet contains
+ * a valid Layer 3 header.
  */
-uint8_t *odp_packet_l3(odp_packet_t pkt);
+int odp_packet_inflag_l3(odp_packet_t pkt);
 
 /**
- * Return the byte offset from the packet buffer to the L3 packet
+ * Control indication of L3 header, e.g. IPv4, IPv6
+ *
+ * @param[in] pkt Packet handle
  *
- * @param pkt  Packet handle
+ * @param[in] val 1 if packet contains a valid & known L3 header, 0 otherwise
  *
- * @return  L3 byte offset or ODP_PACKET_OFFSET_INVALID if not found
+ * @note This routine sets whether the referenced packet contains a
+ * valid Layer 3 header.
  */
-size_t odp_packet_l3_offset(odp_packet_t pkt);
+void odp_packet_set_inflag_l3(odp_packet_t pkt, int val);
 
 /**
- * Set the byte offset to the L3 packet
+ * Check for L4 header, e.g. UDP, TCP, (also ICMP)
  *
- * @param pkt     Packet handle
- * @param offset  L3 byte offset
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains a valid & known L4 header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * a valid Layer 4 header.
  */
-void odp_packet_set_l3_offset(odp_packet_t pkt, size_t offset);
+int odp_packet_inflag_l4(odp_packet_t pkt);
 
+/**
+ * Control indication of L4 header, e.g. UDP, TCP, (also ICMP)
+ *
+ * @param pkt[in] Packet handle
+ * @param val[in] 1 if packet contains a valid & known L4 header, 0 otherwise
+ *
+ * @note This routine sets whether the referenced packet contains a
+ * valid Layer 4 header.
+ */
+void odp_packet_set_inflag_l4(odp_packet_t pkt, int val);
 
 /**
- * Get pointer to the start of the L4 packet
+ * Check for Ethernet header
  *
- * @param pkt  Packet handle
+ * @param[in] pkt Packet handle
  *
- * @return  Pointer to L4 packet or NULL if not found
+ * @return 1 if packet contains a valid eth header, 0 otherwise
  *
+ * @note This routine indicates whether the referenced packet contains
+ * a valid Ethernet header.
  */
-uint8_t *odp_packet_l4(odp_packet_t pkt);
+int odp_packet_inflag_eth(odp_packet_t pkt);
 
 /**
- * Return the byte offset from the packet buffer to the L4 packet
+ * Control indication of Ethernet header
  *
- * @param pkt  Packet handle
+ * @param[in] pkt Packet handle
  *
- * @return  L4 byte offset or ODP_PACKET_OFFSET_INVALID if not found
+ * @return 1 if packet contains a valid eth header, 0 otherwise
+ *
+ * @note This routine sets whether the referenced packet contains a
+ * valid Ethernet header.
  */
-size_t odp_packet_l4_offset(odp_packet_t pkt);
+int odp_packet_inflag_eth(odp_packet_t pkt);
 
 /**
- * Set the byte offset to the L4 packet
+ * Check for Ethernet SNAP vs. DIX format
+ *
+ * @param[in] pkt Packet handle
  *
- * @param pkt     Packet handle
- * @param offset  L4 byte offset
+ * @return 1 if packet is SNAP, 0 if it is DIX
+ *
+ * @note This routine indicates whether the referenced packet Ethernet
+ * is SNAP. If odp_packet_inflag_eth() is 1 and
+ * odp_packet_inflag_snap() is 0 then the packet is in DIX format.
  */
-void odp_packet_set_l4_offset(odp_packet_t pkt, size_t offset);
+int odp_packet_inflag_snap(odp_packet_t pkt);
 
 /**
- * Print (debug) information about the packet
+ * Control indication of Ethernet SNAP vs. DIX format
+ *
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet is SNAP, 0 if it is DIX
  *
- * @param pkt  Packet handle
+ * @note This routine sets whether the referenced packet Ethernet is
+ * SNAP.
  */
-void odp_packet_print(odp_packet_t pkt);
+void odp_packet_set_inflag_snap(odp_packet_t pkt, int val);
 
 /**
- * Copy contents and metadata from pkt_src to pkt_dst
- * Useful when creating copies of packets
+ * Check for jumbo frame
  *
- * @param pkt_dst Destination packet
- * @param pkt_src Source packet
+ * @param[in] pkt Packet handle
  *
- * @return 0 if successful
+ * @return 1 if packet contains jumbo frame, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * a jumbo frame. A jumbo frame has a length greater than 1500 bytes.
  */
-int odp_packet_copy(odp_packet_t pkt_dst, odp_packet_t pkt_src);
+int odp_packet_inflag_jumbo(odp_packet_t pkt);
 
 /**
- * Tests if packet is segmented (a scatter/gather list)
+ * Control indication of jumbo frame
  *
- * @param pkt  Packet handle
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains jumbo frame, 0 otherwise
  *
- * @return Non-zero if packet is segmented, otherwise 0
+ * @note This routine sets whether the referenced packet contains a
+ * jumbo frame. A jumbo frame has a length greater than 1500 bytes.
  */
-int odp_packet_is_segmented(odp_packet_t pkt);
+void odp_packet_set_inflag_jumbo(odp_packet_t pkt, int val);
+
+/**
+ * Check for VLAN
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains a VLAN header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * one or more VLAN headers.
+ */
+int odp_packet_inflag_vlan(odp_packet_t pkt);
 
 /**
- * Segment count
+ * Control indication of VLAN
  *
- * Returns number of segments in the packet. A packet has always at least one
- * segment (the packet buffer itself).
+ * @param[in] pkt Packet handle
  *
- * @param pkt  Packet handle
+ * @param[in] val 1 if packet contains a VLAN header, 0 otherwise
  *
- * @return Segment count
+ * @note This routine sets whether the referenced packet contains one
+ * or more VLAN headers.
  */
-int odp_packet_seg_count(odp_packet_t pkt);
+void odp_packet_set_inflag_vlan(odp_packet_t pkt, int val);
 
 /**
- * Get segment by index
+ * Check for VLAN QinQ (stacked VLAN)
+ *
+ * @param[in] pkt Packet handle
  *
- * @param pkt   Packet handle
- * @param index Segment index (0 ... seg_count-1)
+ * @return 1 if packet contains a VLAN QinQ header, 0 otherwise
  *
- * @return Segment handle, or ODP_PACKET_SEG_INVALID on an error
+ * @note This routine indicates whether the referenced packet contains
+ * a double VLAN header (Q-in-Q) matching the IEEE 802.1ad
+ * specification.
  */
-odp_packet_seg_t odp_packet_seg(odp_packet_t pkt, int index);
+int odp_packet_inflag_vlan_qinq(odp_packet_t pkt);
 
 /**
- * Get next segment
+ * Controls indication of VLAN QinQ (stacked VLAN)
  *
- * @param pkt   Packet handle
- * @param seg   Current segment handle
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains a VLAN QinQ header, 0 otherwise
  *
- * @return Handle to next segment, or ODP_PACKET_SEG_INVALID on an error
+ * @note This routine sets whether the referenced packet contains a
+ * double VLAN header (Q-in-Q) matching the IEEE 802.1ad
+ * specification.
  */
-odp_packet_seg_t odp_packet_seg_next(odp_packet_t pkt, odp_packet_seg_t seg);
+void odp_packet_inflag_set_vlan_qinq(odp_packet_t pkt, int val);
 
 /**
- * Segment info
+ * Check for ARP
  *
- * Copies segment parameters into the info structure.
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains an ARP header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * an ARP header.
+ */
+int odp_packet_inflag_arp(odp_packet_t pkt);
+
+/**
+ * Controls indication of ARP
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
- * @param info Pointer to segment info structure
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains an ARP header, 0 otherwise
  *
- * @return 0 if successful, otherwise non-zero
+ * @note This routine sets whether the referenced packet contains an
+ * ARP header.
  */
-int odp_packet_seg_info(odp_packet_t pkt, odp_packet_seg_t seg,
-			odp_packet_seg_info_t *info);
+void odp_packet_set_inflag_arp(odp_packet_t pkt, int val);
 
 /**
- * Segment start address
+ * Check for IPv4
+ *
+ * @param[in] pkt Packet handle
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
+ * @return 1 if packet contains an IPv4 header, 0 otherwise
  *
- * @return Segment start address, or NULL on an error
+ * @note This routine indicates whether the referenced packet contains
+ * an IPv4 header.
  */
-void *odp_packet_seg_addr(odp_packet_t pkt, odp_packet_seg_t seg);
+int odp_packet_inflag_ipv4(odp_packet_t pkt);
 
 /**
- * Segment maximum data size
+ * Control indication of IPv4
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains an IPv4 header, 0 otherwise
  *
- * @return Segment maximum data size
+ * @note This routine sets whether the referenced packet contains an
+ * IPv4 header.
  */
-size_t odp_packet_seg_size(odp_packet_t pkt, odp_packet_seg_t seg);
+void odp_packet_set_inflag_ipv4(odp_packet_t pkt, int val);
 
 /**
- * Segment data address
+ * Check for IPv6
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
+ * @param[in] pkt Packet handle
  *
- * @return Segment data address
+ * @return 1 if packet contains an IPv6 header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * an IPv6 header.
  */
-void *odp_packet_seg_data(odp_packet_t pkt, odp_packet_seg_t seg);
+int odp_packet_inflag_ipv6(odp_packet_t pkt);
 
 /**
- * Segment data length
+ * Control indication of IPv6
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains an IPv6 header, 0 otherwise
  *
- * @return Segment data length
+ * @note This routine sets whether the referenced packet contains an
+ * IPv6 header.
  */
-size_t odp_packet_seg_data_len(odp_packet_t pkt, odp_packet_seg_t seg);
+void odp_packet_set_inflag_ipv6(odp_packet_t pkt, int val);
 
 /**
- * Segment headroom
+ * Check for IP fragment
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet is an IP fragment, 0 otherwise
  *
- * seg_headroom = seg_data - seg_addr
+ * @note This routine indicates whether the referenced packet contains
+ * an IP fragment.
+ */
+int odp_packet_inflag_ipfrag(odp_packet_t pkt);
+
+/**
+ * Controls indication of IP fragment
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet is an IP fragment, 0 otherwise
  *
- * @return Number of octets from seg_addr to seg_data
+ * @note This routine sets whether the referenced packet contains an
+ * IP fragment.
  */
-size_t odp_packet_seg_headroom(odp_packet_t pkt, odp_packet_seg_t seg);
+void odp_packet_set_inflag_ipfrag(odp_packet_t pkt, int val);
 
 /**
- * Segment tailroom
+ * Check for IP options
  *
- * seg_tailroom = seg_size - seg_headroom - seg_data_len
+ * @param[in] pkt Packet handle
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
+ * @return 1 if packet contains IP options, 0 otherwise
  *
- * @return Number of octets from end-of-data to end-of-segment
+ * @note This routine indicates whether the referenced packet contains
+ * IP options.
  */
-size_t odp_packet_seg_tailroom(odp_packet_t pkt, odp_packet_seg_t seg);
+int odp_packet_inflag_ipopt(odp_packet_t pkt);
 
 /**
- * Push out segment head
+ * Controls indication of IP options
  *
- * Push out segment data address (away from data) and increase data length.
- * Does not modify packet in case of an error.
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains IP options, 0 otherwise
+ *
+ * @note This routine sets whether the referenced packet contains IP
+ * options.
+ */
+void odp_packet_set_inflag_ipopt(odp_packet_t pkt, int val);
+
+/**
+ * Check for IPSec
  *
- * seg_data     -= len
- * seg_data_len += len
+ * @param[in] pkt Packet handle
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
- * @param len  Number of octets to push head (0 ... seg_headroom)
+ * @return 1 if packet requires IPSec processing, 0 otherwise
  *
- * @return New segment data address, or NULL on an error
+ * @note This routine indicates whether the referenced packet contains
+ * an IPSec header (ESP or AH).
  */
-void *odp_packet_seg_push_head(odp_packet_t pkt, odp_packet_seg_t seg,
-			       size_t len);
+int odp_packet_inflag_ipsec(odp_packet_t pkt);
 
 /**
- * Pull in segment head
+ * Control indication of IPSec
  *
- * Pull in segment data address (towards data) and decrease data length.
- * Does not modify packet in case of an error.
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet requires IPSec processing, 0 otherwise
+ *
+ * @note This routine sets whether the referenced packet contains an
+ * IPSec header (ESP or AH).
+ */
+void odp_packet_set_inflag_ipsec(odp_packet_t pkt, int val);
+
+/**
+ * Check for UDP
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains a UDP header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * a UDP header.
+ */
+int odp_packet_inflag_udp(odp_packet_t pkt);
+
+/**
+ * Control indication of UDP
+ *
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains a UDP header, 0 otherwise
+ *
+ * @note This routine sets whether the referenced packet contains a
+ * UDP header.
+ */
+void odp_packet_set_inflag_udp(odp_packet_t pkt, int val);
+
+/**
+ * Check for TCP
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains a TCP header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * a TCP header.
+ */
+int odp_packet_inflag_tcp(odp_packet_t pkt);
+
+/**
+ * Control indication of TCP
+ *
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains a TCP header, 0 otherwise
+ *
+ * @note This routine sets whether the referenced packet contains a
+ * TCP header.
+ */
+void odp_packet_set_inflag_tcp(odp_packet_t pkt, int val);
+
+/**
+ * Check for TCP options
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains TCP options, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * TCP options.
+ */
+int odp_packet_inflag_tcpopt(odp_packet_t pkt);
+
+/**
+ * Controls indication of TCP options
+ *
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains TCP options, 0 otherwise
+ *
+ * @note This routine sets whether the referenced packet contains TCP
+ * options.
+ */
+void odp_packet_set_inflag_tcpopt(odp_packet_t pkt, int val);
+
+/**
+ * Check for ICMP
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains an ICMP header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * an ICMP header.
+ */
+int odp_packet_inflag_icmp(odp_packet_t pkt);
+
+/**
+ * Control indication of ICMP
+ *
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains an ICMP header, 0 otherwise
+ *
+ * @note This routine sets whether the referenced packet contains an
+ * ICMP header.
+ */
+void odp_packet_set_inflag_icmp(odp_packet_t pkt, int val);
+
+/**
+ * Query Layer 3 checksum offload override setting
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 0 if no Layer 3 checksum to be performed, 1 if yes, -1 if not set
+ *
+ * @note This routine indicates whether Layer 3 checksum offload
+ * processing is to be performed for the referenced packet. Since
+ * this is an override bit, if the application has not set this
+ * attribute an error (-1) is returned indicating that this bit has
+ * not been specified.
+ */
+int odp_packet_outflag_l3_chksum(odp_packet_t pkt);
+
+/**
+ * Override Layer 3 checksum calculation
+ *
+ * @param[in] pkt Packet handle
+ * @param[in] val 0 if no Layer 3 checksum to be performed, 1 if yes
+ *
+ * @return 0 if override successful, -1 if not
+ *
+ * @note This routine sets whether Layer 3 checksum offload processing
+ * is to be performed for the referenced packet. An error return (-1)
+ * indicates that the implementation is unable to provide per-packet
+ * overrides of this function.
+ */
+int odp_packet_set_outflag_l3_chksum(odp_packet_t pkt, int val);
+
+/**
+ * Request Layer 4 checksum offload override setting
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 0 if no Layer 4 checksum to be performed, 1 if yes, -1 if not set
+ *
+ * @note This routine indicates whether Layer 4 checksum offload
+ * processing is to be performed for the referenced packet. Since
+ * this is an override bit, if the application has not set this
+ * attribute an error (-1) is returned indicating that this bit has
+ * not been specified.
+ */
+int odp_packet_set_outflag_l4_chksum(odp_packet_t pkt);
+
+/**
+ * Request L4 checksum calculation
+ *
+ * @param[in] pkt Packet handle
+ * @param[in] val 0 if no Layer 4 checksum to be performed, 1 if yes
+ *
+ * @return 0 if override successful, -1 if not
  *
- * seg_data     += len
- * seg_data_len -= len
+ * @note This routine specifies whether Layer 4 checksums offload
+ * processing is to be performed for the referenced packet. An error
+ * return (-1) indicates that the implementation is unable to provide
+ * per-packet overrides of this function.
+ */
+int odp_packet_set_outflag_l4_chksum(odp_packet_t pkt, int val);
+
+/**
+ * Get offset of start of Layer 2 headers
+ *
+ * @param[in] pkt  Packet handle
+ *
+ * @return         Byte offset into packet of start of Layer 2 headers
+ *                 or ODP_PACKET_OFFSET_INVALID if not found.
+ *
+ * @note This routine is an accessor function that returns the byte
+ * offset of the start of the Layer 2 headers of a packet. Results
+ * are undefined if the supplied pkt does not specify a valid packet.
+ * Note that if the packet contains unusual Layer 2 tags the caller
+ * will use this function to allow it to parse the Layer 2 headers
+ * directly if desired.
+ *
+ */
+size_t odp_packet_l2_offset(odp_packet_t pkt);
+
+/**
+ * Specify start of Layer 2 headers
+ *
+ * @param[in] pkt    Packet handle
+ * @param[in] offset Byte offset into packet of start of Layer 2 headers.
+ *
+ * @return 0 on success, -1 on error.
+ *
+ * @note This routine is an accessor function that sets the byte
+ * offset of the start of the Layer 2 headers of a packet. Results
+ * are undefined if the supplied pkt does not specify a valid packet.
+ * An error return results if the specified offset is out of range.
+ * Note that this routine does not verify that the specified offset
+ * correlates with packet contents. The application assumes that
+ * responsibility when using this routine.
+ */
+int odp_packet_set_l2_offset(odp_packet_t pkt, size_t offset);
+
+/**
+ * Returns the VLAN S-Tag and C-Tag associated with packet
+ *
+ * @param[in]  pkt   Packet handle
+ * @param[out] stag  S-Tag associated with packet or 0x00000000
+ * @param[out] ctag  C-Tag associated with packet or 0x00000000
+ *
+ * @note This routine returns the S-Tag (Ethertype 0x88A8) and C-Tag
+ * (Ethertype 0x8100) associated with the referenced packet. Note
+ * that the full tag (including the Ethertype) is returned so that the
+ * caller can easily distinguish between the two as well as handle
+ * older sources that use 0x8100 for both tags (QinQ). If the packet
+ * contains only one VLAN tag, it will be returned as the “S-Tag”. If
+ * the packet does not contain VLAN tags then both arguments will be
+ * returned as zeros.
+ *
+ * @par
+ * Note: as meta data values returned by this routine are in
+ * host-endian format. VLAN tags themselves are always received and
+ * transmitted in network byte order.
+ *
+ */
+void odp_packet_vlans(odp_packet_t pkt, uint32_t *stag, uint32_t *ctag);
+
+/**
+ * Specifies the VLAN S-Tag and C-Tag associated with packet
+ *
+ * @param[in] pkt    Packet handle
+ * @param[in] stag   S-Tag associated with packet or 0xFFFFFFFF
+ * @param[in] ctag   C-Tag associated with packet or 0xFFFFFFFF
+ *
+ * @note This routine sets the S-Tag (Ethertype 0x88A8) and C-Tag
+ * (Ethertype 0x8100) associated with the referenced packet. A value
+ * of 0xFFFFFFFF is specified to indicate that no corresponding S-Tag
+ * or C-Tag is present. Note: This routine simply sets the VLAN meta
+ * data for the packet. It does not affect packet contents. It is
+ * the caller’s responsibility to ensure that the packet contents
+ * matches the specified values.
+ */
+void odp_packet_set_vlans(odp_packet_t pkt, uint32_t stag, uint32_t ctag);
+
+/**
+ * Get offset of start of Layer 3 headers
+ *
+ * @param[in] pkt  Packet handle
+ *
+ * @return         Byte offset into packet of start of Layer 3 headers
+ *                 or ODP_PACKET_OFFSET_INVALID if not found.
+ *
+ * @note This routine is an accessor function that returns the byte
+ * offset of the start of the Layer 3 headers of a packet. Results
+ * are undefined if the supplied pkt does not specify a valid packet.
+ * In conjunction with the odp_packet_l3_protocol() routine, this
+ * routine allows the caller to process the Layer 3 header(s) of the
+ * packet directly, if desired.
+ */
+size_t odp_packet_l3_offset(odp_packet_t pkt);
+
+/**
+ * Set offset of start of Layer 3 headers
+ *
+ * @param[in] pkt    Packet handle
+ * @param[in] offset Byte offset into packet of start of Layer 3 headers
+ *
+ * @return  0 on Success, -1 on errors
+ *
+ * @note This routine is an accessor function that returns the byte
+ * offset of the start of the Layer 3 headers of a packet. Results
+ * are undefined if the supplied pkt does not specify a valid packet.
+ * An error return results if the specified offset is out of range.
+ * In conjunction with the odp_packet_set_l3_protocol() routine, this
+ * routine allows the caller to specify the Layer 3 header meta data
+ * of the packet directly, if desired. Note that this routine does not
+ * verify that the specified offset correlates with packet contents.
+ * The application assumes that responsibility when using this
+ * routine.
+ */
+int odp_packet_set_l3_offset(odp_packet_t pkt, sizt_t offset);
+
+/**
+ * Get the Layer 3 protocol of this packet
+ *
+ * @param[in] pkt  Packet handle
+ *
+ * @return         Ethertype of the Layer 3 protocol used or
+ *                 ODP_NO_L3_PROTOCOL if no Layer 3 protocol exists.
+ *
+ * @note This routine returns the IANA-assigned Ethertype of the Layer
+ * 3 protocol used in the packet. This is the last Layer 2 Ethertype
+ * that defines the Layer 3 protocol. This is widened from a uint16_t
+ * to an int to allow for error return codes. Note: This value is
+ * returned in host-endian format.
+ */
+int odp_packet_l3_protocol(odp_packet_t pkt);
+
+/**
+ * Set the Layer 3 protocol of this packet
+ *
+ * @param[in] pkt  Packet handle
+ * @param[in] pcl  Layer 3 protocol value
+ *
+ * @note This routine sets the IANA-assigned Ethertype of the Layer 3
+ * protocol used in the packet. This is the last Layer 2 Ethertype
+ * that defines the Layer 3 protocol. Note: This routine simply sets
+ * the Layer 3 protocol meta data for the packet. It does not affect
+ * packet contents. It is the caller’s responsibility to ensure that
+ * the packet contents matches the specified value.
+ */
+void odp_packet_set_l3_protocol(odp_packet_t pkt, uint16_t pcl);
+
+/**
+ * Get offset of start of Layer 4 headers
+ *
+ * @param[in] pkt  Packet handle
+ *
+ * @return         Byte offset into packet of start of Layer 4 headers
+ *                 or ODP_PACKET_OFFSET_INVALID if not found.
+ *
+ * @note This routine is an accessor function that returns the byte
+ * offset of the start of the Layer 4 headers of a packet. Results
+ * are undefined if the supplied pkt does not specify a valid packet.
+ * In conjunction with the odp_packet_l4_protocol() routine, this
+ * routine allows the caller to process the Layer 4 header associated
+ * with the packet directly if desired.
+ */
+size_t odp_packet_l4_offset(odp_packet_t pkt);
+
+/**
+ * Set offset of start of Layer 4 headers
+ *
+ * @param[in] pkt    Packet handle
+ * @param[in] offset Packet handle
+ *
+ * @return 0 on Success, -1 on error.
+ *
+ * @note This routine is an accessor function that sets the byte
+ * offset of the start of the Layer 4 headers of a packet. Results
+ * are undefined if the supplied pkt does not specify a valid
+ * packet. An error return results if the specified offset is out of
+ * range. In conjunction with the odp_packet_set_l4_protocol()
+ * routine, this routine allows the caller to specify the Layer 4
+ * header meta data with the packet directly if desired. Note that
+ * this routine does not verify that the specified offset correlates
+ * with packet contents. The application assumes that responsibility
+ * when using this routine.
+ */
+int odp_packet_set_l4_offset(odp_packet_t pkt, size_t offset);
+
+/**
+ * Get the Layer 4 protocol of this packet
+ *
+ * @param[in] pkt  Packet handle
+ *
+ * @return         Protocol number of the Layer 4 protocol used or
+ *                 ODP_NO_L4_PROTOCOL if none exists.
+ *
+ * @note This routine returns the IANA-assigned Protocol number of the
+ * Layer 4 protocol used in the packet. This is widened from uint8_t
+ * to an int to allow for error return codes.
+ */
+int odp_packet_l4_protocol(odp_packet_t pkt);
+
+/**
+ * Set the Layer 4 protocol of this packet
+ *
+ * @param[in] pkt  Packet handle
+ * @param[in] pcl  Layer 4 protocol value
+ *
+ * @note This routine sets the IANA-assigned Protocol number of the
+ * Layer 4 protocol used in the packet. Note: This routine simply
+ * sets the Layer 4 protocol meta data for the packet. It does not
+ * affect packet contents. It is the caller’s responsibility to
+ * ensure that the packet contents matches the specified value.
+ */
+void odp_packet_set_l4_protocol(odp_packet_t pkt, uint8_t pcl);
+
+/**
+ * Get offset of start of packet payload
+ *
+ * @param[in] pkt  Packet handle
+ *
+ * @return         Byte offset into packet of start of packet payload
+ *                 or ODP_PACKET_OFFSET_INVALID if not found.
+ *
+ * @note This routine is an accessor function that returns the byte
+ * offset of the start of the packet payload. Results are undefined
+ * if the supplied pkt does not specify a valid packet. For ODP, the
+ * packet payload is defined as the first byte beyond the last packet
+ * header recognized by the ODP packet parser. For certain protocols
+ * this may in fact be the start of a Layer 5 header, or an
+ * unrecognized Layer 3 or Layer 4 header, however ODP does not make
+ * this distinction.
+ */
+size_t odp_packet_payload_offset(odp_packet_t pkt);
+
+/**
+ * Set offset of start of packet payload
+ *
+ * @param[in] pkt    Packet handle
+ * @param[in] offset Packet handle
+ *
+ * @return 0 on Success, -1 on error
+ *
+ * @note This routine is an accessor function that sets the byte
+ * offset of the start of the packet payload. Results are undefined
+ * if the supplied pkt does not specify a valid packet. An error
+ * return results if the specified offset is out of range. For ODP,
+ * the packet payload is defined as the first byte beyond the last
+ * packet header recognized by the ODP packet parser. For certain
+ * protocols this may in fact be the start of a Layer 5 header, or an
+ * unrecognized Layer 3 or Layer 4 header, however ODP does not make
+ * this distinction. Note that this routine does not verify that the
+ * specified offset correlates with packet contents. The application
+ * assumes that responsibility when using this routine.
+ */
+int odp_packet_set_payload_offset(odp_packet_t pkt, size_t offset);
+
+/**
+ * Get count of number of segments in a packet
+ *
+ * @param[in] pkt  Packet handle
+ *
+ * @return         Count of the number of segments in pkt
+ *
+ * @note This routine returns the number of physical segments in the
+ * referenced packet. A packet that is not in an aggregated buffer
+ * will return 1 since it is comprised of a single segment. The
+ * packet segments of the aggregate buffer are in the range
+ * [0..odp_packet_segment_count-1]. Results are undefined if the
+ * supplied pkt is invalid. Use odp_packet_is_valid() to verify
+ * packet validity if needed.
+ */
+int odp_packet_segment_count(odp_packet_t pkt);
+
+/**
+ * Get the segment identifier for a packet segment by index
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
- * @param len  Number of octets to pull head (0 ... seg_data_len)
+ * @param[in] pkt  Packet handle
+ * @param[in] ndx  Segment index of segment of interest
  *
- * @return New segment data address, or NULL on an error
+ * @return         Segment identifier or ODP_SEGMENT_INVALID if the
+ *                 supplied ndx is out of range.
+ *
+ * @note This routine returns the abstract identifier
+ * (odp_packet_segment_t) of a particular segment by its index value.
+ * Valid ndx values are in the range
+ * [0..odp_packet_segment_count(pkt)-1]. Results are undefined if the
+ * supplied pkt is invalid. Use odp_packet_is_valid() to verify
+ * packet validity if needed.
  */
-void *odp_packet_seg_pull_head(odp_packet_t pkt, odp_packet_seg_t seg,
-			       size_t len);
+odp_packet_segment_t odp_packet_segment_by_index(odp_packet_t pkt, size_t ndx);
 
 /**
- * Push out segment tail
+ * Get the next segment identifier for a packet segment
+ *
+ * @param[in] pkt  Packet handle
+ * @param[in] seg  Segment identifier of the previous segment
+ *
+ * @return         Segment identifier of next segment or ODP_SEGMENT_INVALID
  *
- * Increase segment data length.
+ * @note This routine returns the abstract identifier
+ * (odp_packet_segment_t) of the next packet segment in a buffer
+ * aggregate. The input specifies the packet and the previous segment
+ * identifier. There are three use cases for this routine:
+ *
+ * -# If the input seg is ODP_SEGMENT_START then the segment
+ * identifier returned is that of the first segment in the packet.
+ * ODP_SEGMENT_NULL MAY be used as a synonym for ODP_SEGMENT_START
+ * for symmetry if desired.
+ *
+ * -# If the input seg is not the last segment in the packet then the
+ * segment identifier of the next segment following seg is returned.
+ *
+ * -# If the input seg is the segment identifier of the last segment
+ * in the packet then ODP_SEGMENT_NULL is returned.
+ *
+ */
+odp_packet_segment_t odp_packet_segment_next(odp_packet_t pkt,
+                                             odp_packet_segment_t seg);
+
+/**
+ * Get start address for a specified packet segment
+ *
+ * @param[in]  pkt     Packet handle
+ * @param[in]  seg     Segment identifier of the packet to be addressed
+ * @param[out] seglen  Returned number of bytes in this packet
+ *                     segment available at returned address
+ *
+ * @return             Start address of packet within segment or NULL
+ *
+ * @note This routine is used to obtain addressability to a segment
+ * within a packet aggregate at a specified segment identifier. The
+ * returned seglen indicates the number of bytes addressable at the
+ * returned address. Note that the returned address is always within
+ * the packet and the address returned is the first packet byte within
+ * the specified segment. So if the packet itself begins at a
+ * non-zero byte offset into the physical segment then the address
+ * returned by this call will not be the same as the starting address
+ * of the physical segment containing the packet.
+ */
+void *odp_packet_segment_map(odp_packet_t pkt, odp_packet_segment_t seg,
+                             size_t *seglen);
+
+/**
+ * Unmap a packet segment
+ *
+ * @param[in] seg  Packet segment handle
+ *
+ * @note This routine is used to unmap a packet segment previously
+ * mapped by odp_packet_segment_map(). Following this call,
+ * applications MUST NOT attempt to reference the segment via any
+ * pointer returned from a previous odp_packet_segment_map() call
+ * referring to it. It is intended to allow certain NUMA
+ * architectures to better manage the coherency of mapped segments.
+ * For non-NUMA architectures this routine will be a no-op. Note that
+ * implementations SHOULD implicitly unmap all packet segments
+ * whenever a packet is freed or added to a queue as this indicates
+ * that the caller is relinquishing control of the packet.
+ */
+void odp_packet_segment_unmap(odp_packet_segment_t seg);
+
+/**
+ * Get start address for a specified packet offset
+ *
+ * @param[in]  pkt     Packet handle
+ * @param[in]  offset  Byte offset within the packet to be addressed
+ * @param[out] seglen  Returned number of bytes in this packet
+ *                     segment available at returned address
+ *
+ * @return             Offset start address or NULL
+ *
+ * @note This routine returns the address of the packet starting at
+ * the specified byte offset. The returned seglen indicates the
+ * number of addressable bytes available at the returned address.
+ * This limit MUST be honored by the caller.
+ *
+ * @par
+ * Note that this is a general routine for accessing arbitrary
+ * byte offsets within a packet and is the bases for the “shortcut”
+ * APIs described below that access specific parser-identified offsets
+ * of interest.
+ *
+ * @par
+ * Note also that the returned seglen is always the minimum of
+ * the physical buffer segment size available at the starting offset
+ * and odp_packet_len() - offset. This rule applies to the “shortcut”
+ * routines that follow as well.
+ *
+ * @par
+ * For example, suppose the underlying implementation uses 256
+ * byte physical segment sizes and odp_packet_len() is 900. In this
+ * case a call to odp_packet_map() for offset 200 would return a
+ * seglen of 56, a call to odp_packet_map() for offset 256 would
+ * return a seglen of 256, and a call to odp_packet_map() for offset
+ * 768 would return a seglen of 132 since the packet ends there.
+ */
+void *odp_packet_offset_map(odp_packet_t pkt, size_t offset,
+                            size_t *seglen);
+
+/**
+ * Unmap a packet segment by offset
+ *
+ * @param[in] pkt    Packet handle
+ * @param[in] offset Packet offset
+ *
+ * @note This routine is used to unmap a buffer segment previously
+ * implicitly mapped by odp_packet_offset_map(). Following this call
+ * the application MUST NOT attempt to reference the segment via any
+ * pointer returned by a prior odp_packet_offset_map() call relating
+ * to this offset. It is intended to allow certain NUMA architectures
+ * to better manage the coherency of mapped segments. For non-NUMA
+ * architectures this routine will be a no-op. Note that
+ * implementations SHOULD implicitly unmap all packet segments
+ * whenever a packet is added to a queue as this indicates that the
+ * caller is relinquishing control of the packet.
+ */
+void odp_packet_offset_unmap(odp_packet_t pkt, size_t offset);
+
+/**
+ * Map packet to provide addressability to it
+ *
+ * @param[in]  pkt    Packet handle
+ * @param[out] seglen Number of contiguous bytes available at returned address
+ *
+ * @return         Packet start address or NULL
+ *
+ * @note This routine is an accessor function that returns the
+ * starting address of the packet. This is the first byte that would
+ * be placed on the wire if the packet were transmitted at the time of
+ * the call. This is normally the same as the first byte of the
+ * Ethernet frame that was received, and would normally be the start
+ * of the L2 header. Behavior of this routine is equivalent to the
+ * call:
+ *
+ * @code
+ * odp_packet_offset_map(pkt,0,&seglen);
+ * @endcode
+ *
+ * @par
+ * It is thus a shortcut for rapid access to the raw packet
+ * headers. Note that the returned seglen is the minimum of the
+ * packet length and the number of contiguous bytes available in the
+ * packet segment containing the returned starting address. It is a
+ * programming error to attempt to address beyond this returned
+ * length.
+ *
+ * @par
+ * For packets created by odp_packet_alloc() or
+ * odp_packet_alloc_len() this is the first byte of the allocated
+ * packet’s contents. Note that in the case of odp_packet_alloc() the
+ * packet length defaults to 0 and in the case of
+ * odp_packet_alloc_len() the contents of the packet is indeterminate
+ * until the application creates that content. Results are undefined
+ * if the supplied pkt does not represent a valid packet.
+ *
+ * @par
+ * Note that applications would normally not use this routine
+ * unless they need to do their own parsing of header fields or are
+ * otherwise directly adding or manipulating their own packet headers.
+ * Applications SHOULD normally use accessor functions to obtain the
+ * parsed header information they need directly.
+ *
+ */
+void *odp_packet_map(odp_packet_t pkt, size_t *seglen);
+
+/**
+ * Get address for the preparsed Layer 2 header
+ *
+ * @param[in]  pkt     Packet handle
+ * @param[out] seglen  Returned number of bytes in this packet
+ *                     segment available at returned address
+ *
+ * @return             Layer 2 start address or NULL
+ *
+ * @note This routine provides the caller with addressability to the
+ * first Layer 2 header of the packet, as identified by the ODP
+ * parser. Note that this may not necessarily represent the first
+ * byte of the packet as the caller may have pushed additional
+ * (unparsed) headers onto the packet. Also, if the packet does not
+ * have a recognized Layer 2 header then this routine will return NULL
+ * while odp_packet_map() will always return the address of the first
+ * byte of the packet (even if the packet is of null length).
+ *
+ * @par
+ *  Note that the behavior of this routine is identical to the
+ * call odp_packet_offset_map(pkt,odp_packet_l2_offset(pkt),&seglen).
+ *
+ */
+void *odp_packet_l2_map(odp_packet_t pkt, size_t *seglen);
+
+/**
+ * Get address for the preparsed Layer 3 header
+ *
+ * @param[in]  pkt     Packet handle
+ * @param[out] seglen  Returned number of bytes in this packet
+ *                     segment available at returned address
+ *
+ * @return             Layer 3 start address or NULL
+ *
+ * @note This routine provides the caller with addressability to the
+ * first Layer 3 header of the packet, as identified by the ODP
+ * parser. If the packet does not have a recognized Layer 3 header
+ * then this routine will return NULL.
+ *
+ * @par
+ * Note that the behavior of this routine is identical to the
+ * call odp_packet_offset_map(pkt,odp_packet_l3_offset(pkt),&seglen).
+ *
+ */
+void *odp_packet_l3_map(odp_packet_t pkt, size_t *seglen);
+
+/**
+ * Get address for the preparsed Layer 4 header
+ *
+ * @param[in]  pkt     Packet handle
+ * @param[out] seglen  Returned number of bytes in this packet
+ *                     segment available at returned address
+ *
+ * @return             Layer 4 start address or NULL
+ *
+ * @note This routine provides the caller with addressability to the
+ * first Layer 4 header of the packet, as identified by the ODP
+ * parser. If the packet does not have a recognized Layer 4 header
+ * then this routine will return NULL.
+ *
+ * @par
+ * Note that the behavior of this routine is identical to the
+ * call odp_packet_offset_map(pkt,odp_packet_l4_offset(pkt),&seglen).
+ *
+ */
+void *odp_packet_l4_map(odp_packet_t pkt, size_t *seglen);
+
+/**
+ * Get address for the packet payload
+ *
+ * @param[in]  pkt      Packet handle
+ * @param[out] seglen  Returned number of bytes in this packet
+ *                     segment available at returned address
+ *
+ * @return             Payload start address or NULL
+ *
+ * @note This routine provides the caller with addressability to the
+ * payload of the packet, as identified by the ODP parser. If the
+ * packet does not have a recognized payload (e.g., a TCP ACK packet)
+ * then this routine will return NULL. As noted above, ODP defines
+ * the packet payload to be the first byte after the last recognized
+ * header. This may in fact represent a Layer 5 header, or an
+ * unrecognized Layer 3 or Layer 4 header. It is an application
+ * responsibility to know how to deal with these bytes based on its
+ * protocol knowledge.
+ *
+ * @par
+ * Note that the behavior of this routine is identical to the call
+ * odp_packet_offset_map(pkt,odp_packet_payload_offset(pkt),&seglen).
+ *
+ */
+void *odp_packet_payload_map(odp_packet_t pkt, size_t *seglen);
+
+/**
+ * Clone a packet, returning an exact copy of it
+ *
+ * @param[in] pkt  Packet handle of packet to duplicate
+ *
+ * @return         Handle of the duplicated packet or ODP_PACKET_INVALID
+ *                 if the operation was not performed
+ *
+ * @note This routine allows an ODP packet to be cloned in an
+ * implementation-defined manner. The contents of the returned
+ * odp_packet_t is an exact copy of the input packet. The
+ * implementation MAY perform this operation via reference counts,
+ * resegmentation, or any other technique it wishes to employ. The
+ * cloned packet is an element of the same buffer pool as the input
+ * pkt and shares the same system meta data such as headroom and
+ * tailroom. If the input pkt contains user meta data, then this data
+ * MUST be copied to the returned packet by the ODP implementation.
+ *
+ * @par
+ * This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns ODP_PACKET_INVALID with an errno of
+ * ODP_FUNCTION_NOT_AVAILABLE.
+ */
+odp_packet_t odp_packet_clone(odp_packet_t pkt);
+
+/**
+ * Copy a packet, returning an exact copy of it
+ *
+ * @param[in] pkt  Packet handle of packet to copy
+ * @param[in] pool Buffer pool to contain copied packet
+ *
+ * @return         Handle of the copied packet or ODP_PACKET_INVALID
+ *                 if the operation was not performed
+ *
+ * @note This routine allows an ODP packet to be copied in an
+ * implementation-defined manner. The specified pool may or may not
+ * be different from that of the source packet, but if different MUST
+ * be of type ODP_BUFFER_TYPE_PACKET. The contents of the returned
+ * odp_packet_t is an exact separate copy of the input packet, and as
+ * such inherits its initial headroom and tailroom settings from the
+ * buffer pool from which it is allocated. If the input pkt contains
+ * user meta data, then this data MUST be copied to the returned
+ * packet if needed by the ODP implementation.
+ *
+ * @par
+ * This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns ODP_PACKET_INVALID with an errno of
+ * ODP_FUNCTION_NOT_AVAILABLE.
+ */
+odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t pool);
+
+/**
+ * Copy selected bytes from one packet to another
+ *
+ * @param[in] dstpkt    Handle of destination packet
+ * @param[in] dstoffset Byte offset in destination packet to receive bytes
+ * @param[in] srcpkt    Handle of source packet
+ * @param[in] srcoffset Byte offset in source packet from which to copy
+ * @param[in] len       Number of bytes to be copied
+ *
+ * @return 0 on Success, -1 on errors.
+ *
+ * @note This routine copies a slice of an ODP packet to another
+ * packet in an implementation-defined manner. The call copies len
+ * bytes starting at srcoffset from srcpkt to offset dstoffset in
+ * dstpkt. Any existing bytes in the target range of the destination
+ * packet are overwritten by the operation. The operation will fail
+ * if sufficient bytes are not available in the source packet or
+ * sufficient space is not available in the destination packet. This
+ * routine does not change the length of the destination packet. If
+ * the caller wishes to extend the destination packet it must first
+ * push the tailroom of the destination packet to make space available
+ * to receive the copied bytes.
+ *
+ * @par
+ * This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns -1 with an errno of ODP_FUNCTION_NOT_AVAILABLE.
+ */
+int odp_packet_copy_to_packet(odp_packet_t dstpkt, size_t dstoffset,
+                              odp_packet_t srcpkt, size_t srcoffset,
+                              size_t len);
+
+/**
+ * Copy selected bytes from a packet to a memory area
+ *
+ * @param[out] mem       Address to receive copied bytes
+ * @param[in]  srcpkt    Handle of source packet
+ * @param[in]  srcoffset Byte offset in source packet from which to copy
+ * @param[in]  len       Number of bytes to be copied
+ *
+ * @return 0 on Success, -1 on errors.
+ *
+ * @note This routine copies a slice of an ODP packet to an
+ * application-supplied memory area in an implementation-defined
+ * manner. The call copies len bytes starting at srcoffset from
+ * srcpkt to the address specified by mem. Any existing bytes in the
+ * target memory are overwritten by the operation. The operation will
+ * fail if sufficient bytes are not available in the source packet.
+ * It is the caller’s responsibility to ensure that the specified
+ * memory area is large enough to receive the packet bytes being
+ * copied.
+ *
+ * @par
+ * This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns -1 with an errno of ODP_FUNCTION_NOT_AVAILABLE.
+ *
+ */
+int odp_packet_copy_to_memory(void *mem,
+                              odp_packet_t srcpkt, size_t srcoffset,
+                              size_t len);
+
+/**
+ * Copy bytes from a memory area to a specified offset in a packet
+ *
+ * @param[in] dstpkt    Handle of destination packet
+ * @param[in] dstoffset Byte offset in destination packet to receive bytes
+ * @param[in] mem       Address of bytes to be copied
+ * @param[in] len       Number of bytes to be copied
+ *
+ * @return 0 on Success, -1 on errors.
+ *
+ * @note This routine copies len bytes from the application memory
+ * area mem to a specified offset of an ODP packet in an
+ * implementation-defined manner. Any existing bytes in the target
+ * range of the destination packet are overwritten by the operation.
+ * The operation will fail if sufficient space is not available in the
+ * destination packet. This routine does not change the length of the
+ * destination packet. If the caller wishes to extend the destination
+ * packet it must first push the tailroom of the destination packet to
+ * make space available to receive the copied bytes.
+ *
+ * @par
+ * This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns -1 with an errno of ODP_FUNCTION_NOT_AVAILABLE.
+ *
+ */
+int odp_packet_copy_from_memory(odp_packet_t dstpkt, size_t dstoffset,
+                                void *mem, size_t len);
+
+/**
+ * Split a packet into two packets at a specified split point
+ *
+ * @param[in] pkt    Handle of packet to split
+ * @param[in] offset Byte offset within pkt to split packet
+ * @param[in] hr     Headroom of split packet
+ * @param[in] tr     Tailroom of source packet
+ *
+ * @return           Packet handle of the created split packet
+ *
+ * @note This routine splits a packet into two packets at the
+ * specified byte offset. The odp_packet_t returned by the function
+ * is the handle of the new packet created at the split point. The new
+ * (split) packet is allocated from the same buffer pool as the
+ * original packet. If the original packet was len bytes in length
+ * then upon return the original packet is of length offset while the
+ * split packet is of length (len-offset).
+ *
+ * @par
+ * The original packet’s headroom is unchanged by this function.
+ * The split packet inherits it’s tailroom from the original packet.
+ * The hr and tr parameters are used to assign new headroom and
+ * tailroom values to the split and original packets, respectively.
+ * This operation is illustrated by the following diagrams. Prior to
+ * the split, the original packet looks like this:
+ *
+ * @image html splitbefore.png "Packet before split" width=\textwidth
+ * @image latex splitbefore.eps "Packet before split" width=\textwidth
+ *
+ * @par
+ * After splitting at the specified split offset the result is this:
+ *
+ * @image html splitafter.png "Packet after split" width=\textwidth
+ * @image latex splitafter.eps "Packet after split" width=\textwidth
+ *
+ * @par
+ * The data from the original packet from the specified split
+ * offset to the end of the original packet becomes the split packet.
+ * The packet data at the split point becomes offset 0 of the new
+ * packet created by the split. The split packet inherits the
+ * original packet’s tailroom and is assigned its own headroom from
+ * hr, while the original packet retains its original headroom while
+ * being assigned a new tailroom from tr.
+ *
+ * @par
+ * Upon return from this function, the system meta data for both
+ * packets has been updated appropriately by the call since system
+ * meta data maintenance is the responsibility of the ODP
+ * implementation. Any required updates to the user meta data is the
+ * responsibility of the caller.
+ *
+ * @par
+ * This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a matching routine that simply
+ * returns ODP_PACKET_INVALID with an errno of
+ * ODP_FUNCTION_NOT_AVAILABLE.
+ */
+odp_packet_t odp_packet_split(odp_packet_t pkt, size_t offset,
+                              size_t hr, size_t tr);
+
+/**
+ * Join two packets into a single packet
+ *
+ * @param[in] pkt1  Packet handle of first packet to join
+ * @param[in] pkt2  Packet handle of second packet to join
+ *
+ * @return          Packet handle of the joined packet
+ *
+ * @note This routine joins two packets into a single packet. Both
+ * pkt1 and pkt2 MUST be from the same buffer pool and the resulting
+ * joined packet will be an element of that same pool. The
+ * application MUST NOT assume that either pkt1 or pkt2 survive the
+ * join or that the returned joined packet is contiguous with or
+ * otherwise related to the input packets. An implementation SHOULD
+ * free either or both input packets if they are not reused as part of
+ * the construction of the returned joined packet. If the join cannot
+ * be performed (e.g., if the two input packets are not from the same
+ * buffer pool, insufficient space in the target buffer pool, etc.)
+ * then ODP_PACKET_INVALID SHOULD be returned to indicate that the
+ * operation could not be performed, and an appropriate errno set. In
+ * such case the input packets MUST NOT be freed as part of the failed
+ * join attempt and MUST be unchanged from their input values and
+ * content.
+ *
+ * @par
+ * The result of odp_packet_join() is the logical concatenation
+ * of the two packets using an implementation-defined aggregation
+ * mechanism. The application data contents of the returned packet is
+ * identical to that of the two joined input packets however certain
+ * associated meta data (e.g., information about the packet length)
+ * will likely differ. The headroom associated with the joined packet
+ * is the headroom of pkt1 while the tailroom of the joined packet is
+ * the tailroom of pkt2. Any tailroom from pkt1 or headroom from pkt2
+ * from before the join is handled in an implementation-defined manner
+ * and is no longer visible to the application.
+ *
+ * @par
+ * If user meta data is present in the input packets, then the
+ * user meta data associated with the returned packet MUST be copied
+ * by this routine from the source pkt1.
+ *
+ * @par
+ * This routine is OPTIONAL. An implementation that does not
+ * support this function MUST provide a routine matching that simply
+ * returns ODP_PACKET_INVALID with an errno of
+ * ODP_FUNCTION_NOT_AVAILABLE.
+ */
+odp_packet_t odp_packet_join(odp_packet_t pkt1, odp_packet_t pkt2);
+
+/**
+ * Push out packet head
+ *
+ * Push out packet address (away from data) and increase data length.
  * Does not modify packet in case of an error.
  *
- * seg_data_len  += len
+ * @code
+ * odp_packet_headroom       -= len
+ * odp_packet_len            += len
+ * odp_packet_l2_offset      += len
+ * odp_packet_l3_offset      += len
+ * odp_packet_l4_offset      += len
+ * odp_packet_payload_offset += len
+ * @endcode
+ *
+ * @param[in] pkt     Packet handle
+ * @param[in] len     Number of octets to push head [0...odp_packet_headroom]
+ *
+ * @return 0 on Success, -1 on error
+ *
+ * @note This routine pushes the packet start away from the current
+ * start point and into the packet headroom. This would normally be
+ * used by the application to prepend additional header information to
+ * the start of the packet. Note that pushing the header does not
+ * affect the parse results. Upon completion odp_packet_map() now
+ * points to the new start of the packet data area and
+ * odp_packet_len() is increased by the specified len.
+ *
+ * @par
+ * Note that it is the caller’s responsibility to initialize the
+ * new header area with meaningful data. This routine simply
+ * manipulates packet meta data and does not affect packet contents.
+ * The specified len is added to the following:
+ *
+ * - odp_packet_l2_offset
+ * - odp_packet_l3_offset
+ * - odp_packet_l4_offset
+ * - odp_packet_payload_offset
+ * - odp_packet_len
+ *
+ * @par
+ * In addition odp_packet_headroom is decremented by the specified len.
+ *
+ * @par
+ * Note that this routine simply adjusts the headroom and other
+ * meta data. If the caller also wishes to immediately address the
+ * newly added header area it can use the
+ * odp_packet_push_head_and_map() routine instead.
+ */
+int odp_packet_push_head(odp_packet_t pkt, size_t len);
+
+/**
+ * Push out packet head and map resulting packet
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
- * @param len  Number of octets to push tail (0 ... seg_tailroom)
+ * Push out packet address (away from data) and increase data length.
+ * Does not modify packet in case of an error.
  *
- * @return New segment data length, or -1 on an error
+ * @code
+ * odp_packet_headroom       -= len
+ * odp_packet_len            += len
+ * odp_packet_l2_offset      += len
+ * odp_packet_l3_offset      += len
+ * odp_packet_l4_offset      += len
+ * odp_packet_payload_offset += len
+ * @endcode
+ *
+ * @param[in]  pkt     Packet handle
+ * @param[in]  len     Number of octets to push head [0...odp_packet_headroom]
+ * @param[out] seglen  Number of addressable bytes at returned start address
+ *
+ * @return New packet data start address, or NULL on an error
+ *
+ * @note This routine pushes the packet start away from the current
+ * start point and into the packet headroom. This would normally be
+ * used by the application to prepend additional header information to
+ * the start of the packet. Note that pushing the header does not
+ * affect the parse results. Upon completion odp_packet_map() now
+ * points to the new start of the packet data area and
+ * odp_packet_len() is increased by the specified len.
+ *
+ * @par
+ * The returned seglen specifies the number of contiguously
+ * addressable bytes available at the returned start address. The
+ * caller MUST NOT attempt to address beyond this range. To access
+ * additional parts of the packet following odp_packet_push_head() the
+ * odp_packet_offset_map() routine SHOULD be used.
+ *
+ * @par
+ * Note that it is the caller’s responsibility to initialize the
+ * new header area with meaningful data. This routine simply
+ * manipulates packet meta data and does not affect packet contents.
+ * The specified len is added to the following:
+ *
+ * - odp_packet_l2_offset
+ * - odp_packet_l3_offset
+ * - odp_packet_l4_offset
+ * - odp_packet_payload_offset
+ * - odp_packet_len
+ *
+ * @par
+ * In addition odp_packet_headroom is decremented by the specified len.
+ *
+ * @par
+ * This routine is equivalent to the following code:
+ *
+ * @code
+ * odp_packet_push_head(pkt,len);
+ * void *result = odp_packet_map(pkt,&seglen);
+ * @endcode
+ *
+ * @par
+ * It exists for application convenience and MAY offer
+ * implementation efficiency.
  */
-int odp_packet_seg_push_tail(odp_packet_t pkt, odp_packet_seg_t seg,
-			     size_t len);
+void *odp_packet_push_head_and_map(odp_packet_t pkt, size_t len,
+                                   size_t *seglen);
 
 /**
- * Pull in segment tail
+ * Pull in packet head
  *
- * Decrease segment data length.
+ * Pull in packet address (consuming data) and decrease data length.
  * Does not modify packet in case of an error.
  *
- * seg_data_len  -= len
+ * @code
+ * odp_packet_headroom       += len
+ * odp_packet_len            -= len
+ * odp_packet_l2_offset      -= len
+ * odp_packet_l3_offset      -= len
+ * odp_packet_l4_offset      -= len
+ * odp_packet_payload_offset -= len
+ * @endcode
+ *
+ * @param[in] pkt     Packet handle
+ * @param[in] len     Number of octets to pull head [0...odp_packet_len]
+ *
+ * @return 0 on Success, -1 on error
+ *
+ * @note This routine pulls (consumes) bytes from the start of a
+ * packet, adding to the packet headroom. Typical use of this is to
+ * remove (pop) headers from a packet, possibly prior to pushing new
+ * headers. odp_packet_len() is decreased to reflect the shortened
+ * packet data resulting from the pull. This routine does not affect
+ * the contents of the packet, only meta data that describes it. The
+ * affected parsed offsets are decremented by the specified len,
+ * however no offset is decremented below 0.
+ *
+ * @par
+ * Note: Since odp_packet_push_head() and odp_packet_pull_head()
+ * simply manipulate meta data, it is likely that the meaning of the
+ * pre-parsed header offsets may be lost if headers are stripped and
+ * new headers are inserted. If the application is doing significant
+ * header manipulation, it MAY wish to call odp_packet_parse() when it
+ * is finished to cause the packet to be reparsed and the meaning of
+ * the various parsed meta data to be restored to reflect the new
+ * packet contents.
+ */
+void *odp_packet_pull_head(odp_packet_t pkt, size_t len);
+
+/**
+ * Pull in packet head and make results addressable to caller
+ *
+ * Pull in packet address (consuming data) and decrease data length.
+ * Does not modify packet in case of an error.
+ *
+ * @code
+ * odp_packet_headroom       += len
+ * odp_packet_len            -= len
+ * odp_packet_l2_offset      -= len
+ * odp_packet_l3_offset      -= len
+ * odp_packet_l4_offset      -= len
+ * odp_packet_payload_offset -= len
+ * @endcode
+ *
+ * @param[in]  pkt     Packet handle
+ * @param[in]  len     Number of octets to pull head [0...odp_packet_len]
+ * @param[out] seglen Number of addressable bytes at returned start address
+ *
+ * @return New packet data start address, or NULL on an error
+ *
+ * @note This routine pulls (consumes) bytes from the start of a
+ * packet, adding to the packet headroom. Typical use of this is to
+ * remove (pop) headers from a packet, possibly prior to pushing new
+ * headers. The return value of this routine is the new
+ * odp_packet_map() for the packet and odp_packet_len() is decreased
+ * to reflect the shortened packet data resulting from the pull. This
+ * routine does not affect the contents of the packet, only meta data
+ * that describes it. The affected parsed offsets are decremented by
+ * the specified len, however no offset is decremented below 0.
+ *
+ * @par
+ * Note: Since odp_packet_push_head() and odp_packet_pull_head()
+ * simply manipulate meta data, it is likely that the meaning of the
+ * pre-parsed header offsets may be lost if headers are stripped and
+ * new headers are inserted. If the application is doing significant
+ * header manipulation, it MAY wish to call odp_packet_parse() when it
+ * is finished to cause the packet to be reparsed and the meaning of
+ * the various parsed meta data to be restored to reflect the new
+ * packet contents.
+ *
+ * @par
+ * Note that this routine is equivalent to the calls:
+ *
+ * @code
+ * odp_packet_pull_head(pkt,len);
+ * void *result = odp_packet_map(pkt,&seglen);
+ * @endcode
+ *
+ * @par
+ * It exists for application convenience and MAY offer
+ * implementation efficiency.
+ */
+void *odp_packet_pull_head_and_map(odp_packet_t pkt, size_t len,
+                                   size_t *seglen);
+
+/**
+ * Push out packet tail
+ *
+ * Push out the end of the packet, consuming tailroom and increasing
+ * its length. Does not modify packet in case of an error.
+ *
+ * @code
+ * odp_packet_len      += len
+ * odp_packet_tailroom -= len
+ * @endcode
+ *
+ * @param[in] pkt     Packet handle
+ * @param[in] len     Number of octets to push tail [0...odp_packet_tailroom]
+ *
+ * @return 0 on Success, -1 on Failure
+ *
+ * @note This routine adds additional bytes to the end of a packet,
+ * increasing its length. Note that it does not change the contents
+ * of the packet but simply manipulates the packet meta data. It is
+ * the caller’s responsibility to initialize the new area with
+ * meaningful packet data.
+ *
+ * @par The intended use of this routine is to allow the application
+ * to insert additional payload or trailers onto the packet.
+ */
+void *odp_packet_push_tail(odp_packet_t pkt, size_t len);
+
+/**
+ * Push out packet tail and map results
+ *
+ * Push out the end of the packet, consuming tailroom and increasing
+ * its length. Does not modify packet in case of an error.
+ *
+ * @code
+ * odp_packet_len      += len
+ * odp_packet_tailroom -= len
+ * @endcode
+ *
+ * @param[in]  pkt     Packet handle
+ * @param[in]  len     Number of octets to push tail [0...odp_packet_tailroom]
+ * @param[out] seglen  Number of addressable bytes at returned data address
+ *
+ * @return Address of start of additional packet data, or NULL on an error
+ *
+ * @note This routine adds additional bytes to the end of a packet,
+ * increasing its length. Note that it does not change the contents
+ * of the packet but simply manipulates the packet meta data. It is
+ * the caller’s responsibility to initialize the new area with
+ * meaningful packet data.
+ *
+ * @par
+ * This routine is equivalent to the code:
+ *
+ * @code
+ * void *dataptr;
+ * size_t *seglen;
+ * odp_packet_push_tail(pkt, len);
+ * dataptr = odp_packet_offset_map(pkt, odp_packet_len(pkt) - len, &seglen);
+ * @endcode
+ *
+ * @par
+ * The returned pointer is the mapped start of the new data area
+ * (beginning at the former odp_packet_len() offset) and the returned
+ * seglen is the number of contiguously addressable bytes available at
+ * that address. The caller should initialize the additional data
+ * bytes to meaningful values. If seglen is less than the requested
+ * len then odp_packet_offset_map() should be used to address the
+ * remaining bytes.
+ *
+ * @par
+ * The intended use of this routine is to allow the application
+ * to insert additional payload or trailers onto the packet.
+ */
+void *odp_packet_push_tail_and_map(odp_packet_t pkt, size_t len, size_t *seglen);
+
+/**
+ * Pull in packet tail
+ *
+ * Reduce packet length, trimming data from the end of the packet,
+ * and adding to its tailroom. Does not modify packet in case of an error.
+ *
+ * @code
+ * odp_packet_len      -= len
+ * odp_packet_tailroom += len
+ * @endcode
+ *
+ * @param[in] pkt     Packet handle
+ * @param[in] len     Number of octets to pull tail [0...odp_packet_len]
  *
- * @param pkt  Packet handle
- * @param seg  Segment handle
- * @param len  Number of octets to pull tail (0 ... seg_data_len)
+ * @return 0 on Success, -1 on failure.
  *
- * @return New segment data length, or -1 on an error
+ * @note This routine pulls in the packet tail, adding those bytes to
+ * the packet tailroom. Upon successful return the packet has been
+ * trimmed by len bytes. The intended use of this routine is to allow
+ * the application to remove tailers from the packet.
  */
-int odp_packet_seg_pull_tail(odp_packet_t pkt, odp_packet_seg_t seg,
-			     size_t len);
+int odp_packet_pull_tail(odp_packet_t pkt, size_t len);
 
 /**
  * @}
