Clarify when exactly the function should be called by a platform, and what is
promised about the data modified by it.
Signed-off-by: Zoltan Kiss <zoltan.k...@linaro.org>
---
Petri, please review this before 1.5. It contains the code I quoted in my answer
to the original thread. This lingers around for 3 months now, it would be good
to put an end to it.
The lines were left intentionally unwrapped to ease review. I'll send an
wrapped version once it gets reviewed.
diff --git a/include/odp/api/packet.h b/include/odp/api/packet.h
index 8651a47..45ff1cb 100644
--- a/include/odp/api/packet.h
+++ b/include/odp/api/packet.h
@@ -94,8 +94,9 @@ extern "C" {
* the ODP_CONFIG_PACKET_HEADROOM and ODP_CONFIG_PACKET_TAILROOM defines in
* odp_config.h.
* @note Data changed in user area might be preserved by the platform from
- * previous usage of the buffer, so values preset in uarea_init() are not
- * guaranteed.
+ * previous usage of the packet (if the underlying memory were allocated at
pool
+ * creation time), so values preset by packet pool parameter *uarea_init() are
+ * only guaranteed to be known if the application never changes them.
*/
odp_packet_t odp_packet_alloc(odp_pool_t pool, uint32_t len);
diff --git a/include/odp/api/pool.h b/include/odp/api/pool.h
index 01f770f..a7bce82 100644
--- a/include/odp/api/pool.h
+++ b/include/odp/api/pool.h
@@ -47,14 +47,19 @@ extern "C" {
* @param pkt Handle of the packet
* @param uarea_init_arg Opaque pointer defined in odp_pool_param_t
*
- * @note If the application specifies this pointer, it expects that every
buffer
- * is initialized exactly once with it when the underlying memory is allocated.
+ * @note If the application specifies this pointer, it expects that every
packet handle's user area
+ * is initialised exactly once with it after the underlying memory is
allocated and initialized.
* It is not called from odp_packet_alloc(), unless the platform chooses to
- * allocate the memory at that point. Applications can only assume that this
+ * allocate (or initialize) the memory at that point. Applications can only
assume that this
* callback is called once before the packet is first used. Any subsequent
* change to the user area might be preserved after odp_packet_free() is
called,
- * so applications should take care of (re)initialization if they change data
+ * so applications should not change data
* preset by this function.
+ * @note The packet is not in use when this function is called, so only the
+ * following functions could be called by the init function with this handle:
+ * odp_packet_pool()
+ * odp_packet_user_area()
+ * odp_packet_user_area_size()
*/
typedef void (odp_packet_uarea_init_t)(odp_packet_t pkt, void *uarea_init_arg);
_______________________________________________
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp
