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