/** * Reset packet * * Resets all packet metadata to their default values. Packet length is used * to initialize pointers and lengths. It must be less than the total buffer * length of the packet minus the default headroom length. Packet is not * modified on failure. * * @param pkt Packet handle * @param len Packet data length * * @retval 0 on success * @retval <0 on failure * * @see odp_packet_buf_len() */ int odp_packet_reset(odp_packet_t pkt, uint32_t len);
/** * Total packet buffer length * * Returns sum of buffer lengths over all packet segments. * * @param pkt Packet handle * * @return Total packet buffer length in bytes * * @see odp_packet_reset() */ uint32_t odp_packet_buf_len(odp_packet_t pkt); pkt = odp_packet_alloc(pool, 0); … buf_len = odp_packet_buf_len(pkt); odp_packet_reset(pkt, buf_len - ODP_CONFIG_PACKET_HEADROOM - x); Reset does not refer to initial packet data length, but the current maximum data length (total buffer length). The idea is to reuse a packet, if current segmentation allows it. -Petri From: ext Bill Fischofer [mailto:bill.fischo...@linaro.org] Sent: Friday, May 29, 2015 3:32 PM To: Savolainen, Petri (Nokia - FI/Espoo) Cc: ext Zoltan Kiss; 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 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.savolai...@nokia.com<mailto:petri.savolai...@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.k...@linaro.org<mailto:zoltan.k...@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<mailto: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.k...@linaro.org<mailto:zoltan.k...@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<mailto: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.fischo...@linaro.org<mailto:bill.fischo...@linaro.org>] > >>> *Sent:* Thursday, May 28, 2015 2:48 PM > >>> *To:* Savolainen, Petri (Nokia - FI/Espoo) > >>> *Cc:* lng-odp@lists.linaro.org<mailto: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.savolai...@nokia.com<mailto:petri.savolai...@nokia.com> > >>> <mailto:petri.savolai...@nokia.com<mailto:petri.savolai...@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-boun...@lists.linaro.org<mailto:lng-odp-boun...@lists.linaro.org> > >>> <mailto:lng-odp-boun...@lists.linaro.org<mailto:lng-odp-boun...@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> > >>> <mailto: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.fischo...@linaro.org<mailto:bill.fischo...@linaro.org> > >>> <mailto:bill.fischo...@linaro.org<mailto:bill.fischo...@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> > >>> <mailto: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<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
