Re: [PATCH 12/14] documentation: fpga: move fpga-region.txt to driver-api
On Fri, May 25, 2018 at 9:33 PM, Randy Dunlap wrote: Hi Randy, Thanks for the reviews. These are up on char-misc-next already, so I'll send a patch to fix. Alan > On 05/16/2018 04:50 PM, Alan Tull wrote: >> Move Documentation/fpga/fpga-region.txt to >> driver-api/fpga/fpga-region.rst. Including: >> - Add it to driver-api/fpga/index.rst >> - Formatting changes to build cleanly as ReST documentation >> - Some rewrites for better flow as a ReST doc such as moving >>API reference to the end of the doc >> - Rewrite API reference section to refer to kernel-doc >>documentation in fpga-region.c driver code >> >> Signed-off-by: Alan Tull >> --- >> Documentation/driver-api/fpga/fpga-region.rst | 102 >> ++ >> Documentation/driver-api/fpga/index.rst | 1 + >> Documentation/fpga/fpga-region.txt| 94 >> 3 files changed, 103 insertions(+), 94 deletions(-) >> create mode 100644 Documentation/driver-api/fpga/fpga-region.rst >> delete mode 100644 Documentation/fpga/fpga-region.txt >> >> diff --git a/Documentation/driver-api/fpga/fpga-region.rst >> b/Documentation/driver-api/fpga/fpga-region.rst >> new file mode 100644 >> index 000..f89e4a3 >> --- /dev/null >> +++ b/Documentation/driver-api/fpga/fpga-region.rst >> @@ -0,0 +1,102 @@ >> +FPGA Region >> +=== >> + >> +Overview >> + >> + >> +This document is meant to be an brief overview of the FPGA region API >> usage. A > > a brief overview > >> +more conceptual look at regions can be found in the Device Tree binding >> +document [#f1]_. >> + >> +For the purposes of this API document, let's just say that a region >> associates >> +an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an >> +FPGA or the whole FPGA. The API provides a way to register a region and to >> +program a region. >> + >> +Currently the only layer above fpga-region.c in the kernel is the Device >> Tree >> +support (of-fpga-region.c) described in [#f1]_. The DT support layer uses >> regions >> +to program the FPGA and then DT to handle enumeration. The common region >> code >> +is intended to be used by other schemes that have other ways of >> accomplishing >> +enumeration after programming. >> + >> +An fpga-region can be set up to know the following things: >> + >> + * which FPGA manager to use to do the programming >> + >> + * which bridges to disable before programming and enable afterwards. >> + >> +Additional info needed to program the FPGA image is passed in the struct >> +fpga_image_info including: >> + >> + * pointers to the image as either a scatter-gather buffer, a contiguous >> + buffer, or the name of firmware file >> + >> + * flags indicating specifics such as whether the image if for partial > >is for > >> + reconfiguration. >> + >> +How to program a FPGA using a region > > an FPGA > >> + >> + >> +First, allocate the info struct:: >> + >> + info = fpga_image_info_alloc(dev); >> + if (!info) >> + return -ENOMEM; >> + >> +Set flags as needed, i.e.:: >> + >> + info->flags |= FPGA_MGR_PARTIAL_RECONFIG; >> + >> +Point to your FPGA image, such as:: >> + >> + info->sgt = &sgt; >> + >> +Add info to region and do the programming:: >> + >> + region->info = info; >> + ret = fpga_region_program_fpga(region); >> + >> +:c:func:`fpga_region_program_fpga()` operates on info passed in the >> +fpga_image_info (region->info). This function will attempt to: >> + >> + * lock the region's mutex >> + * lock the region's FPGA manager >> + * build a list of FPGA bridges if a method has been specified to do so >> + * disable the bridges >> + * program the FPGA >> + * re-enable the bridges >> + * release the locks >> + >> +Then you will want to enumerate whatever hardware has appeared in the FPGA. >> + >> +How to add a new FPGA region >> + >> + >> +An example of usage can be seen in the probe function of [#f2]_. >> + >> +.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt >> +.. [#f2] ../../drivers/fpga/of-fpga-region.c >> + >> +API to program a FGPA >> +- >> + >> +.. kernel-doc:: drivers/fpga/fpga-region.c >> + :functions: fpga_region_program_fpga >> + >> +API to add a new FPGA region >> + >> + >> +.. kernel-doc:: include/linux/fpga/fpga-region.h >> + :functions: fpga_region >> + >> +.. kernel-doc:: drivers/fpga/fpga-region.c >> + :functions: fpga_region_create >> + >> +.. kernel-doc:: drivers/fpga/fpga-region.c >> + :functions: fpga_region_free >> + >> +.. kernel-doc:: drivers/fpga/fpga-region.c >> + :functions: fpga_region_register >> + >> +.. kernel-doc:: drivers/fpga/fpga-region.c >> + :functions: fpga_region_unregister > > > -- > ~Randy
Re: [PATCH 12/14] documentation: fpga: move fpga-region.txt to driver-api
On 05/16/2018 04:50 PM, Alan Tull wrote: > Move Documentation/fpga/fpga-region.txt to > driver-api/fpga/fpga-region.rst. Including: > - Add it to driver-api/fpga/index.rst > - Formatting changes to build cleanly as ReST documentation > - Some rewrites for better flow as a ReST doc such as moving >API reference to the end of the doc > - Rewrite API reference section to refer to kernel-doc >documentation in fpga-region.c driver code > > Signed-off-by: Alan Tull > --- > Documentation/driver-api/fpga/fpga-region.rst | 102 > ++ > Documentation/driver-api/fpga/index.rst | 1 + > Documentation/fpga/fpga-region.txt| 94 > 3 files changed, 103 insertions(+), 94 deletions(-) > create mode 100644 Documentation/driver-api/fpga/fpga-region.rst > delete mode 100644 Documentation/fpga/fpga-region.txt > > diff --git a/Documentation/driver-api/fpga/fpga-region.rst > b/Documentation/driver-api/fpga/fpga-region.rst > new file mode 100644 > index 000..f89e4a3 > --- /dev/null > +++ b/Documentation/driver-api/fpga/fpga-region.rst > @@ -0,0 +1,102 @@ > +FPGA Region > +=== > + > +Overview > + > + > +This document is meant to be an brief overview of the FPGA region API usage. > A a brief overview > +more conceptual look at regions can be found in the Device Tree binding > +document [#f1]_. > + > +For the purposes of this API document, let's just say that a region > associates > +an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an > +FPGA or the whole FPGA. The API provides a way to register a region and to > +program a region. > + > +Currently the only layer above fpga-region.c in the kernel is the Device Tree > +support (of-fpga-region.c) described in [#f1]_. The DT support layer uses > regions > +to program the FPGA and then DT to handle enumeration. The common region > code > +is intended to be used by other schemes that have other ways of accomplishing > +enumeration after programming. > + > +An fpga-region can be set up to know the following things: > + > + * which FPGA manager to use to do the programming > + > + * which bridges to disable before programming and enable afterwards. > + > +Additional info needed to program the FPGA image is passed in the struct > +fpga_image_info including: > + > + * pointers to the image as either a scatter-gather buffer, a contiguous > + buffer, or the name of firmware file > + > + * flags indicating specifics such as whether the image if for partial is for > + reconfiguration. > + > +How to program a FPGA using a region an FPGA > + > + > +First, allocate the info struct:: > + > + info = fpga_image_info_alloc(dev); > + if (!info) > + return -ENOMEM; > + > +Set flags as needed, i.e.:: > + > + info->flags |= FPGA_MGR_PARTIAL_RECONFIG; > + > +Point to your FPGA image, such as:: > + > + info->sgt = &sgt; > + > +Add info to region and do the programming:: > + > + region->info = info; > + ret = fpga_region_program_fpga(region); > + > +:c:func:`fpga_region_program_fpga()` operates on info passed in the > +fpga_image_info (region->info). This function will attempt to: > + > + * lock the region's mutex > + * lock the region's FPGA manager > + * build a list of FPGA bridges if a method has been specified to do so > + * disable the bridges > + * program the FPGA > + * re-enable the bridges > + * release the locks > + > +Then you will want to enumerate whatever hardware has appeared in the FPGA. > + > +How to add a new FPGA region > + > + > +An example of usage can be seen in the probe function of [#f2]_. > + > +.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt > +.. [#f2] ../../drivers/fpga/of-fpga-region.c > + > +API to program a FGPA > +- > + > +.. kernel-doc:: drivers/fpga/fpga-region.c > + :functions: fpga_region_program_fpga > + > +API to add a new FPGA region > + > + > +.. kernel-doc:: include/linux/fpga/fpga-region.h > + :functions: fpga_region > + > +.. kernel-doc:: drivers/fpga/fpga-region.c > + :functions: fpga_region_create > + > +.. kernel-doc:: drivers/fpga/fpga-region.c > + :functions: fpga_region_free > + > +.. kernel-doc:: drivers/fpga/fpga-region.c > + :functions: fpga_region_register > + > +.. kernel-doc:: drivers/fpga/fpga-region.c > + :functions: fpga_region_unregister -- ~Randy
[PATCH 12/14] documentation: fpga: move fpga-region.txt to driver-api
Move Documentation/fpga/fpga-region.txt to driver-api/fpga/fpga-region.rst. Including: - Add it to driver-api/fpga/index.rst - Formatting changes to build cleanly as ReST documentation - Some rewrites for better flow as a ReST doc such as moving API reference to the end of the doc - Rewrite API reference section to refer to kernel-doc documentation in fpga-region.c driver code Signed-off-by: Alan Tull --- Documentation/driver-api/fpga/fpga-region.rst | 102 ++ Documentation/driver-api/fpga/index.rst | 1 + Documentation/fpga/fpga-region.txt| 94 3 files changed, 103 insertions(+), 94 deletions(-) create mode 100644 Documentation/driver-api/fpga/fpga-region.rst delete mode 100644 Documentation/fpga/fpga-region.txt diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst new file mode 100644 index 000..f89e4a3 --- /dev/null +++ b/Documentation/driver-api/fpga/fpga-region.rst @@ -0,0 +1,102 @@ +FPGA Region +=== + +Overview + + +This document is meant to be an brief overview of the FPGA region API usage. A +more conceptual look at regions can be found in the Device Tree binding +document [#f1]_. + +For the purposes of this API document, let's just say that a region associates +an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an +FPGA or the whole FPGA. The API provides a way to register a region and to +program a region. + +Currently the only layer above fpga-region.c in the kernel is the Device Tree +support (of-fpga-region.c) described in [#f1]_. The DT support layer uses regions +to program the FPGA and then DT to handle enumeration. The common region code +is intended to be used by other schemes that have other ways of accomplishing +enumeration after programming. + +An fpga-region can be set up to know the following things: + + * which FPGA manager to use to do the programming + + * which bridges to disable before programming and enable afterwards. + +Additional info needed to program the FPGA image is passed in the struct +fpga_image_info including: + + * pointers to the image as either a scatter-gather buffer, a contiguous + buffer, or the name of firmware file + + * flags indicating specifics such as whether the image if for partial + reconfiguration. + +How to program a FPGA using a region + + +First, allocate the info struct:: + + info = fpga_image_info_alloc(dev); + if (!info) + return -ENOMEM; + +Set flags as needed, i.e.:: + + info->flags |= FPGA_MGR_PARTIAL_RECONFIG; + +Point to your FPGA image, such as:: + + info->sgt = &sgt; + +Add info to region and do the programming:: + + region->info = info; + ret = fpga_region_program_fpga(region); + +:c:func:`fpga_region_program_fpga()` operates on info passed in the +fpga_image_info (region->info). This function will attempt to: + + * lock the region's mutex + * lock the region's FPGA manager + * build a list of FPGA bridges if a method has been specified to do so + * disable the bridges + * program the FPGA + * re-enable the bridges + * release the locks + +Then you will want to enumerate whatever hardware has appeared in the FPGA. + +How to add a new FPGA region + + +An example of usage can be seen in the probe function of [#f2]_. + +.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt +.. [#f2] ../../drivers/fpga/of-fpga-region.c + +API to program a FGPA +- + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_program_fpga + +API to add a new FPGA region + + +.. kernel-doc:: include/linux/fpga/fpga-region.h + :functions: fpga_region + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_create + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_free + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_register + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_unregister diff --git a/Documentation/driver-api/fpga/index.rst b/Documentation/driver-api/fpga/index.rst index 968bbbf..c51e5eb 100644 --- a/Documentation/driver-api/fpga/index.rst +++ b/Documentation/driver-api/fpga/index.rst @@ -10,3 +10,4 @@ FPGA Subsystem intro fpga-mgr fpga-bridge + fpga-region diff --git a/Documentation/fpga/fpga-region.txt b/Documentation/fpga/fpga-region.txt deleted file mode 100644 index d38fa3b..000 --- a/Documentation/fpga/fpga-region.txt +++ /dev/null @@ -1,94 +0,0 @@ -FPGA Regions - -Alan Tull 2017 - -CONTENTS - - Introduction - - The FPGA region API - - Usage example - -Introduction - - -This document is meant to be an brief overview of the FPGA region API usage. A -more conceptual look at regions can be found in [1]. - -For the purposes of this API document, let's just say that