← Documents Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg GitHub 원문 ↗

Linux 6.18.37 · ABI / testing

QEMU fw_cfg sysfs ABI

Discoverable QEMU fw_cfg blobs의 authoritative selector-key entries, raw data와 best-effort file-name symlink tree를 설명합니다.

Source pathDocumentation/ABI/testing/sysfs-firmware-qemu_fw_cfg
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

Discoverable blobs and legacy limits

sysfs-firmware-qemu_fw_cfg:1-34

Sysfs는 file directory로 size와 presence를 확인할 수 있는 blobs만 내보내며 legacy 영역에서는 revision만 예외로 제공합니다.

Authoritative keys and convenient names

sysfs-firmware-qemu_fw_cfg:35-103

by_key가 authoritative inventory이고 by_name은 naming conflicts가 있으면 일부 entries를 생략할 수 있는 convenience view입니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
1 What: /sys/firmware/qemu_fw_cfg/
2 Date: August 2015
3 Contact: Gabriel Somlo <[email protected]>
4 Description:
5 Several different architectures supported by QEMU (x86, arm,
6 sun4*, ppc/mac) are provisioned with a firmware configuration
7 (fw_cfg) device, originally intended as a way for the host to
8 provide configuration data to the guest firmware. Starting
9 with QEMU v2.4, arbitrary fw_cfg file entries may be specified
10 by the user on the command line, which makes fw_cfg additionally
11 useful as an out-of-band, asynchronous mechanism for providing
12 configuration data to the guest userspace.
13
14 The authoritative guest-side hardware interface documentation
15 to the fw_cfg device can be found in "docs/specs/fw_cfg.rst"
16 in the QEMU source tree, or online at:
17 https://qemu-project.gitlab.io/qemu/specs/fw_cfg.html
18
19 **SysFS fw_cfg Interface**
20
21 The fw_cfg sysfs interface described in this document is only
22 intended to display discoverable blobs (i.e., those registered
23 with the file directory), as there is no way to determine the
24 presence or size of "legacy" blobs (with selector keys between
25 0x0002 and 0x0018) programmatically.
26
27 All fw_cfg information is shown under:
28
29 /sys/firmware/qemu_fw_cfg/
30
31 The only legacy blob displayed is the fw_cfg device revision:
32
33 /sys/firmware/qemu_fw_cfg/rev
34
35 **Discoverable fw_cfg blobs by selector key**
36
37 All discoverable blobs listed in the fw_cfg file directory are
38 displayed as entries named after their unique selector key
39 value, e.g.:
40
41 /sys/firmware/qemu_fw_cfg/by_key/32
42 /sys/firmware/qemu_fw_cfg/by_key/33
43 /sys/firmware/qemu_fw_cfg/by_key/34
44 ...
45
46 Each such fw_cfg sysfs entry has the following values exported
47 as attributes:
48
49 ==== ====================================================
50 name The 56-byte nul-terminated ASCII string used as the
51 blob's 'file name' in the fw_cfg directory.
52 size The length of the blob, as given in the fw_cfg
53 directory.
54 key The value of the blob's selector key as given in the
55 fw_cfg directory. This value is the same as used in
56 the parent directory name.
57 raw The raw bytes of the blob, obtained by selecting the
58 entry via the control register, and reading a number
59 of bytes equal to the blob size from the data
60 register.
61 ==== ====================================================
62
63 **Listing fw_cfg blobs by file name**
64
65 While the fw_cfg device does not impose any specific naming
66 convention on the blobs registered in the file directory,
67 QEMU developers have traditionally used path name semantics
68 to give each blob a descriptive name. For example::
69
70 "bootorder"
71 "genroms/kvmvapic.bin"
72 "etc/e820"
73 "etc/boot-fail-wait"
74 "etc/system-states"
75 "etc/table-loader"
76 "etc/acpi/rsdp"
77 "etc/acpi/tables"
78 "etc/smbios/smbios-tables"
79 "etc/smbios/smbios-anchor"
80 ...
81
82 In addition to the listing by unique selector key described
83 above, the fw_cfg sysfs driver also attempts to build a tree
84 of directories matching the path name components of fw_cfg
85 blob names, ending in symlinks to the by_key entry for each
86 "basename", as illustrated below (assume current directory is
87 /sys/firmware)::
88
89 qemu_fw_cfg/by_name/bootorder -> ../by_key/38
90 qemu_fw_cfg/by_name/etc/e820 -> ../../by_key/35
91 qemu_fw_cfg/by_name/etc/acpi/rsdp -> ../../../by_key/41
92 ...
93
94 Construction of the directory tree and symlinks is done on a
95 "best-effort" basis, as there is no guarantee that components
96 of fw_cfg blob names are always "well behaved". I.e., there is
97 the possibility that a symlink (basename) will conflict with
98 a dirname component of another fw_cfg blob, in which case the
99 creation of the offending /sys/firmware/qemu_fw_cfg/by_name
100 entry will be skipped.
101
102 The authoritative list of entries will continue to be found
103 under the /sys/firmware/qemu_fw_cfg/by_key directory.
104

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

QEMU fw_cfg sysfs interface

1-103
항목한국어 전문 번역
What/sys/firmware/qemu_fw_cfg/
Date2015년 8월
ContactGabriel Somlo <[email protected]>
DescriptionQEMU가 지원하는 x86, arm, sun4*, ppc/mac 등 여러 architectures에는 원래 host가 guest firmware에 configuration data를 제공하도록 만든 firmware configuration(`fw_cfg`) device가 있습니다. QEMU v2.4부터 user가 command line에서 임의의 fw_cfg file entries를 지정할 수 있어 guest userspace에 configuration data를 out-of-band·asynchronous 방식으로 전달하는 용도로도 쓸 수 있습니다. Guest-side hardware interface의 authoritative documentation은 QEMU source tree의 `docs/specs/fw_cfg.rst` 또는 `https://qemu-project.gitlab.io/qemu/specs/fw_cfg.html`에 있습니다. 이 sysfs interface는 file directory에 등록되어 discoverable한 blobs만 표시합니다. Selector keys가 `0x0002`부터 `0x0018` 사이인 legacy blobs는 presence나 size를 programmatically 알아낼 방법이 없기 때문입니다. 표시하는 유일한 legacy blob은 `/sys/firmware/qemu_fw_cfg/rev`의 device revision입니다. Discoverable blobs는 unique selector key를 이름으로 한 `/sys/firmware/qemu_fw_cfg/by_key/<key>` entries로 제공됩니다. 각 entry의 `name`은 fw_cfg directory에서 file name으로 쓰는 56-byte NUL-terminated ASCII string, `size`는 blob length, `key`는 parent directory name과 같은 selector key, `raw`는 control register로 entry를 선택한 뒤 data register에서 blob size만큼 읽은 raw bytes입니다. Blob names에 강제된 convention은 없지만 QEMU developers는 전통적으로 path-name semantics를 사용했습니다. Driver는 blob name의 path components와 맞는 `/sys/firmware/qemu_fw_cfg/by_name` directory tree를 만들고 각 basename을 `by_key` entry로 향하는 symlink로 구성하려고 합니다. 이 작업은 best-effort이며 blob-name component가 항상 올바르다고 보장할 수 없습니다. 한 blob의 symlink basename과 다른 blob의 directory component가 충돌하면 문제가 되는 `by_name` entry를 건너뜁니다. Authoritative entry list는 계속 `by_key` directory에 있습니다.
QEMU fw_cfg data path
Host or user defines fw_cfg dataQEMU exposes the fw_cfg deviceGuest driver reads the file directoryPublish discoverable blobs under by_keyBuild best-effort by_name symlinks

Host configuration에서 discoverable guest sysfs blobs까지의 흐름입니다.

Discoverable fw_cfg blob attributes
AttributeMeaning
name56-byte NUL-terminated ASCII file name
sizeBlob length from the fw_cfg directory
keySelector key; same as parent directory name
rawRaw blob bytes read through control and data registers

원문의 four-field table을 구조화했습니다.

fw_cfg lookup views
ViewFormAuthority
by_keyOne directory per selector keyAuthoritative
by_namePath tree ending in symlinksBest-effort
revDevice revisionOnly displayed legacy blob

Authoritative selector-key view와 best-effort name view의 차이입니다.

/sys/firmware/qemu_fw_cfg/by_key/32
/sys/firmware/qemu_fw_cfg/by_key/33
/sys/firmware/qemu_fw_cfg/by_key/34
...
"bootorder"
"genroms/kvmvapic.bin"
"etc/e820"
"etc/boot-fail-wait"
"etc/system-states"
"etc/table-loader"
"etc/acpi/rsdp"
"etc/acpi/tables"
"etc/smbios/smbios-tables"
"etc/smbios/smbios-anchor"
...
qemu_fw_cfg/by_name/bootorder -> ../by_key/38
qemu_fw_cfg/by_name/etc/e820 -> ../../by_key/35
qemu_fw_cfg/by_name/etc/acpi/rsdp -> ../../../by_key/41
...