lkml.org 
[lkml]   [2019]   [Apr]   [22]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v2 14/79] docs: fpga: convert docs to ReST and rename to *.rst
    Date
    The dfl.txt file is almost there. It needs just a few
    adjustments to be properly parsed.

    The conversion is actually:
    - add blank lines and identation in order to identify paragraphs;
    - fix tables markups;
    - add some lists markups;
    - mark literal blocks;
    - adjust title markups.

    At its new index.rst, let's add a :orphan: while this is not linked to
    the main index.rst file, in order to avoid build warnings.

    Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
    ---
    Documentation/fpga/{dfl.txt => dfl.rst} | 58 ++++++++++++++-----------
    Documentation/fpga/index.rst | 17 ++++++++
    MAINTAINERS | 2 +-
    3 files changed, 50 insertions(+), 27 deletions(-)
    rename Documentation/fpga/{dfl.txt => dfl.rst} (89%)
    create mode 100644 Documentation/fpga/index.rst

    diff --git a/Documentation/fpga/dfl.txt b/Documentation/fpga/dfl.rst
    similarity index 89%
    rename from Documentation/fpga/dfl.txt
    rename to Documentation/fpga/dfl.rst
    index 6df4621c3f2a..2f125abd777f 100644
    --- a/Documentation/fpga/dfl.txt
    +++ b/Documentation/fpga/dfl.rst
    @@ -1,9 +1,12 @@
    -===============================================================================
    - FPGA Device Feature List (DFL) Framework Overview
    --------------------------------------------------------------------------------
    - Enno Luebbers <enno.luebbers@intel.com>
    - Xiao Guangrong <guangrong.xiao@linux.intel.com>
    - Wu Hao <hao.wu@intel.com>
    +=================================================
    +FPGA Device Feature List (DFL) Framework Overview
    +=================================================
    +
    +Authors:
    +
    +- Enno Luebbers <enno.luebbers@intel.com>
    +- Xiao Guangrong <guangrong.xiao@linux.intel.com>
    +- Wu Hao <hao.wu@intel.com>

    The Device Feature List (DFL) FPGA framework (and drivers according to this
    this framework) hides the very details of low layer hardwares and provides
    @@ -19,7 +22,7 @@ Device Feature List (DFL) defines a linked list of feature headers within the
    device MMIO space to provide an extensible way of adding features. Software can
    walk through these predefined data structures to enumerate FPGA features:
    FPGA Interface Unit (FIU), Accelerated Function Unit (AFU) and Private Features,
    -as illustrated below:
    +as illustrated below::

    Header Header Header Header
    +----------+ +-->+----------+ +-->+----------+ +-->+----------+
    @@ -81,9 +84,9 @@ and release it using close().

    The following functions are exposed through ioctls:

    - Get driver API version (DFL_FPGA_GET_API_VERSION)
    - Check for extensions (DFL_FPGA_CHECK_EXTENSION)
    - Program bitstream (DFL_FPGA_FME_PORT_PR)
    +- Get driver API version (DFL_FPGA_GET_API_VERSION)
    +- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
    +- Program bitstream (DFL_FPGA_FME_PORT_PR)

    More functions are exposed through sysfs
    (/sys/class/fpga_region/regionX/dfl-fme.n/):
    @@ -118,18 +121,19 @@ port by using open() on the port device node and release it using close().

    The following functions are exposed through ioctls:

    - Get driver API version (DFL_FPGA_GET_API_VERSION)
    - Check for extensions (DFL_FPGA_CHECK_EXTENSION)
    - Get port info (DFL_FPGA_PORT_GET_INFO)
    - Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
    - Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
    - Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
    - Reset AFU (*DFL_FPGA_PORT_RESET)
    +- Get driver API version (DFL_FPGA_GET_API_VERSION)
    +- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
    +- Get port info (DFL_FPGA_PORT_GET_INFO)
    +- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
    +- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
    +- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
    +- Reset AFU (DFL_FPGA_PORT_RESET)

    -*DFL_FPGA_PORT_RESET: reset the FPGA Port and its AFU. Userspace can do Port
    -reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
    -never cause any system level issue, only functional failure (e.g. DMA or PR
    -operation failure) and be recoverable from the failure.
    +DFL_FPGA_PORT_RESET:
    + reset the FPGA Port and its AFU. Userspace can do Port
    + reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
    + never cause any system level issue, only functional failure (e.g. DMA or PR
    + operation failure) and be recoverable from the failure.

    User-space applications can also mmap() accelerator MMIO regions.

    @@ -143,6 +147,8 @@ More functions are exposed through sysfs:
    DFL Framework Overview
    ======================

    +::
    +
    +----------+ +--------+ +--------+ +--------+
    | FME | | AFU | | AFU | | AFU |
    | Module | | Module | | Module | | Module |
    @@ -151,7 +157,7 @@ DFL Framework Overview
    | FPGA Container Device | Device Feature List
    | (FPGA Base Region) | Framework
    +-----------------------+
    ---------------------------------------------------------------------
    + ------------------------------------------------------------------
    +----------------------------+
    | FPGA DFL Device Module |
    | (e.g. PCIE/Platform Device)|
    @@ -220,7 +226,7 @@ the sysfs hierarchy under /sys/class/fpga_region.
    In the example below, two DFL based FPGA devices are installed in the host. Each
    fpga device has one FME and two ports (AFUs).

    -FPGA regions are created under /sys/class/fpga_region/
    +FPGA regions are created under /sys/class/fpga_region/::

    /sys/class/fpga_region/region0
    /sys/class/fpga_region/region1
    @@ -231,7 +237,7 @@ Application needs to search each regionX folder, if feature device is found,
    (e.g. "dfl-port.n" or "dfl-fme.m" is found), then it's the base
    fpga region which represents the FPGA device.

    -Each base region has one FME and two ports (AFUs) as child devices:
    +Each base region has one FME and two ports (AFUs) as child devices::

    /sys/class/fpga_region/region0/dfl-fme.0
    /sys/class/fpga_region/region0/dfl-port.0
    @@ -243,7 +249,7 @@ Each base region has one FME and two ports (AFUs) as child devices:
    /sys/class/fpga_region/region3/dfl-port.3
    ...

    -In general, the FME/AFU sysfs interfaces are named as follows:
    +In general, the FME/AFU sysfs interfaces are named as follows::

    /sys/class/fpga_region/<regionX>/<dfl-fme.n>/
    /sys/class/fpga_region/<regionX>/<dfl-port.m>/
    @@ -251,7 +257,7 @@ In general, the FME/AFU sysfs interfaces are named as follows:
    with 'n' consecutively numbering all FMEs and 'm' consecutively numbering all
    ports.

    -The device nodes used for ioctl() or mmap() can be referenced through:
    +The device nodes used for ioctl() or mmap() can be referenced through::

    /sys/class/fpga_region/<regionX>/<dfl-fme.n>/dev
    /sys/class/fpga_region/<regionX>/<dfl-port.n>/dev
    diff --git a/Documentation/fpga/index.rst b/Documentation/fpga/index.rst
    new file mode 100644
    index 000000000000..2c87d1ea084f
    --- /dev/null
    +++ b/Documentation/fpga/index.rst
    @@ -0,0 +1,17 @@
    +:orphan:
    +
    +====
    +fpga
    +====
    +
    +.. toctree::
    + :maxdepth: 1
    +
    + dfl
    +
    +.. only:: subproject and html
    +
    + Indices
    + =======
    +
    + * :ref:`genindex`
    diff --git a/MAINTAINERS b/MAINTAINERS
    index fac4490d2a00..3dd988519a11 100644
    --- a/MAINTAINERS
    +++ b/MAINTAINERS
    @@ -6186,7 +6186,7 @@ FPGA DFL DRIVERS
    M: Wu Hao <hao.wu@intel.com>
    L: linux-fpga@vger.kernel.org
    S: Maintained
    -F: Documentation/fpga/dfl.txt
    +F: Documentation/fpga/dfl.rst
    F: include/uapi/linux/fpga-dfl.h
    F: drivers/fpga/dfl*

    --
    2.20.1
    \
     
     \ /
      Last update: 2019-04-22 15:37    [W:2.036 / U:0.160 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site