3  * main.c - Multi purpose firmware loading support
7  * Please see Documentation/driver-api/firmware/ for more information.
26 #include <linux/firmware.h>
44 #include "firmware.h"
48 MODULE_DESCRIPTION("Multi purpose firmware loading support");
59 	 * Names of firmware images which have been cached successfully
61 	 * helper can trace which firmware images have been cached
167 /* Returns 1 for batching firmware requests with the same name */
308  * ZSTD-compressed firmware support
372  * XZ-compressed firmware support
470 /* direct firmware loading support */
474 	"/lib/firmware/updates/" UTS_RELEASE,
475 	"/lib/firmware/updates",
476 	"/lib/firmware/" UTS_RELEASE,
477 	"/lib/firmware"
486 MODULE_PARM_DESC(path, "customized firmware image search path with a higher priority than default p…
543 		 * firmware was not completely loaded.  in fw_get_filesystem_firmware()
548 		/* load firmware files from the mount namespace of init */  in fw_get_filesystem_firmware()
569 		dev_dbg(device, "Loading firmware from %s\n", path);  in fw_get_filesystem_firmware()
596 /* firmware holds the ownership of pages */
597 static void firmware_free_data(const struct firmware *fw)  in firmware_free_data()
607 /* store the pages buffer info firmware from buf */
608 static void fw_set_page_data(struct fw_priv *fw_priv, struct firmware *fw)  in fw_set_page_data()
660 /* add firmware name into devres list */
695 int assign_fw(struct firmware *fw, struct device *device)  in assign_fw()
707 	 * add firmware name into devres list so that we can auto cache  in assign_fw()
708 	 * and uncache firmware for device.  in assign_fw()
713 	/* don't cache firmware handled without uevent */  in assign_fw()
724 	 * After caching firmware image is started, let it piggyback  in assign_fw()
725 	 * on request firmware.  in assign_fw()
737 /* prepare firmware and firmware_buf structs;
738  * return 0 if a firmware is already assigned, 1 if need to load one,
742 _request_firmware_prepare(struct firmware **firmware_p, const char *name,  in _request_firmware_prepare()
746 	struct firmware *firmware;  in _request_firmware_prepare()  local
750 	*firmware_p = firmware = kzalloc(sizeof(*firmware), GFP_KERNEL);  in _request_firmware_prepare()
751 	if (!firmware) {  in _request_firmware_prepare()
752 		dev_err(device, "%s: kmalloc(struct firmware) failed\n",  in _request_firmware_prepare()
757 	if (firmware_request_builtin_buf(firmware, name, dbuf, size)) {  in _request_firmware_prepare()
767 	 * of requesting firmware.  in _request_firmware_prepare()
769 	firmware->priv = fw_priv;  in _request_firmware_prepare()
774 			fw_set_page_data(fw_priv, firmware);  in _request_firmware_prepare()
793 static void fw_abort_batch_reqs(struct firmware *fw)  in fw_abort_batch_reqs()
812 static void fw_log_firmware_info(const struct firmware *fw, const char *name, struct device *device)  in fw_log_firmware_info()
846 static void fw_log_firmware_info(const struct firmware *fw, const char *name,  in fw_log_firmware_info()
852  * Reject firmware file names with ".." path components.
853  * There are drivers that construct firmware file names from device-supplied
855  * be sent my firmware from ../../../etc/shadow, please".
859  * This intentionally only looks at the firmware name, not at the firmware base
873 _request_firmware(const struct firmware **firmware_p, const char *name,  in _request_firmware()
877 	struct firmware *fw = NULL;  in _request_firmware()
893 			 "Firmware load for '%s' refused, path contains '..' component\n",  in _request_firmware()
905 	 * We are about to try to access the firmware file. Because we may have been  in _request_firmware()
938 				 "Direct firmware load for %s failed with error %d\n",  in _request_firmware()
963  * request_firmware() - send firmware request and wait for it
964  * @firmware_p: pointer to firmware image
965  * @name: name of firmware file
966  * @device: device for which firmware is being loaded
968  *      @firmware_p will be used to return a firmware image by the name
973  *      @name will be used as $FIRMWARE in the uevent environment and
975  *      firmware image for this or any other device.
985 request_firmware(const struct firmware **firmware_p, const char *name,  in request_firmware()
1001  * @firmware: pointer to firmware image
1002  * @name: name of firmware file
1003  * @device: device for which firmware is being loaded
1008  * failures to find the firmware file with it are still suppressed. It is
1012 int firmware_request_nowarn(const struct firmware **firmware, const char *name,  in firmware_request_nowarn()  argument
1019 	ret = _request_firmware(firmware, name, device, NULL, 0, 0,  in firmware_request_nowarn()
1027  * request_firmware_direct() - load firmware directly without usermode helper
1028  * @firmware_p: pointer to firmware image
1029  * @name: name of firmware file
1030  * @device: device for which firmware is being loaded
1033  * fall back to usermode helper even if the firmware couldn't be loaded
1037 int request_firmware_direct(const struct firmware **firmware_p,  in request_firmware_direct()
1052  * firmware_request_platform() - request firmware with platform-fw fallback
1053  * @firmware: pointer to firmware image
1054  * @name: name of firmware file
1055  * @device: device for which firmware is being loaded
1059  * requested firmware embedded in the platform's main (e.g. UEFI) firmware.
1061 int firmware_request_platform(const struct firmware **firmware,  in firmware_request_platform()  argument
1068 	ret = _request_firmware(firmware, name, device, NULL, 0, 0,  in firmware_request_platform()
1076  * firmware_request_cache() - cache firmware for suspend so resume can use it
1077  * @device: device for which firmware should be cached for
1078  * @name: name of firmware file
1081  * require loading firmware on system reboot. This optimization may still
1082  * require the firmware present on resume from suspend. This routine can be
1083  * used to ensure the firmware is present on resume from suspend in these
1100  * request_firmware_into_buf() - load firmware into a previously allocated buffer
1101  * @firmware_p: pointer to firmware image
1102  * @name: name of firmware file
1103  * @device: device for which firmware is being loaded and DMA region allocated
1104  * @buf: address of buffer to load firmware into
1108  * allocate a buffer to hold the firmware data. Instead, the firmware
1112  * This function doesn't cache firmware either.
1115 request_firmware_into_buf(const struct firmware **firmware_p, const char *name,  in request_firmware_into_buf()
1132  * request_partial_firmware_into_buf() - load partial firmware into a previously allocated buffer
1133  * @firmware_p: pointer to firmware image
1134  * @name: name of firmware file
1135  * @device: device for which firmware is being loaded and DMA region allocated
1136  * @buf: address of buffer to load firmware into
1144 request_partial_firmware_into_buf(const struct firmware **firmware_p,  in request_partial_firmware_into_buf()
1163  * release_firmware() - release the resource associated with a firmware image
1164  * @fw: firmware resource to release
1166 void release_firmware(const struct firmware *fw)  in release_firmware()
1183 	void (*cont)(const struct firmware *fw, void *context);
1190 	const struct firmware *fw;  in request_firmware_work_func()
1208 	void (*cont)(const struct firmware *fw, void *context), bool nowarn)  in _request_firmware_nowait()
1249  * @module: module requesting the firmware
1250  * @uevent: sends uevent to copy the firmware image if this flag
1251  *	is non-zero else the firmware copy must be done manually.
1252  * @name: name of firmware file
1253  * @device: device for which firmware is being loaded
1256  *	@fw may be %NULL if firmware request fails.
1257  * @cont: function will be called asynchronously when the firmware
1265  *		  requesting firmware in their ->probe() methods, if
1273 	void (*cont)(const struct firmware *fw, void *context))  in request_firmware_nowait()
1283  * @module: module requesting the firmware
1284  * @name: name of firmware file
1285  * @device: device for which firmware is being loaded
1288  *	@fw may be %NULL if firmware request fails.
1289  * @cont: function will be called asynchronously when the firmware
1293  * when the firmware file could not be found and always sends a uevent to copy
1294  * the firmware image.
1299 	void (*cont)(const struct firmware *fw, void *context))  in firmware_request_nowait_nowarn()
1310  * cache_firmware() - cache one firmware image in kernel memory space
1311  * @fw_name: the firmware image name
1313  * Cache firmware in kernel memory so that drivers can use it when
1314  * system isn't ready for them to request firmware image from userspace.
1316  * nowait version to get the cached firmware without any interacting
1319  * Return 0 if the firmware image has been cached successfully
1326 	const struct firmware *fw;  in cache_firmware()
1352  * uncache_firmware() - remove one cached firmware image
1353  * @fw_name: the firmware image name
1355  * Uncache one firmware image which has been cached successfully
1358  * Return 0 if the firmware cache has been removed successfully
1365 	struct firmware fw;  in uncache_firmware()
1490 		/* only one cache entry for one firmware */  in dev_cache_fw_image()
1527  * device_cache_fw_images() - cache devices' firmware
1530  * successfully before, the firmware names are recored into the
1534  * time when system is not ready to complete loading firmware.
1553 	/* wait for completion of caching firmware for all devices */  in device_cache_fw_images()
1560  * device_uncache_fw_images() - uncache devices' firmware
1598 		 * non-uevent firmware request to avoid stalling suspend.  in fw_pm_notify()
1622 /* stop caching firmware once syscore_suspend is reached */