0001 .. SPDX-License-Identifier: GPL-2.0+
0002
0003 ====================
0004 Xilinx SD-FEC Driver
0005 ====================
0006
0007 Overview
0008 ========
0009
0010 This driver supports SD-FEC Integrated Block for Zynq |Ultrascale+ (TM)| RFSoCs.
0011
0012 .. |Ultrascale+ (TM)| unicode:: Ultrascale+ U+2122
0013 .. with trademark sign
0014
0015 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>`_
0016
0017 This driver supports the following features:
0018
0019 - Retrieval of the Integrated Block configuration and status information
0020 - Configuration of LDPC codes
0021 - Configuration of Turbo decoding
0022 - Monitoring errors
0023
0024 Missing features, known issues, and limitations of the SD-FEC driver are as
0025 follows:
0026
0027 - Only allows a single open file handler to any instance of the driver at any time
0028 - Reset of the SD-FEC Integrated Block is not controlled by this driver
0029 - Does not support shared LDPC code table wraparound
0030
0031 The device tree entry is described in:
0032 `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>`_
0033
0034
0035 Modes of Operation
0036 ------------------
0037
0038 The driver works with the SD-FEC core in two modes of operation:
0039
0040 - Run-time configuration
0041 - Programmable Logic (PL) initialization
0042
0043
0044 Run-time Configuration
0045 ~~~~~~~~~~~~~~~~~~~~~~
0046
0047 For Run-time configuration the role of driver is to allow the software application to do the following:
0048
0049 - Load the configuration parameters for either Turbo decode or LDPC encode or decode
0050 - Activate the SD-FEC core
0051 - Monitor the SD-FEC core for errors
0052 - Retrieve the status and configuration of the SD-FEC core
0053
0054 Programmable Logic (PL) Initialization
0055 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0056
0057 For PL initialization, supporting logic loads configuration parameters for either
0058 the Turbo decode or LDPC encode or decode. The role of the driver is to allow
0059 the software application to do the following:
0060
0061 - Activate the SD-FEC core
0062 - Monitor the SD-FEC core for errors
0063 - Retrieve the status and configuration of the SD-FEC core
0064
0065
0066 Driver Structure
0067 ================
0068
0069 The driver provides a platform device where the ``probe`` and ``remove``
0070 operations are provided.
0071
0072 - 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.
0073
0074
0075 The driver defines the following driver file operations to provide user
0076 application interfaces:
0077
0078 - open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time
0079 - release: Allows another file descriptor to be open, that is after current file descriptor is closed
0080 - poll: Provides a method to monitor for SD-FEC Error events
0081 - unlocked_ioctl: Provides the following ioctl commands that allows the application configure the SD-FEC core:
0082
0083 - :c:macro:`XSDFEC_START_DEV`
0084 - :c:macro:`XSDFEC_STOP_DEV`
0085 - :c:macro:`XSDFEC_GET_STATUS`
0086 - :c:macro:`XSDFEC_SET_IRQ`
0087 - :c:macro:`XSDFEC_SET_TURBO`
0088 - :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS`
0089 - :c:macro:`XSDFEC_GET_CONFIG`
0090 - :c:macro:`XSDFEC_SET_ORDER`
0091 - :c:macro:`XSDFEC_SET_BYPASS`
0092 - :c:macro:`XSDFEC_IS_ACTIVE`
0093 - :c:macro:`XSDFEC_CLEAR_STATS`
0094 - :c:macro:`XSDFEC_SET_DEFAULT_CONFIG`
0095
0096
0097 Driver Usage
0098 ============
0099
0100
0101 Overview
0102 --------
0103
0104 After opening the driver, the user should find out what operations need to be
0105 performed to configure and activate the SD-FEC core and determine the
0106 configuration of the driver.
0107 The following outlines the flow the user should perform:
0108
0109 - Determine Configuration
0110 - Set the order, if not already configured as desired
0111 - Set Turbo decode, LPDC encode or decode parameters, depending on how the
0112 SD-FEC core is configured plus if the SD-FEC has not been configured for PL
0113 initialization
0114 - Enable interrupts, if not already enabled
0115 - Bypass the SD-FEC core, if required
0116 - Start the SD-FEC core if not already started
0117 - Get the SD-FEC core status
0118 - Monitor for interrupts
0119 - Stop the SD-FEC core
0120
0121
0122 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.
0123
0124
0125 Determine Configuration
0126 -----------------------
0127
0128 Determine the configuration of the SD-FEC core by using the ioctl
0129 :c:macro:`XSDFEC_GET_CONFIG`.
0130
0131 Set the Order
0132 -------------
0133
0134 Setting the order determines how the order of Blocks can change from input to output.
0135
0136 Setting the order is done by using the ioctl :c:macro:`XSDFEC_SET_ORDER`
0137
0138 Setting the order can only be done if the following restrictions are met:
0139
0140 - 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
0141
0142
0143 Add LDPC Codes
0144 --------------
0145
0146 The following steps indicate how to add LDPC codes to the SD-FEC core:
0147
0148 - Use the auto-generated parameters to fill the :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>` for the desired LDPC code.
0149 - 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>`
0150 - Set the desired Code Id value in the structure :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>`
0151 - Add the LPDC Code Parameters using the ioctl :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS`
0152 - 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.
0153 - Repeat for each LDPC code parameter.
0154
0155 Adding LDPC codes can only be done if the following restrictions are met:
0156
0157 - 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
0158 - 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
0159 - 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
0160
0161 Set Turbo Decode
0162 ----------------
0163
0164 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.
0165
0166 Adding Turbo decode can only be done if the following restrictions are met:
0167
0168 - 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
0169 - 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
0170
0171 Enable Interrupts
0172 -----------------
0173
0174 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:
0175
0176 - ``enable_isr`` controls the ``tlast`` interrupts
0177 - ``enable_ecc_isr`` controls the ECC interrupts
0178
0179 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.
0180
0181 Bypass the SD-FEC
0182 -----------------
0183
0184 Bypassing the SD-FEC is done by using the ioctl :c:macro:`XSDFEC_SET_BYPASS`
0185
0186 Bypassing the SD-FEC can only be done if the following restrictions are met:
0187
0188 - 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
0189
0190 Start the SD-FEC core
0191 ---------------------
0192
0193 Start the SD-FEC core by using the ioctl :c:macro:`XSDFEC_START_DEV`
0194
0195 Get SD-FEC Status
0196 -----------------
0197
0198 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>`
0199
0200 Monitor for Interrupts
0201 ----------------------
0202
0203 - 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.
0204 - On return Poll ``revents`` will indicate whether stats and/or state have been updated
0205 - ``POLLPRI`` indicates a critical error and the user should use :c:macro:`XSDFEC_GET_STATUS` and :c:macro:`XSDFEC_GET_STATS` to confirm
0206 - ``POLLRDNORM`` indicates a non-critical error has occurred and the user should use :c:macro:`XSDFEC_GET_STATS` to confirm
0207 - Get stats by using the ioctl :c:macro:`XSDFEC_GET_STATS`
0208 - For critical error the ``isr_err_count`` or ``uecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero
0209 - For non-critical errors the ``cecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero
0210 - Get state by using the ioctl :c:macro:`XSDFEC_GET_STATUS`
0211 - For a critical error the ``state`` of :c:type:`xsdfec_status <xsdfec_status>` will indicate a Reset Is Required
0212 - Clear stats by using the ioctl :c:macro:`XSDFEC_CLEAR_STATS`
0213
0214 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`
0215
0216 Note: Using poll system call prevents busy looping using :c:macro:`XSDFEC_GET_STATS` and :c:macro:`XSDFEC_GET_STATUS`
0217
0218 Stop the SD-FEC Core
0219 ---------------------
0220
0221 Stop the device by using the ioctl :c:macro:`XSDFEC_STOP_DEV`
0222
0223 Set the Default Configuration
0224 -----------------------------
0225
0226 Load default configuration by using the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` to restore the driver.
0227
0228 Limitations
0229 -----------
0230
0231 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.
0232
0233 Driver IOCTLs
0234 ==============
0235
0236 .. c:macro:: XSDFEC_START_DEV
0237 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0238 :doc: XSDFEC_START_DEV
0239
0240 .. c:macro:: XSDFEC_STOP_DEV
0241 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0242 :doc: XSDFEC_STOP_DEV
0243
0244 .. c:macro:: XSDFEC_GET_STATUS
0245 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0246 :doc: XSDFEC_GET_STATUS
0247
0248 .. c:macro:: XSDFEC_SET_IRQ
0249 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0250 :doc: XSDFEC_SET_IRQ
0251
0252 .. c:macro:: XSDFEC_SET_TURBO
0253 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0254 :doc: XSDFEC_SET_TURBO
0255
0256 .. c:macro:: XSDFEC_ADD_LDPC_CODE_PARAMS
0257 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0258 :doc: XSDFEC_ADD_LDPC_CODE_PARAMS
0259
0260 .. c:macro:: XSDFEC_GET_CONFIG
0261 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0262 :doc: XSDFEC_GET_CONFIG
0263
0264 .. c:macro:: XSDFEC_SET_ORDER
0265 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0266 :doc: XSDFEC_SET_ORDER
0267
0268 .. c:macro:: XSDFEC_SET_BYPASS
0269 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0270 :doc: XSDFEC_SET_BYPASS
0271
0272 .. c:macro:: XSDFEC_IS_ACTIVE
0273 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0274 :doc: XSDFEC_IS_ACTIVE
0275
0276 .. c:macro:: XSDFEC_CLEAR_STATS
0277 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0278 :doc: XSDFEC_CLEAR_STATS
0279
0280 .. c:macro:: XSDFEC_GET_STATS
0281 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0282 :doc: XSDFEC_GET_STATS
0283
0284 .. c:macro:: XSDFEC_SET_DEFAULT_CONFIG
0285 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0286 :doc: XSDFEC_SET_DEFAULT_CONFIG
0287
0288 Driver Type Definitions
0289 =======================
0290
0291 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
0292 :internal:
