1.. SPDX-License-Identifier: GPL-2.0+ 2 3==================== 4Xilinx SD-FEC Driver 5==================== 6 7Overview 8======== 9 10This driver supports SD-FEC Integrated Block for Zynq |Ultrascale+ (TM)| RFSoCs. 11 12.. |Ultrascale+ (TM)| unicode:: Ultrascale+ U+2122 13 .. with trademark sign 14 15For 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>`_ 16 17This driver supports the following features: 18 19 - Retrieval of the Integrated Block configuration and status information 20 - Configuration of LDPC codes 21 - Configuration of Turbo decoding 22 - Monitoring errors 23 24Missing features, known issues, and limitations of the SD-FEC driver are as 25follows: 26 27 - Only allows a single open file handler to any instance of the driver at any time 28 - Reset of the SD-FEC Integrated Block is not controlled by this driver 29 - Does not support shared LDPC code table wraparound 30 31The device tree entry is described in: 32`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>`_ 33 34 35Modes of Operation 36------------------ 37 38The driver works with the SD-FEC core in two modes of operation: 39 40 - Run-time configuration 41 - Programmable Logic (PL) initialization 42 43 44Run-time Configuration 45~~~~~~~~~~~~~~~~~~~~~~ 46 47For Run-time configuration the role of driver is to allow the software application to do the following: 48 49 - Load the configuration parameters for either Turbo decode or LDPC encode or decode 50 - Activate the SD-FEC core 51 - Monitor the SD-FEC core for errors 52 - Retrieve the status and configuration of the SD-FEC core 53 54Programmable Logic (PL) Initialization 55~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 56 57For PL initialization, supporting logic loads configuration parameters for either 58the Turbo decode or LDPC encode or decode. The role of the driver is to allow 59the software application to do the following: 60 61 - Activate the SD-FEC core 62 - Monitor the SD-FEC core for errors 63 - Retrieve the status and configuration of the SD-FEC core 64 65 66Driver Structure 67================ 68 69The driver provides a platform device where the ``probe`` and ``remove`` 70operations are provided. 71 72 - 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. 73 74 75The driver defines the following driver file operations to provide user 76application interfaces: 77 78 - open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time 79 - release: Allows another file descriptor to be open, that is after current file descriptor is closed 80 - poll: Provides a method to monitor for SD-FEC Error events 81 - unlocked_ioctl: Provides the following ioctl commands that allows the application configure the SD-FEC core: 82 83 - :c:macro:`XSDFEC_START_DEV` 84 - :c:macro:`XSDFEC_STOP_DEV` 85 - :c:macro:`XSDFEC_GET_STATUS` 86 - :c:macro:`XSDFEC_SET_IRQ` 87 - :c:macro:`XSDFEC_SET_TURBO` 88 - :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS` 89 - :c:macro:`XSDFEC_GET_CONFIG` 90 - :c:macro:`XSDFEC_SET_ORDER` 91 - :c:macro:`XSDFEC_SET_BYPASS` 92 - :c:macro:`XSDFEC_IS_ACTIVE` 93 - :c:macro:`XSDFEC_CLEAR_STATS` 94 - :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` 95 96 97Driver Usage 98============ 99 100 101Overview 102-------- 103 104After opening the driver, the user should find out what operations need to be 105performed to configure and activate the SD-FEC core and determine the 106configuration of the driver. 107The following outlines the flow the user should perform: 108 109 - Determine Configuration 110 - Set the order, if not already configured as desired 111 - Set Turbo decode, LPDC encode or decode parameters, depending on how the 112 SD-FEC core is configured plus if the SD-FEC has not been configured for PL 113 initialization 114 - Enable interrupts, if not already enabled 115 - Bypass the SD-FEC core, if required 116 - Start the SD-FEC core if not already started 117 - Get the SD-FEC core status 118 - Monitor for interrupts 119 - Stop the SD-FEC core 120 121 122Note: 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. 123 124 125Determine Configuration 126----------------------- 127 128Determine the configuration of the SD-FEC core by using the ioctl 129:c:macro:`XSDFEC_GET_CONFIG`. 130 131Set the Order 132------------- 133 134Setting the order determines how the order of Blocks can change from input to output. 135 136Setting the order is done by using the ioctl :c:macro:`XSDFEC_SET_ORDER` 137 138Setting the order can only be done if the following restrictions are met: 139 140 - 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 141 142 143Add LDPC Codes 144-------------- 145 146The following steps indicate how to add LDPC codes to the SD-FEC core: 147 148 - Use the auto-generated parameters to fill the :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>` for the desired LDPC code. 149 - 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>` 150 - Set the desired Code Id value in the structure :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>` 151 - Add the LPDC Code Parameters using the ioctl :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS` 152 - 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. 153 - Repeat for each LDPC code parameter. 154 155Adding LDPC codes can only be done if the following restrictions are met: 156 157 - 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 158 - 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 159 - 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 160 161Set Turbo Decode 162---------------- 163 164Configuring 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. 165 166Adding Turbo decode can only be done if the following restrictions are met: 167 168 - 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 169 - 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 170 171Enable Interrupts 172----------------- 173 174Enabling 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: 175 176 - ``enable_isr`` controls the ``tlast`` interrupts 177 - ``enable_ecc_isr`` controls the ECC interrupts 178 179If 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. 180 181Bypass the SD-FEC 182----------------- 183 184Bypassing the SD-FEC is done by using the ioctl :c:macro:`XSDFEC_SET_BYPASS` 185 186Bypassing the SD-FEC can only be done if the following restrictions are met: 187 188 - 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 189 190Start the SD-FEC core 191--------------------- 192 193Start the SD-FEC core by using the ioctl :c:macro:`XSDFEC_START_DEV` 194 195Get SD-FEC Status 196----------------- 197 198Get 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>` 199 200Monitor for Interrupts 201---------------------- 202 203 - 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. 204 - On return Poll ``revents`` will indicate whether stats and/or state have been updated 205 - ``POLLPRI`` indicates a critical error and the user should use :c:macro:`XSDFEC_GET_STATUS` and :c:macro:`XSDFEC_GET_STATS` to confirm 206 - ``POLLRDNORM`` indicates a non-critical error has occurred and the user should use :c:macro:`XSDFEC_GET_STATS` to confirm 207 - Get stats by using the ioctl :c:macro:`XSDFEC_GET_STATS` 208 - For critical error the ``isr_err_count`` or ``uecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero 209 - For non-critical errors the ``cecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero 210 - Get state by using the ioctl :c:macro:`XSDFEC_GET_STATUS` 211 - For a critical error the ``state`` of :c:type:`xsdfec_status <xsdfec_status>` will indicate a Reset Is Required 212 - Clear stats by using the ioctl :c:macro:`XSDFEC_CLEAR_STATS` 213 214If 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` 215 216Note: Using poll system call prevents busy looping using :c:macro:`XSDFEC_GET_STATS` and :c:macro:`XSDFEC_GET_STATUS` 217 218Stop the SD-FEC Core 219--------------------- 220 221Stop the device by using the ioctl :c:macro:`XSDFEC_STOP_DEV` 222 223Set the Default Configuration 224----------------------------- 225 226Load default configuration by using the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` to restore the driver. 227 228Limitations 229----------- 230 231Users should not duplicate SD-FEC device file handlers, for example fork() or dup() a process that has a created an SD-FEC file handler. 232 233Driver IOCTLs 234============== 235 236.. c:macro:: XSDFEC_START_DEV 237.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 238 :doc: XSDFEC_START_DEV 239 240.. c:macro:: XSDFEC_STOP_DEV 241.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 242 :doc: XSDFEC_STOP_DEV 243 244.. c:macro:: XSDFEC_GET_STATUS 245.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 246 :doc: XSDFEC_GET_STATUS 247 248.. c:macro:: XSDFEC_SET_IRQ 249.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 250 :doc: XSDFEC_SET_IRQ 251 252.. c:macro:: XSDFEC_SET_TURBO 253.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 254 :doc: XSDFEC_SET_TURBO 255 256.. c:macro:: XSDFEC_ADD_LDPC_CODE_PARAMS 257.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 258 :doc: XSDFEC_ADD_LDPC_CODE_PARAMS 259 260.. c:macro:: XSDFEC_GET_CONFIG 261.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 262 :doc: XSDFEC_GET_CONFIG 263 264.. c:macro:: XSDFEC_SET_ORDER 265.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 266 :doc: XSDFEC_SET_ORDER 267 268.. c:macro:: XSDFEC_SET_BYPASS 269.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 270 :doc: XSDFEC_SET_BYPASS 271 272.. c:macro:: XSDFEC_IS_ACTIVE 273.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 274 :doc: XSDFEC_IS_ACTIVE 275 276.. c:macro:: XSDFEC_CLEAR_STATS 277.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 278 :doc: XSDFEC_CLEAR_STATS 279 280.. c:macro:: XSDFEC_GET_STATS 281.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 282 :doc: XSDFEC_GET_STATS 283 284.. c:macro:: XSDFEC_SET_DEFAULT_CONFIG 285.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 286 :doc: XSDFEC_SET_DEFAULT_CONFIG 287 288Driver Type Definitions 289======================= 290 291.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h 292 :internal: 293