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