Documentation/misc-devices/xilinx_sdfec.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 ====================
   4 Xilinx SD-FEC Driver
   5 ====================
   6
   7 Overview
   8 ========
   9
  10 This driver supports SD-FEC Integrated Block for Zynq |Ultrascale+ (TM)| RFSoCs.
  11
  12 .. |Ultrascale+ (TM)| unicode:: Ultrascale+ U+2122
  13    .. with trademark sign
  14
  15 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>`_
  16
  17 This 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
  24 Missing features, known issues, and limitations of the SD-FEC driver are as
  25 follows:
  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
  31 The 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
  35 Modes of Operation
  36 ------------------
  37
  38 The driver works with the SD-FEC core in two modes of operation:
  39
  40   - Run-time configuration
  41   - Programmable Logic (PL) initialization
  42
  43
  44 Run-time Configuration
  45 ~~~~~~~~~~~~~~~~~~~~~~
  46
  47 For 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
  54 Programmable Logic (PL) Initialization
  55 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  56
  57 For PL initialization, supporting logic loads configuration parameters for either
  58 the Turbo decode or LDPC encode or decode.  The role of the driver is to allow
  59 the 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
  66 Driver Structure
  67 ================
  68
  69 The driver provides a platform device where the ``probe`` and ``remove``
  70 operations 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
  75 The driver defines the following driver file operations to provide user
  76 application 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
  97 Driver Usage
  98 ============
  99
 100
 101 Overview
 102 --------
 103
 104 After opening the driver, the user should find out what operations need to be
 105 performed to configure and activate the SD-FEC core and determine the
 106 configuration of the driver.
 107 The 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
 122 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.
 123
 124
 125 Determine Configuration
 126 -----------------------
 127
 128 Determine the configuration of the SD-FEC core by using the ioctl
 129 :c:macro:`XSDFEC_GET_CONFIG`.
 130
 131 Set the Order
 132 -------------
 133
 134 Setting the order determines how the order of Blocks can change from input to output.
 135
 136 Setting the order is done by using the ioctl :c:macro:`XSDFEC_SET_ORDER`
 137
 138 Setting 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
 143 Add LDPC Codes
 144 --------------
 145
 146 The 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
 155 Adding 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
 161 Set Turbo Decode
 162 ----------------
 163
 164 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.
 165
 166 Adding 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
 171 Enable Interrupts
 172 -----------------
 173
 174 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:
 175
 176   - ``enable_isr`` controls the ``tlast`` interrupts
 177   - ``enable_ecc_isr`` controls the ECC interrupts
 178
 179 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.
 180
 181 Bypass the SD-FEC
 182 -----------------
 183
 184 Bypassing the SD-FEC is done by using the ioctl :c:macro:`XSDFEC_SET_BYPASS`
 185
 186 Bypassing 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
 190 Start the SD-FEC core
 191 ---------------------
 192
 193 Start the SD-FEC core by using the ioctl :c:macro:`XSDFEC_START_DEV`
 194
 195 Get SD-FEC Status
 196 -----------------
 197
 198 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>`
 199
 200 Monitor 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
 214 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`
 215
 216 Note: Using poll system call prevents busy looping using :c:macro:`XSDFEC_GET_STATS` and :c:macro:`XSDFEC_GET_STATUS`
 217
 218 Stop the SD-FEC Core
 219 ---------------------
 220
 221 Stop the device by using the ioctl :c:macro:`XSDFEC_STOP_DEV`
 222
 223 Set the Default Configuration
 224 -----------------------------
 225
 226 Load default configuration by using the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` to restore the driver.
 227
 228 Limitations
 229 -----------
 230
 231 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.
 232
 233 Driver 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
 288 Driver Type Definitions
 289 =======================
 290
 291 .. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
 292    :internal: