Xilinx SD-FEC 驱动程序

概述

此驱动程序支持 Zynq Ultrascale+™ RFSoC 的 SD-FEC 集成模块。

有关 SD-FEC 核心功能的完整描述，请参阅SD-FEC 产品指南 (PG256)

此驱动程序支持以下功能

  • 检索集成模块配置和状态信息

  • LDPC 代码配置

  • Turbo 解码配置

  • 错误监控

SD-FEC 驱动程序的缺失功能、已知问题和限制如下

  • 在任何时候只允许一个打开的文件句柄指向驱动程序的任何实例

  • SD-FEC 集成模块的重置不由该驱动程序控制

  • 不支持共享 LDPC 代码表回绕

设备树条目描述在：linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml

操作模式

该驱动程序在两种操作模式下与 SD-FEC 核心一起工作

  • 运行时配置

  • 可编程逻辑 (PL) 初始化

运行时配置

对于运行时配置，驱动程序的作用是允许软件应用程序执行以下操作

  • 加载 Turbo 解码或 LDPC 编码或解码的配置参数

  • 激活 SD-FEC 核心

  • 监控 SD-FEC 核心的错误

  • 检索 SD-FEC 核心的状态和配置

可编程逻辑 (PL) 初始化

对于 PL 初始化，支持逻辑加载 Turbo 解码或 LDPC 编码或解码的配置参数。 驱动程序的作用是允许软件应用程序执行以下操作

  • 激活 SD-FEC 核心

  • 监控 SD-FEC 核心的错误

  • 检索 SD-FEC 核心的状态和配置

驱动程序结构

该驱动程序提供了一个平台设备，其中提供了probe和remove操作。

  • probe：使用设备树条目更新配置寄存器，并确定核心的当前激活状态，例如，核心是否被旁路或核心是否已启动。

驱动程序定义了以下驱动程序文件操作以提供用户应用程序接口

驱动程序使用

概述

打开驱动程序后，用户应找出需要执行哪些操作来配置和激活 SD-FEC 核心，并确定驱动程序的配置。 以下概述了用户应执行的流程

  • 确定配置

  • 如果尚未按所需方式配置，则设置顺序

  • 设置 Turbo 解码、LPDC 编码或解码参数，具体取决于 SD-FEC 核心的配置方式，以及 SD-FEC 是否已配置为 PL 初始化

  • 如果尚未启用，则启用中断

  • 如果需要，旁路 SD-FEC 核心

  • 如果尚未启动，则启动 SD-FEC 核心

  • 获取 SD-FEC 核心状态

  • 监视中断

  • 停止 SD-FEC 核心

注意：在监视中断时，如果检测到需要重置的严重错误，则需要驱动程序加载默认配置。

确定配置

通过使用 ioctl XSDFEC_GET_CONFIG确定 SD-FEC 核心的配置。

设置顺序

设置顺序决定了块的顺序如何从输入更改为输出。

设置顺序是通过使用 ioctl XSDFEC_SET_ORDER完成的

只有在满足以下限制的情况下才能设置顺序

添加 LDPC 代码

以下步骤指示如何将 LDPC 代码添加到 SD-FEC 核心

  • 使用自动生成的参数填充所需 LDPC 代码的struct xsdfec_ldpc_params。

  • 为 LPDC 参数和结构struct xsdfec_ldpc_params中的参数设置 SC、QA 和 LA 表偏移量

  • 在结构struct xsdfec_ldpc_params中设置所需的代码 ID 值

  • 使用 ioctl XSDFEC_ADD_LDPC_CODE_PARAMS添加 LPDC 代码参数

  • 对于应用的 LPDC 代码参数，使用函数xsdfec_calculate_shared_ldpc_table_entry_size()计算共享 LPDC 代码表的大小。 这允许用户确定共享表的使用情况，以便在为下一个 LDPC 代码参数选择表偏移量时可以选择未使用的表区域。

  • 为每个 LDPC 代码参数重复。

只有在满足以下限制的情况下才能添加 LDPC 代码

设置 Turbo 解码

配置 Turbo 解码参数是通过使用 ioctl XSDFEC_SET_TURBO，并使用自动生成的参数填充所需 Turbo 代码的struct xsdfec_turbo来完成的。

只有在满足以下限制的情况下才能添加 Turbo 解码

启用中断

启用或禁用中断是通过使用 ioctl XSDFEC_SET_IRQ完成的。 传递给 ioctl 的参数struct xsdfec_irq的成员用于设置和清除不同类别的中断。 中断类别控制如下

  • enable_isr控制tlast中断

  • enable_ecc_isr控制 ECC 中断

如果 ioctl XSDFEC_GET_CONFIG填充的struct xsdfec_config的code成员指示 SD-FEC 核心配置为 TURBO，则不需要启用 ECC 错误。

旁路 SD-FEC

旁路 SD-FEC 是通过使用 ioctl XSDFEC_SET_BYPASS完成的

只有在满足以下限制的情况下才能旁路 SD-FEC

启动 SD-FEC 核心

通过使用 ioctl XSDFEC_START_DEV启动 SD-FEC 核心

获取 SD-FEC 状态

通过使用 ioctl XSDFEC_GET_STATUS获取设备 SD-FEC 状态，这将填充struct xsdfec_status

监视中断

如果检测到需要重置的严重错误。 应用程序需要在重置后调用 ioctl XSDFEC_SET_DEFAULT_CONFIG，并且不需要调用 ioctl XSDFEC_STOP_DEV

注意：使用 poll 系统调用可以防止使用XSDFEC_GET_STATS和XSDFEC_GET_STATUS进行繁忙循环

停止 SD-FEC 核心

通过使用 ioctl XSDFEC_STOP_DEV停止设备

设置默认配置

通过使用 ioctl XSDFEC_SET_DEFAULT_CONFIG加载默认配置以恢复驱动程序。

限制

用户不应重复 SD-FEC 设备文件句柄，例如 fork() 或 dup() 具有已创建 SD-FEC 文件句柄的进程。

驱动程序 IOCTL

XSDFEC_START_DEV

描述

ioctl 以启动 SD-FEC 核心

如果之前未调用 XSDFEC_SET_ORDER ioctl，则此操作将失败

XSDFEC_STOP_DEV

描述

ioctl 以停止 SD-FEC 核心

XSDFEC_GET_STATUS

描述

ioctl，返回 SD-FEC 核心的状态

XSDFEC_SET_IRQ

参数

struct xsdfec_irq *

指向struct xsdfec_irq的指针，其中包含 SD-FEC 核心的中断设置

描述

ioctl 以启用或禁用 irq

XSDFEC_SET_TURBO

参数

struct xsdfec_turbo *

指向struct xsdfec_turbo的指针，其中包含 SD-FEC 核心的 Turbo 解码设置

描述

ioctl，设置 SD-FEC Turbo 参数值

这只能在驱动程序处于 XSDFEC_STOPPED 状态时使用

XSDFEC_ADD_LDPC_CODE_PARAMS

参数

struct xsdfec_ldpc_params *

指向struct xsdfec_ldpc_params的指针，其中包含要添加到 SD-FEC 块的 LDPC 代码参数

描述 ioctl，用于将 LDPC 代码添加到 SD-FEC LDPC 代码

这只能在以下情况下使用

  • 驱动程序处于 XSDFEC_STOPPED 状态

  • SD-FEC 核心配置为 LPDC

  • SD-FEC 代码写入保护已禁用

XSDFEC_GET_CONFIG

参数

struct xsdfec_config *

指向struct xsdfec_config的指针，其中包含 SD-FEC 块的当前配置设置

描述

ioctl，返回 SD-FEC 核心配置

XSDFEC_SET_ORDER

参数

struct unsigned long *

指向 unsigned long 的指针，其中包含来自 enum xsdfec_order 的值

描述

ioctl，用于设置顺序，如果块的顺序可以从输入更改为输出

这只能在驱动程序处于 XSDFEC_STOPPED 状态时使用

XSDFEC_SET_BYPASS

参数

struct bool *

指向 bool 的指针，用于设置旁路值，其中 false 会导致正常操作，而 false 会导致 SD-FEC 执行配置的操作（相同数量的周期），但输出数据与输入数据匹配

描述

ioctl，用于设置旁路。

这只能在驱动程序处于 XSDFEC_STOPPED 状态时使用

XSDFEC_IS_ACTIVE

参数

struct bool *

指向 bool 的指针，如果 SD-FEC 正在处理数据，则返回 true

描述

ioctl，用于确定 SD-FEC 是否正在处理数据

XSDFEC_CLEAR_STATS

描述

ioctl，用于清除中断期间收集的错误统计信息

XSDFEC_GET_STATS

参数

struct xsdfec_stats *

指向struct xsdfec_stats的指针，其中将包含更新的 stats 值

描述

ioctl，返回 SD-FEC 核心 stats

这只能在驱动程序处于 XSDFEC_STOPPED 状态时使用

XSDFEC_SET_DEFAULT_CONFIG

描述

ioctl，用于将 SD-FEC 核心返回到默认配置，在重置后使用

这只能在驱动程序处于 XSDFEC_STOPPED 状态时使用

驱动程序类型定义

enum xsdfec_code

代码类型。

常量

XSDFEC_TURBO_CODE

驱动程序配置为 Turbo 模式。

XSDFEC_LDPC_CODE

驱动程序配置为 LDPC 模式。

描述

此枚举用于指示驱动程序的模式。 该模式通过检查驱动程序中设置了哪些代码来确定。 请注意，模式无法由驱动程序更改。

enum xsdfec_order

顺序

常量

XSDFEC_MAINTAIN_ORDER

保持块的顺序执行。

XSDFEC_OUT_OF_ORDER

块的乱序执行。

描述

此枚举用于指示块的顺序是否可以从输入更改为输出。

enum xsdfec_turbo_alg

Turbo 算法类型。

常量

XSDFEC_MAX_SCALE

具有外在缩放的最大对数映射算法。 当缩放设置为此值时，等效于最大对数映射算法。

XSDFEC_MAX_STAR

对数映射算法。

XSDFEC_TURBO_ALG_MAX

用于指示越界 Turbo 算法。

描述

此枚举指定正在使用的 Turbo 解码算法。

enum xsdfec_state

状态。

常量

XSDFEC_INIT

驱动程序已初始化。

XSDFEC_STARTED

驱动程序已启动。

XSDFEC_STOPPED

驱动程序已停止。

XSDFEC_NEEDS_RESET

驱动程序需要重置。

XSDFEC_PL_RECONFIGURE

可编程逻辑需要重新配置。

描述

此枚举用于指示驱动程序的状态。

enum xsdfec_axis_width

AXIS_WIDTH.DIN 128 位宽度的设置。

常量

XSDFEC_1x128b

DIN 数据输入流由 128 位通道组成

XSDFEC_2x128b

DIN 数据输入流由两个 128 位通道组成

XSDFEC_4x128b

DIN 数据输入流由四个 128 位通道组成

描述

此枚举用于指示 128 位宽度的 AXIS_WIDTH.DIN 设置。 DIN 数据输入流的通道数取决于 AXIS_WIDTH.DIN 参数。

enum xsdfec_axis_word_include

字配置。

常量

XSDFEC_FIXED_VALUE

固定，DIN_WORDS AXI4-Stream 接口从 IP 实例中删除，并由指定的字数驱动。

XSDFEC_IN_BLOCK

在块中，将 IP 实例配置为期望每个输入代码块一个 DIN_WORDS 值。 DIN_WORDS 接口存在。

XSDFEC_PER_AXI_TRANSACTION

每个事务，将 IP 实例配置为期望每个 DIN 接口上的输入事务一个 DIN_WORDS 值。 DIN_WORDS 接口存在。

XSDFEC_AXIS_WORDS_INCLUDE_MAX

用于指示越界字配置。

描述

此枚举用于指定 DIN_WORDS 配置。

struct xsdfec_turbo

Turbo 代码的用户数据。

定义:

struct xsdfec_turbo {
    __u32 alg;
    __u8 scale;
};

成员

alg

指定要使用的 Turbo 解码算法

scale

指定在选择最大比例算法时要应用的外在缩放

描述

Turbo 代码结构，用于将参数传递到 XSDFEC 驱动程序。

struct xsdfec_ldpc_params

LDPC 代码的用户数据。

定义:

struct xsdfec_ldpc_params {
    __u32 n;
    __u32 k;
    __u32 psize;
    __u32 nlayers;
    __u32 nqc;
    __u32 nmqc;
    __u32 nm;
    __u32 norm_type;
    __u32 no_packing;
    __u32 special_qc;
    __u32 no_final_parity;
    __u32 max_schedule;
    __u32 sc_off;
    __u32 la_off;
    __u32 qc_off;
    __u32 *sc_table;
    __u32 *la_table;
    __u32 *qc_table;
    __u16 code_id;
};

成员

n

代码字位数

k

信息位数

psize

子矩阵的大小

nlayers

代码中的层数

nqc

准循环数

nmqc

奇偶校验矩阵中 M 大小的 QC 操作数

nm

N 中 M 大小向量的数量

norm_type

是否需要规范化

no_packing

确定是否应执行多个 QC 操作

special_qc

Circulant 权重 > 0 的子矩阵属性

no_final_parity

确定是否需要执行最终奇偶校验

max_schedule

实验代码字调度限制

sc_off

SC 偏移量

la_off

LA 偏移量

qc_off

QC 偏移量

sc_table

指向 SC 表的指针，该指针必须页对齐

la_table

指向 LA 表的指针，该指针必须页对齐

qc_table

指向 QC 表的指针，该指针必须页对齐

code_id

LDPC 代码

描述

此结构描述了应用程序传递给驱动程序的 LDPC 代码。

struct xsdfec_status

SD-FEC 核心的状态。

定义:

struct xsdfec_status {
    __u32 state;
    __s8 activity;
};

成员

state

SD-FEC 核心的状态

activity

描述 SD-FEC 实例是否处于活动状态

struct xsdfec_irq

启用或禁用中断。

定义:

struct xsdfec_irq {
    __s8 enable_isr;
    __s8 enable_ecc_isr;
};

成员

enable_isr

如果为 true，则启用 ISR

enable_ecc_isr

如果为 true，则启用 ECC ISR

struct xsdfec_config

SD-FEC 核心的配置。

定义:

struct xsdfec_config {
    __u32 code;
    __u32 order;
    __u32 din_width;
    __u32 din_word_include;
    __u32 dout_width;
    __u32 dout_word_include;
    struct xsdfec_irq irq;
    __s8 bypass;
    __s8 code_wr_protect;
};

成员

code

SD-FEC 实例使用的代码

order

操作顺序

din_width

DIN AXI4-Stream 的宽度

din_word_include

如何输入 DIN_WORDS

dout_width

DOUT AXI4-Stream 的宽度

dout_word_include

如何输出 DOUT_WORDS

irq

启用或禁用中断

bypass

核心是否被旁路

code_wr_protect

是否启用了 LDPC 代码的写入保护

struct xsdfec_stats

由 ioctl XSDFEC_GET_STATS 检索的 Stats。 用于缓冲来自 struct xsdfec_dev 的 atomic_t 变量。 计数会累积，直到用户清除它们。

定义:

struct xsdfec_stats {
    __u32 isr_err_count;
    __u32 cecc_count;
    __u32 uecc_count;
};

成员

isr_err_count

ISR 错误计数

cecc_count

可纠正 ECC 错误 (SBE) 计数

uecc_count

不可纠正 ECC 错误 (MBE) 计数

struct xsdfec_ldpc_param_table_sizes

用于存储单个 LPDC 代码参数的 SD-FEC 表条目的大小。

定义:

struct xsdfec_ldpc_param_table_sizes {
    __u32 sc_size;
    __u32 la_size;
    __u32 qc_size;
};

成员

sc_size

使用的 SC 表大小

la_size

使用的 LA 表大小

qc_size

使用的 QC 表大小