@@ -44,7 +44,6 @@ extern "C" {
#include <odp_schedule.h>
#include <odp_sync.h>
#include <odp_packet.h>
-#include <odp_packet_flags.h>
#include <odp_packet_io.h>
#include <odp_crypto.h>
#include <odp_rwlock.h>
@@ -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 metadata 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 metadata 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 metadata and the
+ * only built-in metadata 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 metadata. 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 metadata. 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 Metadata
+ * Metadata is additional information relating to a
+ * buffer that is distinct from the application data normally held in
+ * the buffer. Implementations MAY choose to implement metadata as
+ * contiguous with a buffer (e.g., in an implementation-managed prefix
+ * area of the buffer) or in a physically separate metadata 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 metadata, or between metadata items.
+ * Application use of metadata 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,457 @@ 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 = 0, /**< Default, no buffer options */
+ ODP_BUFFER_OPTS_UNSEGMENTED = 1, /**< No segments, please */
+} odp_buffer_opts_e;
+
+/**
+ * Error returns
+ */
+#define ODP_BUFFER_INVALID (odp_buffer_t)(-1)
+#define ODP_SEGMENT_INVALID (odp_buffer_segment_t)(-1)
+
+/**
+ * Obtain buffer pool handle of a buffer
+ *
+ * @param[in] buf Buffer handle
+ *
+ * @return Buffer pool the buffer was allocated from
+ *
+ * @note This routine is an accessor function that returns the handle
+ * of the buffer pool containing the referenced buffer.
+ */
+odp_buffer_pool_t odp_buffer_pool(odp_buffer_t buf);
/**
* 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 metadata, 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 metadata for buffer
+ *
+ * @param[in] buf Buffer handle
+ * @param[out] udata_size Number of bytes of user metadata available
+ * at the returned address
+ * @return Address of the user metadata for this buffer
+ * or NULL if the buffer has no user metadata.
+ */
+void *odp_buffer_udata(odp_buffer_t buf, size_t *udata_size);
+/**
+ * Get address of user metadata for buffer
+ *
+ * @param[in] buf Buffer handle
+ *
+ * @return Address of the user metadata for this buffer
+ * or NULL if the buffer has no user metadata.
+ *
+ * @note This is a "fastpath" version of odp_buffer_udata() since it
+ * omits returning the size of the user metadata 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:
+ * @note
+ * -# 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).
+ *
+ * @note Upon return from this function, the system metadata for both
+ * buffers has been updated appropriately by the call since system
+ * metadata maintenance is the responsibility of the ODP
+ * implementation. Any required updates to the user metadata 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.
+ *
+ * @note 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 metadata (e.g., information
+ * about the buffer size) will likely differ.
+ *
+ * @note If user metadata is present in the buffer pool containing the
+ * input buffers, then the user metadata associated with the returned
+ * buffer MUST be copied by this routine from the source buf1.
+ */
+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.
+ *
+ * @note If the input buf contains user metadata, then this data MUST
+ * be copied to the returned buffer if needed by the API
+ * implementation.
+ */
+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.
+ *
+ * @note 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.
+ */
+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.
+ */
+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 metadata, then this data
+ * MUST be copied to the returned buffer by the ODP implementation.
+ */
+odp_buffer_t odp_buffer_copy(odp_buffer_t buf, odp_buffer_pool_t pool);
+
+/**
* @}
*/
@@ -8,7 +8,43 @@
/**
* @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_
@@ -34,75 +70,336 @@ extern "C" {
/** Invalid buffer pool */
#define ODP_BUFFER_POOL_INVALID 0
-/** ODP buffer pool */
-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 metadata
+ * 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 metadata for each buffer
+ * @param[in] buf_init Function pointer to be called to initialize the
+ * user metadata 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 metadata 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 metadata that should be associated with each buffer in
+ * the pool. If no user metadata is required, the init_params SHOULD
+ * be specified as NULL. If user metadata is requested, then
+ * udata_size SHOULD be set to the requested size of the per-buffer
+ * user metadata. 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);
+/**
+ * Destroy a buffer pool previously created by odp_buffer_pool_create()
+ *
+ * @param[in] pool Handle of the buffer pool to be destroyed
+ *
+ * @return 0 on Success, -1 on Failure.
+ *
+ * @note This routine destroys a previously created buffer pool.
+ * Attempts to destroy a predefined buffer pool will be rejected
+ * since the application did not create it. Results are undefined if
+ * an attempt is made to destroy a buffer pool that contains allocated
+ * or otherwise active buffers.
+ */
+int odp_buffer_pool_destroy(odp_buffer_pool_t pool);
/**
* 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 metadata 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.
+ *
+ * @note 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);
/**
- * Print buffer pool info
+ * 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.
*
- * @param pool Pool handle
+ * @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.
*
+ * @note 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.
+ *
+ * @note 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.
*/
-void odp_buffer_pool_print(odp_buffer_pool_t pool);
+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);
+/**
+ * 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.
+ *
+ * @note This routine returns the headroom associated with the buffer
+ * pool. This is the headroom that will be set for packets allocated
+ * from this packet buffer pool.
+ */
+size_t odp_buffer_pool_headroom(odp_buffer_pool_t pool);
/**
- * Buffer alloc
+ * Set the headroom for a packet buffer pool
*
- * The validity of a buffer can be cheked at any time with odp_buffer_is_valid()
- * @param pool Pool handle
+ * @param[in] pool Handle of the buffer pool
+ * @param[in] hr The headroom for the pool
*
- * @return Buffer handle or ODP_BUFFER_INVALID
+ * @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.
+ *
+ * @note Headroom serves two purposes. The first is to reserve a prefix area
+ * of buffers that will hold packets for header expansion. Applications
+ * can add headers to packets via the odp_packet_push_headroom() to make
+ * headroom space available for new headers.
+ *
+ * @note The second use of headroom is to control packet alignment
+ * within buffers. The buffers in a buffer pool MUST be "naturally
+ * aligned" for addressing purposes by the implementation. It is
+ * RECOMMENDED that this be cache aligned. Because a standard
+ * Ethernet header is 14 octets in length, it is usually convenient to
+ * offset packets by 2 octets so that the following Layer 3 header
+ * (typically IPv4 or IPv6) is naturally aligned on a word boundary.
+ * So applications SHOULD specify an offset that reflects the packet
+ * alignment they wish to see. For example, a call like
+ * odp_buffer_pool_set_headroom(pool, hr+2); would force packets to by
+ * offset by two bytes to achieve the desired Layer 3 alignment while
+ * also reserving hr bytes of headroom for application use.
*/
-odp_buffer_t odp_buffer_alloc(odp_buffer_pool_t 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.
+ *
+ * @note This routine returns the tailroom associated with buffers
+ * allocated from a packet buffer pool.
+ */
+size_t odp_buffer_pool_tailroom(odp_buffer_pool_t pool);
/**
- * Buffer free
+ * Set the tailroom for a packet buffer pool
*
- * @param buf Buffer handle
+ * @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.
*/
-void odp_buffer_free(odp_buffer_t buf);
+int odp_buffer_pool_set_tailroom(odp_buffer_pool_t pool, size_t tr);
+/**
+ * Print buffer pool info
+ *
+ * @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);
/**
- * Buffer pool of the buffer
+ * Buffer alloc
*
- * @param buf Buffer handle
+ * The validity of a buffer can be cheked at any time with odp_buffer_is_valid()
+ * @param[in] pool Pool handle
*
- * @return Buffer pool the buffer was allocated from
+ * @return Buffer handle or ODP_BUFFER_INVALID
*/
-odp_buffer_pool_t odp_buffer_pool(odp_buffer_t buf);
+odp_buffer_t odp_buffer_alloc(odp_buffer_pool_t pool);
+
+/**
+ * Buffer free
+ *
+ * @param[in] buf Buffer handle
+ *
+ */
+void odp_buffer_free(odp_buffer_t buf);
/**
* @}
@@ -49,6 +49,12 @@ extern "C" {
#define ODP_CONFIG_PKTIO_ENTRIES 64
/**
+ * Packet processing limits
+ */
+#define ODP_CONFIG_BUF_SEG_SIZE (512*3)
+#define ODP_CONFIG_BUF_MAX_SIZE (ODP_CONFIG_BUF_SEG_SIZE*7)
+
+/**
* @}
*/
@@ -8,7 +8,262 @@
/**
* @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 metadata beyond those found
+ * in buffers that is populated by the parse function of the ODP
+ * classifier. See below for a discussion of this metadata 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 metadata 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 metadata, ODP
+ * applications accelerate packet processing by minimizing the need to
+ * examine packet data. This is because the packet metadata 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 metadata 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 metadata 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 metadata 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 metadata 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 metadata 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 metadata 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
+ * metadata 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 metadata 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 metadata 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 +276,7 @@ extern "C" {
#include <odp_buffer.h>
/** @defgroup odp_packet ODP PACKET
- * Operations on a packet.
+ *
* @{
*/
@@ -31,7 +286,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 +295,2050 @@ 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);
+
+/**
+ * Obtain buffer pool handle of a packet
+ *
+ * @param[in] pkt 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_buffer_pool_t odp_packet_pool(odp_packet_t pkt);
/**
- * ODP packet segment info
+ * 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.
*/
-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;
+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.
+ *
+ * @note 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.
+ *
+ * @note 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.
+ *
+ * @note 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);
/**
- * Initialize the packet
+ * Packet alloc
*
- * 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] pool Pool handle for a pool of type ODP_BUFFER_TYPE_PACKET
*
- * @param pkt Packet handle
+ * @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.
+ *
+ * @note If non-persistent user metadata 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 metadata associated with it.
+ */
+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 metadata that would be present
+ * following a packet parse.
+ */
+odp_packet_t odp_packet_alloc_len(odp_buffer_pool_t pool, size_t len);
+
+/**
+ * Packet free
+ *
+ * @param[in] pkt Handle of the packet to be freed
+ *
+ * @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 metadata 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);
+size_t odp_packet_len(odp_packet_t pkt);
/**
- * Set packet user context
+ * Get address and size of user metadata associated with a packet
+ *
+ * @param[in] pkt Packet handle
+ * @param[out] udata_size Number of bytes of user metadata available
+ * at the returned address
*
- * @param buf Packet handle
- * @param ctx User context
+ * @return Address of the user metadata for this packet
+ * or NULL if the buffer has no user metadata.
*
+ * @note This routine returns the address of the user metadata
+ * associated with an ODP packet. This enables the caller to read or
+ * write the user metadata 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 metadata associated with a packet
*
- * @param buf Packet handle
+ * @param[in] pkt Packet handle
*
- * @return User context
+ * @return Address of the user metadata for this packet
+ * or NULL if the buffer has no user metadata.
+ *
+ * @note This routine returns the address of the user metadata
+ * associated with an ODP packet. This enables the caller to read or
+ * write the user metadata 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 metadata 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_udata_addr(odp_packet_t pkt);
+
+/**
+ * Tests if packet is valid
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if valid, otherwise 0
+ *
+ * @note This routine tests whether a packet is valid. A packet is
+ * valid if the packet identified by the supplied odp_packet_t exists
+ * and has been allocated.
*/
-void *odp_packet_get_ctx(odp_packet_t buf);
+int odp_packet_is_valid(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 metadata.
+ *
+ * @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 metadata 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).
*
- * @param pkt Packet handle
+ * @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[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 pkt Packet handle
+ * @param[in] pkt Packet handle
+ * @param[in] val Value to decrement refcount by
*
- * @return L2 byte offset or ODP_PACKET_OFFSET_INVALID if not found
+ * @return The packet refcount following decrement
+ *
+ * @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[in] pkt Packet handle
*
- * @param pkt Packet handle
- * @param offset L2 byte offset
+ * @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 pkt Packet handle
+ * @param[in] pkt Packet handle
*
- * @return L3 byte offset or ODP_PACKET_OFFSET_INVALID if not found
+ * @param[in] val 1 if packet contains a valid & known L3 header, 0 otherwise
+ *
+ * @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);
+
+/**
+ * Check for L4 header, e.g. UDP, TCP, (also ICMP)
+ *
+ * @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.
+ */
+int odp_packet_inflag_l4(odp_packet_t pkt);
/**
- * Set the byte offset to the L3 packet
+ * Control indication of L4 header, e.g. UDP, TCP, (also ICMP)
*
- * @param pkt Packet handle
- * @param offset L3 byte offset
+ * @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_l3_offset(odp_packet_t pkt, size_t offset);
+void odp_packet_set_inflag_l4(odp_packet_t pkt, int val);
+/**
+ * Check for Ethernet header
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains a valid eth header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * a valid Ethernet header.
+ */
+int odp_packet_inflag_eth(odp_packet_t pkt);
/**
- * Get pointer to the start of the L4 packet
+ * Control indication of 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 sets whether the referenced packet contains a
+ * valid Ethernet header.
*/
-uint8_t *odp_packet_l4(odp_packet_t pkt);
+void odp_packet_set_inflag_eth(odp_packet_t pkt, int val);
/**
- * Return the byte offset from the packet buffer to the L4 packet
+ * Check for Ethernet SNAP vs. DIX format
+ *
+ * @param[in] pkt Packet handle
*
- * @param pkt Packet handle
+ * @return 1 if packet is SNAP, 0 if it is DIX
*
- * @return L4 byte offset or ODP_PACKET_OFFSET_INVALID if not found
+ * @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.
*/
-size_t odp_packet_l4_offset(odp_packet_t pkt);
+int odp_packet_inflag_snap(odp_packet_t pkt);
/**
- * Set the byte offset to the L4 packet
+ * Control indication of Ethernet SNAP vs. DIX format
*
- * @param pkt Packet handle
- * @param offset L4 byte offset
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet is SNAP, 0 if it is DIX
+ *
+ * @note This routine sets whether the referenced packet Ethernet is
+ * SNAP.
*/
-void odp_packet_set_l4_offset(odp_packet_t pkt, size_t offset);
+void odp_packet_set_inflag_snap(odp_packet_t pkt, int val);
/**
- * Print (debug) information about the packet
+ * Check for jumbo frame
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains jumbo frame, 0 otherwise
*
- * @param pkt Packet handle
+ * @note This routine indicates whether the referenced packet contains
+ * a jumbo frame. A jumbo frame has a length greater than 1500 bytes.
*/
-void odp_packet_print(odp_packet_t pkt);
+int odp_packet_inflag_jumbo(odp_packet_t pkt);
/**
- * Copy contents and metadata from pkt_src to pkt_dst
- * Useful when creating copies of packets
+ * Control indication of jumbo frame
*
- * @param pkt_dst Destination packet
- * @param pkt_src Source packet
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains jumbo frame, 0 otherwise
*
- * @return 0 if successful
+ * @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_copy(odp_packet_t pkt_dst, odp_packet_t pkt_src);
+void odp_packet_set_inflag_jumbo(odp_packet_t pkt, int val);
/**
- * Tests if packet is segmented (a scatter/gather list)
+ * Check for VLAN
+ *
+ * @param[in] pkt Packet handle
*
- * @param pkt Packet handle
+ * @return 1 if packet contains a VLAN header, 0 otherwise
*
- * @return Non-zero if packet is segmented, otherwise 0
+ * @note This routine indicates whether the referenced packet contains
+ * one or more VLAN headers.
*/
-int odp_packet_is_segmented(odp_packet_t pkt);
+int odp_packet_inflag_vlan(odp_packet_t pkt);
+
+/**
+ * Control indication of VLAN
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @param[in] val 1 if packet contains a VLAN header, 0 otherwise
+ *
+ * @note This routine sets whether the referenced packet contains one
+ * or more VLAN headers.
+ */
+void odp_packet_set_inflag_vlan(odp_packet_t pkt, int val);
/**
- * Segment count
+ * Check for VLAN QinQ (stacked 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
+ *
+ * @return 1 if packet contains a VLAN QinQ header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * a double VLAN header (Q-in-Q) matching the IEEE 802.1ad
+ * specification.
+ */
+int odp_packet_inflag_vlan_qinq(odp_packet_t pkt);
+
+/**
+ * Controls indication of VLAN QinQ (stacked VLAN)
*
- * @param pkt Packet handle
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains a VLAN QinQ header, 0 otherwise
*
- * @return Segment count
+ * @note This routine sets whether the referenced packet contains a
+ * double VLAN header (Q-in-Q) matching the IEEE 802.1ad
+ * specification.
*/
-int odp_packet_seg_count(odp_packet_t pkt);
+void odp_packet_set_inflag_vlan_qinq(odp_packet_t pkt, int val);
/**
- * Get segment by index
+ * Check for ARP
*
- * @param pkt Packet handle
- * @param index Segment index (0 ... seg_count-1)
+ * @param[in] pkt Packet handle
*
- * @return Segment handle, or ODP_PACKET_SEG_INVALID on an error
+ * @return 1 if packet contains an ARP header, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * an ARP header.
*/
-odp_packet_seg_t odp_packet_seg(odp_packet_t pkt, int index);
+int odp_packet_inflag_arp(odp_packet_t pkt);
/**
- * Get next segment
+ * Controls indication of ARP
*
- * @param pkt Packet handle
- * @param seg Current segment handle
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains an ARP 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 an
+ * ARP header.
*/
-odp_packet_seg_t odp_packet_seg_next(odp_packet_t pkt, odp_packet_seg_t seg);
+void odp_packet_set_inflag_arp(odp_packet_t pkt, int val);
/**
- * Segment info
+ * Check for IPv4
*
- * Copies segment parameters into the info structure.
+ * @param[in] pkt Packet handle
*
- * @param pkt Packet handle
- * @param seg Segment handle
- * @param info Pointer to segment info structure
+ * @return 1 if packet contains an IPv4 header, 0 otherwise
*
- * @return 0 if successful, otherwise non-zero
+ * @note This routine indicates whether the referenced packet contains
+ * an IPv4 header.
*/
-int odp_packet_seg_info(odp_packet_t pkt, odp_packet_seg_t seg,
- odp_packet_seg_info_t *info);
+int odp_packet_inflag_ipv4(odp_packet_t pkt);
/**
- * Segment start address
+ * 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 start address, or NULL on an error
+ * @note This routine sets whether the referenced packet contains an
+ * IPv4 header.
*/
-void *odp_packet_seg_addr(odp_packet_t pkt, odp_packet_seg_t seg);
+void odp_packet_set_inflag_ipv4(odp_packet_t pkt, int val);
/**
- * Segment maximum data size
+ * Check for IPv6
+ *
+ * @param[in] pkt Packet handle
*
- * @param pkt Packet handle
- * @param seg Segment handle
+ * @return 1 if packet contains an IPv6 header, 0 otherwise
*
- * @return Segment maximum data size
+ * @note This routine indicates whether the referenced packet contains
+ * an IPv6 header.
*/
-size_t odp_packet_seg_size(odp_packet_t pkt, odp_packet_seg_t seg);
+int odp_packet_inflag_ipv6(odp_packet_t pkt);
/**
- * Segment data address
+ * 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 address
+ * @note This routine sets whether the referenced packet contains an
+ * IPv6 header.
*/
-void *odp_packet_seg_data(odp_packet_t pkt, odp_packet_seg_t seg);
+void odp_packet_set_inflag_ipv6(odp_packet_t pkt, int val);
/**
- * Segment data length
+ * Check for IP fragment
*
- * @param pkt Packet handle
- * @param seg Segment handle
+ * @param[in] pkt Packet handle
*
- * @return Segment data length
+ * @return 1 if packet is an IP fragment, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * an IP fragment.
*/
-size_t odp_packet_seg_data_len(odp_packet_t pkt, odp_packet_seg_t seg);
+int odp_packet_inflag_ipfrag(odp_packet_t pkt);
/**
- * Segment headroom
+ * Controls indication of IP fragment
*
- * seg_headroom = seg_data - seg_addr
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet is an IP fragment, 0 otherwise
*
- * @param pkt Packet handle
- * @param seg Segment handle
+ * @note This routine sets whether the referenced packet contains an
+ * IP fragment.
+ */
+void odp_packet_set_inflag_ipfrag(odp_packet_t pkt, int val);
+
+/**
+ * Check for IP options
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet contains IP options, 0 otherwise
*
- * @return Number of octets from seg_addr to seg_data
+ * @note This routine indicates whether the referenced packet contains
+ * IP options.
*/
-size_t odp_packet_seg_headroom(odp_packet_t pkt, odp_packet_seg_t seg);
+int odp_packet_inflag_ipopt(odp_packet_t pkt);
/**
- * Segment tailroom
+ * Controls indication of IP options
*
- * seg_tailroom = seg_size - seg_headroom - seg_data_len
+ * @param[in] pkt Packet handle
+ * @param[in] val 1 if packet contains IP options, 0 otherwise
*
- * @param pkt Packet handle
- * @param seg Segment handle
+ * @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
*
- * @return Number of octets from end-of-data to end-of-segment
+ * @param[in] pkt Packet handle
+ *
+ * @return 1 if packet requires IPSec processing, 0 otherwise
+ *
+ * @note This routine indicates whether the referenced packet contains
+ * an IPSec header (ESP or AH).
*/
-size_t odp_packet_seg_tailroom(odp_packet_t pkt, odp_packet_seg_t seg);
+int odp_packet_inflag_ipsec(odp_packet_t pkt);
/**
- * Push out segment head
+ * Control indication of IPSec
*
- * 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 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
*
- * 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 contains a UDP header, 0 otherwise
*
- * @return New segment data address, or NULL on an error
+ * @note This routine indicates whether the referenced packet contains
+ * a UDP header.
*/
-void *odp_packet_seg_push_head(odp_packet_t pkt, odp_packet_seg_t seg,
- size_t len);
+int odp_packet_inflag_udp(odp_packet_t pkt);
/**
- * Pull in segment head
+ * Control indication of UDP
*
- * 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 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_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
+ *
+ * @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 errors
+ *
+ * @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 metadata 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 metadata
+ * 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, size_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.
+ */
+uint32_t 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 metadata 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 metadata 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.
+ */
+uint32_t 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 metadata 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[in] pkt Packet handle
+ * @param[in] ndx Segment index of segment of interest
+ *
+ * @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.
+ */
+odp_packet_segment_t odp_packet_segment_by_index(odp_packet_t pkt, size_t ndx);
+
+/**
+ * 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
+ *
+ * @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 addressability to first packet segment
+ *
+ * @param[in] pkt Packet handle
+ *
+ * @return Packet start address or NULL
+ *
+ * @warning Deprecated API!
+ * @warning
+ * This API provides a fast path for addressability to the first
+ * segment of a packet. Calls to this routine SHOULD be replaced
+ * with corresponding calls to odp_packet_map() since this routine
+ * gives no indication of addressing limits of the returned pointer.
+ */
+void *odp_packet_addr(odp_packet_t pkt);
+
+/**
+ * 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.
*
- * seg_data += len
- * seg_data_len -= len
+ * @par
+ * Note that the behavior of this routine is identical to the call
+ * odp_packet_offset_map(pkt,odp_packet_payload_offset(pkt),&seglen).
*
- * @param pkt Packet handle
- * @param seg Segment handle
- * @param len Number of octets to pull head (0 ... seg_data_len)
+ */
+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 metadata such as headroom and
+ * tailroom. If the input pkt contains user metadata, 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 metadata, 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 metadata for both
+ * packets has been updated appropriately by the call since system
+ * metadata maintenance is the responsibility of the ODP
+ * implementation. Any required updates to the user metadata 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 metadata (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 metadata is present in the input packets, then the
+ * user metadata 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.
*
- * @return New segment data address, or NULL 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]
+ *
+ * @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 metadata 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
+ * metadata. 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.
*/
-void *odp_packet_seg_pull_head(odp_packet_t pkt, odp_packet_seg_t seg,
- size_t len);
+int odp_packet_push_head(odp_packet_t pkt, size_t len);
/**
- * Push out segment tail
+ * Push out packet head and map resulting packet
*
- * Increase segment data length.
+ * 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]
+ * @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 metadata 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.
+ */
+void *odp_packet_push_head_and_map(odp_packet_t pkt, size_t len,
+ size_t *seglen);
+
+/**
+ * Pull in packet head
*
- * @param pkt Packet handle
- * @param seg Segment handle
- * @param len Number of octets to push tail (0 ... seg_tailroom)
+ * Pull in packet address (consuming data) and decrease 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 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 metadata 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 metadata, 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 metadata to be restored to reflect the new
+ * packet contents.
*/
-int odp_packet_seg_push_tail(odp_packet_t pkt, odp_packet_seg_t seg,
- size_t len);
+int odp_packet_pull_head(odp_packet_t pkt, size_t len);
/**
- * Pull in segment tail
+ * Pull in packet head and make results addressable to caller
*
- * 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]
+ * @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 metadata
+ * 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 metadata, 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 metadata 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 metadata. 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.
+ */
+int 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 metadata. 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);
/**
* @}
deleted file mode 100644
@@ -1,334 +0,0 @@
-/* Copyright (c) 2014, Linaro Limited
- * All rights reserved.
- *
- * SPDX-License-Identifier: BSD-3-Clause
- */
-
-
-/**
- * @file
- *
- * ODP packet flags
- */
-
-#ifndef ODP_PACKET_FLAGS_H_
-#define ODP_PACKET_FLAGS_H_
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#include <odp_std_types.h>
-#include <odp_packet.h>
-
-/** @addtogroup odp_packet
- * Boolean operations on a packet.
- * @{
- */
-
-/**
- * Check for packet errors
- *
- * Checks all error flags at once.
- *
- * @param pkt Packet handle
- * @return 1 if packet has errors, 0 otherwise
- */
-int odp_packet_error(odp_packet_t pkt);
-
-/**
- * Check if error was 'frame length' error
- *
- * @param pkt Packet handle
- * @return 1 if frame length error detected, 0 otherwise
- */
-int odp_packet_errflag_frame_len(odp_packet_t pkt);
-
-/**
- * Check for L2 header, e.g. ethernet
- *
- * @param pkt Packet handle
- * @return 1 if packet contains a valid & known L2 header, 0 otherwise
- */
-int odp_packet_inflag_l2(odp_packet_t pkt);
-
-/**
- * Check for L3 header, e.g. IPv4, IPv6
- *
- * @param pkt Packet handle
- * @return 1 if packet contains a valid & known L3 header, 0 otherwise
- */
-int odp_packet_inflag_l3(odp_packet_t pkt);
-
-/**
- * Check for L4 header, e.g. UDP, TCP, SCTP (also ICMP)
- *
- * @param pkt Packet handle
- * @return 1 if packet contains a valid & known L4 header, 0 otherwise
- */
-int odp_packet_inflag_l4(odp_packet_t pkt);
-
-/**
- * Check for Ethernet header
- *
- * @param pkt Packet handle
- * @return 1 if packet contains a valid eth header, 0 otherwise
- */
-int odp_packet_inflag_eth(odp_packet_t pkt);
-
-/**
- * Check for jumbo frame
- *
- * @param pkt Packet handle
- * @return 1 if packet contains jumbo frame, 0 otherwise
- */
-int odp_packet_inflag_jumbo(odp_packet_t pkt);
-
-/**
- * Check for VLAN
- *
- * @param pkt Packet handle
- * @return 1 if packet contains a VLAN header, 0 otherwise
- */
-int odp_packet_inflag_vlan(odp_packet_t pkt);
-
-/**
- * Check for VLAN QinQ (stacked VLAN)
- *
- * @param pkt Packet handle
- * @return 1 if packet contains a VLAN QinQ header, 0 otherwise
- */
-int odp_packet_inflag_vlan_qinq(odp_packet_t pkt);
-
-/**
- * Check for ARP
- *
- * @param pkt Packet handle
- * @return 1 if packet contains an ARP header, 0 otherwise
- */
-int odp_packet_inflag_arp(odp_packet_t pkt);
-
-/**
- * Check for IPv4
- *
- * @param pkt Packet handle
- * @return 1 if packet contains an IPv4 header, 0 otherwise
- */
-int odp_packet_inflag_ipv4(odp_packet_t pkt);
-
-/**
- * Check for IPv6
- *
- * @param pkt Packet handle
- * @return 1 if packet contains an IPv6 header, 0 otherwise
- */
-int odp_packet_inflag_ipv6(odp_packet_t pkt);
-
-/**
- * Check for IP fragment
- *
- * @param pkt Packet handle
- * @return 1 if packet is an IP fragment, 0 otherwise
- */
-int odp_packet_inflag_ipfrag(odp_packet_t pkt);
-
-/**
- * Check for IP options
- *
- * @param pkt Packet handle
- * @return 1 if packet contains IP options, 0 otherwise
- */
-int odp_packet_inflag_ipopt(odp_packet_t pkt);
-
-/**
- * Check for IPSec
- *
- * @param pkt Packet handle
- * @return 1 if packet requires IPSec processing, 0 otherwise
- */
-int odp_packet_inflag_ipsec(odp_packet_t pkt);
-
-/**
- * Check for UDP
- *
- * @param pkt Packet handle
- * @return 1 if packet contains a UDP header, 0 otherwise
- */
-int odp_packet_inflag_udp(odp_packet_t pkt);
-
-/**
- * Check for TCP
- *
- * @param pkt Packet handle
- * @return 1 if packet contains a TCP header, 0 otherwise
- */
-int odp_packet_inflag_tcp(odp_packet_t pkt);
-
-/**
- * Check for SCTP
- *
- * @param pkt Packet handle
- * @return 1 if packet contains an SCTP header, 0 otherwise
- */
-int odp_packet_inflag_sctp(odp_packet_t pkt);
-
-/**
- * Check for ICMP
- *
- * @param pkt Packet handle
- * @return 1 if packet contains an ICMP header, 0 otherwise
- */
-int odp_packet_inflag_icmp(odp_packet_t pkt);
-
-/**
- * Request L4 checksum calculation
- *
- * @param pkt Packet handle
- */
-void odp_packet_outflag_l4_chksum(odp_packet_t pkt);
-
-/**
- * Set flag for L2 header, e.g. ethernet
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_l2(odp_packet_t pkt, int val);
-
-/**
- * Set flag for L3 header, e.g. IPv4, IPv6
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_l3(odp_packet_t pkt, int val);
-
-/**
- * Set flag for L4 header, e.g. UDP, TCP, SCTP (also ICMP)
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_l4(odp_packet_t pkt, int val);
-
-/**
- * Set flag for Ethernet header
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_eth(odp_packet_t pkt, int val);
-
-/**
- * Set flag for jumbo frame
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_jumbo(odp_packet_t pkt, int val);
-
-/**
- * Set flag for VLAN
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_vlan(odp_packet_t pkt, int val);
-
-/**
- * Set flag for VLAN QinQ (stacked VLAN)
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_vlan_qinq(odp_packet_t pkt, int val);
-
-/**
- * Set flag for ARP
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_arp(odp_packet_t pkt, int val);
-
-/**
- * Set flag for IPv4
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_ipv4(odp_packet_t pkt, int val);
-
-/**
- * Set flag for IPv6
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_ipv6(odp_packet_t pkt, int val);
-
-/**
- * Set flag for IP fragment
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_ipfrag(odp_packet_t pkt, int val);
-
-/**
- * Set flag for IP options
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_ipopt(odp_packet_t pkt, int val);
-
-/**
- * Set flag for IPSec
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_ipsec(odp_packet_t pkt, int val);
-
-/**
- * Set flag for UDP
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_udp(odp_packet_t pkt, int val);
-
-/**
- * Set flag for TCP
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_tcp(odp_packet_t pkt, int val);
-
-/**
- * Set flag for SCTP
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_sctp(odp_packet_t pkt, int val);
-
-/**
- * Set flag for ICMP
- *
- * @param pkt Packet handle
- * @param val Value
- */
-void odp_packet_set_inflag_icmp(odp_packet_t pkt, int val);
-
-/**
- * @}
- */
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- platform/linux-generic/include/api/odp.h | 1 - platform/linux-generic/include/api/odp_buffer.h | 513 ++++- .../linux-generic/include/api/odp_buffer_pool.h | 355 ++- platform/linux-generic/include/api/odp_config.h | 6 + platform/linux-generic/include/api/odp_packet.h | 2304 ++++++++++++++++++-- .../linux-generic/include/api/odp_packet_flags.h | 334 --- 6 files changed, 2925 insertions(+), 588 deletions(-) delete mode 100644 platform/linux-generic/include/api/odp_packet_flags.h