On Fri, Dec 19, 2014 at 8:16 AM, Petri Savolainen < [email protected]> wrote: > > Document purpose of configuration options in generic terms and > label linux-generic implementation limits with @internal doxygen > tag. > > Signed-off-by: Petri Savolainen <[email protected]> >
Reviewed-by: Bill Fischofer <[email protected]> > --- > platform/linux-generic/include/api/odp_config.h | 83 > +++++++++++++------------ > 1 file 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 2f839b3..542a719 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) > > -- > 2.2.1 > > > _______________________________________________ > lng-odp mailing list > [email protected] > http://lists.linaro.org/mailman/listinfo/lng-odp >
_______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
