요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
FPGA Region
===========
Overview
--------
This document is meant to be a brief overview of the FPGA region API usage. A
more conceptual look at regions can be found in the Device Tree binding
document [#f1]_.
For the purposes of this API document, let's just say that a region associates
an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
FPGA or the whole FPGA. The API provides a way to register a region and to
program a region.
Currently the only layer above fpga-region.c in the kernel is the Device Tree
support (of-fpga-region.c) described in [#f1]_. The DT support layer uses regions
to program the FPGA and then DT to handle enumeration. The common region code
is intended to be used by other schemes that have other ways of accomplishing
enumeration after programming.
An fpga-region can be set up to know the following things:
* which FPGA manager to use to do the programming
* which bridges to disable before programming and enable afterwards.
Additional info needed to program the FPGA image is passed in the struct
fpga_image_info including:
* pointers to the image as either a scatter-gather buffer, a contiguous
buffer, or the name of firmware file
* flags indicating specifics such as whether the image is for partial
reconfiguration.
How to add a new FPGA region
----------------------------
An example of usage can be seen in the probe function of [#f2]_.
.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
.. [#f2] ../../drivers/fpga/of-fpga-region.c
API to add a new FPGA region
----------------------------
* struct fpga_region - The FPGA region struct
* struct fpga_region_info - Parameter structure for __fpga_region_register_full()
* __fpga_region_register_full() - Create and register an FPGA region using the
fpga_region_info structure to provide the full flexibility of options
* __fpga_region_register() - Create and register an FPGA region using standard
arguments
* fpga_region_unregister() - Unregister an FPGA region
Helper macros ``fpga_region_register()`` and ``fpga_region_register_full()``
automatically set the module that registers the FPGA region as the owner.
The FPGA region's probe function will need to get a reference to the FPGA
Manager it will be using to do the programming. This usually would happen
during the region's probe function.
* fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count
* of_fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count,
given a device node.
* fpga_mgr_put() - Put an FPGA manager
The FPGA region will need to specify which bridges to control while programming
the FPGA. The region driver can build a list of bridges during probe time
(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
the list of bridges to program just before programming
(:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the
following APIs to handle building or tearing down that list.
* fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
list
* of_fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
list, given a device node
* fpga_bridges_put() - Given a list of bridges, put them
.. kernel-doc:: include/linux/fpga/fpga-region.h
:functions: fpga_region
.. kernel-doc:: include/linux/fpga/fpga-region.h
:functions: fpga_region_info
.. kernel-doc:: drivers/fpga/fpga-region.c
:functions: __fpga_region_register_full
.. kernel-doc:: drivers/fpga/fpga-region.c
:functions: __fpga_region_register
.. kernel-doc:: drivers/fpga/fpga-region.c
:functions: fpga_region_unregister
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_get
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: of_fpga_mgr_get
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_put
.. kernel-doc:: drivers/fpga/fpga-bridge.c
:functions: fpga_bridge_get_to_list
.. kernel-doc:: drivers/fpga/fpga-bridge.c
:functions: of_fpga_bridge_get_to_list
.. kernel-doc:: drivers/fpga/fpga-bridge.c
:functions: fpga_bridges_put
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
FPGA region 개요
1-20문서 제목은 `FPGA Region`입니다. 이 문서는 FPGA region API 사용법을 간략히 설명하며, region의 개념적 설명은 Device Tree binding 문서 `../devicetree/bindings/fpga/fpga-region.txt`에서 볼 수 있습니다.
이 API에서 region은 FPGA manager와 하나 이상의 bridge를 FPGA의 재programming 가능 영역 또는 FPGA 전체에 연결합니다. API는 region을 등록하고 programming하는 방법을 제공합니다.
현재 kernel에서 `fpga-region.c` 위의 유일한 layer는 `of-fpga-region.c`의 Device Tree 지원입니다. DT layer는 region으로 FPGA를 programming하고 Device Tree로 enumeration을 처리합니다. 공통 region code는 programming 후 다른 방식으로 enumeration하는 scheme도 사용할 수 있도록 설계되었습니다.
상위 enumeration scheme과 manager·bridge를 region이 연결하는 구조입니다.
Region이 보관하는 programming 정보
21-36`fpga-region`은 programming에 사용할 FPGA manager와, programming 전에 disable하고 이후 enable할 bridge를 알아야 합니다.
FPGA image programming에 필요한 추가 정보는 `struct fpga_image_info`로 전달합니다. Image는 scatter-gather buffer, contiguous buffer 또는 firmware file name으로 지정할 수 있고, partial reconfiguration 여부 같은 세부 flag도 포함합니다.
Region과 image info가 담당하는 입력을 구분합니다.
새 FPGA region 추가
37-44새 FPGA region 추가 예제는 `../../drivers/fpga/of-fpga-region.c`의 probe function에서 볼 수 있습니다. 개념적 Device Tree binding은 `../devicetree/bindings/fpga/fpga-region.txt`를 참조합니다.
.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
.. [#f2] ../../drivers/fpga/of-fpga-region.c새 FPGA region 등록 API
45-80새 region을 추가하는 핵심 API는 `struct fpga_region`, full registration parameter인 `struct fpga_region_info`, `__fpga_region_register_full()`, `__fpga_region_register()`, `fpga_region_unregister()`입니다.
Helper macro `fpga_region_register()`와 `fpga_region_register_full()`은 FPGA region을 등록한 module을 owner로 자동 설정합니다.
Region probe function은 programming에 사용할 FPGA manager reference를 얻어야 합니다. `fpga_mgr_get()`은 manager reference를 얻고 reference count를 증가시키며, `of_fpga_mgr_get()`은 device node를 사용해 같은 작업을 합니다. `fpga_mgr_put()`은 reference를 반환합니다.
Programming 중 제어할 bridge는 probe 시 `fpga_region->bridge_list`에 목록을 만들거나, programming 직전에 `fpga_region->get_bridges` callback으로 목록을 생성할 수 있습니다.
Bridge framework의 `fpga_bridge_get_to_list()`와 `of_fpga_bridge_get_to_list()`는 bridge reference를 얻어 목록에 추가하고, 후자는 device node를 받습니다. `fpga_bridges_put()`은 목록의 bridge reference를 반환합니다.
Region 등록 뒤 manager와 bridge reference를 준비하는 흐름입니다.
FPGA region kernel-doc
81-112Region structure와 registration info 문서는 `include/linux/fpga/fpga-region.h`에서 가져옵니다.
.. kernel-doc:: include/linux/fpga/fpga-region.h
:functions: fpga_region.. kernel-doc:: include/linux/fpga/fpga-region.h
:functions: fpga_region_infoRegion 등록·해제 function 문서는 `drivers/fpga/fpga-region.c`에서 가져옵니다.
.. kernel-doc:: drivers/fpga/fpga-region.c
:functions: __fpga_region_register_full.. kernel-doc:: drivers/fpga/fpga-region.c
:functions: __fpga_region_register.. kernel-doc:: drivers/fpga/fpga-region.c
:functions: fpga_region_unregisterManager reference function 문서는 `drivers/fpga/fpga-mgr.c`에서 가져옵니다.
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_get.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: of_fpga_mgr_get.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_putBridge 목록 function 문서는 `drivers/fpga/fpga-bridge.c`에서 가져옵니다.
.. kernel-doc:: drivers/fpga/fpga-bridge.c
:functions: fpga_bridge_get_to_list.. kernel-doc:: drivers/fpga/fpga-bridge.c
:functions: of_fpga_bridge_get_to_list.. kernel-doc:: drivers/fpga/fpga-bridge.c
:functions: fpga_bridges_put
요약과 해설
fpga-region.rst:1-112FPGA region은 programming을 수행할 manager와 격리할 bridge를 한 reconfigurable 영역으로 묶습니다. Driver는 region을 등록하고 manager·bridge reference를 준비한 뒤 programming 후 enumeration을 수행합니다.