Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Sat, 10 Dec 2022 10:17:10 +0700
From:   Bagas Sanjaya <bagasdotme@gmail.com>
To:     matthew.gerlach@linux.intel.com, hao.wu@intel.com,
        yilun.xu@intel.com, russell.h.weight@intel.com,
        basheer.ahmed.muddebihal@intel.com, trix@redhat.com,
        mdf@kernel.org, linux-fpga@vger.kernel.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        tianfei.zhang@intel.com, corbet@lwn.net,
        gregkh@linuxfoundation.org, linux-serial@vger.kernel.org,
        jirislaby@kernel.org, geert+renesas@glider.be,
        andriy.shevchenko@linux.intel.com,
        niklas.soderlund+renesas@ragnatech.se, macro@orcam.me.uk,
        johan@kernel.org, lukas@wunner.de, ilpo.jarvinen@linux.intel.com,
        marpagan@redhat.com
Subject: Re: [PATCH v6 1/4] Documentation: fpga: dfl: Add documentation for
 DFHv1
Message-ID: <Y5P6NjDxy/S7nlF7@debian.me>
References: <20221209214523.3484193-1-matthew.gerlach@linux.intel.com>
 <20221209214523.3484193-2-matthew.gerlach@linux.intel.com>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha256;
        protocol="application/pgp-signature"; boundary="HlPKI/korhvKEuYx"
Content-Disposition: inline
In-Reply-To: <20221209214523.3484193-2-matthew.gerlach@linux.intel.com>
Precedence: bulk


--HlPKI/korhvKEuYx
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Fri, Dec 09, 2022 at 01:45:20PM -0800, matthew.gerlach@linux.intel.com w=
rote:
> diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst
> index 15b670926084..606b4b070c33 100644
> --- a/Documentation/fpga/dfl.rst
> +++ b/Documentation/fpga/dfl.rst
> @@ -561,6 +561,109 @@ new DFL feature via UIO direct access, its feature =
id should be added to the
>  driver's id_table.
> =20
> =20
> +Device Feature Header - Version 0
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +Version 0 (DFHv0) is the original version of the Device Feature Header.
> +The format of DFHv0 is shown below::
> +
> +    +-------------------------------------------------------------------=
----+
> +    |63 Type 60|59 DFH VER 52|51 Rsvd 41|40 EOL|39 Next 16|15 VER 12|11 =
ID 0| 0x00
> +    +-------------------------------------------------------------------=
----+
> +    |63                                 GUID_L                          =
   0| 0x08
> +    +-------------------------------------------------------------------=
----+
> +    |63                                 GUID_H                          =
   0| 0x10
> +    +-------------------------------------------------------------------=
----+
> +
> +- Offset 0x00
> +
> +  * Type - The type of DFH (e.g. FME, AFU, or private feature).
> +  * DFH VER - The version of the DFH.
> +  * Rsvd - Currently unused.
> +  * EOL - Set if this DFH is the end of the Device Feature List (DFL).
> +  * Next - The offset of the next DFH in the DFL from the start of the D=
FH. If EOL is set, Next is the size of MMIO ofthe last feature in the list.
> +  * ID - The ID of the feature if Type is private feature.
> +
> +- Offset 0x08
> +
> +  * GUID_L - Least significant 64 bits of a 128 bit Globally Unique Iden=
tifier (present only if Type is FME or AFU).
> +
> +- Offset 0x10
> +
> +  * GUID_H - Most significant 64 bits of a 128 bit Globally Unique Ident=
ifier (present only if Type is FME or AFU).
> +
> +
> +Device Feature Header - Version 1
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +Version 1 (DFHv1) of the Device Feature Header adds the following functi=
onality:
> +
> +* Provides a standardized mechanism for features to describe parameters/=
capabilities to software.
> +* Standardize the use of a GUID for all DFHv1 types.
> +* Decouples the location of the DFH from the register space of the featu=
re itself.
> +
> +The format of Version 1 of the Device Feature Header (DFH) is shown belo=
w::
> +
> +    +-------------------------------------------------------------------=
----+
> +    |63 Type 60|59 DFH VER 52|51 Rsvd 41|40 EOL|39 Next 16|15 VER 12|11 =
ID 0| 0x00
> +    +-------------------------------------------------------------------=
----+
> +    |63                                 GUID_L                          =
   0| 0x08
> +    +-------------------------------------------------------------------=
----+
> +    |63                                 GUID_H                          =
   0| 0x10
> +    +-------------------------------------------------------------------=
----+
> +    |63                   Reg Address/Offset                      1|  Re=
l  0| 0x18
> +    +-------------------------------------------------------------------=
----+
> +    |63        Reg Size       32|Params 31|30 Group    16|15 Instance   =
   0| 0x20
> +    +-------------------------------------------------------------------=
----+
> +    |63 Next    35|34RSV33|EOP32|31 Param Version 16|15 Param ID        =
   0| 0x28
> +    +-------------------------------------------------------------------=
----+
> +    |63                 Parameter Data                                  =
   0| 0x30
> +    +-------------------------------------------------------------------=
----+
> +
> +                                  ...
> +
> +    +-------------------------------------------------------------------=
----+
> +    |63 Next    35|34RSV33|EOP32|31 Param Version 16|15 Param ID        =
   0|
> +    +-------------------------------------------------------------------=
----+
> +    |63                 Parameter Data                                  =
   0|
> +    +-------------------------------------------------------------------=
----+
> +
> +- Offset 0x00
> +
> +  * Type - The type of DFH (e.g. FME, AFU, or private feature).
> +  * DFH VER - The version of the DFH.
> +  * Rsvd - Currently unused.
> +  * EOL - Set if this DFH is the end of the Device Feature List (DFL).
> +  * Next - The offset of the next DFH in the DFL from the start of the D=
FH.
> +  * ID - The ID of the feature if Type is private feature.
> +
> +- Offset 0x08
> +
> +  * GUID_L - Least significant 64 bits of a 128 bit Globally Unique Iden=
tifier.
> +
> +- Offset 0x10
> +
> +  * GUID_H - Most significant 64 bits of a 128 bit Globally Unique Ident=
ifier.
> +
> +- Offset 0x18
> +
> +  * Reg Address/Offset - If Rel bit is set, then the value is the high 6=
3 bits of a 16 bit aligned absolute address of the feature's registers. If =
Rel bit is clear, then the value is the offset from the start of the DFH of=
 the feature's registers.
> +
> +- Offset 0x20
> +
> +  * Reg Size - Size of feature's register set in bytes.
> +  * Params - Set if DFH has a list of parameter blocks.
> +  * Group - Id of group if feature is part of a group.
> +  * Instance - Id of instance of feature within a group.
> +
> +- Offset 0x28 if feature has parameters
> +
> +  * Next - Offset to the next parameter block in 8 byte words. If EOP se=
t, size in 8 byte words of last parameter.
> +  * Param Version - Version of Param ID.
> +  * Param ID - ID of parameter.
> +
> +- Offset 0x30
> +
> +  * Parameter Data - Parameter data whose size and format is defined by =
version and ID of the parameter.
> +
>  Open discussion
>  =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>  FME driver exports one ioctl (DFL_FPGA_FME_PORT_PR) for partial reconfig=
uration

What about this wording below (including fitting the prose within 80 column=
s)?

---- >8 ----
diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst
index 606b4b070c3321..3d8f8dde6021db 100644
--- a/Documentation/fpga/dfl.rst
+++ b/Documentation/fpga/dfl.rst
@@ -579,26 +579,30 @@ The format of DFHv0 is shown below::
   * Type - The type of DFH (e.g. FME, AFU, or private feature).
   * DFH VER - The version of the DFH.
   * Rsvd - Currently unused.
-  * EOL - Set if this DFH is the end of the Device Feature List (DFL).
-  * Next - The offset of the next DFH in the DFL from the start of the DFH=
=2E If EOL is set, Next is the size of MMIO ofthe last feature in the list.
-  * ID - The ID of the feature if Type is private feature.
+  * EOL - Set if the DFH is the end of the Device Feature List (DFL).
+  * Next - The offset of the next DFH in the DFL from the DFH start. If EO=
L is
+    set, Next is the size of MMIO of the last feature in the list.
+  * ID - The feature ID if Type is private feature.
=20
 - Offset 0x08
=20
-  * GUID_L - Least significant 64 bits of a 128 bit Globally Unique Identi=
fier (present only if Type is FME or AFU).
+  * GUID_L - Least significant 64 bits of a 128-bit Globally Unique Identi=
fier
+    (present only if Type is FME or AFU).
=20
 - Offset 0x10
=20
-  * GUID_H - Most significant 64 bits of a 128 bit Globally Unique Identif=
ier (present only if Type is FME or AFU).
+  * GUID_H - Most significant 64 bits of a 128-bit Globally Unique Identif=
ier
+    (present only if Type is FME or AFU).
=20
=20
 Device Feature Header - Version 1
 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
 Version 1 (DFHv1) of the Device Feature Header adds the following function=
ality:
=20
-* Provides a standardized mechanism for features to describe parameters/ca=
pabilities to software.
+* Provides a standardized mechanism for features to describe
+  parameters/capabilities to software.
 * Standardize the use of a GUID for all DFHv1 types.
-* Decouples the location of the DFH from the register space of the feature=
 itself.
+* Decouples the DFH location from the register space of the feature itself.
=20
 The format of Version 1 of the Device Feature Header (DFH) is shown below::
=20
@@ -631,38 +635,43 @@ The format of Version 1 of the Device Feature Header =
(DFH) is shown below::
   * Type - The type of DFH (e.g. FME, AFU, or private feature).
   * DFH VER - The version of the DFH.
   * Rsvd - Currently unused.
-  * EOL - Set if this DFH is the end of the Device Feature List (DFL).
-  * Next - The offset of the next DFH in the DFL from the start of the DFH.
-  * ID - The ID of the feature if Type is private feature.
+  * EOL - Set if the DFH is the end of the Device Feature List (DFL).
+  * Next - The offset of the next DFH in the DFL from the DFH start.
+  * ID - The feature ID if Type is private feature.
=20
 - Offset 0x08
=20
-  * GUID_L - Least significant 64 bits of a 128 bit Globally Unique Identi=
fier.
+  * GUID_L - Least significant 64 bits of a 128-bit Globally Unique Identi=
fier.
=20
 - Offset 0x10
=20
-  * GUID_H - Most significant 64 bits of a 128 bit Globally Unique Identif=
ier.
+  * GUID_H - Most significant 64 bits of a 128-bit Globally Unique Identif=
ier.
=20
 - Offset 0x18
=20
-  * Reg Address/Offset - If Rel bit is set, then the value is the high 63 =
bits of a 16 bit aligned absolute address of the feature's registers. If Re=
l bit is clear, then the value is the offset from the start of the DFH of t=
he feature's registers.
+  * Reg Address/Offset - If Rel bit is set, then the value is the high 63 =
bits
+    of a 16-bit aligned absolute address of the feature's registers. Other=
wise
+    the value is the offset from the start of the DFH of the feature's
+    registers.
=20
 - Offset 0x20
=20
   * Reg Size - Size of feature's register set in bytes.
   * Params - Set if DFH has a list of parameter blocks.
-  * Group - Id of group if feature is part of a group.
-  * Instance - Id of instance of feature within a group.
+  * Group - ID of group if feature is part of a group.
+  * Instance - ID of feature instance within a group.
=20
 - Offset 0x28 if feature has parameters
=20
-  * Next - Offset to the next parameter block in 8 byte words. If EOP set,=
 size in 8 byte words of last parameter.
+  * Next - Offset to the next parameter block in 8 byte words. If EOP set,
+    the value is size in 8 byte words of last parameter.
   * Param Version - Version of Param ID.
   * Param ID - ID of parameter.
=20
 - Offset 0x30
=20
-  * Parameter Data - Parameter data whose size and format is defined by ve=
rsion and ID of the parameter.
+  * Parameter Data - Parameter data whose size and format is defined by
+    version and ID of the parameter.
=20
 Open discussion
 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

Thanks.

--=20
An old man doll... just what I always wanted! - Clara

--HlPKI/korhvKEuYx
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iHUEABYIAB0WIQSSYQ6Cy7oyFNCHrUH2uYlJVVFOowUCY5P6LAAKCRD2uYlJVVFO
o85tAQCQ/X7C1BEESFknhpc4XhzPdvuzYCUGCrYY8DoHuUzFcwEApc18F0w7QxFL
9q1TeTSERdjvegYjcO0UIpLDCmSE2Qc=
=0Q96
-----END PGP SIGNATURE-----

--HlPKI/korhvKEuYx--