| Message ID | 1486990410-14928-2-git-send-email-petri.savolainen@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Packet references as copy | expand |
On Mon, Feb 13, 2017 at 6:53 AM, Petri Savolainen <petri.savolainen@linaro.org> wrote: > Some implementations may implement new references as packet copy. > odp_packet_has_ref() will return 0 for copies, since those are > unique packets. > > Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org> > --- > include/odp/api/spec/packet.h | 20 +++++++++++++------- > 1 file changed, 13 insertions(+), 7 deletions(-) > > diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h > index b6450c1..05ffd68 100644 > --- a/include/odp/api/spec/packet.h > +++ b/include/odp/api/spec/packet.h > @@ -892,9 +892,6 @@ odp_packet_t odp_packet_ref_static(odp_packet_t pkt); > * dynamic references must not be mixed. Results are undefined if these > * restrictions are not observed. > * > - * odp_packet_unshared_len() may be used to determine the number of bytes > - * starting at offset zero that are unique to a packet handle. > - * Why do you want to delete this here? It's useful info and still valid whether or not copying is done. > * The packet handle 'pkt' may itself by a (dynamic) reference to a packet. > * > * If the caller does not intend to modify either the packet or the new > @@ -952,8 +949,9 @@ odp_packet_t odp_packet_ref_pkt(odp_packet_t pkt, uint32_t offset, > * When a packet has multiple references, packet data is divided into two > * parts: unshared and shared. The unshared part always precedes the shared > * part. This call returns number of bytes in the unshared part. When a > - * packet has only a single reference, all packet data is unshared and > - * unshared length equals the packet length (odp_packet_len()). > + * packet has only a single reference (see odp_packet_has_ref()), all packet > + * data is unshared and unshared length equals the packet length > + * (odp_packet_len()). > * > * Application may modify only the unshared part, the rest of the packet data > * must be treated as read only. > @@ -967,8 +965,16 @@ uint32_t odp_packet_unshared_len(odp_packet_t pkt); > /** > * Test if packet has multiple references > * > - * A packet that has multiple references shares data and possibly metadata > - * with other packets. Shared part must be treated as read only. > + * A packet that has multiple references share data with other packets. In case > + * of a static reference it also shares metadata. Shared parts must be treated > + * as read only. > + * > + * New references are created with odp_packet_ref_static(), odp_packet_ref() and > + * odp_packet_ref_pkt() calls. However, some of those calls may implement the > + * new reference as a packet copy. If a copy is done, the new reference is > + * actually a new, unique packet and this function returns '0' for it. > + * When a real reference is created (instead of a copy), this function > + * returns '1' for both packets (the original packet and the new reference). This is good but perhaps needs a bit of clarification as this gives the impression that packet copying is more likely than it might be, given that the intent of these APIs is that they be implemented in a zero-copy manner. Perhaps: "New references are created with odp_packet_ref(static), odp_packet_ref(), and odp_packet_ref_pkt(). Note that some implementations may simulate packet references by returning a packet copy instead of a shared reference. If a copy is done... " > * > * @param pkt Packet handle > * > -- > 2.8.1 >
diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h index b6450c1..05ffd68 100644 --- a/include/odp/api/spec/packet.h +++ b/include/odp/api/spec/packet.h @@ -892,9 +892,6 @@ odp_packet_t odp_packet_ref_static(odp_packet_t pkt); * dynamic references must not be mixed. Results are undefined if these * restrictions are not observed. * - * odp_packet_unshared_len() may be used to determine the number of bytes - * starting at offset zero that are unique to a packet handle. - * * The packet handle 'pkt' may itself by a (dynamic) reference to a packet. * * If the caller does not intend to modify either the packet or the new @@ -952,8 +949,9 @@ odp_packet_t odp_packet_ref_pkt(odp_packet_t pkt, uint32_t offset, * When a packet has multiple references, packet data is divided into two * parts: unshared and shared. The unshared part always precedes the shared * part. This call returns number of bytes in the unshared part. When a - * packet has only a single reference, all packet data is unshared and - * unshared length equals the packet length (odp_packet_len()). + * packet has only a single reference (see odp_packet_has_ref()), all packet + * data is unshared and unshared length equals the packet length + * (odp_packet_len()). * * Application may modify only the unshared part, the rest of the packet data * must be treated as read only. @@ -967,8 +965,16 @@ uint32_t odp_packet_unshared_len(odp_packet_t pkt); /** * Test if packet has multiple references * - * A packet that has multiple references shares data and possibly metadata - * with other packets. Shared part must be treated as read only. + * A packet that has multiple references share data with other packets. In case + * of a static reference it also shares metadata. Shared parts must be treated + * as read only. + * + * New references are created with odp_packet_ref_static(), odp_packet_ref() and + * odp_packet_ref_pkt() calls. However, some of those calls may implement the + * new reference as a packet copy. If a copy is done, the new reference is + * actually a new, unique packet and this function returns '0' for it. + * When a real reference is created (instead of a copy), this function + * returns '1' for both packets (the original packet and the new reference). * * @param pkt Packet handle *
Some implementations may implement new references as packet copy. odp_packet_has_ref() will return 0 for copies, since those are unique packets. Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org> --- include/odp/api/spec/packet.h | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) -- 2.8.1