diff mbox series

[API-NEXT,v2,1/1] api: packet: add cautionary note regarding odp_packet_data()

Message ID 1518724808-28103-2-git-send-email-odpbot@yandex.ru
State New
Headers show
Series [API-NEXT,v2,1/1] api: packet: add cautionary note regarding odp_packet_data() | expand

Commit Message

Github ODP bot Feb. 15, 2018, 8 p.m. UTC 
From: Bill Fischofer <bill.fischofer@linaro.org>


Add additional documentation to note that odp_packet_data() only
returns the starting address of the first packet segment, not the
entire packet.

Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>

---
/** Email created from pull request 486 (Bill-Fischofer-Linaro:pktdatadoc)
 ** https://github.com/Linaro/odp/pull/486
 ** Patch: https://github.com/Linaro/odp/pull/486.patch
 ** Base sha: 4b1101adedf0941f6db34047cc06fde11fb06a34
 ** Merge commit sha: 05ee3cc1ec0ef8a1e125aea0d19497c2a3a632e3
 **/
 include/odp/api/spec/packet.h | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)
diff mbox series

Patch

diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h
index 4be515c7b..1a3c5c8c3 100644
--- a/include/odp/api/spec/packet.h
+++ b/include/odp/api/spec/packet.h
@@ -395,11 +395,22 @@  uint32_t odp_packet_buf_len(odp_packet_t pkt);
  * User can adjust the data pointer with head_push/head_pull (does not modify
  * segmentation) and add_data/rem_data calls (may modify segmentation).
  *
+ * Note that the address returned by this routine is the starting address of
+ * the current first segment of the packet. For newly allocated packets the
+ * caller can be assured that this segment is at least the min_seg_len
+ * specified for the pool it was allocated from. For all other cases, the
+ * caller must take care that it does not attempt to address bytes that extend
+ * beyond the current segment length. Use the odp_packet_offset() or similar
+ * routines for addressing safety in the general case as these return the
+ * number of bytes that are valid along with the returned address. The
+ * odp_packet_seg_len() API can also be used to return the number of bytes
+ * valid from the current odp_packet_data() pointer.
+ *
  * @param pkt  Packet handle
  *
  * @return  Pointer to the packet data
  *
- * @see odp_packet_l2_ptr(), odp_packet_seg_len()
+ * @see odp_packet_l2_ptr(), odp_packet_seg_len(), odp_packet_offset()
  */
 void *odp_packet_data(odp_packet_t pkt);