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