Re: [lng-odp] [API-NEXT PATCHv6 1/5] api: packet: add support for packet references

[Bill Fischofer]

On Mon, Jan 9, 2017 at 10:08 AM, Bala Manoharan
 wrote:
> Except for the Minor documentation comment below
>
> Reviewed-by: Balasubramanian Manoharan 
>
> On 5 January 2017 at 20:25, Bill Fischofer  wrote:
>> Introduce three new APIs that support efficient sharing of portions of
>> packets.
>>
>> odp_packet_ref_static() creates an alias for a base packet
>>
>> odp_packet_ref() creates a reference to a base packet
>>
>> odp_packet_ref_pkt() creates a reference to a base packet from a supplied
>> header packet
>>
>> In addition, two other APIs simplify working with references
>>
>> odp_packet_is_ref() says whether a packet is a reference
>>
>> odp_packet_unshared_len() gives the sum of data lengths over all unshared
>> packet segments. These are the only bytes of the packet that may be
>> modified safely.
>>
>> Signed-off-by: Bill Fischofer 
>> ---
>> Changes in v6:
>> - Miscellaneous formatting corrections
>> - Minor documentation improvements
>>
>> Changes in v5:
>> - Clarified that both input packets to odp_packet_ref_pkt() must be from the
>>   same pool and results are undefined if they are not.
>> - Clarified that input(s) to reference create APIs may be references and that
>>   implementations are free to perform partial or full packet copies if needed
>>   to support such compound references.
>> - Removed odp_packet_has_ref() and redefined odp_packet_is_ref() to indicate
>>   simply whether other handles exist that share bytes with this packet.
>> - Modified validation tests to reflect the above changes.
>>
>> Changes in v4:
>> - Bug fixes
>> - Expand validation testing to cover extensions on packets with references
>>
>> Changes in v3:
>> - Rebased to latest API-NEXT
>> - Bug fixes
>> - Eliminate concept of base packets, both references and referenced packets 
>> may
>>   have head extensions as needed
>>  include/odp/api/spec/packet.h | 172 
>> +-
>>  1 file changed, 171 insertions(+), 1 deletion(-)
>>
>> diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h
>> index 4a86eba..9b6681c 100644
>> --- a/include/odp/api/spec/packet.h
>> +++ b/include/odp/api/spec/packet.h
>> @@ -256,6 +256,20 @@ uint32_t odp_packet_seg_len(odp_packet_t pkt);
>>  uint32_t odp_packet_len(odp_packet_t pkt);
>>
>>  /**
>> + * Packet unshared data len
>> + *
>> + * Returns the sum of data lengths over all unshared packet segments. These
>> + * are the only bytes that should be modified by the caller. The rest of the
>> + * packet should be treated as read only. odp_packet_unshared_len() will be
>> + * equal to odp_packet_len() if odp_packet_is_ref() is 0.
>> + *
>> + * @param pkt Packet handle
>> + *
>> + * @return Packet unshared data length
>> + */
>> +uint32_t odp_packet_unshared_len(odp_packet_t pkt);
>> +
>> +/**
>>   * Packet headroom length
>>   *
>>   * Returns the current packet level headroom length.
>> @@ -795,7 +809,7 @@ uint32_t odp_packet_seg_data_len(odp_packet_t pkt, 
>> odp_packet_seg_t seg);
>>   * data pointers. Otherwise, all old pointers remain valid.
>>   *
>>   * The resulting packet is always allocated from the same pool as
>> - * the destination packet. The source packet may have been allocate from
>> + * the destination packet. The source packet may have been allocated from
>>   * any pool.
>>   *
>>   * On failure, both handles remain valid and packets are not modified.
>> @@ -848,6 +862,162 @@ int odp_packet_split(odp_packet_t *pkt, uint32_t len, 
>> odp_packet_t *tail);
>>
>>  /*
>>   *
>> + * References
>> + * 
>> + *
>> + */
>> +
>> +/**
>> + * Create a static reference to a packet
>> + *
>> + * A static reference is used to obtain an additional handle for referring 
>> to
>> + * a packet so that the storage behind it is not freed until all references 
>> to
>> + * the packet are freed. This can be used, for example, to support efficient
>> + * retransmission processing.
>> + *
>> + * The intent of a static reference is that both the packet and the returned
>> + * reference to it will be treated as read only after this call. Results are
>> + * undefined if this restriction is not observed.
>> + *
>> + * Static references have restrictions but may have performance advantages 
>> on
>> + * some platforms if the caller does not intend to modify the reference
>> + * packet. If modification is needed (e.g., to prefix a unique header onto 
>> the
>> + * packet) then odp_packet_ref() or odp_packet_ref_pkt() should be used.
>> + *
>> + * @param pktHandle of the packet for which a static reference is
>> + *   to be created.
>> + *
>> + * @returnHandle of the static reference packet
>> + * @retval ODP_PACKET_INVALID Operation failed. pkt remains unchanged.
>> + */
>> +odp_packet_t odp_packet_ref_static(odp_packet_t pkt);
>> +
>> +/**
>> + * Create 

Re: [lng-odp] [API-NEXT PATCHv6 1/5] api: packet: add support for packet references

[Bala Manoharan]

Except for the Minor documentation comment below

Reviewed-by: Balasubramanian Manoharan 

On 5 January 2017 at 20:25, Bill Fischofer  wrote:
> Introduce three new APIs that support efficient sharing of portions of
> packets.
>
> odp_packet_ref_static() creates an alias for a base packet
>
> odp_packet_ref() creates a reference to a base packet
>
> odp_packet_ref_pkt() creates a reference to a base packet from a supplied
> header packet
>
> In addition, two other APIs simplify working with references
>
> odp_packet_is_ref() says whether a packet is a reference
>
> odp_packet_unshared_len() gives the sum of data lengths over all unshared
> packet segments. These are the only bytes of the packet that may be
> modified safely.
>
> Signed-off-by: Bill Fischofer 
> ---
> Changes in v6:
> - Miscellaneous formatting corrections
> - Minor documentation improvements
>
> Changes in v5:
> - Clarified that both input packets to odp_packet_ref_pkt() must be from the
>   same pool and results are undefined if they are not.
> - Clarified that input(s) to reference create APIs may be references and that
>   implementations are free to perform partial or full packet copies if needed
>   to support such compound references.
> - Removed odp_packet_has_ref() and redefined odp_packet_is_ref() to indicate
>   simply whether other handles exist that share bytes with this packet.
> - Modified validation tests to reflect the above changes.
>
> Changes in v4:
> - Bug fixes
> - Expand validation testing to cover extensions on packets with references
>
> Changes in v3:
> - Rebased to latest API-NEXT
> - Bug fixes
> - Eliminate concept of base packets, both references and referenced packets 
> may
>   have head extensions as needed
>  include/odp/api/spec/packet.h | 172 
> +-
>  1 file changed, 171 insertions(+), 1 deletion(-)
>
> diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h
> index 4a86eba..9b6681c 100644
> --- a/include/odp/api/spec/packet.h
> +++ b/include/odp/api/spec/packet.h
> @@ -256,6 +256,20 @@ uint32_t odp_packet_seg_len(odp_packet_t pkt);
>  uint32_t odp_packet_len(odp_packet_t pkt);
>
>  /**
> + * Packet unshared data len
> + *
> + * Returns the sum of data lengths over all unshared packet segments. These
> + * are the only bytes that should be modified by the caller. The rest of the
> + * packet should be treated as read only. odp_packet_unshared_len() will be
> + * equal to odp_packet_len() if odp_packet_is_ref() is 0.
> + *
> + * @param pkt Packet handle
> + *
> + * @return Packet unshared data length
> + */
> +uint32_t odp_packet_unshared_len(odp_packet_t pkt);
> +
> +/**
>   * Packet headroom length
>   *
>   * Returns the current packet level headroom length.
> @@ -795,7 +809,7 @@ uint32_t odp_packet_seg_data_len(odp_packet_t pkt, 
> odp_packet_seg_t seg);
>   * data pointers. Otherwise, all old pointers remain valid.
>   *
>   * The resulting packet is always allocated from the same pool as
> - * the destination packet. The source packet may have been allocate from
> + * the destination packet. The source packet may have been allocated from
>   * any pool.
>   *
>   * On failure, both handles remain valid and packets are not modified.
> @@ -848,6 +862,162 @@ int odp_packet_split(odp_packet_t *pkt, uint32_t len, 
> odp_packet_t *tail);
>
>  /*
>   *
> + * References
> + * 
> + *
> + */
> +
> +/**
> + * Create a static reference to a packet
> + *
> + * A static reference is used to obtain an additional handle for referring to
> + * a packet so that the storage behind it is not freed until all references 
> to
> + * the packet are freed. This can be used, for example, to support efficient
> + * retransmission processing.
> + *
> + * The intent of a static reference is that both the packet and the returned
> + * reference to it will be treated as read only after this call. Results are
> + * undefined if this restriction is not observed.
> + *
> + * Static references have restrictions but may have performance advantages on
> + * some platforms if the caller does not intend to modify the reference
> + * packet. If modification is needed (e.g., to prefix a unique header onto 
> the
> + * packet) then odp_packet_ref() or odp_packet_ref_pkt() should be used.
> + *
> + * @param pktHandle of the packet for which a static reference is
> + *   to be created.
> + *
> + * @returnHandle of the static reference packet
> + * @retval ODP_PACKET_INVALID Operation failed. pkt remains unchanged.
> + */
> +odp_packet_t odp_packet_ref_static(odp_packet_t pkt);
> +
> +/**
> + * Create a reference to a packet
> + *
> + * Create a dynamic reference to a packet starting at a specified byte
> + * offset. This reference may be used as an argument to header manipulation
> + * APIs to prefix a unique header