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