Documentation/misc-devices/xilinx_sdfec.rst

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