diff mbox

[API-NEXT] api: pktio: Clarify doc on default pool usage on odp_pktio_open

Message ID 1428335762-8511-1-git-send-email-bill.fischofer@linaro.org
State New
Headers show

Commit Message

Bill Fischofer April 6, 2015, 3:56 p.m. UTC
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
---
 include/odp/api/packet_io.h | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

Comments

Ciprian Barbu April 8, 2015, 7:21 a.m. UTC | #1
Looks good, thanks.

On Mon, Apr 6, 2015 at 6:56 PM, Bill Fischofer
<bill.fischofer@linaro.org> wrote:
> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
> ---
>  include/odp/api/packet_io.h | 15 +++++++++++----
>  1 file changed, 11 insertions(+), 4 deletions(-)
>
> diff --git a/include/odp/api/packet_io.h b/include/odp/api/packet_io.h
> index 6d31aeb..e960f10 100644
> --- a/include/odp/api/packet_io.h
> +++ b/include/odp/api/packet_io.h
> @@ -52,15 +52,22 @@ extern "C" {
>   * odp_pktio_lookup() may be used to obtain a handle to an already open device.
>   *
>   * @param dev    Packet IO device name
> - * @param pool   Pool from which to allocate buffers for storing packets
> + * @param pool   Default pool from which to allocate buffers for storing packets
>   *               received over this packet IO
>   *
>   * @return ODP packet IO handle
>   * @retval ODP_PKTIO_INVALID on failure
>   *
> - * @note dev name loop is specially pktio reserved name for
> - *      device used for testing. Usually it's loop back
> - *      interface.
> + * @note dev name loop is specially pktio reserved name for device used for
> + *      testing. Usually it's loop back interface.
> + *
> + * @note Packets arriving via this interface assigned to a CoS by the
> + *      classifier are received into the pool associated with that CoS. This
> + *      will occur either becuase this pktio is assigned a default CoS via
> + *      the odp_pktio_default_cos_set() routine, or because a matching PMR
> + *      assigned the packet to a specific CoS. The default pool specified
> + *      here is applicable only for those packets that are not assigned to a
> + *      more specific CoS.
>   */
>  odp_pktio_t odp_pktio_open(const char *dev, odp_pool_t pool);
>
> --
> 2.1.0
>
> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> https://lists.linaro.org/mailman/listinfo/lng-odp
Maxim Uvarov April 8, 2015, 7:31 a.m. UTC | #2
But why that can not go to current version? It's not API change, it's 
only text clarifying?

Maxim.

On 04/08/15 10:21, Ciprian Barbu wrote:
> Looks good, thanks.
>
> On Mon, Apr 6, 2015 at 6:56 PM, Bill Fischofer
> <bill.fischofer@linaro.org> wrote:
>> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
>> ---
>>   include/odp/api/packet_io.h | 15 +++++++++++----
>>   1 file changed, 11 insertions(+), 4 deletions(-)
>>
>> diff --git a/include/odp/api/packet_io.h b/include/odp/api/packet_io.h
>> index 6d31aeb..e960f10 100644
>> --- a/include/odp/api/packet_io.h
>> +++ b/include/odp/api/packet_io.h
>> @@ -52,15 +52,22 @@ extern "C" {
>>    * odp_pktio_lookup() may be used to obtain a handle to an already open device.
>>    *
>>    * @param dev    Packet IO device name
>> - * @param pool   Pool from which to allocate buffers for storing packets
>> + * @param pool   Default pool from which to allocate buffers for storing packets
>>    *               received over this packet IO
>>    *
>>    * @return ODP packet IO handle
>>    * @retval ODP_PKTIO_INVALID on failure
>>    *
>> - * @note dev name loop is specially pktio reserved name for
>> - *      device used for testing. Usually it's loop back
>> - *      interface.
>> + * @note dev name loop is specially pktio reserved name for device used for
>> + *      testing. Usually it's loop back interface.
>> + *
>> + * @note Packets arriving via this interface assigned to a CoS by the
>> + *      classifier are received into the pool associated with that CoS. This
>> + *      will occur either becuase this pktio is assigned a default CoS via
>> + *      the odp_pktio_default_cos_set() routine, or because a matching PMR
>> + *      assigned the packet to a specific CoS. The default pool specified
>> + *      here is applicable only for those packets that are not assigned to a
>> + *      more specific CoS.
>>    */
>>   odp_pktio_t odp_pktio_open(const char *dev, odp_pool_t pool);
>>
>> --
>> 2.1.0
>>
>> _______________________________________________
>> lng-odp mailing list
>> lng-odp@lists.linaro.org
>> https://lists.linaro.org/mailman/listinfo/lng-odp
> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> https://lists.linaro.org/mailman/listinfo/lng-odp
Bill Fischofer April 8, 2015, 12:26 p.m. UTC | #3
We've stated that any change to include/odp goes into API-NEXT, however I
agree this is just documentation clarification so it could be promoted.
However, that should get approval from Petri/Robbie/Michael.


On Wed, Apr 8, 2015 at 2:31 AM, Maxim Uvarov <maxim.uvarov@linaro.org>
wrote:

> But why that can not go to current version? It's not API change, it's only
> text clarifying?
>
> Maxim.
>
>
> On 04/08/15 10:21, Ciprian Barbu wrote:
>
>> Looks good, thanks.
>>
>> On Mon, Apr 6, 2015 at 6:56 PM, Bill Fischofer
>> <bill.fischofer@linaro.org> wrote:
>>
>>> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
>>> ---
>>>   include/odp/api/packet_io.h | 15 +++++++++++----
>>>   1 file changed, 11 insertions(+), 4 deletions(-)
>>>
>>> diff --git a/include/odp/api/packet_io.h b/include/odp/api/packet_io.h
>>> index 6d31aeb..e960f10 100644
>>> --- a/include/odp/api/packet_io.h
>>> +++ b/include/odp/api/packet_io.h
>>> @@ -52,15 +52,22 @@ extern "C" {
>>>    * odp_pktio_lookup() may be used to obtain a handle to an already
>>> open device.
>>>    *
>>>    * @param dev    Packet IO device name
>>> - * @param pool   Pool from which to allocate buffers for storing packets
>>> + * @param pool   Default pool from which to allocate buffers for
>>> storing packets
>>>    *               received over this packet IO
>>>    *
>>>    * @return ODP packet IO handle
>>>    * @retval ODP_PKTIO_INVALID on failure
>>>    *
>>> - * @note dev name loop is specially pktio reserved name for
>>> - *      device used for testing. Usually it's loop back
>>> - *      interface.
>>> + * @note dev name loop is specially pktio reserved name for device used
>>> for
>>> + *      testing. Usually it's loop back interface.
>>> + *
>>> + * @note Packets arriving via this interface assigned to a CoS by the
>>> + *      classifier are received into the pool associated with that CoS.
>>> This
>>> + *      will occur either becuase this pktio is assigned a default CoS
>>> via
>>> + *      the odp_pktio_default_cos_set() routine, or because a matching
>>> PMR
>>> + *      assigned the packet to a specific CoS. The default pool
>>> specified
>>> + *      here is applicable only for those packets that are not assigned
>>> to a
>>> + *      more specific CoS.
>>>    */
>>>   odp_pktio_t odp_pktio_open(const char *dev, odp_pool_t pool);
>>>
>>> --
>>> 2.1.0
>>>
>>> _______________________________________________
>>> lng-odp mailing list
>>> lng-odp@lists.linaro.org
>>> https://lists.linaro.org/mailman/listinfo/lng-odp
>>>
>> _______________________________________________
>> lng-odp mailing list
>> lng-odp@lists.linaro.org
>> https://lists.linaro.org/mailman/listinfo/lng-odp
>>
>
> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> https://lists.linaro.org/mailman/listinfo/lng-odp
>
Mike Holmes April 9, 2015, 4:34 p.m. UTC | #4
I think we should get this in api-next for inclusion in odp-1.1.0.

It does have to go via api-next as Bill suggests because a doc change does
change how the api is defined, it is just text but an introduced ambiguity
could lead to incompatible implementations.
We want  users to be confident that they can monitor all such changes
before they are accepted, and be clear that any such change is indicated by
the revision number change.

Some comments in line below

On 8 April 2015 at 08:26, Bill Fischofer <bill.fischofer@linaro.org> wrote:

> We've stated that any change to include/odp goes into API-NEXT, however I
> agree this is just documentation clarification so it could be promoted.
> However, that should get approval from Petri/Robbie/Michael.
>
>
> On Wed, Apr 8, 2015 at 2:31 AM, Maxim Uvarov <maxim.uvarov@linaro.org>
> wrote:
>
>> But why that can not go to current version? It's not API change, it's
>> only text clarifying?
>>
>> Maxim.
>>
>>
>> On 04/08/15 10:21, Ciprian Barbu wrote:
>>
>>> Looks good, thanks.
>>>
>>> On Mon, Apr 6, 2015 at 6:56 PM, Bill Fischofer
>>> <bill.fischofer@linaro.org> wrote:
>>>
>>>> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
>>>> ---
>>>>   include/odp/api/packet_io.h | 15 +++++++++++----
>>>>   1 file changed, 11 insertions(+), 4 deletions(-)
>>>>
>>>> diff --git a/include/odp/api/packet_io.h b/include/odp/api/packet_io.h
>>>> index 6d31aeb..e960f10 100644
>>>> --- a/include/odp/api/packet_io.h
>>>> +++ b/include/odp/api/packet_io.h
>>>> @@ -52,15 +52,22 @@ extern "C" {
>>>>    * odp_pktio_lookup() may be used to obtain a handle to an already
>>>> open device.
>>>>    *
>>>>    * @param dev    Packet IO device name
>>>> - * @param pool   Pool from which to allocate buffers for storing
>>>> packets
>>>> + * @param pool   Default pool from which to allocate buffers for
>>>> storing packets
>>>>    *               received over this packet IO
>>>>    *
>>>>    * @return ODP packet IO handle
>>>>    * @retval ODP_PKTIO_INVALID on failure
>>>>    *
>>>> - * @note dev name loop is specially pktio reserved name for
>>>> - *      device used for testing. Usually it's loop back
>>>> - *      interface.
>>>> + * @note dev name loop is specially pktio reserved name for device
>>>> used for
>>>>
>>>
@note dev The device name "loop" is a special reserved name for a  pktio device
used for

+ *      testing. Usually it's loop back interface.
>>>
>>>

testing. It is a loop back interface, it may be implemented int he HW or in
SW. Its behavior is indistinguishable to that of the interface if it had
been simply looped back externally to the device under test.


> + *
>>>> + * @note Packets arriving via this interface assigned to a CoS by the
>>>> + *      classifier are received into the pool associated with that
>>>> CoS. This
>>>> + *      will occur either becuase this pktio is assigned a default CoS
>>>> via
>>>>
>>>
because


> + *      the odp_pktio_default_cos_set() routine, or because a matching PMR
>>>> + *      assigned the packet to a specific CoS. The default pool
>>>> specified
>>>> + *      here is applicable only for those packets that are not
>>>> assigned to a
>>>> + *      more specific CoS.
>>>>    */
>>>>   odp_pktio_t odp_pktio_open(const char *dev, odp_pool_t pool);
>>>>
>>>> --
>>>> 2.1.0
>>>>
>>>> _______________________________________________
>>>> lng-odp mailing list
>>>> lng-odp@lists.linaro.org
>>>> https://lists.linaro.org/mailman/listinfo/lng-odp
>>>>
>>> _______________________________________________
>>> lng-odp mailing list
>>> lng-odp@lists.linaro.org
>>> https://lists.linaro.org/mailman/listinfo/lng-odp
>>>
>>
>> _______________________________________________
>> lng-odp mailing list
>> lng-odp@lists.linaro.org
>> https://lists.linaro.org/mailman/listinfo/lng-odp
>>
>
>
> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> https://lists.linaro.org/mailman/listinfo/lng-odp
>
>
Maxim Uvarov April 14, 2015, 11:23 a.m. UTC | #5
took this patch to api-next.

Maxim.

On 04/06/15 18:56, Bill Fischofer wrote:
> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
> ---
>   include/odp/api/packet_io.h | 15 +++++++++++----
>   1 file changed, 11 insertions(+), 4 deletions(-)
>
> diff --git a/include/odp/api/packet_io.h b/include/odp/api/packet_io.h
> index 6d31aeb..e960f10 100644
> --- a/include/odp/api/packet_io.h
> +++ b/include/odp/api/packet_io.h
> @@ -52,15 +52,22 @@ extern "C" {
>    * odp_pktio_lookup() may be used to obtain a handle to an already open device.
>    *
>    * @param dev    Packet IO device name
> - * @param pool   Pool from which to allocate buffers for storing packets
> + * @param pool   Default pool from which to allocate buffers for storing packets
>    *               received over this packet IO
>    *
>    * @return ODP packet IO handle
>    * @retval ODP_PKTIO_INVALID on failure
>    *
> - * @note dev name loop is specially pktio reserved name for
> - *	 device used for testing. Usually it's loop back
> - *	 interface.
> + * @note dev name loop is specially pktio reserved name for device used for
> + *	 testing. Usually it's loop back interface.
> + *
> + * @note Packets arriving via this interface assigned to a CoS by the
> + *	 classifier are received into the pool associated with that CoS. This
> + *	 will occur either becuase this pktio is assigned a default CoS via
> + *	 the odp_pktio_default_cos_set() routine, or because a matching PMR
> + *	 assigned the packet to a specific CoS. The default pool specified
> + *	 here is applicable only for those packets that are not assigned to a
> + *	 more specific CoS.
>    */
>   odp_pktio_t odp_pktio_open(const char *dev, odp_pool_t pool);
>
diff mbox

Patch

diff --git a/include/odp/api/packet_io.h b/include/odp/api/packet_io.h
index 6d31aeb..e960f10 100644
--- a/include/odp/api/packet_io.h
+++ b/include/odp/api/packet_io.h
@@ -52,15 +52,22 @@  extern "C" {
  * odp_pktio_lookup() may be used to obtain a handle to an already open device.
  *
  * @param dev    Packet IO device name
- * @param pool   Pool from which to allocate buffers for storing packets
+ * @param pool   Default pool from which to allocate buffers for storing packets
  *               received over this packet IO
  *
  * @return ODP packet IO handle
  * @retval ODP_PKTIO_INVALID on failure
  *
- * @note dev name loop is specially pktio reserved name for
- *	 device used for testing. Usually it's loop back
- *	 interface.
+ * @note dev name loop is specially pktio reserved name for device used for
+ *	 testing. Usually it's loop back interface.
+ *
+ * @note Packets arriving via this interface assigned to a CoS by the
+ *	 classifier are received into the pool associated with that CoS. This
+ *	 will occur either becuase this pktio is assigned a default CoS via
+ *	 the odp_pktio_default_cos_set() routine, or because a matching PMR
+ *	 assigned the packet to a specific CoS. The default pool specified
+ *	 here is applicable only for those packets that are not assigned to a
+ *	 more specific CoS.
  */
 odp_pktio_t odp_pktio_open(const char *dev, odp_pool_t pool);