[PATCH v2] PCI: ABI change request for adding new field in rte_pci_id structure

[PATCH v2] PCI: ABI change request for adding new field in rte_pci_id structure

[Ziye Yang]

From: Ziye <ziye.yang@intel.com>

The purpose of this patch is used to add a new field
"class" in rte_pci_id structure. The new class field includes
class_id, subcalss_id, programming interface of a pci device.
With this field, we can identify pci device by its class info,
which can be more flexible instead of probing the device by
vendor_id OR device_id OR subvendor_id OR subdevice_id.
For example, we can probe all nvme devices by class field, which
can be quite convenient.

Signed-off-by: Ziye Yang <ziye.yang@intel.com>
---
 doc/guides/rel_notes/release_16_04.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/guides/rel_notes/release_16_04.rst b/doc/guides/rel_notes/release_16_04.rst
index 27fc624..fe843a5 100644
--- a/doc/guides/rel_notes/release_16_04.rst
+++ b/doc/guides/rel_notes/release_16_04.rst
@@ -95,9 +95,10 @@ This section should contain API changes. Sample format:
 ABI Changes
 -----------
 
-* Add a short 1-2 sentence description of the ABI change that was announced in
-  the previous releases and made in this release. Use fixed width quotes for
-  ``rte_function_names`` or ``rte_struct_names``. Use the past tense.
+* New field ``class`` is added into ``rte_pci_id`` structure. This new
+  added ``class`` field can be used to probe pci devices by class related
+  info. With this new field, the size of structure ``rte_pci_device`` will
+  be increased.
 
 
 Shared Library Versions
-- 
1.9.3

Re: [PATCH v2] PCI: ABI change request for adding new field in rte_pci_id structure

[Panu Matilainen]

On 02/16/2016 05:16 AM, Ziye Yang wrote:
> From: Ziye <ziye.yang@intel.com>
>
> The purpose of this patch is used to add a new field
> "class" in rte_pci_id structure. The new class field includes
> class_id, subcalss_id, programming interface of a pci device.
> With this field, we can identify pci device by its class info,
> which can be more flexible instead of probing the device by
> vendor_id OR device_id OR subvendor_id OR subdevice_id.
> For example, we can probe all nvme devices by class field, which
> can be quite convenient.
>
> Signed-off-by: Ziye Yang <ziye.yang@intel.com>
> ---
>   doc/guides/rel_notes/release_16_04.rst | 7 ++++---
>   1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/doc/guides/rel_notes/release_16_04.rst b/doc/guides/rel_notes/release_16_04.rst
> index 27fc624..fe843a5 100644
> --- a/doc/guides/rel_notes/release_16_04.rst
> +++ b/doc/guides/rel_notes/release_16_04.rst
> @@ -95,9 +95,10 @@ This section should contain API changes. Sample format:
>   ABI Changes
>   -----------
>
> -* Add a short 1-2 sentence description of the ABI change that was announced in
> -  the previous releases and made in this release. Use fixed width quotes for
> -  ``rte_function_names`` or ``rte_struct_names``. Use the past tense.
> +* New field ``class`` is added into ``rte_pci_id`` structure. This new
> +  added ``class`` field can be used to probe pci devices by class related
> +  info. With this new field, the size of structure ``rte_pci_device`` will
> +  be increased.
>
>
>   Shared Library Versions
>

ABI breakage announcements go into doc/guides/rel_notes/deprecation.rst, 
see the examples there. Also you can't break the ABI in the version 
under development but only the next one, so right now the earliest ABI 
breakage opportunity is in the release *after* 16.04, which is supposed 
to be 16.07 according to the roadmap.

	- Panu -

Re: [PATCH v2] PCI: ABI change request for adding new field in rte_pci_id structure

[Yang, Ziye]

Hi Panu,

" ABI breakage announcements go into doc/guides/rel_notes/deprecation.rst,
see the examples there. Also you can't break the ABI in the version under development but only the next one, so right now the earliest ABI breakage opportunity is in the release *after* 16.04, which is supposed to be 16.07 according to the roadmap."

So I only need to do the ABI breakage announcements  into doc/guides/rel_notes/deprecation.rst, right?

Thanks.

Best Regards,
Ziye Yang

-----Original Message-----
From: Panu Matilainen [mailto:pmatilai@redhat.com] 
Sent: Tuesday, February 16, 2016 3:39 PM
To: Yang, Ziye <ziye.yang@intel.com>; dev@dpdk.org
Subject: Re: [dpdk-dev] [PATCH v2] PCI: ABI change request for adding new field in rte_pci_id structure

On 02/16/2016 05:16 AM, Ziye Yang wrote:
> From: Ziye <ziye.yang@intel.com>
>
> The purpose of this patch is used to add a new field "class" in 
> rte_pci_id structure. The new class field includes class_id, 
> subcalss_id, programming interface of a pci device.
> With this field, we can identify pci device by its class info, which 
> can be more flexible instead of probing the device by vendor_id OR 
> device_id OR subvendor_id OR subdevice_id.
> For example, we can probe all nvme devices by class field, which can 
> be quite convenient.
>
> Signed-off-by: Ziye Yang <ziye.yang@intel.com>
> ---
>   doc/guides/rel_notes/release_16_04.rst | 7 ++++---
>   1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/doc/guides/rel_notes/release_16_04.rst 
> b/doc/guides/rel_notes/release_16_04.rst
> index 27fc624..fe843a5 100644
> --- a/doc/guides/rel_notes/release_16_04.rst
> +++ b/doc/guides/rel_notes/release_16_04.rst
> @@ -95,9 +95,10 @@ This section should contain API changes. Sample format:
>   ABI Changes
>   -----------
>
> -* Add a short 1-2 sentence description of the ABI change that was 
> announced in
> -  the previous releases and made in this release. Use fixed width 
> quotes for
> -  ``rte_function_names`` or ``rte_struct_names``. Use the past tense.
> +* New field ``class`` is added into ``rte_pci_id`` structure. This 
> +new
> +  added ``class`` field can be used to probe pci devices by class 
> +related
> +  info. With this new field, the size of structure ``rte_pci_device`` 
> +will
> +  be increased.
>
>
>   Shared Library Versions
>

ABI breakage announcements go into doc/guides/rel_notes/deprecation.rst,
see the examples there. Also you can't break the ABI in the version under development but only the next one, so right now the earliest ABI breakage opportunity is in the release *after* 16.04, which is supposed to be 16.07 according to the roadmap.

	- Panu -

Re: [PATCH v2] PCI: ABI change request for adding new field in rte_pci_id structure

[Panu Matilainen]

On 02/16/2016 09:43 AM, Yang, Ziye wrote:
> Hi Panu,
>
> " ABI breakage announcements go into doc/guides/rel_notes/deprecation.rst,
> see the examples there. Also you can't break the ABI in the version under development but only the next one, so right now the earliest ABI breakage opportunity is in the release *after* 16.04, which is supposed to be 16.07 according to the roadmap."
>
> So I only need to do the ABI breakage announcements  into doc/guides/rel_notes/deprecation.rst, right?
>

Yes.

The version-specific release notes ABI/API changes section is to be 
updated along with the actual changes to the code.

If you haven't already done so, do read
http://dpdk.org/doc/guides/contributing/versioning.html

	- Panu -

[PATCH v2] PCI: ABI change request for adding new field in rte_pci_id structure

[Ziye Yang]

From: Ziye <ziye.yang@intel.com>

The purpose of this patch is used to add a new field
"class" in rte_pci_id structure. The new class field includes
class_id, subcalss_id, programming interface of a pci device.
With this field, we can identify pci device by its class info,
which can be more flexible instead of probing the device by
vendor_id OR device_id OR subvendor_id OR subdevice_id.
For example, we can probe all nvme devices by class field, which
can be quite convenient.

As release_2_3.rst is replaced with release_16_04.rst

Signed-off-by: Ziye Yang <ziye.yang@intel.com>
---
 doc/guides/rel_notes/release_16_04.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/guides/rel_notes/release_16_04.rst b/doc/guides/rel_notes/release_16_04.rst
index 27fc624..fe843a5 100644
--- a/doc/guides/rel_notes/release_16_04.rst
+++ b/doc/guides/rel_notes/release_16_04.rst
@@ -95,9 +95,10 @@ This section should contain API changes. Sample format:
 ABI Changes
 -----------
 
-* Add a short 1-2 sentence description of the ABI change that was announced in
-  the previous releases and made in this release. Use fixed width quotes for
-  ``rte_function_names`` or ``rte_struct_names``. Use the past tense.
+* New field ``class`` is added into ``rte_pci_id`` structure. This new
+  added ``class`` field can be used to probe pci devices by class related
+  info. With this new field, the size of structure ``rte_pci_device`` will
+  be increased.
 
 
 Shared Library Versions
-- 
1.9.3

[PATCH] PCI: ABI change request for adding new field in rte_pci_id structure

[Ziye Yang]

From: Ziye <ziye.yang@intel.com>

The purpose of this patch is used to add a new field
"class" in rte_pci_id structure. The new class field includes
class_id, subcalss_id, programming interface of a pci device.
With this field, we can identify pci device by its class info,
which can be more flexible instead of probing the device by
vendor_id OR device_id OR subvendor_id OR subdevice_id.
For example, we can probe all nvme devices by class field, which
can be quite convenient.

Signed-off-by: Ziye Yang <ziye.yang@intel.com>
---
 doc/guides/rel_notes/release_2_3.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/guides/rel_notes/release_2_3.rst b/doc/guides/rel_notes/release_2_3.rst
index 99de186..8fcb43f 100644
--- a/doc/guides/rel_notes/release_2_3.rst
+++ b/doc/guides/rel_notes/release_2_3.rst
@@ -39,6 +39,10 @@ API Changes
 ABI Changes
 -----------
 
+* New field ``class`` is added into ``rte_pci_id`` structure. This new
+  added ``class`` field can be used to probe pci devices by class related
+  info. With this new field, the size of structure ``rte_pci_device`` will
+  be increased.
 
 Shared Library Versions
 -----------------------
-- 
1.9.3

[PATCH v2] PCI: ABI change request for adding new field in rte_pci_id structure

[Ziye Yang]

From: Ziye <ziye.yang@intel.com>

The purpose of this patch is used to add a new field
"class" in rte_pci_id structure. The new class field includes
class_id, subcalss_id, programming interface of a pci device.
With this field, we can identify pci device by its class info,
which can be more flexible instead of probing the device by
vendor_id OR device_id OR subvendor_id OR subdevice_id.
For example, we can probe all nvme devices by class field, which
can be quite convenient.

As release_2_3.rst is replaced with release_16_04.rst.

Signed-off-by: Ziye Yang <ziye.yang@intel.com>
---
 doc/guides/rel_notes/release_16_04.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/guides/rel_notes/release_16_04.rst b/doc/guides/rel_notes/release_16_04.rst
index 27fc624..fe843a5 100644
--- a/doc/guides/rel_notes/release_16_04.rst
+++ b/doc/guides/rel_notes/release_16_04.rst
@@ -95,9 +95,10 @@ This section should contain API changes. Sample format:
 ABI Changes
 -----------
 
-* Add a short 1-2 sentence description of the ABI change that was announced in
-  the previous releases and made in this release. Use fixed width quotes for
-  ``rte_function_names`` or ``rte_struct_names``. Use the past tense.
+* New field ``class`` is added into ``rte_pci_id`` structure. This new
+  added ``class`` field can be used to probe pci devices by class related
+  info. With this new field, the size of structure ``rte_pci_device`` will
+  be increased.
 
 
 Shared Library Versions
-- 
1.9.3

Re: [PATCH v2] PCI: ABI change request for adding new field in rte_pci_id structure

[Bruce Richardson]

On Tue, Feb 16, 2016 at 12:15:19PM +0800, Ziye Yang wrote:
> From: Ziye <ziye.yang@intel.com>
> 
> The purpose of this patch is used to add a new field
> "class" in rte_pci_id structure. The new class field includes
> class_id, subcalss_id, programming interface of a pci device.
> With this field, we can identify pci device by its class info,
> which can be more flexible instead of probing the device by
> vendor_id OR device_id OR subvendor_id OR subdevice_id.
> For example, we can probe all nvme devices by class field, which
> can be quite convenient.
> 
> As release_2_3.rst is replaced with release_16_04.rst.
> 
> Signed-off-by: Ziye Yang <ziye.yang@intel.com>
> ---
>  doc/guides/rel_notes/release_16_04.rst | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/doc/guides/rel_notes/release_16_04.rst b/doc/guides/rel_notes/release_16_04.rst
> index 27fc624..fe843a5 100644
> --- a/doc/guides/rel_notes/release_16_04.rst
> +++ b/doc/guides/rel_notes/release_16_04.rst
> @@ -95,9 +95,10 @@ This section should contain API changes. Sample format:
>  ABI Changes
>  -----------
>  
> -* Add a short 1-2 sentence description of the ABI change that was announced in
> -  the previous releases and made in this release. Use fixed width quotes for
> -  ``rte_function_names`` or ``rte_struct_names``. Use the past tense.
> +* New field ``class`` is added into ``rte_pci_id`` structure. This new
> +  added ``class`` field can be used to probe pci devices by class related
> +  info. With this new field, the size of structure ``rte_pci_device`` will
> +  be increased.
>  
>  
>  Shared Library Versions
> -- 

Hi,

since this is new ABI change announcement, and not one that was previously
announced and is now being applied, this announcement should go in the 
deprecation.rst file, rather than release_16_04.rst.

Thomas, is there some reason why the deprecation notices are not called out in
the release notes for a new release? Why are they kept separately?

/Bruce

Re: [PATCH v2] PCI: ABI change request for adding new field in rte_pci_id structure

[Thomas Monjalon]

2016-02-16 10:11, Bruce Richardson:
> Thomas, is there some reason why the deprecation notices are not called out in
> the release notes for a new release? Why are they kept separately?

No strong reason.
It is part of the release notes but not in the versioned section.
Probably because there is no interest in keeping the history of planned
deprecations in the release notes. When the API/ABI is changed, the deprecation
notice is replaced by an entry in the versioned section.