Xilinx SD-FEC Driver

지원 기능과 제한

이 GPL-2.0+ 문서는 Zynq Ultrascale+ RFSoC의 SD-FEC Integrated Block을 지원하는 Xilinx SD-FEC driver를 설명합니다. 전체 core 기능은 SD-FEC Product Guide(PG256)를 참조합니다.

Driver는 Integrated Block configuration·status 조회, LDPC code 구성, Turbo decoding 구성, error monitoring을 지원합니다.

현재 제한은 driver instance마다 동시에 open할 수 있는 file handler가 하나뿐이라는 점, SD-FEC Integrated Block reset을 driver가 제어하지 않는다는 점, shared LDPC code table wraparound를 지원하지 않는다는 점입니다.

Device-tree entry는 원문이 연결한 `linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml`에 설명되어 있습니다.

.. SPDX-License-Identifier: GPL-2.0+

====================
Xilinx SD-FEC Driver
====================

Overview
========

This driver supports SD-FEC Integrated Block for Zynq |Ultrascale+ (TM)| RFSoCs.

.. |Ultrascale+ (TM)| unicode:: Ultrascale+ U+2122
   .. with trademark sign

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>`_

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.yaml <https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/misc/xlnx%2Csd-fec.yaml>`_

두 operation mode

SD-FEC core는 run-time configuration과 Programmable Logic(PL) initialization 두 mode로 동작합니다.

Run-time configuration에서는 software application이 Turbo decode 또는 LDPC encode/decode parameter를 load하고, SD-FEC core를 activate하고, error를 monitor하며, status와 configuration을 조회하도록 driver가 지원합니다.

PL initialization에서는 supporting logic이 Turbo decode 또는 LDPC encode/decode parameter를 load합니다. Driver는 application이 core를 activate하고 error를 monitor하며 status와 configuration을 조회하도록 합니다. 즉 PL mode에서는 parameter load가 driver 역할에서 빠집니다.

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

Platform driver와 file operation

Driver는 `probe`와 `remove` operation을 가진 platform device를 제공합니다. `probe`는 device-tree entry로 configuration register를 갱신하고 core가 bypass 상태인지 start 상태인지 같은 현재 activation state를 판단합니다.

`open`은 SD-FEC instance마다 file descriptor 하나만 열도록 제한합니다. `release`는 현재 fd가 닫힌 뒤 다른 fd를 열 수 있게 하고, `poll`은 SD-FEC error event를 감시합니다.

`unlocked_ioctl`은 `XSDFEC_START_DEV`, `XSDFEC_STOP_DEV`, `XSDFEC_GET_STATUS`, `XSDFEC_SET_IRQ`, `XSDFEC_SET_TURBO`, `XSDFEC_ADD_LDPC_CODE_PARAMS`, `XSDFEC_GET_CONFIG`, `XSDFEC_SET_ORDER`, `XSDFEC_SET_BYPASS`, `XSDFEC_IS_ACTIVE`, `XSDFEC_CLEAR_STATS`, `XSDFEC_SET_DEFAULT_CONFIG` command를 제공합니다.

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:

                - :c:macro:`XSDFEC_START_DEV`
                - :c:macro:`XSDFEC_STOP_DEV`
                - :c:macro:`XSDFEC_GET_STATUS`
                - :c:macro:`XSDFEC_SET_IRQ`
                - :c:macro:`XSDFEC_SET_TURBO`
                - :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS`
                - :c:macro:`XSDFEC_GET_CONFIG`
                - :c:macro:`XSDFEC_SET_ORDER`
                - :c:macro:`XSDFEC_SET_BYPASS`
                - :c:macro:`XSDFEC_IS_ACTIVE`
                - :c:macro:`XSDFEC_CLEAR_STATS`
                - :c:macro:`XSDFEC_SET_DEFAULT_CONFIG`

전체 구성·실행 순서

Driver를 open한 뒤 application은 SD-FEC core를 구성·activate하기 위해 필요한 operation과 현재 driver configuration을 먼저 판단해야 합니다.

• `XSDFEC_GET_CONFIG`로 configuration을 확인합니다.
• 필요하면 block order를 설정합니다.
• PL initialization이 아니라면 core mode에 맞춰 Turbo decode 또는 LDPC encode/decode parameter를 설정합니다.
• 필요하면 interrupt를 enable합니다.
• 필요하면 core를 bypass합니다.
• 아직 start하지 않았다면 core를 start합니다.
• Core status를 가져오고 interrupt를 monitor합니다.
• 마지막에 core를 stop합니다.

Interrupt monitoring 중 reset이 필요한 critical error를 감지하면 driver가 default configuration을 load해야 합니다.

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.

Configuration 확인과 block order

`XSDFEC_GET_CONFIG` ioctl로 SD-FEC core configuration을 확인합니다. Block의 input-to-output 순서 변경 방식을 정하려면 `XSDFEC_SET_ORDER`를 사용합니다.

Order 설정은 `XSDFEC_GET_STATUS`가 채운 `struct xsdfec_status`의 `state`가 core가 아직 `STARTED`되지 않았음을 나타낼 때만 가능합니다.

Determine Configuration
-----------------------

Determine the configuration of the SD-FEC core by using the ioctl
:c:macro:`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 :c:macro:`XSDFEC_SET_ORDER`

Setting the order can only be done if the following restrictions are met:

        - 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

LDPC code 추가

원하는 LDPC code의 auto-generated parameter로 `struct xsdfec_ldpc_params`를 채우고 SC·QA·LA table offset과 Code ID를 설정한 뒤 `XSDFEC_ADD_LDPC_CODE_PARAMS` ioctl로 parameter를 추가합니다.

적용한 parameter마다 `xsdfec_calculate_shared_ldpc_table_entry_size()`로 shared LDPC code table 크기를 계산합니다. 그러면 다음 LDPC parameter의 table offset을 고를 때 사용하지 않은 영역을 선택할 수 있습니다. 각 LDPC code에 이 과정을 반복합니다.

LDPC code 추가는 `XSDFEC_GET_CONFIG` 결과의 `code`가 LDPC이고 `code_wr_protect`가 disable이며, `XSDFEC_GET_STATUS` 결과의 `state`가 아직 start되지 않은 경우에만 가능합니다.

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 :c:type:`struct xsdfec_ldpc_params <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 :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>`
        - Set the desired Code Id value in the structure :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>`
        - Add the LPDC Code Parameters using the ioctl :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS`
        - 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.
        - Repeat for each LDPC code parameter.

Adding LDPC codes can only be done if the following restrictions are met:

        - 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
        - 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
        - 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

Turbo decode 설정

원하는 Turbo code의 auto-generated parameter로 `struct xsdfec_turbo`를 채워 `XSDFEC_SET_TURBO` ioctl에 전달합니다.

Turbo decode parameter 추가는 `XSDFEC_GET_CONFIG`의 `code`가 `TURBO`이고 `XSDFEC_GET_STATUS`의 `state`가 아직 `STARTED`되지 않은 경우에만 가능합니다.

Set Turbo Decode
----------------

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.

Adding Turbo decode can only be done if the following restrictions are met:

        - 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
        - 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

Interrupt category 설정

`XSDFEC_SET_IRQ` ioctl로 interrupt를 enable 또는 disable합니다. 전달하는 `struct xsdfec_irq`에서 `enable_isr`은 `tlast` interrupt, `enable_ecc_isr`은 ECC interrupt를 제어합니다.

`XSDFEC_GET_CONFIG`의 `code`가 `TURBO`이면 ECC error enable은 필요하지 않습니다.

Enable Interrupts
-----------------

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:

  - ``enable_isr`` controls the ``tlast`` interrupts
  - ``enable_ecc_isr`` controls the ECC interrupts

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.

Bypass·start·status

`XSDFEC_SET_BYPASS`로 SD-FEC를 bypass할 수 있으며, 이 설정은 `XSDFEC_GET_STATUS`의 `state`가 아직 `STARTED`되지 않았을 때만 가능합니다.

Core start에는 `XSDFEC_START_DEV`, status 조회에는 `XSDFEC_GET_STATUS`를 사용합니다. Status ioctl은 `struct xsdfec_status`를 채웁니다.

Bypass the SD-FEC
-----------------

Bypassing the SD-FEC is done by using the ioctl :c:macro:`XSDFEC_SET_BYPASS`

Bypassing the SD-FEC can only be done if the following restrictions are met:

        - 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

Start the SD-FEC core
---------------------

Start the SD-FEC core by using the ioctl :c:macro:`XSDFEC_START_DEV`

Get SD-FEC Status
-----------------

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>`

Poll과 오류 복구

`poll` system call은 interrupt가 깨우거나 timeout될 때까지 기다립니다. Return한 `revents`의 `POLLPRI`는 critical error를 뜻하므로 `XSDFEC_GET_STATUS`와 `XSDFEC_GET_STATS`로 확인하고, `POLLRDNORM`은 non-critical error를 뜻하므로 `XSDFEC_GET_STATS`로 확인합니다.

`XSDFEC_GET_STATS` 결과에서 critical error는 `struct xsdfec_stats`의 `isr_err_count` 또는 `uecc_count`가 0이 아닌 경우입니다. Non-critical error는 `cecc_count`가 0이 아닌 경우입니다.

Critical error이면 `XSDFEC_GET_STATUS`의 `state`가 Reset Is Required를 나타냅니다. 통계는 `XSDFEC_CLEAR_STATS`로 clear합니다.

Reset이 필요한 critical error를 감지하면 reset 후 application이 `XSDFEC_SET_DEFAULT_CONFIG`를 호출해야 하며 `XSDFEC_STOP_DEV`는 호출할 필요가 없습니다. `poll`을 사용하면 `XSDFEC_GET_STATS`와 `XSDFEC_GET_STATUS`를 busy loop로 반복하지 않아도 됩니다.

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 use :c:macro:`XSDFEC_GET_STATUS` and :c:macro:`XSDFEC_GET_STATS` to confirm
                - ``POLLRDNORM`` indicates a non-critical error has occurred and the user should use  :c:macro:`XSDFEC_GET_STATS` to confirm
        - Get stats by using the ioctl :c:macro:`XSDFEC_GET_STATS`
                - For critical error the ``isr_err_count`` or ``uecc_count`` member  of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero
                - For non-critical errors the ``cecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero
        - Get state by using the ioctl :c:macro:`XSDFEC_GET_STATUS`
                - For a critical error the ``state`` of :c:type:`xsdfec_status <xsdfec_status>` will indicate a Reset Is Required
        - Clear stats by using the ioctl :c:macro:`XSDFEC_CLEAR_STATS`

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`

Note: Using poll system call prevents busy looping using :c:macro:`XSDFEC_GET_STATS` and :c:macro:`XSDFEC_GET_STATUS`

Stop·default configuration·fd 제한

`XSDFEC_STOP_DEV`로 device를 stop하고 `XSDFEC_SET_DEFAULT_CONFIG`로 default configuration을 load해 driver를 복원합니다.

사용자는 SD-FEC file handler를 duplicate하면 안 됩니다. 예를 들어 SD-FEC file handler를 만든 process에서 `fork()` 또는 `dup()`을 사용하지 않아야 합니다.

Stop the SD-FEC Core
---------------------

Stop the device by using the ioctl :c:macro:`XSDFEC_STOP_DEV`

Set the Default Configuration
-----------------------------

Load default configuration by using the ioctl :c:macro:`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.

IOCTL kernel-doc 목록

이 section은 `include/uapi/misc/xilinx_sdfec.h`에서 다음 ioctl의 kernel-doc을 포함합니다.

Driver IOCTLs
==============

.. c:macro:: XSDFEC_START_DEV
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_START_DEV

.. c:macro:: XSDFEC_STOP_DEV
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_STOP_DEV

.. c:macro:: XSDFEC_GET_STATUS
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_GET_STATUS

.. c:macro:: XSDFEC_SET_IRQ
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_SET_IRQ

.. c:macro:: XSDFEC_SET_TURBO
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_SET_TURBO

.. c:macro:: XSDFEC_ADD_LDPC_CODE_PARAMS
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_ADD_LDPC_CODE_PARAMS

.. c:macro:: XSDFEC_GET_CONFIG
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_GET_CONFIG

.. c:macro:: XSDFEC_SET_ORDER
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_SET_ORDER

.. c:macro:: XSDFEC_SET_BYPASS
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_SET_BYPASS

.. c:macro:: XSDFEC_IS_ACTIVE
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_IS_ACTIVE

.. c:macro:: XSDFEC_CLEAR_STATS
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_CLEAR_STATS

.. c:macro:: XSDFEC_GET_STATS
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_GET_STATS

.. c:macro:: XSDFEC_SET_DEFAULT_CONFIG
.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :doc: XSDFEC_SET_DEFAULT_CONFIG

Driver type definition

Driver type definition도 `include/uapi/misc/xilinx_sdfec.h`의 internal kernel-doc에서 가져옵니다.

Driver Type Definitions
=======================

.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
   :internal: