요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
In-kernel API for FPGA Programming
==================================
Overview
--------
The in-kernel API for FPGA programming is a combination of APIs from
FPGA manager, bridge, and regions. The actual function used to
trigger FPGA programming is fpga_region_program_fpga().
fpga_region_program_fpga() uses functionality supplied by
the FPGA manager and bridges. It will:
* lock the region's mutex
* lock the mutex of the region's FPGA manager
* build a list of FPGA bridges if a method has been specified to do so
* disable the bridges
* program the FPGA using info passed in :c:expr:`fpga_region->info`.
* re-enable the bridges
* release the locks
The struct fpga_image_info specifies what FPGA image to program. It is
allocated/freed by fpga_image_info_alloc() and freed with
fpga_image_info_free()
How to program an FPGA using a region
-------------------------------------
When the FPGA region driver probed, it was given a pointer to an FPGA manager
driver so it knows which manager to use. The region also either has a list of
bridges to control during programming or it has a pointer to a function that
will generate that list. Here's some sample code of what to do next::
#include <linux/fpga/fpga-mgr.h>
#include <linux/fpga/fpga-region.h>
struct fpga_image_info *info;
int ret;
/*
* First, alloc the struct with information about the FPGA image to
* program.
*/
info = fpga_image_info_alloc(dev);
if (!info)
return -ENOMEM;
/* Set flags as needed, such as: */
info->flags = FPGA_MGR_PARTIAL_RECONFIG;
/*
* Indicate where the FPGA image is. This is pseudo-code; you're
* going to use one of these three.
*/
if (image is in a scatter gather table) {
info->sgt = [your scatter gather table]
} else if (image is in a buffer) {
info->buf = [your image buffer]
info->count = [image buffer size]
} else if (image is in a firmware file) {
info->firmware_name = devm_kstrdup(dev, firmware_name,
GFP_KERNEL);
}
/* Add info to region and do the programming */
region->info = info;
ret = fpga_region_program_fpga(region);
/* Deallocate the image info if you're done with it */
region->info = NULL;
fpga_image_info_free(info);
if (ret)
return ret;
/* Now enumerate whatever hardware has appeared in the FPGA. */
API for programming an FPGA
---------------------------
* fpga_region_program_fpga() - Program an FPGA
* fpga_image_info() - Specifies what FPGA image to program
* fpga_image_info_alloc() - Allocate an FPGA image info struct
* fpga_image_info_free() - Free an FPGA image info struct
.. kernel-doc:: drivers/fpga/fpga-region.c
:functions: fpga_region_program_fpga
FPGA Manager flags
.. kernel-doc:: include/linux/fpga/fpga-mgr.h
:doc: FPGA Manager flags
.. kernel-doc:: include/linux/fpga/fpga-mgr.h
:functions: fpga_image_info
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_image_info_alloc
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_image_info_free
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
커널 내부 FPGA programming API 개요
1-25문서 제목은 `In-kernel API for FPGA Programming`입니다.
커널 내부 FPGA programming API는 FPGA manager, bridge, region API의 조합입니다. 실제 programming을 시작하는 function은 `fpga_region_program_fpga()`입니다.
`fpga_region_program_fpga()`는 FPGA manager와 bridge가 제공하는 기능을 사용해 region mutex와 해당 region의 FPGA manager mutex를 잠급니다. Bridge 목록 생성 method가 지정되어 있으면 목록을 만들고, bridge를 disable한 뒤 `fpga_region->info`로 전달된 정보를 사용해 FPGA를 programming합니다. 이후 bridge를 다시 enable하고 lock을 해제합니다.
`struct fpga_image_info`는 programming할 FPGA image를 지정합니다. `fpga_image_info_alloc()`으로 할당하고 `fpga_image_info_free()`로 해제합니다.
Region과 manager lock, bridge 격리, image programming과 복구 순서입니다.
Region을 사용해 FPGA programming하기
26-83FPGA region driver가 probe될 때 사용할 FPGA manager driver pointer를 전달받습니다. Region은 programming 중 제어할 bridge 목록을 이미 갖거나, 그 목록을 생성하는 function pointer를 갖습니다. 그 다음 작업의 예제 코드는 아래와 같습니다.
#include <linux/fpga/fpga-mgr.h>
#include <linux/fpga/fpga-region.h>
struct fpga_image_info *info;
int ret;
/*
* First, alloc the struct with information about the FPGA image to
* program.
*/
info = fpga_image_info_alloc(dev);
if (!info)
return -ENOMEM;
/* Set flags as needed, such as: */
info->flags = FPGA_MGR_PARTIAL_RECONFIG;
/*
* Indicate where the FPGA image is. This is pseudo-code; you're
* going to use one of these three.
*/
if (image is in a scatter gather table) {
info->sgt = [your scatter gather table]
} else if (image is in a buffer) {
info->buf = [your image buffer]
info->count = [image buffer size]
} else if (image is in a firmware file) {
info->firmware_name = devm_kstrdup(dev, firmware_name,
GFP_KERNEL);
}
/* Add info to region and do the programming */
region->info = info;
ret = fpga_region_program_fpga(region);
/* Deallocate the image info if you're done with it */
region->info = NULL;
fpga_image_info_free(info);
if (ret)
return ret;
/* Now enumerate whatever hardware has appeared in the FPGA. */먼저 `fpga_image_info_alloc(dev)`로 image 정보를 할당하고 필요한 flag를 설정합니다. 예제의 `FPGA_MGR_PARTIAL_RECONFIG`는 partial reconfiguration image임을 나타냅니다.
Image 위치는 세 방식 중 하나로 지정합니다. Scatter-gather table이면 `info->sgt`, memory buffer이면 `info->buf`와 `info->count`, firmware file이면 `info->firmware_name`을 설정합니다.
준비한 `info`를 `region->info`에 연결하고 `fpga_region_program_fpga(region)`을 호출합니다. 완료 후 `region->info`를 `NULL`로 되돌리고 image info를 해제하며, 성공한 경우 FPGA 안에 새로 나타난 hardware를 enumerate합니다.
Programming image의 저장 방식별 필드입니다.
FPGA programming API
84-107FPGA programming API는 다음 항목으로 구성됩니다.
- `fpga_region_program_fpga()`: FPGA programming 실행
- `fpga_image_info`: programming할 FPGA image 지정
- `fpga_image_info_alloc()`: FPGA image info structure 할당
- `fpga_image_info_free()`: FPGA image info structure 해제
`fpga_region_program_fpga()` 문서는 `drivers/fpga/fpga-region.c`에서 가져옵니다.
.. kernel-doc:: drivers/fpga/fpga-region.c
:functions: fpga_region_program_fpgaFPGA Manager flag와 `fpga_image_info` 문서는 `include/linux/fpga/fpga-mgr.h`에서 가져옵니다.
.. kernel-doc:: include/linux/fpga/fpga-mgr.h
:doc: FPGA Manager flags.. kernel-doc:: include/linux/fpga/fpga-mgr.h
:functions: fpga_image_infoImage info 할당·해제 function 문서는 `drivers/fpga/fpga-mgr.c`에서 가져옵니다.
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_image_info_alloc.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_image_info_free
요약과 해설
fpga-programming.rst:1-107`fpga_region_program_fpga()`는 region과 manager lock을 획득하고 bridge를 격리한 뒤 `fpga_image_info`의 image를 programming합니다. Image는 scatter-gather table, contiguous buffer 또는 firmware file로 제공할 수 있습니다.