| Message ID | 1432741856-17199-1-git-send-email-bill.fischofer@linaro.org |
|---|---|
| State | New |
| Headers | show |
Reviewed-by: Zoltan Kiss <zoltan.kiss@linaro.org> Please don't forget a note for odp_buffer_alloc() as well, to state that it doesn't work with packet pools. On 27/05/15 16:50, Bill Fischofer wrote: > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > include/odp/api/packet.h | 10 ++++++++++ > 1 file changed, 10 insertions(+) > > diff --git a/include/odp/api/packet.h b/include/odp/api/packet.h > index 3a454b5..ea124df 100644 > --- a/include/odp/api/packet.h > +++ b/include/odp/api/packet.h > @@ -73,6 +73,16 @@ extern "C" { > * @note The default headroom and tailroom used for packets is specified by > * the ODP_CONFIG_PACKET_HEADROOM and ODP_CONFIG_PACKET_TAILROOM defines in > * odp_config.h. > + * > + * @note The len parameter sets the initial length of the allocated packet. > + * If specified as 0, the implementation will allocate a packet of a default > + * length chosen by the implementation based on the pool create parameters > + * and will then set the actual length of the packet to 0. The result is > + * the same as if the following sequence had been called by the application: > + * @code > + * pkt = odp_packet_alloc(pool, default_len); > + * odp_packet_reset(pkt, 0); > + * @endcode > */ > odp_packet_t odp_packet_alloc(odp_pool_t pool, uint32_t len); > >
The purpose of the note was to expand on the case of len = 0. Are you saying this is not needed? The consensus on the Wednesday arch call was that it was, hence this patch. On Thu, May 28, 2015 at 5:40 AM, Savolainen, Petri (Nokia - FI/Espoo) < petri.savolainen@nokia.com> wrote: > > * ... The > * packet is initialized with data pointers and lengths set according to > the > * specified len, ... > > The current documentation covers functionality also when len is 0. We > should minimize @note content over all the APIs, otherwise the actual API > spec gets fragmented. API documentation and functionality is the same for > len == 0, len == 1, ... In all the cases, implementation decides on packet > segmentation in limits of pool parameters. > > If needed, we could add: > > @note Zero is a valid 'len' value > > > -Petri > > > > -----Original Message----- > > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of ext > > Bill Fischofer > > Sent: Wednesday, May 27, 2015 6:51 PM > > To: lng-odp@lists.linaro.org > > Subject: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify use of > 0 > > len on odp_packet_alloc() > > > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > > --- > > include/odp/api/packet.h | 10 ++++++++++ > > 1 file changed, 10 insertions(+) > > > > diff --git a/include/odp/api/packet.h b/include/odp/api/packet.h > > index 3a454b5..ea124df 100644 > > --- a/include/odp/api/packet.h > > +++ b/include/odp/api/packet.h > > @@ -73,6 +73,16 @@ extern "C" { > > * @note The default headroom and tailroom used for packets is specified > > by > > * the ODP_CONFIG_PACKET_HEADROOM and ODP_CONFIG_PACKET_TAILROOM defines > > in > > * odp_config.h. > > + * > > + * @note The len parameter sets the initial length of the allocated > > packet. > > + * If specified as 0, the implementation will allocate a packet of a > > default > > + * length chosen by the implementation based on the pool create > > parameters > > + * and will then set the actual length of the packet to 0. The result is > > + * the same as if the following sequence had been called by the > > application: > > + * @code > > + * pkt = odp_packet_alloc(pool, default_len); > > + * odp_packet_reset(pkt, 0); > > + * @endcode > > */ > > odp_packet_t odp_packet_alloc(odp_pool_t pool, uint32_t len); > > > > -- > > 2.1.0 > > > > _______________________________________________ > > lng-odp mailing list > > lng-odp@lists.linaro.org > > https://lists.linaro.org/mailman/listinfo/lng-odp >
I don't think so. There was a lengthy discussion on the arch meeting how should you interpret that, I think that proves it's worth to clarify what's the expected behaviour. On 28/05/15 13:45, Savolainen, Petri (Nokia - FI/Espoo) wrote: > I think it should be enough to note that len can be 0. There’s no > special handling for value zero. > > -Petri > > *From:*ext Bill Fischofer [mailto:bill.fischofer@linaro.org] > *Sent:* Thursday, May 28, 2015 2:48 PM > *To:* Savolainen, Petri (Nokia - FI/Espoo) > *Cc:* lng-odp@lists.linaro.org > *Subject:* Re: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify > use of 0 len on odp_packet_alloc() > > The purpose of the note was to expand on the case of len = 0. Are you > saying this is not needed? The consensus on the Wednesday arch call was > that it was, hence this patch. > > On Thu, May 28, 2015 at 5:40 AM, Savolainen, Petri (Nokia - FI/Espoo) > <petri.savolainen@nokia.com <mailto:petri.savolainen@nokia.com>> wrote: > > > * ... The > * packet is initialized with data pointers and lengths set according > to the > * specified len, ... > > The current documentation covers functionality also when len is 0. We > should minimize @note content over all the APIs, otherwise the actual > API spec gets fragmented. API documentation and functionality is the > same for len == 0, len == 1, ... In all the cases, implementation > decides on packet segmentation in limits of pool parameters. > > If needed, we could add: > > @note Zero is a valid 'len' value > > > -Petri > > > > > -----Original Message----- > > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org > <mailto:lng-odp-bounces@lists.linaro.org>] On Behalf Of ext > > Bill Fischofer > > Sent: Wednesday, May 27, 2015 6:51 PM > > To: lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > > Subject: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify use > of 0 > > len on odp_packet_alloc() > > > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org > <mailto:bill.fischofer@linaro.org>> > > --- > > include/odp/api/packet.h | 10 ++++++++++ > > 1 file changed, 10 insertions(+) > > > > diff --git a/include/odp/api/packet.h b/include/odp/api/packet.h > > index 3a454b5..ea124df 100644 > > --- a/include/odp/api/packet.h > > +++ b/include/odp/api/packet.h > > @@ -73,6 +73,16 @@ extern "C" { > > * @note The default headroom and tailroom used for packets is specified > > by > > * the ODP_CONFIG_PACKET_HEADROOM and ODP_CONFIG_PACKET_TAILROOM defines > > in > > * odp_config.h. > > + * > > + * @note The len parameter sets the initial length of the allocated > > packet. > > + * If specified as 0, the implementation will allocate a packet of a > > default > > + * length chosen by the implementation based on the pool create > > parameters > > + * and will then set the actual length of the packet to 0. The result is > > + * the same as if the following sequence had been called by the > > application: > > + * @code > > + * pkt = odp_packet_alloc(pool, default_len); > > + * odp_packet_reset(pkt, 0); > > + * @endcode > > */ > > odp_packet_t odp_packet_alloc(odp_pool_t pool, uint32_t len); > > > > -- > > 2.1.0 > > > > > _______________________________________________ > > lng-odp mailing list > > lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > > https://lists.linaro.org/mailman/listinfo/lng-odp > > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
On 28/05/15 13:58, Savolainen, Petri (Nokia - FI/Espoo) wrote: > How people think 0 is special or different from e.g. value 1? Well, 0 is a special number in many ways, not just in mathematics and computer science: http://en.wikipedia.org/wiki/0_%28number%29 It is special in this case as well, because it's defined to be equal to: pkt = odp_packet_alloc(pool, default_len); odp_packet_reset(pkt, 0); Which is not necessarily what you would expect. Most people had different ideas what 0 should mean. > > We can change documentation wording, but not add lengthy documentation for value 0 as a special case (which is not). > > -Petri > > >> -----Original Message----- >> From: ext Zoltan Kiss [mailto:zoltan.kiss@linaro.org] >> Sent: Thursday, May 28, 2015 3:51 PM >> To: Savolainen, Petri (Nokia - FI/Espoo); ext Bill Fischofer >> Cc: lng-odp@lists.linaro.org >> Subject: Re: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify use >> of 0 len on odp_packet_alloc() >> >> I don't think so. There was a lengthy discussion on the arch meeting how >> should you interpret that, I think that proves it's worth to clarify >> what's the expected behaviour. >> >> On 28/05/15 13:45, Savolainen, Petri (Nokia - FI/Espoo) wrote: >>> I think it should be enough to note that len can be 0. There’s no >>> special handling for value zero. >>> >>> -Petri >>> >>> *From:*ext Bill Fischofer [mailto:bill.fischofer@linaro.org] >>> *Sent:* Thursday, May 28, 2015 2:48 PM >>> *To:* Savolainen, Petri (Nokia - FI/Espoo) >>> *Cc:* lng-odp@lists.linaro.org >>> *Subject:* Re: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify >>> use of 0 len on odp_packet_alloc() >>> >>> The purpose of the note was to expand on the case of len = 0. Are you >>> saying this is not needed? The consensus on the Wednesday arch call was >>> that it was, hence this patch. >>> >>> On Thu, May 28, 2015 at 5:40 AM, Savolainen, Petri (Nokia - FI/Espoo) >>> <petri.savolainen@nokia.com <mailto:petri.savolainen@nokia.com>> wrote: >>> >>> >>> * ... The >>> * packet is initialized with data pointers and lengths set according >>> to the >>> * specified len, ... >>> >>> The current documentation covers functionality also when len is 0. We >>> should minimize @note content over all the APIs, otherwise the actual >>> API spec gets fragmented. API documentation and functionality is the >>> same for len == 0, len == 1, ... In all the cases, implementation >>> decides on packet segmentation in limits of pool parameters. >>> >>> If needed, we could add: >>> >>> @note Zero is a valid 'len' value >>> >>> >>> -Petri >>> >>> >>> >>> > -----Original Message----- >>> > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org >>> <mailto:lng-odp-bounces@lists.linaro.org>] On Behalf Of ext >>> > Bill Fischofer >>> > Sent: Wednesday, May 27, 2015 6:51 PM >>> > To: lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> >>> > Subject: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify use >>> of 0 >>> > len on odp_packet_alloc() >>> > >>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org >>> <mailto:bill.fischofer@linaro.org>> >>> > --- >>> > include/odp/api/packet.h | 10 ++++++++++ >>> > 1 file changed, 10 insertions(+) >>> > >>> > diff --git a/include/odp/api/packet.h b/include/odp/api/packet.h >>> > index 3a454b5..ea124df 100644 >>> > --- a/include/odp/api/packet.h >>> > +++ b/include/odp/api/packet.h >>> > @@ -73,6 +73,16 @@ extern "C" { >>> > * @note The default headroom and tailroom used for packets is >> specified >>> > by >>> > * the ODP_CONFIG_PACKET_HEADROOM and ODP_CONFIG_PACKET_TAILROOM >> defines >>> > in >>> > * odp_config.h. >>> > + * >>> > + * @note The len parameter sets the initial length of the allocated >>> > packet. >>> > + * If specified as 0, the implementation will allocate a packet of a >>> > default >>> > + * length chosen by the implementation based on the pool create >>> > parameters >>> > + * and will then set the actual length of the packet to 0. The >> result is >>> > + * the same as if the following sequence had been called by the >>> > application: >>> > + * @code >>> > + * pkt = odp_packet_alloc(pool, default_len); >>> > + * odp_packet_reset(pkt, 0); >>> > + * @endcode >>> > */ >>> > odp_packet_t odp_packet_alloc(odp_pool_t pool, uint32_t len); >>> > >>> > -- >>> > 2.1.0 >>> > >>> >>> > _______________________________________________ >>> > lng-odp mailing list >>> > lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> >>> > https://lists.linaro.org/mailman/listinfo/lng-odp >>> >>> >>> >>> _______________________________________________ >>> lng-odp mailing list >>> lng-odp@lists.linaro.org >>> https://lists.linaro.org/mailman/listinfo/lng-odp >>>
On 28 May 2015 at 14:58, Savolainen, Petri (Nokia - FI/Espoo) < petri.savolainen@nokia.com> wrote: > How people think 0 is special or different from e.g. value 1? > A packet of length 1 will require at least one segment. A packet of length 0 does not require any segment from a formal point of view (but an implementation will probably allocate a segment anyway). So implementations might implement zer0 length packets differently. The question is how this can be observed by applications. Preferably not at all. But it seems like implementation specifics are leaking out and some code might expect a certain behavior which is not mandated by the API. We want to avoid this and think we can achieve it by amending the API documentation. I also think the validation suite might need some specific test cases here. > We can change documentation wording, but not add lengthy documentation for > value 0 as a special case (which is not). > > -Petri > > > > -----Original Message----- > > From: ext Zoltan Kiss [mailto:zoltan.kiss@linaro.org] > > Sent: Thursday, May 28, 2015 3:51 PM > > To: Savolainen, Petri (Nokia - FI/Espoo); ext Bill Fischofer > > Cc: lng-odp@lists.linaro.org > > Subject: Re: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify use > > of 0 len on odp_packet_alloc() > > > > I don't think so. There was a lengthy discussion on the arch meeting how > > should you interpret that, I think that proves it's worth to clarify > > what's the expected behaviour. > > > > On 28/05/15 13:45, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > > I think it should be enough to note that len can be 0. There’s no > > > special handling for value zero. > > > > > > -Petri > > > > > > *From:*ext Bill Fischofer [mailto:bill.fischofer@linaro.org] > > > *Sent:* Thursday, May 28, 2015 2:48 PM > > > *To:* Savolainen, Petri (Nokia - FI/Espoo) > > > *Cc:* lng-odp@lists.linaro.org > > > *Subject:* Re: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify > > > use of 0 len on odp_packet_alloc() > > > > > > The purpose of the note was to expand on the case of len = 0. Are you > > > saying this is not needed? The consensus on the Wednesday arch call > was > > > that it was, hence this patch. > > > > > > On Thu, May 28, 2015 at 5:40 AM, Savolainen, Petri (Nokia - FI/Espoo) > > > <petri.savolainen@nokia.com <mailto:petri.savolainen@nokia.com>> > wrote: > > > > > > > > > * ... The > > > * packet is initialized with data pointers and lengths set according > > > to the > > > * specified len, ... > > > > > > The current documentation covers functionality also when len is 0. We > > > should minimize @note content over all the APIs, otherwise the actual > > > API spec gets fragmented. API documentation and functionality is the > > > same for len == 0, len == 1, ... In all the cases, implementation > > > decides on packet segmentation in limits of pool parameters. > > > > > > If needed, we could add: > > > > > > @note Zero is a valid 'len' value > > > > > > > > > -Petri > > > > > > > > > > > > > -----Original Message----- > > > > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org > > > <mailto:lng-odp-bounces@lists.linaro.org>] On Behalf Of ext > > > > Bill Fischofer > > > > Sent: Wednesday, May 27, 2015 6:51 PM > > > > To: lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > > > > Subject: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify > use > > > of 0 > > > > len on odp_packet_alloc() > > > > > > > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org > > > <mailto:bill.fischofer@linaro.org>> > > > > --- > > > > include/odp/api/packet.h | 10 ++++++++++ > > > > 1 file changed, 10 insertions(+) > > > > > > > > diff --git a/include/odp/api/packet.h b/include/odp/api/packet.h > > > > index 3a454b5..ea124df 100644 > > > > --- a/include/odp/api/packet.h > > > > +++ b/include/odp/api/packet.h > > > > @@ -73,6 +73,16 @@ extern "C" { > > > > * @note The default headroom and tailroom used for packets is > > specified > > > > by > > > > * the ODP_CONFIG_PACKET_HEADROOM and ODP_CONFIG_PACKET_TAILROOM > > defines > > > > in > > > > * odp_config.h. > > > > + * > > > > + * @note The len parameter sets the initial length of the allocated > > > > packet. > > > > + * If specified as 0, the implementation will allocate a packet of > a > > > > default > > > > + * length chosen by the implementation based on the pool create > > > > parameters > > > > + * and will then set the actual length of the packet to 0. The > > result is > > > > + * the same as if the following sequence had been called by the > > > > application: > > > > + * @code > > > > + * pkt = odp_packet_alloc(pool, default_len); > > > > + * odp_packet_reset(pkt, 0); > > > > + * @endcode > > > > */ > > > > odp_packet_t odp_packet_alloc(odp_pool_t pool, uint32_t len); > > > > > > > > -- > > > > 2.1.0 > > > > > > > > > > > _______________________________________________ > > > > lng-odp mailing list > > > > lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > > > > https://lists.linaro.org/mailman/listinfo/lng-odp > > > > > > > > > > > > _______________________________________________ > > > lng-odp mailing list > > > lng-odp@lists.linaro.org > > > https://lists.linaro.org/mailman/listinfo/lng-odp > > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
The issue has to do with odp_packet_reset(). If I say: pkt = odp_packet_alloc(pool, 1500); I can then subsequently call: odp_packet_reset(pkt, n); for any value of N <= 1500. If I try to reset a packet to a length greater than was initially allocated for it, that is an error. If we followed that definition then allocating a packet of length 0 would be pointless since it could never be grown to anything useful. The purpose of the note regarding the use of 0 is to have a convenient means of allocating a packet of implementation-default useful but unknown length and then be able to build packets from there via odp_packet_push_tail() calls. On Fri, May 29, 2015 at 5:06 AM, Savolainen, Petri (Nokia - FI/Espoo) < petri.savolainen@nokia.com> wrote: > The API does not specify "default length". Pool pkt parameters guide pool > size (number of packet with min len) and segmentation (min bytes in the > first segment). Implementation decides on segmentation and actual segment > sizes. > > pkt = odp_packet_alloc(pool, default_len); > odp_packet_reset(pkt, 0); > > So, the example above does not actually specify anything. Any value of > "default_len" is handled the same way. Implementation uses 'len' to > allocate enough segments and initialize data pointers/lengths accordingly. > > // Allocated packet can hold at least 0 data bytes > // odp_packet_data() points to the first byte of data. Valid start > pointer, although no data follows. > // odp_packet_len() returns 0 > pkt1 = odp_packet_alloc(pool, 0); > > > // Allocated packet can hold at least 1 data bytes > // odp_packet_data() points to the first byte of data > // odp_packet_len() returns 1 > pkt2 = odp_packet_alloc(pool, 1); > > ... > > > Which API definition was source of the confusion? It should be enough to > highlight that either zero is legal or illegal value of 'len'. > > > -Petri > > > > -----Original Message----- > > From: ext Zoltan Kiss [mailto:zoltan.kiss@linaro.org] > > Sent: Thursday, May 28, 2015 4:59 PM > > To: Savolainen, Petri (Nokia - FI/Espoo); ext Bill Fischofer > > Cc: lng-odp@lists.linaro.org > > Subject: Re: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify use > > of 0 len on odp_packet_alloc() > > > > > > > > On 28/05/15 13:58, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > > How people think 0 is special or different from e.g. value 1? > > > > Well, 0 is a special number in many ways, not just in mathematics and > > computer science: > > > > http://en.wikipedia.org/wiki/0_%28number%29 > > > > It is special in this case as well, because it's defined to be equal to: > > > > pkt = odp_packet_alloc(pool, default_len); > > odp_packet_reset(pkt, 0); > > > > Which is not necessarily what you would expect. Most people had > > different ideas what 0 should mean. > > > > > > > > We can change documentation wording, but not add lengthy documentation > > for value 0 as a special case (which is not). > > > > > > -Petri > > > > > > > > >> -----Original Message----- > > >> From: ext Zoltan Kiss [mailto:zoltan.kiss@linaro.org] > > >> Sent: Thursday, May 28, 2015 3:51 PM > > >> To: Savolainen, Petri (Nokia - FI/Espoo); ext Bill Fischofer > > >> Cc: lng-odp@lists.linaro.org > > >> Subject: Re: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify > > use > > >> of 0 len on odp_packet_alloc() > > >> > > >> I don't think so. There was a lengthy discussion on the arch meeting > > how > > >> should you interpret that, I think that proves it's worth to clarify > > >> what's the expected behaviour. > > >> > > >> On 28/05/15 13:45, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > >>> I think it should be enough to note that len can be 0. There’s no > > >>> special handling for value zero. > > >>> > > >>> -Petri > > >>> > > >>> *From:*ext Bill Fischofer [mailto:bill.fischofer@linaro.org] > > >>> *Sent:* Thursday, May 28, 2015 2:48 PM > > >>> *To:* Savolainen, Petri (Nokia - FI/Espoo) > > >>> *Cc:* lng-odp@lists.linaro.org > > >>> *Subject:* Re: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: > > clarify > > >>> use of 0 len on odp_packet_alloc() > > >>> > > >>> The purpose of the note was to expand on the case of len = 0. Are > you > > >>> saying this is not needed? The consensus on the Wednesday arch call > > was > > >>> that it was, hence this patch. > > >>> > > >>> On Thu, May 28, 2015 at 5:40 AM, Savolainen, Petri (Nokia - FI/Espoo) > > >>> <petri.savolainen@nokia.com <mailto:petri.savolainen@nokia.com>> > > wrote: > > >>> > > >>> > > >>> * ... The > > >>> * packet is initialized with data pointers and lengths set > > according > > >>> to the > > >>> * specified len, ... > > >>> > > >>> The current documentation covers functionality also when len is 0. We > > >>> should minimize @note content over all the APIs, otherwise the actual > > >>> API spec gets fragmented. API documentation and functionality is the > > >>> same for len == 0, len == 1, ... In all the cases, implementation > > >>> decides on packet segmentation in limits of pool parameters. > > >>> > > >>> If needed, we could add: > > >>> > > >>> @note Zero is a valid 'len' value > > >>> > > >>> > > >>> -Petri > > >>> > > >>> > > >>> > > >>> > -----Original Message----- > > >>> > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org > > >>> <mailto:lng-odp-bounces@lists.linaro.org>] On Behalf Of ext > > >>> > Bill Fischofer > > >>> > Sent: Wednesday, May 27, 2015 6:51 PM > > >>> > To: lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > > >>> > Subject: [lng-odp] [API-NEXT PATCH 2/2] api-next: packet: clarify > > use > > >>> of 0 > > >>> > len on odp_packet_alloc() > > >>> > > > >>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org > > >>> <mailto:bill.fischofer@linaro.org>> > > >>> > --- > > >>> > include/odp/api/packet.h | 10 ++++++++++ > > >>> > 1 file changed, 10 insertions(+) > > >>> > > > >>> > diff --git a/include/odp/api/packet.h b/include/odp/api/packet.h > > >>> > index 3a454b5..ea124df 100644 > > >>> > --- a/include/odp/api/packet.h > > >>> > +++ b/include/odp/api/packet.h > > >>> > @@ -73,6 +73,16 @@ extern "C" { > > >>> > * @note The default headroom and tailroom used for packets is > > >> specified > > >>> > by > > >>> > * the ODP_CONFIG_PACKET_HEADROOM and ODP_CONFIG_PACKET_TAILROOM > > >> defines > > >>> > in > > >>> > * odp_config.h. > > >>> > + * > > >>> > + * @note The len parameter sets the initial length of the > > allocated > > >>> > packet. > > >>> > + * If specified as 0, the implementation will allocate a packet > > of a > > >>> > default > > >>> > + * length chosen by the implementation based on the pool create > > >>> > parameters > > >>> > + * and will then set the actual length of the packet to 0. The > > >> result is > > >>> > + * the same as if the following sequence had been called by the > > >>> > application: > > >>> > + * @code > > >>> > + * pkt = odp_packet_alloc(pool, default_len); > > >>> > + * odp_packet_reset(pkt, 0); > > >>> > + * @endcode > > >>> > */ > > >>> > odp_packet_t odp_packet_alloc(odp_pool_t pool, uint32_t len); > > >>> > > > >>> > -- > > >>> > 2.1.0 > > >>> > > > >>> > > >>> > _______________________________________________ > > >>> > lng-odp mailing list > > >>> > lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > > >>> > https://lists.linaro.org/mailman/listinfo/lng-odp > > >>> > > >>> > > >>> > > >>> _______________________________________________ > > >>> lng-odp mailing list > > >>> lng-odp@lists.linaro.org > > >>> https://lists.linaro.org/mailman/listinfo/lng-odp > > >>> >
diff --git a/include/odp/api/packet.h b/include/odp/api/packet.h index 3a454b5..ea124df 100644 --- a/include/odp/api/packet.h +++ b/include/odp/api/packet.h @@ -73,6 +73,16 @@ extern "C" { * @note The default headroom and tailroom used for packets is specified by * the ODP_CONFIG_PACKET_HEADROOM and ODP_CONFIG_PACKET_TAILROOM defines in * odp_config.h. + * + * @note The len parameter sets the initial length of the allocated packet. + * If specified as 0, the implementation will allocate a packet of a default + * length chosen by the implementation based on the pool create parameters + * and will then set the actual length of the packet to 0. The result is + * the same as if the following sequence had been called by the application: + * @code + * pkt = odp_packet_alloc(pool, default_len); + * odp_packet_reset(pkt, 0); + * @endcode */ odp_packet_t odp_packet_alloc(odp_pool_t pool, uint32_t len);
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- include/odp/api/packet.h | 10 ++++++++++ 1 file changed, 10 insertions(+)