api: config: Separate api spec and linux-generic limits

Document purpose of configuration options in generic terms and
label linux-generic implementation limits with @internal doxygen
tag.

Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org>
Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

1 files changed, 42 insertions, 41 deletions

diff --git a/platform/linux-generic/include/api/odp_config.h b/platform/linux-generic/include/api/odp_config.h
index 2f839b391..542a719f8 100644
--- a/platform/linux-generic/include/api/odp_config.h
+++ b/platform/linux-generic/include/api/odp_config.h
@@ -49,72 +49,73 @@ extern "C" {
 #define ODP_CONFIG_PKTIO_ENTRIES 64
 
 /**
- * Minimum supported buffer alignment
- * This defines the minimum buffer alignment request. Requests for
- * values below this will be rounded up to this value.
+ * Minimum buffer alignment
+ *
+ * This defines the minimum supported buffer alignment. Requests for values
+ * below this will be rounded up to this value.
  */
 #define ODP_CONFIG_BUFFER_ALIGN_MIN 8
 
 /**
- * Maximum supported buffer alignment
- * This defines the maximum supported buffer alignment. Requests for
- * values above this will fail.
+ * Maximum buffer alignment
+ *
+ * This defines the maximum supported buffer alignment. Requests for values
+ * above this will fail.
  */
-
 #define ODP_CONFIG_BUFFER_ALIGN_MAX (4*1024)
 
 /**
  * Default packet headroom
- * This is default headroom that will be applied to any buffer pool created
- * for packets. Note that while headroom serves to reserve space for packet
- * header expansion via the odp_packet_push_head() routine, it also serves to
- * align packets within the buffer. ODP packet buffers always have a minimum
- * of 8 byte alignment, so the headroom can be used to offset packets so that,
- * for example, a 14 byte standard Ethernet header ends on a 4 byte boundary
- * so that the following IP header begins on a 4 byte alignment. Note also
- * that this is the minimum headroom value that the application
- * requires. Implementations are free to add to whatever value is specified
- * here in multiples of 8 bytes to preserve the implied alignment
- * specification. The specific default shown here allows a 1500-byte packet
- * to be received into a single segment with Ethernet offset alignment and
- * room for some header expansion.
+ *
+ * This defines the minimum number of headroom bytes that newly created packets
+ * have by default. The default apply to both ODP packet input and user
+ * allocated packets. Implementations may reserve a larger than minimum headroom
+ * size e.g. due to HW or a protocol specific alignment requirement.
+ *
+ * @internal In linux-generic implementation:
+ * The default value (66) allows a 1500-byte packet to be received into a single
+ * segment with Ethernet offset alignment and room for some header expansion.
  */
 #define ODP_CONFIG_PACKET_HEADROOM 66
 
 /**
  * Default packet tailroom
- * This is the default tailroom that will be applied to any buffer pool
- * created for packets. This specifies the minimum tailroom value that the
- * application requires. Implementations are free to add to this as desired
+ *
+ * This defines the minimum number of tailroom bytes that newly created packets
+ * have by default. The default apply to both ODP packet input and user
+ * allocated packets. Implementations are free to add to this as desired
  * without restriction. Note that most implementations will automatically
  * consider any unused portion of the last segment of a packet as tailroom
  */
 #define ODP_CONFIG_PACKET_TAILROOM 0
 
 /**
- * Minimum packet segment size
- * This defines the minimum allowable size for packet segments. It exists to
- * ensure that the application can have a reasonable expectation that all
- * packet headers will reside in the first packet segment. Note that this
- * value MUST be a multiple of 8.
+ * Minimum packet segment length
+ *
+ * This defines the minimum packet segment length in bytes. The user defined
+ * buffer size (in odp_buffer_pool_param_t) in buffer pool creation will be
+ * rounded up into this value.
  *
- * This is the granularity of segmented buffers/packets. Note that this is
- * currently only applicable to buffers of type ODP_BUFFER_TYPE_PACKET. It is
- * sized for now to be large enough to support 1536-byte packets with the
- * default headroom shown above, since the raw socket interface does not
- * at present support scatter/gather I/O. This is subject to the
- * ODP_CONFIG_PACKET_BUF_MIN_LEN configuration shown above and MUST be a
- * multiple of ODP_CACHE_LINE_SIZE. 1664 is used here as a default since it is
- * a multiple of both 64 and 128, which are the most common cache line sizes.
- * Adjust as needed for your platform.
+ * @internal In linux-generic implementation:
+ * - The value MUST be a multiple of 8.
+ * - The value MUST be a multiple of ODP_CACHE_LINE_SIZE
+ * - The default value (1664) is large enough to support 1536-byte packets
+ *   with the default headroom shown above and is a multiple of both 64 and 128,
+ *   which are the most common cache line sizes.
  */
 #define ODP_CONFIG_PACKET_BUF_LEN_MIN (1664)
 
 /**
- * Maximum packet length supported
- * MUST be an integral number of segments and SHOULD be large enough to
- * accommodate jumbo packets (9K). Attempts to allocate or extend packets to
- * sizes larger than this limit will fail.
+ * Maximum packet buffer length
+ *
+ * This defines the maximum number of bytes that can be stored into a packet
+ * (maximum return value of odp_packet_buf_len()). Attempts to allocate
+ * (including default head- and tailrooms) or extend packets to sizes larger
+ * than this limit will fail.
+ *
+ * @internal In linux-generic implementation:
+ * - The value MUST be an integral number of segments
+ * - The value SHOULD be large enough to accommodate jumbo packets (9K)
  */
 #define ODP_CONFIG_PACKET_BUF_LEN_MAX (ODP_CONFIG_PACKET_BUF_LEN_MIN*6)