@@ -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);
@@ -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);
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.kiss@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.