| Message ID | 1418998565-5097-1-git-send-email-petri.savolainen@linaro.org |
|---|---|
| State | Accepted |
| Commit | e89d6e28c9af08ef49032a32478fa46ced86f8cb |
| Headers | show |
On Fri, Dec 19, 2014 at 8:16 AM, Petri Savolainen < petri.savolainen@linaro.org> wrote: > > 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> > --- > 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 > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
I don't agree in principle to having implementation specifics in the public API, why should other platforms have to remove all of that data to clean up the header files for their own use ? On 19 December 2014 at 09:16, Petri Savolainen <petri.savolainen@linaro.org> wrote: > 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> > --- > 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 > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
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)
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> --- platform/linux-generic/include/api/odp_config.h | 83 +++++++++++++------------ 1 file changed, 42 insertions(+), 41 deletions(-)