요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
====================
request_firmware API
====================
You would typically load firmware and then load it into your device somehow.
The typical firmware work flow is reflected below::
if(request_firmware(&fw_entry, $FIRMWARE, device) == 0)
copy_fw_to_device(fw_entry->data, fw_entry->size);
release_firmware(fw_entry);
Synchronous firmware requests
=============================
Synchronous firmware requests will wait until the firmware is found or until
an error is returned.
request_firmware
----------------
.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware
firmware_request_nowarn
-----------------------
.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: firmware_request_nowarn
firmware_request_platform
-------------------------
.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: firmware_request_platform
request_firmware_direct
-----------------------
.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware_direct
request_firmware_into_buf
-------------------------
.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware_into_buf
Asynchronous firmware requests
==============================
Asynchronous firmware requests allow driver code to not have to wait
until the firmware or an error is returned. Function callbacks are
provided so that when the firmware or an error is found the driver is
informed through the callback. request_firmware_nowait() cannot be called
in atomic contexts.
request_firmware_nowait
-----------------------
.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware_nowait
Special optimizations on reboot
===============================
Some devices have an optimization in place to enable the firmware to be
retained during system reboot. When such optimizations are used the driver
author must ensure the firmware is still available on resume from suspend,
this can be done with firmware_request_cache() instead of requesting for the
firmware to be loaded.
firmware_request_cache()
------------------------
.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: firmware_request_cache
request firmware API expected driver use
========================================
Once an API call returns you process the firmware and then release the
firmware. For example if you used request_firmware() and it returns,
the driver has the firmware image accessible in fw_entry->{data,size}.
If something went wrong request_firmware() returns non-zero and fw_entry
is set to NULL. Once your driver is done with processing the firmware it
can call release_firmware(fw_entry) to release the firmware image
and any related resource.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
일반적인 firmware workflow
1-11문서 제목은 `request_firmware API`입니다.
일반적으로 firmware를 load한 다음 어떤 방식으로든 device에 기록합니다. 아래 예는 `request_firmware()`가 성공하면 `fw_entry->data`와 `fw_entry->size`를 device로 복사하고, 마지막에 `release_firmware()`로 resource를 해제하는 전형적인 workflow입니다.
if(request_firmware(&fw_entry, $FIRMWARE, device) == 0)
copy_fw_to_device(fw_entry->data, fw_entry->size);
release_firmware(fw_entry);Request, device programming, release의 필수 생명주기입니다.
Synchronous firmware request
12-42Synchronous firmware request는 firmware를 찾거나 error가 반환될 때까지 기다립니다.
기본 `request_firmware`, warning을 억제하는 `firmware_request_nowarn`, platform fallback을 포함하는 `firmware_request_platform`, direct lookup용 `request_firmware_direct`, caller buffer를 사용하는 `request_firmware_into_buf`가 제공됩니다.
.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: firmware_request_nowarn.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: firmware_request_platform.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware_direct.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware_into_buf동일한 blocking 모델에서 lookup 방식과 buffer 정책이 다른 API입니다.
Asynchronous firmware request
43-56Asynchronous firmware request를 사용하면 driver code가 firmware 또는 error가 반환될 때까지 기다릴 필요가 없습니다. Firmware나 error를 찾으면 callback을 통해 driver에 알립니다.
`request_firmware_nowait()`은 atomic context에서 호출할 수 없습니다.
.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: request_firmware_nowaitReboot 최적화와 firmware cache
57-70일부 device에는 system reboot 동안 firmware를 유지하는 최적화가 있습니다. 이 방식을 사용하면 driver 작성자는 suspend에서 resume할 때도 firmware가 여전히 사용 가능한지 보장해야 합니다.
Firmware를 다시 load하도록 request하는 대신 `firmware_request_cache()`를 사용해 이를 보장할 수 있습니다.
.. kernel-doc:: drivers/base/firmware_loader/main.c
:functions: firmware_request_cacheDriver의 예상 API 사용법
71-80API call이 반환되면 firmware를 처리한 뒤 release해야 합니다. `request_firmware()`가 성공하면 driver는 `fw_entry->{data,size}`를 통해 firmware image에 접근할 수 있습니다.
문제가 생기면 `request_firmware()`는 0이 아닌 값을 반환하고 `fw_entry`를 NULL로 설정합니다. Driver가 firmware 처리를 마치면 `release_firmware(fw_entry)`를 호출해 firmware image와 관련 resource를 해제합니다.
Return value와 fw_entry 상태에 따른 driver 동작입니다.
요약과 해설
request_firmware.rst:1-80Firmware API는 blocking synchronous 변형과 callback 기반 asynchronous 변형을 제공합니다. Direct·platform·caller-buffer 등 lookup 요구에 맞는 API를 선택하고 atomic context에서는 nowait API를 호출하지 않아야 합니다.
성공한 request의 `fw_entry->{data,size}`를 처리한 뒤 반드시 `release_firmware()`를 호출합니다. Reboot 때 firmware를 유지하는 device도 suspend/resume 안전성을 위해 `firmware_request_cache()`를 사용할 수 있습니다.