@@ -336,9 +336,9 @@ The key characteristic of a static reference is that because there are
multiple independent handles that refer to the same packet, the caller should
treat the packet as read only following the creation of a static reference
until all other references to it are freed. This is because all static
-references are simply aliases of the same packet, so if multiple threads were
-independently manipulating the packet this would lead to unpredictable race
-conditions.
+references are simply aliases of the same packet and associated metadata, so
+if multiple threads were independently manipulating the packet this would lead
+to unpredictable race conditions.
To assist in determining whether there are other references to a packet, ODP
provides the API:
@@ -513,7 +513,10 @@ packets as part of any reference creation call. The
`odp_packet_unshared_len()` API will always provide an authoritative answer to
the question of how many bytes of a packet may safely be modified in any
context, so whether or not copies have been performed applications can be
-assured of portability across all conforming ODP implementations.
+assured of portability across all conforming ODP implementations. In addition,
+if a reference call returns a copy of a packet for whatever reason, the
+`odp_packet_has_ref()` API will return 0 to confirm that this is an
+independent packet.
Note also that a packet may not reference itself, nor may circular reference
relationships be formed, _e.g.,_ packet A is used as a header for a reference
Clarify usage information around packet references in cases where implementations simulate references by returning copies of packets. Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- doc/users-guide/users-guide-packet.adoc | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) -- 2.12.0.rc1