Xsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget;/translations/zh_CN/driver-api/firmware/fallback-mechanismsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget;/translations/zh_TW/driver-api/firmware/fallback-mechanismsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget;/translations/it_IT/driver-api/firmware/fallback-mechanismsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget;/translations/ja_JP/driver-api/firmware/fallback-mechanismsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget;/translations/ko_KR/driver-api/firmware/fallback-mechanismsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget;/translations/pt_BR/driver-api/firmware/fallback-mechanismsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget;/translations/sp_SP/driver-api/firmware/fallback-mechanismsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hFallback mechanismsh]hFallback mechanisms}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhU/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms.rsthKubh paragraph)}(hX1A fallback mechanism is supported to allow to overcome failures to do a direct filesystem lookup on the root filesystem or when the firmware simply cannot be installed for practical reasons on the root filesystem. The kernel configuration options related to supporting the firmware fallback mechanism are:h]hX1A fallback mechanism is supported to allow to overcome failures to do a direct filesystem lookup on the root filesystem or when the firmware simply cannot be installed for practical reasons on the root filesystem. The kernel configuration options related to supporting the firmware fallback mechanism are:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh block_quote)}(hX^* CONFIG_FW_LOADER_USER_HELPER: enables building the firmware fallback mechanism. Most distributions enable this option today. If enabled but CONFIG_FW_LOADER_USER_HELPER_FALLBACK is disabled, only the custom fallback mechanism is available and for the request_firmware_nowait() call. * CONFIG_FW_LOADER_USER_HELPER_FALLBACK: force enables each request to enable the kobject uevent fallback mechanism on all firmware API calls except request_firmware_direct(). Most distributions disable this option today. The call request_firmware_nowait() allows for one alternative fallback mechanism: if this kconfig option is enabled and your second argument to request_firmware_nowait(), uevent, is set to false you are informing the kernel that you have a custom fallback mechanism and it will manually load the firmware. Read below for more details. h]h bullet_list)}(hhh](h list_item)}(hXCONFIG_FW_LOADER_USER_HELPER: enables building the firmware fallback mechanism. Most distributions enable this option today. If enabled but CONFIG_FW_LOADER_USER_HELPER_FALLBACK is disabled, only the custom fallback mechanism is available and for the request_firmware_nowait() call.h]h)}(hXCONFIG_FW_LOADER_USER_HELPER: enables building the firmware fallback mechanism. Most distributions enable this option today. If enabled but CONFIG_FW_LOADER_USER_HELPER_FALLBACK is disabled, only the custom fallback mechanism is available and for the request_firmware_nowait() call.h]hXCONFIG_FW_LOADER_USER_HELPER: enables building the firmware fallback mechanism. Most distributions enable this option today. If enabled but CONFIG_FW_LOADER_USER_HELPER_FALLBACK is disabled, only the custom fallback mechanism is available and for the request_firmware_nowait() call.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhubah}(h]h ]h"]h$]h&]uh1hhhubh)}(hX+CONFIG_FW_LOADER_USER_HELPER_FALLBACK: force enables each request to enable the kobject uevent fallback mechanism on all firmware API calls except request_firmware_direct(). Most distributions disable this option today. The call request_firmware_nowait() allows for one alternative fallback mechanism: if this kconfig option is enabled and your second argument to request_firmware_nowait(), uevent, is set to false you are informing the kernel that you have a custom fallback mechanism and it will manually load the firmware. Read below for more details. h]h)}(hX*CONFIG_FW_LOADER_USER_HELPER_FALLBACK: force enables each request to enable the kobject uevent fallback mechanism on all firmware API calls except request_firmware_direct(). Most distributions disable this option today. The call request_firmware_nowait() allows for one alternative fallback mechanism: if this kconfig option is enabled and your second argument to request_firmware_nowait(), uevent, is set to false you are informing the kernel that you have a custom fallback mechanism and it will manually load the firmware. Read below for more details.h]hX*CONFIG_FW_LOADER_USER_HELPER_FALLBACK: force enables each request to enable the kobject uevent fallback mechanism on all firmware API calls except request_firmware_direct(). Most distributions disable this option today. The call request_firmware_nowait() allows for one alternative fallback mechanism: if this kconfig option is enabled and your second argument to request_firmware_nowait(), uevent, is set to false you are informing the kernel that you have a custom fallback mechanism and it will manually load the firmware. Read below for more details.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]bullet*uh1hhhhK hhubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(h4Note that this means when having this configuration:h]h4Note that this means when having this configuration:}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hFCONFIG_FW_LOADER_USER_HELPER=y CONFIG_FW_LOADER_USER_HELPER_FALLBACK=nh]hFCONFIG_FW_LOADER_USER_HELPER=y CONFIG_FW_LOADER_USER_HELPER_FALLBACK=n}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(h{the kobject uevent fallback mechanism will never take effect even for request_firmware_nowait() when uevent is set to true.h]h{the kobject uevent fallback mechanism will never take effect even for request_firmware_nowait() when uevent is set to true.}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h*Justifying the firmware fallback mechanismh]h*Justifying the firmware fallback mechanism}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhjPhhhhhK ubh)}(hDirect filesystem lookups may fail for a variety of reasons. Known reasons for this are worth itemizing and documenting as it justifies the need for the fallback mechanism:h]hDirect filesystem lookups may fail for a variety of reasons. Known reasons for this are worth itemizing and documenting as it justifies the need for the fallback mechanism:}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK"hjPhhubh)}(hhh](h)}(h:Race against access with the root filesystem upon bootup. h]h)}(h9Race against access with the root filesystem upon bootup.h]h9Race against access with the root filesystem upon bootup.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK&hjrubah}(h]h ]h"]h$]h&]uh1hhjohhhhhNubh)}(hRaces upon resume from suspend. This is resolved by the firmware cache, but the firmware cache is only supported if you use uevents, and its not supported for request_firmware_into_buf(). h]h)}(hRaces upon resume from suspend. This is resolved by the firmware cache, but the firmware cache is only supported if you use uevents, and its not supported for request_firmware_into_buf().h]hRaces upon resume from suspend. This is resolved by the firmware cache, but the firmware cache is only supported if you use uevents, and its not supported for request_firmware_into_buf().}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hjubah}(h]h ]h"]h$]h&]uh1hhjohhhhhNubh)}(hX Firmware is not accessible through typical means: * It cannot be installed into the root filesystem * The firmware provides very unique device specific data tailored for the unit gathered with local information. An example is calibration data for WiFi chipsets for mobile devices. This calibration data is not common to all units, but tailored per unit. Such information may be installed on a separate flash partition other than where the root filesystem is provided. h](h)}(h1Firmware is not accessible through typical means:h]h1Firmware is not accessible through typical means:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK,hjubh)}(hX* It cannot be installed into the root filesystem * The firmware provides very unique device specific data tailored for the unit gathered with local information. An example is calibration data for WiFi chipsets for mobile devices. This calibration data is not common to all units, but tailored per unit. Such information may be installed on a separate flash partition other than where the root filesystem is provided. h]h)}(hhh](h)}(h/It cannot be installed into the root filesystemh]h)}(hjh]h/It cannot be installed into the root filesystem}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(hXoThe firmware provides very unique device specific data tailored for the unit gathered with local information. An example is calibration data for WiFi chipsets for mobile devices. This calibration data is not common to all units, but tailored per unit. Such information may be installed on a separate flash partition other than where the root filesystem is provided. h]h)}(hXnThe firmware provides very unique device specific data tailored for the unit gathered with local information. An example is calibration data for WiFi chipsets for mobile devices. This calibration data is not common to all units, but tailored per unit. Such information may be installed on a separate flash partition other than where the root filesystem is provided.h]hXnThe firmware provides very unique device specific data tailored for the unit gathered with local information. An example is calibration data for WiFi chipsets for mobile devices. This calibration data is not common to all units, but tailored per unit. Such information may be installed on a separate flash partition other than where the root filesystem is provided.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK/hjubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]jjuh1hhhhK.hjubah}(h]h ]h"]h$]h&]uh1hhhhK.hjubeh}(h]h ]h"]h$]h&]uh1hhjohhhhhNubeh}(h]h ]h"]h$]h&]jjuh1hhhhK&hjPhhubeh}(h]*justifying-the-firmware-fallback-mechanismah ]h"]*justifying the firmware fallback mechanismah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(hTypes of fallback mechanismsh]hTypes of fallback mechanisms}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhK7ubh)}(hjThere are really two fallback mechanisms available using one shared sysfs interface as a loading facility:h]hjThere are really two fallback mechanisms available using one shared sysfs interface as a loading facility:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hj hhubh)}(hhh](h)}(h!Kobject uevent fallback mechanismh]h)}(hj.h]h!Kobject uevent fallback mechanism}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK /sys/$DEVPATH/loadingh]hecho 1 > /sys/$DEVPATH/loading}hj;sbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1j9hhhKfhjwhhubh)}(hWill clean any previous partial load at once and make the firmware API return an error. When loading firmware the firmware_class grows a buffer for the firmware in PAGE_SIZE increments to hold the image as it comes in.h]hWill clean any previous partial load at once and make the firmware API return an error. When loading firmware the firmware_class grows a buffer for the firmware in PAGE_SIZE increments to hold the image as it comes in.}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhjwhhubh)}(hfirmware_data_read() and firmware_loading_show() are just provided for the test_firmware driver for testing, they are not called in normal use or expected to be used regularly by userspace.h]hfirmware_data_read() and firmware_loading_show() are just provided for the test_firmware driver for testing, they are not called in normal use or expected to be used regularly by userspace.}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKlhjwhhubh)}(hhh](h)}(hfirmware_fallback_sysfsh]hfirmware_fallback_sysfs}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjghhhhhKqubhindex)}(hhh]h}(h]h ]h"]h$]h&]entries](single$firmware_fallback_sysfs (C function)c.firmware_fallback_sysfshNtauh1jxhjghhhNhNubhdesc)}(hhh](hdesc_signature)}(hrint firmware_fallback_sysfs (struct firmware *fw, const char *name, struct device *device, u32 opt_flags, int ret)h]hdesc_signature_line)}(hqint firmware_fallback_sysfs(struct firmware *fw, const char *name, struct device *device, u32 opt_flags, int ret)h](hdesc_sig_keyword_type)}(hinth]hint}(hjhhhNhNubah}(h]h ]ktah"]h$]h&]uh1jhjhhh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKubhdesc_sig_space)}(h h]h }(hjhhhNhNubah}(h]h ]wah"]h$]h&]uh1jhjhhhjhKubh desc_name)}(hfirmware_fallback_sysfsh]h desc_sig_name)}(hfirmware_fallback_sysfsh]hfirmware_fallback_sysfs}(hjhhhNhNubah}(h]h ]nah"]h$]h&]uh1jhjubah}(h]h ](sig-namedescnameeh"]h$]h&]jIjJuh1jhjhhhjhKubhdesc_parameterlist)}(hV(struct firmware *fw, const char *name, struct device *device, u32 opt_flags, int ret)h](hdesc_parameter)}(hstruct firmware *fwh](hdesc_sig_keyword)}(hstructh]hstruct}(hjhhhNhNubah}(h]h ]kah"]h$]h&]uh1jhjubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubh)}(hhh]j)}(hfirmwareh]hfirmware}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&] refdomainj reftype identifier reftargetj modnameN classnameN c:parent_keysphinx.domains.c LookupKey)}data]j% ASTIdentifier)}j jsbc.firmware_fallback_sysfsasbuh1hhjubj)}(h h]h }(hj2hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubhdesc_sig_punctuation)}(hjh]h*}(hjBhhhNhNubah}(h]h ]pah"]h$]h&]uh1j@hjubj)}(hfwh]hfw}(hjPhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphjIjJuh1jhjubj)}(hconst char *nameh](j)}(hconsth]hconst}(hjihhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjeubj)}(h h]h }(hjwhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjeubj)}(hcharh]hchar}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjeubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjeubjA)}(hjh]h*}(hjhhhNhNubah}(h]h ]jLah"]h$]h&]uh1j@hjeubj)}(hnameh]hname}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjeubeh}(h]h ]h"]h$]h&]noemphjIjJuh1jhjubj)}(hstruct device *deviceh](j)}(hjh]hstruct}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubh)}(hhh]j)}(hdeviceh]hdevice}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&] refdomainj reftypej  reftargetjmodnameN classnameNj$j')}j*]j.c.firmware_fallback_sysfsasbuh1hhjubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubjA)}(hjh]h*}(hjhhhNhNubah}(h]h ]jLah"]h$]h&]uh1j@hjubj)}(hdeviceh]hdevice}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphjIjJuh1jhjubj)}(h u32 opt_flagsh](h)}(hhh]j)}(hu32h]hu32}(hj:hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj7ubah}(h]h ]h"]h$]h&] refdomainj reftypej  reftargetj<modnameN classnameNj$j')}j*]j.c.firmware_fallback_sysfsasbuh1hhj3ubj)}(h h]h }(hjXhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj3ubj)}(h opt_flagsh]h opt_flags}(hjfhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj3ubeh}(h]h ]h"]h$]h&]noemphjIjJuh1jhjubj)}(hint reth](j)}(hinth]hint}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj{ubj)}(h h]h }(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj{ubj)}(hreth]hret}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj{ubeh}(h]h ]h"]h$]h&]noemphjIjJuh1jhjubeh}(h]h ]h"]h$]h&]jIjJuh1jhjhhhjhKubeh}(h]h ]h"]h$]h&]jIjJ add_permalinkuh1jsphinx_line_type declaratorhjhhhjhKubah}(h]jah ](sig sig-objecteh"]h$]h&] is_multiline _toc_parts) _toc_namehuh1jhjhKhjhhubh desc_content)}(hhh]h)}(h+use the fallback mechanism to find firmwareh]h+use the fallback mechanism to find firmware}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKhjhhubah}(h]h ]h"]h$]h&]uh1jhjhhhjhKubeh}(h]h ](j functioneh"]h$]h&]domainj objtypejdesctypejnoindex noindexentrynocontentsentryuh1jhhhjghNhNubh container)}(hX**Parameters** ``struct firmware *fw`` pointer to firmware image ``const char *name`` name of firmware file to look for ``struct device *device`` device for which firmware is being loaded ``u32 opt_flags`` options to control firmware loading behaviour, as defined by :c:type:`enum fw_opt ` ``int ret`` return value from direct lookup which triggered the fallback mechanism **Description** This function is called if direct lookup for the firmware failed, it enables a fallback mechanism through userspace by exposing a sysfs loading interface. Userspace is in charge of loading the firmware through the sysfs loading interface. This sysfs fallback mechanism may be disabled completely on a system by setting the proc sysctl value ignore_sysfs_fallback to true. If this is false we check if the internal API caller set the **FW_OPT_NOFALLBACK_SYSFS** flag, if so it would also disable the fallback mechanism. A system may want to enforce the sysfs fallback mechanism at all times, it can do this by setting ignore_sysfs_fallback to false and force_sysfs_fallback to true. Enabling force_sysfs_fallback is functionally equivalent to build a kernel with CONFIG_FW_LOADER_USER_HELPER_FALLBACK.h](h)}(h**Parameters**h]hstrong)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKhjubhdefinition_list)}(hhh](hdefinition_list_item)}(h2``struct firmware *fw`` pointer to firmware image h](hterm)}(h``struct firmware *fw``h]j)}(hj h]hstruct firmware *fw}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKhjubh definition)}(hhh]h)}(hpointer to firmware imageh]hpointer to firmware image}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj5hKhj8ubah}(h]h ]h"]h$]h&]uh1j6hjubeh}(h]h ]h"]h$]h&]uh1jhj5hKhjubj)}(h7``const char *name`` name of firmware file to look for h](j)}(h``const char *name``h]j)}(hj[h]hconst char *name}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjYubah}(h]h ]h"]h$]h&]uh1jh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKhjUubj7)}(hhh]h)}(h!name of firmware file to look forh]h!name of firmware file to look for}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhjphKhjqubah}(h]h ]h"]h$]h&]uh1j6hjUubeh}(h]h ]h"]h$]h&]uh1jhjphKhjubj)}(hD``struct device *device`` device for which firmware is being loaded h](j)}(h``struct device *device``h]j)}(hjh]hstruct device *device}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKhjubj7)}(hhh]h)}(h)device for which firmware is being loadedh]h)device for which firmware is being loaded}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1j6hjubeh}(h]h ]h"]h$]h&]uh1jhjhKhjubj)}(hn``u32 opt_flags`` options to control firmware loading behaviour, as defined by :c:type:`enum fw_opt ` h](j)}(h``u32 opt_flags``h]j)}(hjh]h u32 opt_flags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKhjubj7)}(hhh]h)}(h[options to control firmware loading behaviour, as defined by :c:type:`enum fw_opt `h](h=options to control firmware loading behaviour, as defined by }(hjhhhNhNubh)}(h:c:type:`enum fw_opt `h]j)}(hjh]h enum fw_opt}(hjhhhNhNubah}(h]h ](j j c-typeeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj refdomainj reftypetype refexplicitrefwarnj$j')}j*]sbjfw_optuh1hh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKhjubeh}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1j6hjubeh}(h]h ]h"]h$]h&]uh1jhjhKhjubj)}(hS``int ret`` return value from direct lookup which triggered the fallback mechanism h](j)}(h ``int ret``h]j)}(hj)h]hint ret}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj'ubah}(h]h ]h"]h$]h&]uh1jh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKhj#ubj7)}(hhh]h)}(hFreturn value from direct lookup which triggered the fallback mechanismh]hFreturn value from direct lookup which triggered the fallback mechanism}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>hKhj?ubah}(h]h ]h"]h$]h&]uh1j6hj#ubeh}(h]h ]h"]h$]h&]uh1jhj>hKhjubeh}(h]h ]h"]h$]h&]uh1jhjubh)}(h**Description**h]j)}(hjdh]h Description}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjbubah}(h]h ]h"]h$]h&]uh1hh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKhjubh)}(hX This function is called if direct lookup for the firmware failed, it enables a fallback mechanism through userspace by exposing a sysfs loading interface. Userspace is in charge of loading the firmware through the sysfs loading interface. This sysfs fallback mechanism may be disabled completely on a system by setting the proc sysctl value ignore_sysfs_fallback to true. If this is false we check if the internal API caller set the **FW_OPT_NOFALLBACK_SYSFS** flag, if so it would also disable the fallback mechanism. A system may want to enforce the sysfs fallback mechanism at all times, it can do this by setting ignore_sysfs_fallback to false and force_sysfs_fallback to true. Enabling force_sysfs_fallback is functionally equivalent to build a kernel with CONFIG_FW_LOADER_USER_HELPER_FALLBACK.h](hXThis function is called if direct lookup for the firmware failed, it enables a fallback mechanism through userspace by exposing a sysfs loading interface. Userspace is in charge of loading the firmware through the sysfs loading interface. This sysfs fallback mechanism may be disabled completely on a system by setting the proc sysctl value ignore_sysfs_fallback to true. If this is false we check if the internal API caller set the }(hjzhhhNhNubj)}(h**FW_OPT_NOFALLBACK_SYSFS**h]hFW_OPT_NOFALLBACK_SYSFS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjzubhXT flag, if so it would also disable the fallback mechanism. A system may want to enforce the sysfs fallback mechanism at all times, it can do this by setting ignore_sysfs_fallback to false and force_sysfs_fallback to true. Enabling force_sysfs_fallback is functionally equivalent to build a kernel with CONFIG_FW_LOADER_USER_HELPER_FALLBACK.}(hjzhhhNhNubeh}(h]h ]h"]h$]h&]uh1hh/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:114: ./drivers/base/firmware_loader/fallback.chKhjubeh}(h]h ] kernelindentah"]h$]h&]uh1jhjghhhNhNubeh}(h]firmware-fallback-sysfsah ]h"]firmware_fallback_sysfsah$]h&]uh1hhjwhhhhhKqubeh}(h]firmware-sysfs-loading-facilityah ]h"]firmware sysfs loading facilityah$]h&]uh1hhhhhhhhKBubh)}(hhh](h)}(h*Firmware kobject uevent fallback mechanismh]h*Firmware kobject uevent fallback mechanism}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKvubh)}(hXSince a device is created for the sysfs interface to help load firmware as a fallback mechanism userspace can be informed of the addition of the device by relying on kobject uevents. The addition of the device into the device hierarchy means the fallback mechanism for firmware loading has been initiated. For details of implementation refer to fw_load_sysfs_fallback(), in particular on the use of dev_set_uevent_suppress() and kobject_uevent().h]hXSince a device is created for the sysfs interface to help load firmware as a fallback mechanism userspace can be informed of the addition of the device by relying on kobject uevents. The addition of the device into the device hierarchy means the fallback mechanism for firmware loading has been initiated. For details of implementation refer to fw_load_sysfs_fallback(), in particular on the use of dev_set_uevent_suppress() and kobject_uevent().}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKxhjhhubh)}(hXFThe kernel's kobject uevent mechanism is implemented in lib/kobject_uevent.c, it issues uevents to userspace. As a supplement to kobject uevents Linux distributions could also enable CONFIG_UEVENT_HELPER_PATH, which makes use of core kernel's usermode helper (UMH) functionality to call out to a userspace helper for kobject uevents. In practice though no standard distribution has ever used the CONFIG_UEVENT_HELPER_PATH. If CONFIG_UEVENT_HELPER_PATH is enabled this binary would be called each time kobject_uevent_env() gets called in the kernel for each kobject uevent triggered.h]hXJThe kernel’s kobject uevent mechanism is implemented in lib/kobject_uevent.c, it issues uevents to userspace. As a supplement to kobject uevents Linux distributions could also enable CONFIG_UEVENT_HELPER_PATH, which makes use of core kernel’s usermode helper (UMH) functionality to call out to a userspace helper for kobject uevents. In practice though no standard distribution has ever used the CONFIG_UEVENT_HELPER_PATH. If CONFIG_UEVENT_HELPER_PATH is enabled this binary would be called each time kobject_uevent_env() gets called in the kernel for each kobject uevent triggered.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXDifferent implementations have been supported in userspace to take advantage of this fallback mechanism. When firmware loading was only possible using the sysfs mechanism the userspace component "hotplug" provided the functionality of monitoring for kobject events. Historically this was superseded be systemd's udev, however firmware loading support was removed from udev as of systemd commit be2ea723b1d0 ("udev: remove userspace firmware loading support") as of v217 on August, 2014. This means most Linux distributions today are not using or taking advantage of the firmware fallback mechanism provided by kobject uevents. This is specially exacerbated due to the fact that most distributions today disable CONFIG_FW_LOADER_USER_HELPER_FALLBACK.h]hXDifferent implementations have been supported in userspace to take advantage of this fallback mechanism. When firmware loading was only possible using the sysfs mechanism the userspace component “hotplug” provided the functionality of monitoring for kobject events. Historically this was superseded be systemd’s udev, however firmware loading support was removed from udev as of systemd commit be2ea723b1d0 (“udev: remove userspace firmware loading support”) as of v217 on August, 2014. This means most Linux distributions today are not using or taking advantage of the firmware fallback mechanism provided by kobject uevents. This is specially exacerbated due to the fact that most distributions today disable CONFIG_FW_LOADER_USER_HELPER_FALLBACK.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hRefer to do_firmware_uevent() for details of the kobject event variables setup. The variables currently passed to userspace with a "kobject add" event are:h]hRefer to do_firmware_uevent() for details of the kobject event variables setup. The variables currently passed to userspace with a “kobject add” event are:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh](h)}(hFIRMWARE=firmware nameh]h)}(hjh]hFIRMWARE=firmware name}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hTIMEOUT=timeout valueh]h)}(hjh]hTIMEOUT=timeout value}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h6ASYNC=whether or not the API request was asynchronous h]h)}(h5ASYNC=whether or not the API request was asynchronoush]h5ASYNC=whether or not the API request was asynchronous}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj,ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1hhhhKhjhhubh)}(h{By default DEVPATH is set by the internal kernel kobject infrastructure. Below is an example simple kobject uevent script::h]hzBy default DEVPATH is set by the internal kernel kobject infrastructure. Below is an example simple kobject uevent script:}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj:)}(h# Both $DEVPATH and $FIRMWARE are already provided in the environment. MY_FW_DIR=/lib/firmware/ echo 1 > /sys/$DEVPATH/loading cat $MY_FW_DIR/$FIRMWARE > /sys/$DEVPATH/data echo 0 > /sys/$DEVPATH/loadingh]h# Both $DEVPATH and $FIRMWARE are already provided in the environment. MY_FW_DIR=/lib/firmware/ echo 1 > /sys/$DEVPATH/loading cat $MY_FW_DIR/$FIRMWARE > /sys/$DEVPATH/data echo 0 > /sys/$DEVPATH/loading}hjXsbah}(h]h ]h"]h$]h&]jIjJuh1j9hhhKhjhhubeh}(h]*firmware-kobject-uevent-fallback-mechanismah ]h"]*firmware kobject uevent fallback mechanismah$]h&]uh1hhhhhhhhKvubh)}(hhh](h)}(h"Firmware custom fallback mechanismh]h"Firmware custom fallback mechanism}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjnhhhhhKubh)}(hXUsers of the request_firmware_nowait() call have yet another option available at their disposal: rely on the sysfs fallback mechanism but request that no kobject uevents be issued to userspace. The original logic behind this was that utilities other than udev might be required to lookup firmware in non-traditional paths -- paths outside of the listing documented in the section 'Direct filesystem lookup'. This option is not available to any of the other API calls as uevents are always forced for them.h]hXUsers of the request_firmware_nowait() call have yet another option available at their disposal: rely on the sysfs fallback mechanism but request that no kobject uevents be issued to userspace. The original logic behind this was that utilities other than udev might be required to lookup firmware in non-traditional paths -- paths outside of the listing documented in the section ‘Direct filesystem lookup’. This option is not available to any of the other API calls as uevents are always forced for them.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjnhhubh)}(hXSince uevents are only meaningful if the fallback mechanism is enabled in your kernel it would seem odd to enable uevents with kernels that do not have the fallback mechanism enabled in their kernels. Unfortunately we also rely on the uevent flag which can be disabled by request_firmware_nowait() to also setup the firmware cache for firmware requests. As documented above, the firmware cache is only set up if uevent is enabled for an API call. Although this can disable the firmware cache for request_firmware_nowait() calls, users of this API should not use it for the purposes of disabling the cache as that was not the original purpose of the flag. Not setting the uevent flag means you want to opt-in for the firmware fallback mechanism but you want to suppress kobject uevents, as you have a custom solution which will monitor for your device addition into the device hierarchy somehow and load firmware for you through a custom path.h]hXSince uevents are only meaningful if the fallback mechanism is enabled in your kernel it would seem odd to enable uevents with kernels that do not have the fallback mechanism enabled in their kernels. Unfortunately we also rely on the uevent flag which can be disabled by request_firmware_nowait() to also setup the firmware cache for firmware requests. As documented above, the firmware cache is only set up if uevent is enabled for an API call. Although this can disable the firmware cache for request_firmware_nowait() calls, users of this API should not use it for the purposes of disabling the cache as that was not the original purpose of the flag. Not setting the uevent flag means you want to opt-in for the firmware fallback mechanism but you want to suppress kobject uevents, as you have a custom solution which will monitor for your device addition into the device hierarchy somehow and load firmware for you through a custom path.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjnhhubeh}(h]"firmware-custom-fallback-mechanismah ]h"]"firmware custom fallback mechanismah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hFirmware fallback timeouth]hFirmware fallback timeout}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXThe firmware fallback mechanism has a timeout. If firmware is not loaded onto the sysfs interface by the timeout value an error is sent to the driver. By default the timeout is set to 60 seconds if uevents are desirable, otherwise MAX_JIFFY_OFFSET is used (max timeout possible). The logic behind using MAX_JIFFY_OFFSET for non-uevents is that a custom solution will have as much time as it needs to load firmware.h]hXThe firmware fallback mechanism has a timeout. If firmware is not loaded onto the sysfs interface by the timeout value an error is sent to the driver. By default the timeout is set to 60 seconds if uevents are desirable, otherwise MAX_JIFFY_OFFSET is used (max timeout possible). The logic behind using MAX_JIFFY_OFFSET for non-uevents is that a custom solution will have as much time as it needs to load firmware.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h`You can customize the firmware timeout by echo'ing your desired timeout into the following file:h]hbYou can customize the firmware timeout by echo’ing your desired timeout into the following file:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh]h)}(h/sys/class/firmware/timeout h]h)}(h/sys/class/firmware/timeouth]h/sys/class/firmware/timeout}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubah}(h]h ]h"]h$]h&]jjuh1hhhhKhjhhubh)}(hcIf you echo 0 into it means MAX_JIFFY_OFFSET will be used. The data type for the timeout is an int.h]hcIf you echo 0 into it means MAX_JIFFY_OFFSET will be used. The data type for the timeout is an int.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]firmware-fallback-timeoutah ]h"]firmware fallback timeoutah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h(EFI embedded firmware fallback mechanismh]h(EFI embedded firmware fallback mechanism}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hOn some devices the system's EFI code / ROM may contain an embedded copy of firmware for some of the system's integrated peripheral devices and the peripheral's Linux device-driver needs to access this firmware.h]hOn some devices the system’s EFI code / ROM may contain an embedded copy of firmware for some of the system’s integrated peripheral devices and the peripheral’s Linux device-driver needs to access this firmware.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hDevice drivers which need such firmware can use the firmware_request_platform() function for this, note that this is a separate fallback mechanism from the other fallback mechanisms and this does not use the sysfs interface.h]hDevice drivers which need such firmware can use the firmware_request_platform() function for this, note that this is a separate fallback mechanism from the other fallback mechanisms and this does not use the sysfs interface.}(hj& hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hiA device driver which needs this can describe the firmware it needs using an efi_embedded_fw_desc struct:h]hiA device driver which needs this can describe the firmware it needs using an efi_embedded_fw_desc struct:}(hj4 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubjy)}(hhh]h}(h]h ]h"]h$]h&]entries](jefi_embedded_fw_desc (C struct)c.efi_embedded_fw_deschNtauh1jxhj hhhNhNubj)}(hhh](j)}(hefi_embedded_fw_desch]j)}(hstruct efi_embedded_fw_desch](j)}(hjh]hstruct}(hj[ hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjW hhhx/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:222: ./include/linux/efi_embedded_fw.hhKubj)}(h h]h }(hji hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjW hhhjh hKubj)}(hefi_embedded_fw_desch]j)}(hjU h]hefi_embedded_fw_desc}(hj{ hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjw ubah}(h]h ](jjeh"]h$]h&]jIjJuh1jhjW hhhjh hKubeh}(h]h ]h"]h$]h&]jIjJjuh1jjjhjS hhhjh hKubah}(h]jN ah ](jjeh"]h$]h&]jj)jhuh1jhjh hKhjP hhubj)}(hhh]h)}(hQThis struct is used by the EFI embedded-fw code to search for embedded firmwares.h]hQThis struct is used by the EFI embedded-fw code to search for embedded firmwares.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhx/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:222: ./include/linux/efi_embedded_fw.hhKhj hhubah}(h]h ]h"]h$]h&]uh1jhjP hhhjh hKubeh}(h]h ](j structeh"]h$]h&]jj jj jj jjjuh1jhhhj hNhNubj)}(hXw**Definition**:: struct efi_embedded_fw_desc { const char *name; u8 prefix[EFI_EMBEDDED_FW_PREFIX_LEN]; u32 length; u8 sha256[32]; }; **Members** ``name`` Name to register the firmware with if found ``prefix`` First 8 bytes of the firmware ``length`` Length of the firmware in bytes including prefix ``sha256`` SHA256 of the firmwareh](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhx/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:222: ./include/linux/efi_embedded_fw.hhKhj ubj:)}(hstruct efi_embedded_fw_desc { const char *name; u8 prefix[EFI_EMBEDDED_FW_PREFIX_LEN]; u32 length; u8 sha256[32]; };h]hstruct efi_embedded_fw_desc { const char *name; u8 prefix[EFI_EMBEDDED_FW_PREFIX_LEN]; u32 length; u8 sha256[32]; };}hj sbah}(h]h ]h"]h$]h&]jIjJuh1j9hx/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:222: ./include/linux/efi_embedded_fw.hhKhj ubh)}(h **Members**h]j)}(hj h]hMembers}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1hhx/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:222: ./include/linux/efi_embedded_fw.hhK#hj ubj)}(hhh](j)}(h5``name`` Name to register the firmware with if found h](j)}(h``name``h]j)}(hj h]hname}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jhx/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:222: ./include/linux/efi_embedded_fw.hhKhj ubj7)}(hhh]h)}(h+Name to register the firmware with if foundh]h+Name to register the firmware with if found}(hj# hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hKhj ubah}(h]h ]h"]h$]h&]uh1j6hj ubeh}(h]h ]h"]h$]h&]uh1jhj hKhj ubj)}(h)``prefix`` First 8 bytes of the firmware h](j)}(h ``prefix``h]j)}(hjC h]hprefix}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjA ubah}(h]h ]h"]h$]h&]uh1jhx/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:222: ./include/linux/efi_embedded_fw.hhKhj= ubj7)}(hhh]h)}(hFirst 8 bytes of the firmwareh]hFirst 8 bytes of the firmware}(hj\ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjX hKhjY ubah}(h]h ]h"]h$]h&]uh1j6hj= ubeh}(h]h ]h"]h$]h&]uh1jhjX hKhj ubj)}(h<``length`` Length of the firmware in bytes including prefix h](j)}(h ``length``h]j)}(hj| h]hlength}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjz ubah}(h]h ]h"]h$]h&]uh1jhx/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:222: ./include/linux/efi_embedded_fw.hhKhjv ubj7)}(hhh]h)}(h0Length of the firmware in bytes including prefixh]h0Length of the firmware in bytes including prefix}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hKhj ubah}(h]h ]h"]h$]h&]uh1j6hjv ubeh}(h]h ]h"]h$]h&]uh1jhj hKhj ubj)}(h!``sha256`` SHA256 of the firmwareh](j)}(h ``sha256``h]j)}(hj h]hsha256}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jhx/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:222: ./include/linux/efi_embedded_fw.hhKhj ubj7)}(hhh]h)}(hSHA256 of the firmwareh]hSHA256 of the firmware}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhx/var/lib/git/docbuild/linux/Documentation/driver-api/firmware/fallback-mechanisms:222: ./include/linux/efi_embedded_fw.hhKhj ubah}(h]h ]h"]h$]h&]uh1j6hj ubeh}(h]h ]h"]h$]h&]uh1jhj hKhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ] kernelindentah"]h$]h&]uh1jhj hhhNhNubh)}(hX!The EFI embedded-fw code works by scanning all EFI_BOOT_SERVICES_CODE memory segments for an eight byte sequence matching prefix; if the prefix is found it then does a sha256 over length bytes and if that matches makes a copy of length bytes and adds that to its list with found firmwares.h]hX!The EFI embedded-fw code works by scanning all EFI_BOOT_SERVICES_CODE memory segments for an eight byte sequence matching prefix; if the prefix is found it then does a sha256 over length bytes and if that matches makes a copy of length bytes and adds that to its list with found firmwares.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hTo avoid doing this somewhat expensive scan on all systems, dmi matching is used. Drivers are expected to export a dmi_system_id array, with each entries' driver_data pointing to an efi_embedded_fw_desc.h]hTo avoid doing this somewhat expensive scan on all systems, dmi matching is used. Drivers are expected to export a dmi_system_id array, with each entries’ driver_data pointing to an efi_embedded_fw_desc.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hHTo register this array with the efi-embedded-fw code, a driver needs to:h]hHTo register this array with the efi-embedded-fw code, a driver needs to:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubhenumerated_list)}(hhh](h)}(hvAlways be builtin to the kernel or store the dmi_system_id array in a separate object file which always gets builtin. h]h)}(huAlways be builtin to the kernel or store the dmi_system_id array in a separate object file which always gets builtin.h]huAlways be builtin to the kernel or store the dmi_system_id array in a separate object file which always gets builtin.}(hj) hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj% ubah}(h]h ]h"]h$]h&]uh1hhj" hhhhhNubh)}(hZAdd an extern declaration for the dmi_system_id array to include/linux/efi_embedded_fw.h. h]h)}(hYAdd an extern declaration for the dmi_system_id array to include/linux/efi_embedded_fw.h.h]hYAdd an extern declaration for the dmi_system_id array to include/linux/efi_embedded_fw.h.}(hjA hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj= ubah}(h]h ]h"]h$]h&]uh1hhj" hhhhhNubh)}(hAdd the dmi_system_id array to the embedded_fw_table in drivers/firmware/efi/embedded-firmware.c wrapped in a #ifdef testing that the driver is being builtin. h]h)}(hAdd the dmi_system_id array to the embedded_fw_table in drivers/firmware/efi/embedded-firmware.c wrapped in a #ifdef testing that the driver is being builtin.h]hAdd the dmi_system_id array to the embedded_fw_table in drivers/firmware/efi/embedded-firmware.c wrapped in a #ifdef testing that the driver is being builtin.}(hjY hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjU ubah}(h]h ]h"]h$]h&]uh1hhj" hhhhhNubh)}(hEAdd "select EFI_EMBEDDED_FIRMWARE if EFI_STUB" to its Kconfig entry. h]h)}(hDAdd "select EFI_EMBEDDED_FIRMWARE if EFI_STUB" to its Kconfig entry.h]hHAdd “select EFI_EMBEDDED_FIRMWARE if EFI_STUB” to its Kconfig entry.}(hjq hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjm ubah}(h]h ]h"]h$]h&]uh1hhj" hhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1j hj hhhhhKubh)}(hThe firmware_request_platform() function will always first try to load firmware with the specified name directly from the disk, so the EFI embedded-fw can always be overridden by placing a file under /lib/firmware.h]hThe firmware_request_platform() function will always first try to load firmware with the specified name directly from the disk, so the EFI embedded-fw can always be overridden by placing a file under /lib/firmware.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(h Note that:h]h Note that:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj! )}(hhh](h)}(hX The code scanning for EFI embedded-firmware runs near the end of start_kernel(), just before calling rest_init(). For normal drivers and subsystems using subsys_initcall() to register themselves this does not matter. This means that code running earlier cannot use EFI embedded-firmware. h]h)}(hXThe code scanning for EFI embedded-firmware runs near the end of start_kernel(), just before calling rest_init(). For normal drivers and subsystems using subsys_initcall() to register themselves this does not matter. This means that code running earlier cannot use EFI embedded-firmware.h]hXThe code scanning for EFI embedded-firmware runs near the end of start_kernel(), just before calling rest_init(). For normal drivers and subsystems using subsys_initcall() to register themselves this does not matter. This means that code running earlier cannot use EFI embedded-firmware.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(hAt the moment the EFI embedded-fw code assumes that firmwares always start at an offset which is a multiple of 8 bytes, if this is not true for your case send in a patch to fix this. h]h)}(hAt the moment the EFI embedded-fw code assumes that firmwares always start at an offset which is a multiple of 8 bytes, if this is not true for your case send in a patch to fix this.h]hAt the moment the EFI embedded-fw code assumes that firmwares always start at an offset which is a multiple of 8 bytes, if this is not true for your case send in a patch to fix this.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(hAt the moment the EFI embedded-fw code only works on x86 because other archs free EFI_BOOT_SERVICES_CODE before the EFI embedded-fw code gets a chance to scan it. h]h)}(hAt the moment the EFI embedded-fw code only works on x86 because other archs free EFI_BOOT_SERVICES_CODE before the EFI embedded-fw code gets a chance to scan it.h]hAt the moment the EFI embedded-fw code only works on x86 because other archs free EFI_BOOT_SERVICES_CODE before the EFI embedded-fw code gets a chance to scan it.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(hXaThe current brute-force scanning of EFI_BOOT_SERVICES_CODE is an ad-hoc brute-force solution. There has been discussion to use the UEFI Platform Initialization (PI) spec's Firmware Volume protocol. This has been rejected because the FV Protocol relies on *internal* interfaces of the PI spec, and: 1. The PI spec does not define peripheral firmware at all 2. The internal interfaces of the PI spec do not guarantee any backward compatibility. Any implementation details in FV may be subject to change, and may vary system to system. Supporting the FV Protocol would be difficult as it is purposely ambiguous. h]h)}(hX`The current brute-force scanning of EFI_BOOT_SERVICES_CODE is an ad-hoc brute-force solution. There has been discussion to use the UEFI Platform Initialization (PI) spec's Firmware Volume protocol. This has been rejected because the FV Protocol relies on *internal* interfaces of the PI spec, and: 1. The PI spec does not define peripheral firmware at all 2. The internal interfaces of the PI spec do not guarantee any backward compatibility. Any implementation details in FV may be subject to change, and may vary system to system. Supporting the FV Protocol would be difficult as it is purposely ambiguous.h](hXThe current brute-force scanning of EFI_BOOT_SERVICES_CODE is an ad-hoc brute-force solution. There has been discussion to use the UEFI Platform Initialization (PI) spec’s Firmware Volume protocol. This has been rejected because the FV Protocol relies on }(hj hhhNhNubhemphasis)}(h *internal*h]hinternal}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubhXW interfaces of the PI spec, and: 1. The PI spec does not define peripheral firmware at all 2. The internal interfaces of the PI spec do not guarantee any backward compatibility. Any implementation details in FV may be subject to change, and may vary system to system. Supporting the FV Protocol would be difficult as it is purposely ambiguous.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubeh}(h]h ]h"]h$]h&]j j j hj j uh1j hj hhhhhKubh)}(hhh](h)}(h6Example how to check for and extract embedded firmwareh]h6Example how to check for and extract embedded firmware}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj) hhhhhMubh)}(h\To check for, for example Silead touchscreen controller embedded firmware, do the following:h]h\To check for, for example Silead touchscreen controller embedded firmware, do the following:}(hj: hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj) hhubj! )}(hhh](h)}(h9Boot the system with efi=debug on the kernel commandline h]h)}(h8Boot the system with efi=debug on the kernel commandlineh]h8Boot the system with efi=debug on the kernel commandline}(hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjK ubah}(h]h ]h"]h$]h&]uh1hhjH hhhhhNubh)}(h>cp /sys/kernel/debug/efi/boot_services_code? to your home dir h]h)}(h=cp /sys/kernel/debug/efi/boot_services_code? to your home dirh]h=cp /sys/kernel/debug/efi/boot_services_code? to your home dir}(hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjc ubah}(h]h ]h"]h$]h&]uh1hhjH hhhhhNubh)}(hOpen the boot_services_code? files in a hex-editor, search for the magic prefix for Silead firmware: F0 00 00 00 02 00 00 00, this gives you the beginning address of the firmware inside the boot_services_code? file. h]h)}(hOpen the boot_services_code? files in a hex-editor, search for the magic prefix for Silead firmware: F0 00 00 00 02 00 00 00, this gives you the beginning address of the firmware inside the boot_services_code? file.h]hOpen the boot_services_code? files in a hex-editor, search for the magic prefix for Silead firmware: F0 00 00 00 02 00 00 00, this gives you the beginning address of the firmware inside the boot_services_code? file.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj{ ubah}(h]h ]h"]h$]h&]uh1hhjH hhhhhNubh)}(hXThe firmware has a specific pattern, it starts with a 8 byte page-address, typically F0 00 00 00 02 00 00 00 for the first page followed by 32-bit word-address + 32-bit value pairs. With the word-address incrementing 4 bytes (1 word) for each pair until a page is complete. A complete page is followed by a new page-address, followed by more word + value pairs. This leads to a very distinct pattern. Scroll down until this pattern stops, this gives you the end of the firmware inside the boot_services_code? file. h]h)}(hXThe firmware has a specific pattern, it starts with a 8 byte page-address, typically F0 00 00 00 02 00 00 00 for the first page followed by 32-bit word-address + 32-bit value pairs. With the word-address incrementing 4 bytes (1 word) for each pair until a page is complete. A complete page is followed by a new page-address, followed by more word + value pairs. This leads to a very distinct pattern. Scroll down until this pattern stops, this gives you the end of the firmware inside the boot_services_code? file.Wh]hXThe firmware has a specific pattern, it starts with a 8 byte page-address, typically F0 00 00 00 02 00 00 00 for the first page followed by 32-bit word-address + 32-bit value pairs. With the word-address incrementing 4 bytes (1 word) for each pair until a page is complete. A complete page is followed by a new page-address, followed by more word + value pairs. This leads to a very distinct pattern. Scroll down until this pattern stops, this gives you the end of the firmware inside the boot_services_code? file.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM$hj ubah}(h]h ]h"]h$]h&]uh1hhjH hhhhhNubh)}(h"dd if=boot_services_code? of=firmware bs=1 skip= count=" will extract the firmware for you. Inspect the firmware file in a hexeditor to make sure you got the dd parameters correct. h]h)}(h"dd if=boot_services_code? of=firmware bs=1 skip= count=" will extract the firmware for you. Inspect the firmware file in a hexeditor to make sure you got the dd parameters correct.h]h“dd if=boot_services_code? of=firmware bs=1 skip= count=” will extract the firmware for you. Inspect the firmware file in a hexeditor to make sure you got the dd parameters correct.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hj ubah}(h]h ]h"]h$]h&]uh1hhjH hhhhhNubh)}(h=Copy it to /lib/firmware under the expected name to test it. h]h)}(h