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