[v3,1/2] Documentation: fpga: dfl: add PCI Identification documentation

Commit Message

Matthew Gerlach July 7, 2022, 3:05 p.m. UTC

From: Matthew Gerlach <[e-mail]>

Add documentation on identifying FPGA based PCI cards prompted
by discussion on the [e-mail] mailing list.

Signed-off-by: Matthew Gerlach <[e-mail]>
---
v3: Add url to page tracking PCI ID information for DFL based cards.

v2: Introduced in v2.
---
 Documentation/fpga/dfl.rst | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

Comments

Marco Pagani July 12, 2022, 5:14 p.m. UTC | #1

On 2022-07-07 17:05, [e-mail] wrote:
> From: Matthew Gerlach <[e-mail]>
> 
> Add documentation on identifying FPGA based PCI cards prompted
> by discussion on the [e-mail] mailing list.
> 
> Signed-off-by: Matthew Gerlach <[e-mail]>
> ---
> v3: Add url to page tracking PCI ID information for DFL based cards.
> 
> v2: Introduced in v2.
> ---
>  Documentation/fpga/dfl.rst | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst
> index 15b670926084..5144775b860a 100644
> --- a/Documentation/fpga/dfl.rst
> +++ b/Documentation/fpga/dfl.rst
> @@ -507,6 +507,27 @@ ids application.
>  https://github.com/OPAE/dfl-feature-id
>  
>  
> +PCI Device Identification
> +================================
> +Since FPGA based PCI cards can be reconfigured to a perform a completely

There's a small typo: "to a perform" --> "to perform"

> +new function at runtime, properly identifying such cards and binding the
> +correct driver can be challenging. In many use cases, deployed FPGA based
> +PCI cards are essentially static and the PCI Product ID and Vendor ID pair
> +is sufficient to identify the card.  The DFL framework helps with the
> +dynamic case of deployed FPGA cards changing at run time by providing
> +more detailed information about card discoverable at runtime.
> +
> +At one level, the DFL on a PCI card describes the function of the card.
> +However, the same DFL could be instantiated on different physical cards.
> +Conversely, different DFLs could be instantiated on the same physical card.
> +Practical management of a cloud containing a heterogeneous set of such cards
> +requires a PCI level of card identification. While the PCI Product ID and
> +Vendor ID may be sufficient to bind the dfl-pci driver, it is expected
> +that FPGA PCI cards would advertise suitable Subsystem ID and Subsystem
> +Vendor ID values. Further PCI Product, Vendor, and Subsystem id tracking
> +can be found at https://github.com/OPAE/dfl-feature-id/blob/main/dfl-pci-ids.rst.
> +
> +
>  Location of DFLs on a PCI Device
>  ================================
>  The original method for finding a DFL on a PCI device assumed the start of the

Marco

Tom Rix July 13, 2022, 10:07 p.m. UTC | #2

On 7/7/22 8:05 AM, [e-mail] wrote:
> From: Matthew Gerlach <[e-mail]>
>
> Add documentation on identifying FPGA based PCI cards prompted
> by discussion on the [e-mail] mailing list.
>
> Signed-off-by: Matthew Gerlach <[e-mail]>
> ---
> v3: Add url to page tracking PCI ID information for DFL based cards.
>
> v2: Introduced in v2.
> ---
>   Documentation/fpga/dfl.rst | 21 +++++++++++++++++++++
>   1 file changed, 21 insertions(+)
>
> diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst
> index 15b670926084..5144775b860a 100644
> --- a/Documentation/fpga/dfl.rst
> +++ b/Documentation/fpga/dfl.rst
> @@ -507,6 +507,27 @@ ids application.
>   https://github.com/OPAE/dfl-feature-id
>   
>   
> +PCI Device Identification
> +================================
> +Since FPGA based PCI cards can be reconfigured to a perform a completely
> +new function at runtime, properly identifying such cards and binding the
> +correct driver can be challenging. In many use cases, deployed FPGA based
> +PCI cards are essentially static and the PCI Product ID and Vendor ID pair
> +is sufficient to identify the card.  The DFL framework helps with the
> +dynamic case of deployed FPGA cards changing at run time by providing
> +more detailed information about card discoverable at runtime.
> +
> +At one level, the DFL on a PCI card describes the function of the card.
> +However, the same DFL could be instantiated on different physical cards.
> +Conversely, different DFLs could be instantiated on the same physical card.
> +Practical management of a cloud containing a heterogeneous set of such cards
> +requires a PCI level of card identification. While the PCI Product ID and
> +Vendor ID may be sufficient to bind the dfl-pci driver, it is expected
> +that FPGA PCI cards would advertise suitable Subsystem ID and Subsystem
> +Vendor ID values. Further PCI Product, Vendor, and Subsystem id tracking
> +can be found at https://github.com/OPAE/dfl-feature-id/blob/main/dfl-pci-ids.rst.

This link looks good.

It may be good to be explicit and say which device(s) needs to be 
specified by the quadruple.

Reviewed-by: Tom Rix <[e-mail]>

> +
> +
>   Location of DFLs on a PCI Device
>   ================================
>   The original method for finding a DFL on a PCI device assumed the start of the

Wu, Hao July 18, 2022, 4:43 a.m. UTC | #3

> -----Original Message-----
> From: [e-mail] <[e-mail]>
> Sent: Thursday, July 7, 2022 11:06 PM
> To: Wu, Hao <[e-mail]>; Xu, Yilun <[e-mail]>; Weight,
> Russell H <[e-mail]>; Muddebihal, Basheer Ahmed
> <[e-mail]>; [e-mail];
> [e-mail]; [e-mail]; [e-mail]; linux-
> [e-mail]; [e-mail]; Zhang, Tianfei
> <[e-mail]>
> Cc: Matthew Gerlach <[e-mail]>
> Subject: [PATCH v3 1/2] Documentation: fpga: dfl: add PCI Identification
> documentation
> 
> From: Matthew Gerlach <[e-mail]>
> 
> Add documentation on identifying FPGA based PCI cards prompted
> by discussion on the [e-mail] mailing list.
> 
> Signed-off-by: Matthew Gerlach <[e-mail]>
> ---
> v3: Add url to page tracking PCI ID information for DFL based cards.
> 
> v2: Introduced in v2.
> ---
>  Documentation/fpga/dfl.rst | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst
> index 15b670926084..5144775b860a 100644
> --- a/Documentation/fpga/dfl.rst
> +++ b/Documentation/fpga/dfl.rst
> @@ -507,6 +507,27 @@ ids application.
>  https://github.com/OPAE/dfl-feature-id
> 
> 
> +PCI Device Identification
> +================================
> +Since FPGA based PCI cards can be reconfigured to a perform a completely
> +new function at runtime, properly identifying such cards and binding the
> +correct driver can be challenging. In many use cases, deployed FPGA based
> +PCI cards are essentially static and the PCI Product ID and Vendor ID pair
> +is sufficient to identify the card.  The DFL framework helps with the
> +dynamic case of deployed FPGA cards changing at run time by providing
> +more detailed information about card discoverable at runtime.
> +
> +At one level, the DFL on a PCI card describes the function of the card.
> +However, the same DFL could be instantiated on different physical cards.
> +Conversely, different DFLs could be instantiated on the same physical card.
> +Practical management of a cloud containing a heterogeneous set of such
> cards
> +requires a PCI level of card identification. While the PCI Product ID and
> +Vendor ID may be sufficient to bind the dfl-pci driver, it is expected
> +that FPGA PCI cards would advertise suitable Subsystem ID and Subsystem
> +Vendor ID values. Further PCI Product, Vendor, and Subsystem id tracking
> +can be found at https://github.com/OPAE/dfl-feature-id/blob/main/dfl-pci-
> ids.rst.

I feel that we may not really need this in fpga-dfl doc, as this is not describing
any new method provided by DFL, but just something from PCI standard, right?

Thanks
Hao

Matthew Gerlach July 18, 2022, 7:30 p.m. UTC | #4

On Mon, 18 Jul 2022, Wu, Hao wrote:

>> -----Original Message-----
>> From: [e-mail] <[e-mail]>
>> Sent: Thursday, July 7, 2022 11:06 PM
>> To: Wu, Hao <[e-mail]>; Xu, Yilun <[e-mail]>; Weight,
>> Russell H <[e-mail]>; Muddebihal, Basheer Ahmed
>> <[e-mail]>; [e-mail];
>> [e-mail]; [e-mail]; [e-mail]; linux-
>> [e-mail]; [e-mail]; Zhang, Tianfei
>> <[e-mail]>
>> Cc: Matthew Gerlach <[e-mail]>
>> Subject: [PATCH v3 1/2] Documentation: fpga: dfl: add PCI Identification
>> documentation
>>
>> From: Matthew Gerlach <[e-mail]>
>>
>> Add documentation on identifying FPGA based PCI cards prompted
>> by discussion on the [e-mail] mailing list.
>>
>> Signed-off-by: Matthew Gerlach <[e-mail]>
>> ---
>> v3: Add url to page tracking PCI ID information for DFL based cards.
>>
>> v2: Introduced in v2.
>> ---
>>  Documentation/fpga/dfl.rst | 21 +++++++++++++++++++++
>>  1 file changed, 21 insertions(+)
>>
>> diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst
>> index 15b670926084..5144775b860a 100644
>> --- a/Documentation/fpga/dfl.rst
>> +++ b/Documentation/fpga/dfl.rst
>> @@ -507,6 +507,27 @@ ids application.
>>  https://github.com/OPAE/dfl-feature-id
>>
>>
>> +PCI Device Identification
>> +================================
>> +Since FPGA based PCI cards can be reconfigured to a perform a completely
>> +new function at runtime, properly identifying such cards and binding the
>> +correct driver can be challenging. In many use cases, deployed FPGA based
>> +PCI cards are essentially static and the PCI Product ID and Vendor ID pair
>> +is sufficient to identify the card.  The DFL framework helps with the
>> +dynamic case of deployed FPGA cards changing at run time by providing
>> +more detailed information about card discoverable at runtime.
>> +
>> +At one level, the DFL on a PCI card describes the function of the card.
>> +However, the same DFL could be instantiated on different physical cards.
>> +Conversely, different DFLs could be instantiated on the same physical card.
>> +Practical management of a cloud containing a heterogeneous set of such
>> cards
>> +requires a PCI level of card identification. While the PCI Product ID and
>> +Vendor ID may be sufficient to bind the dfl-pci driver, it is expected
>> +that FPGA PCI cards would advertise suitable Subsystem ID and Subsystem
>> +Vendor ID values. Further PCI Product, Vendor, and Subsystem id tracking
>> +can be found at https://github.com/OPAE/dfl-feature-id/blob/main/dfl-pci-
>> ids.rst.
>
> I feel that we may not really need this in fpga-dfl doc, as this is not describing
> any new method provided by DFL, but just something from PCI standard, right?

I think you are correct that this documentation change is not necessary. 
It was useful as a mechanism for discussion, but it is really just 
something from the PCI standard.

I will not include it in the v4 patch set.

>
> Thanks
> Hao
>

Patch

diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst
index 15b670926084..5144775b860a 100644
--- a/Documentation/fpga/dfl.rst
+++ b/Documentation/fpga/dfl.rst
@@ -507,6 +507,27 @@  ids application.
 https://github.com/OPAE/dfl-feature-id
 
 
+PCI Device Identification
+================================
+Since FPGA based PCI cards can be reconfigured to a perform a completely
+new function at runtime, properly identifying such cards and binding the
+correct driver can be challenging. In many use cases, deployed FPGA based
+PCI cards are essentially static and the PCI Product ID and Vendor ID pair
+is sufficient to identify the card.  The DFL framework helps with the
+dynamic case of deployed FPGA cards changing at run time by providing
+more detailed information about card discoverable at runtime.
+
+At one level, the DFL on a PCI card describes the function of the card.
+However, the same DFL could be instantiated on different physical cards.
+Conversely, different DFLs could be instantiated on the same physical card.
+Practical management of a cloud containing a heterogeneous set of such cards
+requires a PCI level of card identification. While the PCI Product ID and
+Vendor ID may be sufficient to bind the dfl-pci driver, it is expected
+that FPGA PCI cards would advertise suitable Subsystem ID and Subsystem
+Vendor ID values. Further PCI Product, Vendor, and Subsystem id tracking
+can be found at https://github.com/OPAE/dfl-feature-id/blob/main/dfl-pci-ids.rst.
+
+
 Location of DFLs on a PCI Device
 ================================
 The original method for finding a DFL on a PCI device assumed the start of the