| Message ID | 20221004143718.1076710-2-matthew.gerlach@linux.intel.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | Enhance definition of DFH and use enhancements for uart driver | expand |
On Tue, 4 Oct 2022, matthew.gerlach@linux.intel.com wrote: > From: Matthew Gerlach <matthew.gerlach@linux.intel.com> > > Add documentation describing the extensions provided by Version > 1 of the Device Feature Header (DFHv1). > > Signed-off-by: Matthew Gerlach <matthew.gerlach@linux.intel.com> > --- > v3: no change > > v2: s/GUILD/GUID/ > add picture > --- > Documentation/fpga/dfl.rst | 49 ++++++++++++++++++++++++++++++++++++++ > 1 file changed, 49 insertions(+) > > diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst > index 15b670926084..7c786b75b498 100644 > --- a/Documentation/fpga/dfl.rst > +++ b/Documentation/fpga/dfl.rst > @@ -561,6 +561,55 @@ new DFL feature via UIO direct access, its feature id should be added to the > driver's id_table. > > > +Extending the Device Feature Header - DFHv1 > +=========================================== > +The current 8 bytes of the Device Feature Header, hereafter referred to as > +to DFHv0, provide very little opportunity for the hardware to describe itself > +to software. Version 1 of the Device Feature Header (DFHv1) is being introduced > +to provide increased flexibility and extensibility to hardware designs using > +Device Feature Lists. The list below describes some of the goals behind the > +changes in DFHv1: > + > +* Provide a standardized mechanism for features to describe > + parameters/capabilities to software. > +* Standardize the use of a GUID for all DFHv1 types. > +* Decouple the location of the DFH from the register space of the feature itself. > + > +Modeled after PCI Capabilities, DFHv1 Parameters provide a mechanism to associate > +a list of parameter values to a particular feature. > + > +With DFHv0, not all features types contained a GUID. DFHv1 makes the GUID standard > +across all types. > + > +With DFHv0, the register map of a given feature is located immediately following > +the DFHv0 in the memory space. With DFHv1, the location of the feature register > +map can be specified as an offset to the DFHv1 or as an absolute address. The DFHv1 > +structure is shown below: I think this is not a good place for be some kind of v1 marketing speak (that said, I think it's fine to include those goals you have there). I'd restructure this so that this section only talks about DFHv1 w/o any comparing how v1 is better than v0. Don't base the description on how things changed from v0 but just describe v1, that is, like v1 is already there, not only being introduced to supercede/extend v0. And then create v0 section after this section which focuses solely on v0.
On Wed, 5 Oct 2022, Ilpo Järvinen wrote: > On Tue, 4 Oct 2022, matthew.gerlach@linux.intel.com wrote: > >> From: Matthew Gerlach <matthew.gerlach@linux.intel.com> >> >> Add documentation describing the extensions provided by Version >> 1 of the Device Feature Header (DFHv1). >> >> Signed-off-by: Matthew Gerlach <matthew.gerlach@linux.intel.com> >> --- >> v3: no change >> >> v2: s/GUILD/GUID/ >> add picture >> --- >> Documentation/fpga/dfl.rst | 49 ++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 49 insertions(+) >> >> diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst >> index 15b670926084..7c786b75b498 100644 >> --- a/Documentation/fpga/dfl.rst >> +++ b/Documentation/fpga/dfl.rst >> @@ -561,6 +561,55 @@ new DFL feature via UIO direct access, its feature id should be added to the >> driver's id_table. >> >> >> +Extending the Device Feature Header - DFHv1 >> +=========================================== >> +The current 8 bytes of the Device Feature Header, hereafter referred to as >> +to DFHv0, provide very little opportunity for the hardware to describe itself >> +to software. Version 1 of the Device Feature Header (DFHv1) is being introduced >> +to provide increased flexibility and extensibility to hardware designs using >> +Device Feature Lists. The list below describes some of the goals behind the >> +changes in DFHv1: >> + >> +* Provide a standardized mechanism for features to describe >> + parameters/capabilities to software. >> +* Standardize the use of a GUID for all DFHv1 types. >> +* Decouple the location of the DFH from the register space of the feature itself. >> + >> +Modeled after PCI Capabilities, DFHv1 Parameters provide a mechanism to associate >> +a list of parameter values to a particular feature. >> + >> +With DFHv0, not all features types contained a GUID. DFHv1 makes the GUID standard >> +across all types. >> + >> +With DFHv0, the register map of a given feature is located immediately following >> +the DFHv0 in the memory space. With DFHv1, the location of the feature register >> +map can be specified as an offset to the DFHv1 or as an absolute address. The DFHv1 >> +structure is shown below: > > I think this is not a good place for be some kind of v1 marketing speak > (that said, I think it's fine to include those goals you have there). I understand the need to avoid marketing speak here. I will update to just state the facts. > > I'd restructure this so that this section only talks about DFHv1 w/o > any comparing how v1 is better than v0. Don't base the description on > how things changed from v0 but just describe v1, that is, like v1 is > already there, not only being introduced to supercede/extend v0. > > And then create v0 section after this section which focuses solely on v0. I agree that separate sections simply describing v0 and v1 would be better. I may describe v0 first since it shares some fields with v1. > > -- > i. > >> + +-----------------------------------------------------------------------+ >> + |63 Type 60|59 DFH VER 52|51 Rsvd 41|40 EOL|39 Next 16|15 VER 12|11 ID 0| >> + +-----------------------------------------------------------------------+ >> + |63 GUID_L 0| >> + +-----------------------------------------------------------------------+ >> + |63 GUID_H 0| >> + +-----------------------------------------------------------------------+ >> + |63 Address/Offset 1| Rel 0| >> + +-----------------------------------------------------------------------+ >> + |63 Size of register set 32|Params 31|30 Group 16|15 Instance 0| >> + +-----------------------------------------------------------------------+ >> + |63 Next parameter offset 32|31 Param Version 16|15 Param ID 0| >> + +-----------------------------------------------------------------------+ >> + |63 Parameter Data 0| >> + +-----------------------------------------------------------------------+ >> + >> + ... >> + >> + +-----------------------------------------------------------------------+ >> + |63 Next parameter offset 32|31 Param Version 16|15 Param ID 0| >> + +-----------------------------------------------------------------------+ >> + |63 Parameter Data 0| >> + +-----------------------------------------------------------------------+ >> + >> Open discussion >> =============== >> FME driver exports one ioctl (DFL_FPGA_FME_PORT_PR) for partial reconfiguration >> > >
diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst index 15b670926084..7c786b75b498 100644 --- a/Documentation/fpga/dfl.rst +++ b/Documentation/fpga/dfl.rst @@ -561,6 +561,55 @@ new DFL feature via UIO direct access, its feature id should be added to the driver's id_table. +Extending the Device Feature Header - DFHv1 +=========================================== +The current 8 bytes of the Device Feature Header, hereafter referred to as +to DFHv0, provide very little opportunity for the hardware to describe itself +to software. Version 1 of the Device Feature Header (DFHv1) is being introduced +to provide increased flexibility and extensibility to hardware designs using +Device Feature Lists. The list below describes some of the goals behind the +changes in DFHv1: + +* Provide a standardized mechanism for features to describe + parameters/capabilities to software. +* Standardize the use of a GUID for all DFHv1 types. +* Decouple the location of the DFH from the register space of the feature itself. + +Modeled after PCI Capabilities, DFHv1 Parameters provide a mechanism to associate +a list of parameter values to a particular feature. + +With DFHv0, not all features types contained a GUID. DFHv1 makes the GUID standard +across all types. + +With DFHv0, the register map of a given feature is located immediately following +the DFHv0 in the memory space. With DFHv1, the location of the feature register +map can be specified as an offset to the DFHv1 or as an absolute address. The DFHv1 +structure is shown below: + + +-----------------------------------------------------------------------+ + |63 Type 60|59 DFH VER 52|51 Rsvd 41|40 EOL|39 Next 16|15 VER 12|11 ID 0| + +-----------------------------------------------------------------------+ + |63 GUID_L 0| + +-----------------------------------------------------------------------+ + |63 GUID_H 0| + +-----------------------------------------------------------------------+ + |63 Address/Offset 1| Rel 0| + +-----------------------------------------------------------------------+ + |63 Size of register set 32|Params 31|30 Group 16|15 Instance 0| + +-----------------------------------------------------------------------+ + |63 Next parameter offset 32|31 Param Version 16|15 Param ID 0| + +-----------------------------------------------------------------------+ + |63 Parameter Data 0| + +-----------------------------------------------------------------------+ + + ... + + +-----------------------------------------------------------------------+ + |63 Next parameter offset 32|31 Param Version 16|15 Param ID 0| + +-----------------------------------------------------------------------+ + |63 Parameter Data 0| + +-----------------------------------------------------------------------+ + Open discussion =============== FME driver exports one ioctl (DFL_FPGA_FME_PORT_PR) for partial reconfiguration