1 ===================
2 Fallback mechanisms
3 ===================
4
5 A fallback mechanism is supported to allow to
6 filesystem lookup on the root filesystem or wh
7 installed for practical reasons on the root fi
8 configuration options related to supporting th
9
10 * CONFIG_FW_LOADER_USER_HELPER: enables buil
11 mechanism. Most distributions enable this
12 CONFIG_FW_LOADER_USER_HELPER_FALLBACK is d
13 mechanism is available and for the request
14 * CONFIG_FW_LOADER_USER_HELPER_FALLBACK: for
15 enable the kobject uevent fallback mechani
16 except request_firmware_direct(). Most dis
17 today. The call request_firmware_nowait()
18 fallback mechanism: if this kconfig option
19 argument to request_firmware_nowait(), uev
20 informing the kernel that you have a custo
21 manually load the firmware. Read below for
22
23 Note that this means when having this configur
24
25 CONFIG_FW_LOADER_USER_HELPER=y
26 CONFIG_FW_LOADER_USER_HELPER_FALLBACK=n
27
28 the kobject uevent fallback mechanism will nev
29 for request_firmware_nowait() when uevent is s
30
31 Justifying the firmware fallback mechanism
32 ==========================================
33
34 Direct filesystem lookups may fail for a varie
35 this are worth itemizing and documenting as it
36 fallback mechanism:
37
38 * Race against access with the root filesystem
39
40 * Races upon resume from suspend. This is reso
41 the firmware cache is only supported if you
42 supported for request_firmware_into_buf().
43
44 * Firmware is not accessible through typical m
45
46 * It cannot be installed into the root
47 * The firmware provides very unique de
48 the unit gathered with local informa
49 data for WiFi chipsets for mobile de
50 not common to all units, but tailore
51 be installed on a separate flash par
52 filesystem is provided.
53
54 Types of fallback mechanisms
55 ============================
56
57 There are really two fallback mechanisms avail
58 interface as a loading facility:
59
60 * Kobject uevent fallback mechanism
61 * Custom fallback mechanism
62
63 First lets document the shared sysfs loading f
64
65 Firmware sysfs loading facility
66 ===============================
67
68 In order to help device drivers upload firmwar
69 the firmware infrastructure creates a sysfs in
70 to load and indicate when firmware is ready. T
71 via fw_create_instance(). This call creates a
72 the firmware requested, and establishes it in
73 associating the device used to make the reques
74 The sysfs directory's file attributes are defi
75 the new device's class (firmware_class) and gr
76 This is actually where the original firmware_c
77 given that originally the only firmware loadin
78 mechanism we now use as a fallback mechanism,
79 firmware_class. Because the attributes exposed
80 module name firmware_class cannot be renamed i
81 compatibility with old userspace.
82
83 To load firmware using the sysfs interface we
84 and a file upload firmware into:
85
86 * /sys/$DEVPATH/loading
87 * /sys/$DEVPATH/data
88
89 To upload firmware you will echo 1 onto the lo
90 you are loading firmware. You then write the f
91 and you notify the kernel the firmware is read
92 the loading file.
93
94 The firmware device used to help load firmware
95 direct firmware loading fails and if the fallb
96 firmware request, this is set up with :c:func:
97 important to re-iterate that no device is crea
98 succeeded.
99
100 Using::
101
102 echo 1 > /sys/$DEVPATH/loading
103
104 Will clean any previous partial load at once a
105 return an error. When loading firmware the fir
106 for the firmware in PAGE_SIZE increments to ho
107
108 firmware_data_read() and firmware_loading_show
109 test_firmware driver for testing, they are not
110 expected to be used regularly by userspace.
111
112 firmware_fallback_sysfs
113 -----------------------
114 .. kernel-doc:: drivers/base/firmware_loader/f
115 :functions: firmware_fallback_sysfs
116
117 Firmware kobject uevent fallback mechanism
118 ==========================================
119
120 Since a device is created for the sysfs interf
121 fallback mechanism userspace can be informed o
122 relying on kobject uevents. The addition of th
123 hierarchy means the fallback mechanism for fir
124 For details of implementation refer to fw_load
125 on the use of dev_set_uevent_suppress() and ko
126
127 The kernel's kobject uevent mechanism is imple
128 it issues uevents to userspace. As a supplemen
129 distributions could also enable CONFIG_UEVENT_
130 core kernel's usermode helper (UMH) functional
131 helper for kobject uevents. In practice though
132 ever used the CONFIG_UEVENT_HELPER_PATH. If CO
133 enabled this binary would be called each time
134 in the kernel for each kobject uevent triggere
135
136 Different implementations have been supported
137 this fallback mechanism. When firmware loading
138 sysfs mechanism the userspace component "hotpl
139 monitoring for kobject events. Historically th
140 udev, however firmware loading support was rem
141 commit be2ea723b1d0 ("udev: remove userspace f
142 as of v217 on August, 2014. This means most Li
143 not using or taking advantage of the firmware
144 by kobject uevents. This is specially exacerba
145 distributions today disable CONFIG_FW_LOADER_U
146
147 Refer to do_firmware_uevent() for details of t
148 setup. The variables currently passed to users
149 event are:
150
151 * FIRMWARE=firmware name
152 * TIMEOUT=timeout value
153 * ASYNC=whether or not the API request was asy
154
155 By default DEVPATH is set by the internal kern
156 Below is an example simple kobject uevent scri
157
158 # Both $DEVPATH and $FIRMWARE are alre
159 MY_FW_DIR=/lib/firmware/
160 echo 1 > /sys/$DEVPATH/loading
161 cat $MY_FW_DIR/$FIRMWARE > /sys/$DEVPA
162 echo 0 > /sys/$DEVPATH/loading
163
164 Firmware custom fallback mechanism
165 ==================================
166
167 Users of the request_firmware_nowait() call ha
168 at their disposal: rely on the sysfs fallback
169 kobject uevents be issued to userspace. The or
170 was that utilities other than udev might be re
171 in non-traditional paths -- paths outside of t
172 section 'Direct filesystem lookup'. This optio
173 the other API calls as uevents are always forc
174
175 Since uevents are only meaningful if the fallb
176 in your kernel it would seem odd to enable uev
177 have the fallback mechanism enabled in their k
178 rely on the uevent flag which can be disabled
179 also setup the firmware cache for firmware req
180 the firmware cache is only set up if uevent is
181 Although this can disable the firmware cache f
182 calls, users of this API should not use it for
183 the cache as that was not the original purpose
184 the uevent flag means you want to opt-in for t
185 but you want to suppress kobject uevents, as y
186 will monitor for your device addition into the
187 load firmware for you through a custom path.
188
189 Firmware fallback timeout
190 =========================
191
192 The firmware fallback mechanism has a timeout.
193 onto the sysfs interface by the timeout value
194 driver. By default the timeout is set to 60 se
195 desirable, otherwise MAX_JIFFY_OFFSET is used
196 The logic behind using MAX_JIFFY_OFFSET for no
197 solution will have as much time as it needs to
198
199 You can customize the firmware timeout by echo
200 the following file:
201
202 * /sys/class/firmware/timeout
203
204 If you echo 0 into it means MAX_JIFFY_OFFSET w
205 for the timeout is an int.
206
207 EFI embedded firmware fallback mechanism
208 ========================================
209
210 On some devices the system's EFI code / ROM ma
211 of firmware for some of the system's integrate
212 the peripheral's Linux device-driver needs to
213
214 Device drivers which need such firmware can us
215 firmware_request_platform() function for this,
216 separate fallback mechanism from the other fal
217 this does not use the sysfs interface.
218
219 A device driver which needs this can describe
220 using an efi_embedded_fw_desc struct:
221
222 .. kernel-doc:: include/linux/efi_embedded_fw.
223 :functions: efi_embedded_fw_desc
224
225 The EFI embedded-fw code works by scanning all
226 segments for an eight byte sequence matching p
227 then does a sha256 over length bytes and if th
228 bytes and adds that to its list with found fir
229
230 To avoid doing this somewhat expensive scan on
231 used. Drivers are expected to export a dmi_sys
232 driver_data pointing to an efi_embedded_fw_des
233
234 To register this array with the efi-embedded-f
235
236 1. Always be builtin to the kernel or store th
237 separate object file which always gets buil
238
239 2. Add an extern declaration for the dmi_syste
240 include/linux/efi_embedded_fw.h.
241
242 3. Add the dmi_system_id array to the embedded
243 drivers/firmware/efi/embedded-firmware.c wr
244 the driver is being builtin.
245
246 4. Add "select EFI_EMBEDDED_FIRMWARE if EFI_ST
247
248 The firmware_request_platform() function will
249 with the specified name directly from the disk
250 always be overridden by placing a file under /
251
252 Note that:
253
254 1. The code scanning for EFI embedded-firmware
255 of start_kernel(), just before calling rest
256 subsystems using subsys_initcall() to regis
257 matter. This means that code running earlie
258 embedded-firmware.
259
260 2. At the moment the EFI embedded-fw code assu
261 an offset which is a multiple of 8 bytes, i
262 send in a patch to fix this.
263
264 3. At the moment the EFI embedded-fw code only
265 free EFI_BOOT_SERVICES_CODE before the EFI
266 scan it.
267
268 4. The current brute-force scanning of EFI_BOO
269 brute-force solution. There has been discus
270 Initialization (PI) spec's Firmware Volume
271 because the FV Protocol relies on *internal
272 1. The PI spec does not define peripheral f
273 2. The internal interfaces of the PI spec d
274 compatibility. Any implementation details i
275 and may vary system to system. Supporting t
276 difficult as it is purposely ambiguous.
277
278 Example how to check for and extract embedded
279 ----------------------------------------------
280
281 To check for, for example Silead touchscreen c
282 do the following:
283
284 1. Boot the system with efi=debug on the kerne
285
286 2. cp /sys/kernel/debug/efi/boot_services_code
287
288 3. Open the boot_services_code? files in a hex
289 magic prefix for Silead firmware: F0 00 00
290 the beginning address of the firmware insid
291
292 4. The firmware has a specific pattern, it sta
293 typically F0 00 00 00 02 00 00 00 for the f
294 word-address + 32-bit value pairs. With the
295 bytes (1 word) for each pair until a page i
296 followed by a new page-address, followed by
297 leads to a very distinct pattern. Scroll do
298 this gives you the end of the firmware insi
299
300 5. "dd if=boot_services_code? of=firmware bs=1
301 will extract the firmware for you. Inspect
302 hexeditor to make sure you got the dd param
303
304 6. Copy it to /lib/firmware under the expected
305
306 7. If the extracted firmware works, you can us
307 efi_embedded_fw_desc struct to describe it,
308 to get the sha256sum to put in the sha256 f
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.