Balasubramanian Manoharan(bala-manoharan) replied on github web page:

include/odp/api/spec/packet.h
line 39
@@ -401,30 +401,39 @@ uint32_t odp_packet_buf_len(odp_packet_t pkt);
 /**
  * Packet data pointer
  *
- * Returns the current packet data pointer. When a packet is received
- * from packet input, this points to the first byte of the received
- * packet. Packet level offsets are calculated relative to this position.
+ * Returns pointer to the first byte of packet data. When packet is segmented,
+ * only a portion of packet data follows the pointer. When unsure, use e.g.
+ * odp_packet_seg_len() to check the data length following the pointer. Packet
+ * level offsets are calculated relative to this position.
  *
- * User can adjust the data pointer with head_push/head_pull (does not modify
- * segmentation) and add_data/rem_data calls (may modify segmentation).
+ * When a packet is received from packet input, this points to the first byte
+ * of the received packet. Pool configuration parameters may be used to ensure
+ * that the first packet segment contains all/most of the data relevant to the
+ * application.
+ *
+ * User can adjust the data pointer with e.g. push_head/pull_head (does not
+ * modify segmentation) and extend_head/trunc_head (may modify segmentation)
+ * calls.
  *
  * @param pkt  Packet handle
  *
  * @return  Pointer to the packet data
  *
- * @see odp_packet_l2_ptr(), odp_packet_seg_len()
+ * @see odp_packet_seg_len(), odp_packet_push_head(), odp_packet_extend_head()
  */
 void *odp_packet_data(odp_packet_t pkt);
 
 /**
- * Packet segment data length
+ * Packet data length following the data pointer
  *
- * Returns number of data bytes following the current data pointer
- * (odp_packet_data()) location in the segment.
+ * Returns number of data bytes (in the segment) following the current data
+ * pointer position. When unsure, use this function to check how many bytes


Comment:
In the entire documentation you have avoided the term "first segment" is it by 
choice?
IMO we could refer this as first segment valid data bytes

> Petri Savolainen(psavol) wrote:
> seg_len / push_head / extend_head are mentioned above. Packet_offset is not 
> specialized for handling first N bytes of packet, so it's not directly 
> related to these ones.


>> Petri Savolainen(psavol) wrote:
>> packet_offset is for different purpose (access data on arbitrary offset), 
>> these calls are optimized for the common case (offset zero). Also 
>> odp_packet_seg_data_len(), the new data_seg_len(),  odp_packet_l2_ptr(), 
>> odp_packet_l3_ptr()  and odp_packet_l4_ptr() output seg len, but we don't 
>> need to list all possible ways to get it. It's enough that the reader 
>> understands that a packet may have segments and segment length is different 
>> thing than total packet length


>>> Dmitry Eremin-Solenikov(lumag) wrote:
>>> And here too, please.


>>>> Dmitry Eremin-Solenikov(lumag) wrote:
>>>> odp_packet_seg_len() **or odp_packet_offset()**, if you don't mind.


https://github.com/Linaro/odp/pull/497#discussion_r170204670
updated_at 2018-02-23 09:36:37

Reply via email to