On 10/10/19 3:35 PM, Kees Cook wrote: > On Wed, Oct 02, 2019 at 10:03:55AM -0700, Kees Cook wrote: >> From: Derek Kiernan <derek.kier...@xilinx.com> >> >> Add SD-FEC driver documentation. >> >> Signed-off-by: Derek Kiernan <derek.kier...@xilinx.com> >> Signed-off-by: Dragan Cvetic <dragan.cve...@xilinx.com> >> Link: >> https://lore.kernel.org/r/1560274185-264438-11-git-send-email-dragan.cve...@xilinx.com >> [kees: extracted from v7 as it was missing in the commit for v8] >> Signed-off-by: Kees Cook <keesc...@chromium.org> >> --- >> As mentioned[1], this file went missing and causes a warning in ReST >> parsing, so I've extracted the patch and am sending it directly to Jon. >> [1] https://lore.kernel.org/lkml/201909231450.4C6CF32@keescook/ >> --- > > friendly ping! :) > > -Kees > >> Documentation/misc-devices/xilinx_sdfec.rst | 291 ++++++++++++++++++++ >> 1 file changed, 291 insertions(+) >> create mode 100644 Documentation/misc-devices/xilinx_sdfec.rst >> >> diff --git a/Documentation/misc-devices/xilinx_sdfec.rst >> b/Documentation/misc-devices/xilinx_sdfec.rst >> new file mode 100644 >> index 000000000000..87966e3aa5fe >> --- /dev/null >> +++ b/Documentation/misc-devices/xilinx_sdfec.rst >> @@ -0,0 +1,291 @@ >> +.. SPDX-License-Identifier: GPL-2.0+ >> +==================== >> +Xilinx SD-FEC Driver >> +==================== >> + >> +Overview >> +======== >> + >> +This driver supports SD-FEC Integrated Block for Zynq |Ultrascale+ (TM)| >> RFSoCs. >> + >> +.. |Ultrascale+ (TM)| unicode:: Ultrascale+ U+2122 >> + .. with trademark sign >> + >> +For a full description of SD-FEC core features, see the `SD-FEC Product >> Guide (PG256) >> <https://www.xilinx.com/cgi-bin/docs/ipdoc?c=sd_fec;v=latest;d=pg256-sdfec-integrated-block.pdf>`_ >> + >> +This driver supports the following features: >> + >> + - Retrieval of the Integrated Block configuration and status information >> + - Configuration of LDPC codes >> + - Configuration of Turbo decoding >> + - Monitoring errors >> + >> +Missing features, known issues, and limitations of the SD-FEC driver are as >> +follows: >> + >> + - Only allows a single open file handler to any instance of the driver at >> any time >> + - Reset of the SD-FEC Integrated Block is not controlled by this driver >> + - Does not support shared LDPC code table wraparound >> + >> +The device tree entry is described in: >> +`linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt >> <https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/misc/xlnx%2Csd-fec.txt>`_ >> + >> + >> +Modes of Operation >> +------------------ >> + >> +The driver works with the SD-FEC core in two modes of operation: >> + >> + - Run-time configuration >> + - Programmable Logic (PL) initialization >> + >> + >> +Run-time Configuration >> +~~~~~~~~~~~~~~~~~~~~~~ >> + >> +For Run-time configuration the role of driver is to allow the software >> application to do the following: >> + >> + - Load the configuration parameters for either Turbo decode or LDPC >> encode or decode >> + - Activate the SD-FEC core >> + - Monitor the SD-FEC core for errors >> + - Retrieve the status and configuration of the SD-FEC core >> + >> +Programmable Logic (PL) Initialization >> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >> + >> +For PL initialization, supporting logic loads configuration parameters for >> either >> +the Turbo decode or LDPC encode or decode. The role of the driver is to >> allow >> +the software application to do the following: >> + >> + - Activate the SD-FEC core >> + - Monitor the SD-FEC core for errors >> + - Retrieve the status and configuration of the SD-FEC core >> + >> + >> +Driver Structure >> +================ >> + >> +The driver provides a platform device where the ``probe`` and ``remove`` >> +operations are provided. >> + >> + - probe: Updates configuration register with device-tree entries plus >> determines the current activate state of the core, for example, is the core >> bypassed or has the core been started. >> + >> + >> +The driver defines the following driver file operations to provide user >> +application interfaces: >> + >> + - open: Implements restriction that only a single file descriptor can be >> open per SD-FEC instance at any time >> + - release: Allows another file descriptor to be open, that is after >> current file descriptor is closed >> + - poll: Provides a method to monitor for SD-FEC Error events >> + - unlocked_ioctl: Provides the the following ioctl commands that allows >> the application configure the SD-FEC core: >> + >> + - :c:macro:`XSDFEC_START_DEV` >> + - :c:macro:`XSDFEC_STOP_DEV` >> + - :c:macro:`XSDFEC_GET_STATUS` >> + - :c:macro:`XSDFEC_SET_IRQ` >> + - :c:macro:`XSDFEC_SET_TURBO` >> + - :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS` >> + - :c:macro:`XSDFEC_GET_CONFIG` >> + - :c:macro:`XSDFEC_SET_ORDER` >> + - :c:macro:`XSDFEC_SET_BYPASS` >> + - :c:macro:`XSDFEC_IS_ACTIVE` >> + - :c:macro:`XSDFEC_CLEAR_STATS` >> + - :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` >> + >> + >> +Driver Usage >> +============ >> + >> + >> +Overview >> +-------- >> + >> +After opening the driver, the user should find out what operations need to >> be >> +performed to configure and activate the SD-FEC core and determine the >> +configuration of the driver. >> +The following outlines the flow the user should perform: >> + >> + - Determine Configuration >> + - Set the order, if not already configured as desired >> + - Set Turbo decode, LPDC encode or decode parameters, depending on how the >> + SD-FEC core is configured plus if the SD-FEC has not been configured >> for PL >> + initialization >> + - Enable interrupts, if not already enabled >> + - Bypass the SD-FEC core, if required >> + - Start the SD-FEC core if not already started >> + - Get the SD-FEC core status >> + - Monitor for interrupts >> + - Stop the SD-FEC core >> + >> + >> +Note: When monitoring for interrupts if a critical error is detected where >> a reset is required, the driver will be required to load the default >> configuration. >> + >> + >> +Determine Configuration >> +----------------------- >> + >> +Determine the configuration of the SD-FEC core by using the ioctl >> +:c:macro:`XSDFEC_GET_CONFIG`. >> + >> +Set the Order >> +------------- >> + >> +Setting the order determines how the order of Blocks can change from input >> to output. >> + >> +Setting the order is done by using the ioctl :c:macro:`XSDFEC_SET_ORDER` >> + >> +Setting the order can only be done if the following restrictions are met: >> + >> + - The ``state`` member of struct :c:type:`xsdfec_status >> <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates >> the SD-FEC core has not STARTED >> + >> + >> +Add LDPC Codes >> +-------------- >> + >> +The following steps indicate how to add LDPC codes to the SD-FEC core: >> + >> + - Use the auto-generated parameters to fill the :c:type:`struct >> xsdfec_ldpc_params <xsdfec_ldpc_params>` for the desired LDPC code. >> + - Set the SC, QA, and LA table offsets for the LPDC parameters and the >> parameters in the structure :c:type:`struct xsdfec_ldpc_params >> <xsdfec_ldpc_params>` >> + - Set the desired Code Id value in the structure :c:type:`struct >> xsdfec_ldpc_params <xsdfec_ldpc_params>` >> + - Add the LPDC Code Parameters using the ioctl >> :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS` >> + - For the applied LPDC Code Parameter use the function >> :c:func:`xsdfec_calculate_shared_ldpc_table_entry_size` to calculate the >> size of shared LPDC code tables. This allows the user to determine the >> shared table usage so when selecting the table offsets for the next LDPC >> code parameters unused table areas can be selected. >> + - Repeat for each LDPC code parameter. >> + >> +Adding LDPC codes can only be done if the following restrictions are met: >> + >> + - The ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` >> filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core >> is configured as LDPC >> + - The ``code_wr_protect`` of :c:type:`struct xsdfec_config >> <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates >> that write protection is not enabled >> + - The ``state`` member of struct :c:type:`xsdfec_status >> <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates >> the SD-FEC core has not started >> + >> +Set Turbo Decode >> +---------------- >> + >> +Configuring the Turbo decode parameters is done by using the ioctl >> :c:macro:`XSDFEC_SET_TURBO` using auto-generated parameters to fill the >> :c:type:`struct xsdfec_turbo <xsdfec_turbo>` for the desired Turbo code. >> + >> +Adding Turbo decode can only be done if the following restrictions are met: >> + >> + - The ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` >> filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core >> is configured as TURBO >> + - The ``state`` member of struct :c:type:`xsdfec_status >> <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates >> the SD-FEC core has not STARTED >> + >> +Enable Interrupts >> +----------------- >> + >> +Enabling or disabling interrupts is done by using the ioctl >> :c:macro:`XSDFEC_SET_IRQ`. The members of the parameter passed, >> :c:type:`struct xsdfec_irq <xsdfec_irq>`, to the ioctl are used to set and >> clear different categories of interrupts. The category of interrupt is >> controlled as following: >> + >> + - ``enable_isr`` controls the ``tlast`` interrupts >> + - ``enable_ecc_isr`` controls the ECC interrupts >> + >> +If the ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` >> filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core >> is configured as TURBO then the enabling ECC errors is not required. >> + >> +Bypass the SD-FEC >> +----------------- >> + >> +Bypassing the SD-FEC is done by using the ioctl :c:macro:`XSDFEC_SET_BYPASS` >> + >> +Bypassing the SD-FEC can only be done if the following restrictions are met: >> + >> + - The ``state`` member of :c:type:`struct xsdfec_status >> <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates >> the SD-FEC core has not STARTED >> + >> +Start the SD-FEC core >> +--------------------- >> + >> +Start the SD-FEC core by using the ioctl :c:macro:`XSDFEC_START_DEV` >> + >> +Get SD-FEC Status >> +----------------- >> + >> +Get the SD-FEC status of the device by using the ioctl >> :c:macro:`XSDFEC_GET_STATUS`, which will fill the :c:type:`struct >> xsdfec_status <xsdfec_status>` >> + >> +Monitor for Interrupts >> +---------------------- >> + >> + - Use the poll system call to monitor for an interrupt. The poll system >> call waits for an interrupt to wake it up or times out if no interrupt >> occurs. >> + - On return Poll ``revents`` will indicate whether stats and/or state >> have been updated >> + - ``POLLPRI`` indicates a critical error and the user should >> use :c:macro:`XSDFEC_GET_STATUS` and :c:macro:`XSDFEC_GET_STATS` to confirm >> + - ``POLLRDNORM`` indicates a non-critical error has occurred >> and the user should use :c:macro:`XSDFEC_GET_STATS` to confirm >> + - Get stats by using the ioctl :c:macro:`XSDFEC_GET_STATS` >> + - For critical error the ``isr_err_count`` or ``uecc_count`` >> member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero >> + - For non-critical errors the ``cecc_count`` member of >> :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero >> + - Get state by using the ioctl :c:macro:`XSDFEC_GET_STATUS` >> + - For a critical error the ``state`` of :c:type:`xsdfec_status >> <xsdfec_status>` will indicate a Reset Is Required >> + - Clear stats by using the ioctl :c:macro:`XSDFEC_CLEAR_STATS` >> + >> +If a critical error is detected where a reset is required. The application >> is required to call the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG`, after >> the reset and it is not required to call the ioctl :c:macro:`XSDFEC_STOP_DEV` >> + >> +Note: Using poll system call prevents busy looping using >> :c:macro:`XSDFEC_GET_STATS` and :c:macro:`XSDFEC_GET_STATUS` >> + >> +Stop the SD-FEC Core >> +--------------------- >> + >> +Stop the device by using the ioctl :c:macro:`XSDFEC_STOP_DEV` >> + >> +Set the Default Configuration >> +----------------------------- >> + >> +Load default configuration by using the ioctl >> :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` to restore the driver. >> + >> +Limitations >> +----------- >> + >> +Users should not duplicate SD-FEC device file handlers, for example fork() >> or dup() a process that has a created an SD-FEC file handler. >> + >> +Driver IOCTLs >> +============== >> + >> +.. c:macro:: XSDFEC_START_DEV >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_START_DEV >> + >> +.. c:macro:: XSDFEC_STOP_DEV >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_STOP_DEV >> + >> +.. c:macro:: XSDFEC_GET_STATUS >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_GET_STATUS >> + >> +.. c:macro:: XSDFEC_SET_IRQ >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_SET_IRQ >> + >> +.. c:macro:: XSDFEC_SET_TURBO >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_SET_TURBO >> + >> +.. c:macro:: XSDFEC_ADD_LDPC_CODE_PARAMS >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_ADD_LDPC_CODE_PARAMS >> + >> +.. c:macro:: XSDFEC_GET_CONFIG >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_GET_CONFIG >> + >> +.. c:macro:: XSDFEC_SET_ORDER >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_SET_ORDER >> + >> +.. c:macro:: XSDFEC_SET_BYPASS >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_SET_BYPASS >> + >> +.. c:macro:: XSDFEC_IS_ACTIVE >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_IS_ACTIVE >> + >> +.. c:macro:: XSDFEC_CLEAR_STATS >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_CLEAR_STATS >> + >> +.. c:macro:: XSDFEC_GET_STATS >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_GET_STATS >> + >> +.. c:macro:: XSDFEC_SET_DEFAULT_CONFIG >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :doc: XSDFEC_SET_DEFAULT_CONFIG >> + >> +Driver Type Definitions >> +======================= >> + >> +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h >> + :internal: >> \ No newline at end of file >> --
eh? ^^^^^ anyway, Tested-by: Randy Dunlap <rdun...@infradead.org> -- ~Randy
