Xilinx SD-FEC Driver¶
Overview¶
This driver supports SD-FEC Integrated Block for Zynq Ultrascale+™ RFSoCs.
For a full description of SD-FEC core features, see the SD-FEC Product Guide (PG256)
This driver supports the following features:
Retrieval of the Integrated Block configuration and status information
Configuration of LDPC codes
Configuration of Turbo decoding
Monitoring errors
Missing features, known issues, and limitations of the SD-FEC driver are as follows:
Only allows a single open file handler to any instance of the driver at any time
Reset of the SD-FEC Integrated Block is not controlled by this driver
Does not support shared LDPC code table wraparound
The device tree entry is described in: linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt
Modes of Operation¶
The driver works with the SD-FEC core in two modes of operation:
Run-time configuration
Programmable Logic (PL) initialization
Run-time Configuration¶
For Run-time configuration the role of driver is to allow the software application to do the following:
Load the configuration parameters for either Turbo decode or LDPC encode or decode
Activate the SD-FEC core
Monitor the SD-FEC core for errors
Retrieve the status and configuration of the SD-FEC core
Programmable Logic (PL) Initialization¶
For PL initialization, supporting logic loads configuration parameters for either the Turbo decode or LDPC encode or decode. The role of the driver is to allow the software application to do the following:
Activate the SD-FEC core
Monitor the SD-FEC core for errors
Retrieve the status and configuration of the SD-FEC core
Driver Structure¶
The driver provides a platform device where the probe
and remove
operations are provided.
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.
The driver defines the following driver file operations to provide user application interfaces:
open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time
release: Allows another file descriptor to be open, that is after current file descriptor is closed
poll: Provides a method to monitor for SD-FEC Error events
unlocked_ioctl: Provides the following ioctl commands that allows the application configure the SD-FEC core:
Driver Usage¶
Overview¶
After opening the driver, the user should find out what operations need to be performed to configure and activate the SD-FEC core and determine the configuration of the driver. The following outlines the flow the user should perform:
Determine Configuration
Set the order, if not already configured as desired
Set Turbo decode, LPDC encode or decode parameters, depending on how the SD-FEC core is configured plus if the SD-FEC has not been configured for PL initialization
Enable interrupts, if not already enabled
Bypass the SD-FEC core, if required
Start the SD-FEC core if not already started
Get the SD-FEC core status
Monitor for interrupts
Stop the SD-FEC core
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.
Determine Configuration¶
Determine the configuration of the SD-FEC core by using the ioctl
XSDFEC_GET_CONFIG
.
Set the Order¶
Setting the order determines how the order of Blocks can change from input to output.
Setting the order is done by using the ioctl XSDFEC_SET_ORDER
Setting the order can only be done if the following restrictions are met:
The
state
member of structxsdfec_status
filled by the ioctlXSDFEC_GET_STATUS
indicates the SD-FEC core has not STARTED
Add LDPC Codes¶
The following steps indicate how to add LDPC codes to the SD-FEC core:
Use the auto-generated parameters to fill the
struct xsdfec_ldpc_params
for the desired LDPC code.Set the SC, QA, and LA table offsets for the LPDC parameters and the parameters in the structure
struct xsdfec_ldpc_params
Set the desired Code Id value in the structure
struct xsdfec_ldpc_params
Add the LPDC Code Parameters using the ioctl
XSDFEC_ADD_LDPC_CODE_PARAMS
For the applied LPDC Code Parameter use the function
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.Repeat for each LDPC code parameter.
Adding LDPC codes can only be done if the following restrictions are met:
The
code
member ofstruct xsdfec_config
filled by the ioctlXSDFEC_GET_CONFIG
indicates the SD-FEC core is configured as LDPCThe
code_wr_protect
ofstruct xsdfec_config
filled by the ioctlXSDFEC_GET_CONFIG
indicates that write protection is not enabledThe
state
member of structxsdfec_status
filled by the ioctlXSDFEC_GET_STATUS
indicates the SD-FEC core has not started
Set Turbo Decode¶
Configuring the Turbo decode parameters is done by using the ioctl XSDFEC_SET_TURBO
using auto-generated parameters to fill the struct xsdfec_turbo
for the desired Turbo code.
Adding Turbo decode can only be done if the following restrictions are met:
The
code
member ofstruct xsdfec_config
filled by the ioctlXSDFEC_GET_CONFIG
indicates the SD-FEC core is configured as TURBOThe
state
member of structxsdfec_status
filled by the ioctlXSDFEC_GET_STATUS
indicates the SD-FEC core has not STARTED
Enable Interrupts¶
Enabling or disabling interrupts 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:
enable_isr
controls thetlast
interrupts
enable_ecc_isr
controls the ECC interrupts
If the code
member of struct xsdfec_config
filled by the ioctl XSDFEC_GET_CONFIG
indicates the SD-FEC core is configured as TURBO then the enabling ECC errors is not required.
Bypass the SD-FEC¶
Bypassing the SD-FEC is done by using the ioctl XSDFEC_SET_BYPASS
Bypassing the SD-FEC can only be done if the following restrictions are met:
The
state
member ofstruct xsdfec_status
filled by the ioctlXSDFEC_GET_STATUS
indicates the SD-FEC core has not STARTED
Start the SD-FEC core¶
Start the SD-FEC core by using the ioctl XSDFEC_START_DEV
Get SD-FEC Status¶
Get the SD-FEC status of the device by using the ioctl XSDFEC_GET_STATUS
, which will fill the struct xsdfec_status
Monitor for Interrupts¶
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.
- On return Poll
revents
will indicate whether stats and/or state have been updated
POLLPRI
indicates a critical error and the user should useXSDFEC_GET_STATUS
andXSDFEC_GET_STATS
to confirm
POLLRDNORM
indicates a non-critical error has occurred and the user should useXSDFEC_GET_STATS
to confirm
- Get stats by using the ioctl
XSDFEC_GET_STATS
For critical error the
isr_err_count
oruecc_count
member ofstruct xsdfec_stats
is non-zeroFor non-critical errors the
cecc_count
member ofstruct xsdfec_stats
is non-zero
- Get state by using the ioctl
XSDFEC_GET_STATUS
For a critical error the
state
ofxsdfec_status
will indicate a Reset Is RequiredClear stats by using the ioctl
XSDFEC_CLEAR_STATS
If a critical error is detected where a reset is required. The application is required to call the ioctl XSDFEC_SET_DEFAULT_CONFIG
, after the reset and it is not required to call the ioctl XSDFEC_STOP_DEV
Note: Using poll system call prevents busy looping using XSDFEC_GET_STATS
and XSDFEC_GET_STATUS
Stop the SD-FEC Core¶
Stop the device by using the ioctl XSDFEC_STOP_DEV
Set the Default Configuration¶
Load default configuration by using the ioctl XSDFEC_SET_DEFAULT_CONFIG
to restore the driver.
Limitations¶
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.
Driver IOCTLs¶
-
XSDFEC_START_DEV¶
Error
kernel-doc missing
-
XSDFEC_STOP_DEV¶
Error
kernel-doc missing
-
XSDFEC_GET_STATUS¶
Error
kernel-doc missing
-
XSDFEC_SET_IRQ¶
Error
kernel-doc missing
-
XSDFEC_SET_TURBO¶
Error
kernel-doc missing
-
XSDFEC_ADD_LDPC_CODE_PARAMS¶
Error
kernel-doc missing
-
XSDFEC_GET_CONFIG¶
Error
kernel-doc missing
-
XSDFEC_SET_ORDER¶
Error
kernel-doc missing
-
XSDFEC_SET_BYPASS¶
Error
kernel-doc missing
-
XSDFEC_IS_ACTIVE¶
Error
kernel-doc missing
-
XSDFEC_CLEAR_STATS¶
Error
kernel-doc missing
-
XSDFEC_GET_STATS¶
Error
kernel-doc missing
-
XSDFEC_SET_DEFAULT_CONFIG¶
Error
kernel-doc missing
Driver Type Definitions¶
Error
kernel-doc missing