[deliverable/linux.git] / Documentation / firmware_class / README


 request_firmware() hotplug interface:
 ------------------------------------
	Copyright (C) 2003 Manuel Estrada Sainz

 Why:
 ---

 Today, the most extended way to use firmware in the Linux kernel is linking
 it statically in a header file. Which has political and technical issues:

  1) Some firmware is not legal to redistribute.
  2) The firmware occupies memory permanently, even though it often is just
     used once.
  3) Some people, like the Debian crowd, don't consider some firmware free
     enough and remove entire drivers (e.g.: keyspan).

 High level behavior (mixed):
 ============================

 1), kernel(driver):
	- calls request_firmware(&fw_entry, $FIRMWARE, device)
	- kernel searchs the fimware image with name $FIRMWARE directly
	in the below search path of root filesystem:
		"/lib/firmware/updates/" UTS_RELEASE,
		"/lib/firmware/updates",
		"/lib/firmware/" UTS_RELEASE,
		"/lib/firmware"
	- If found, goto 7), else goto 2)

 2), userspace:
 	- /sys/class/firmware/xxx/{loading,data} appear.
	- hotplug gets called with a firmware identifier in $FIRMWARE
	  and the usual hotplug environment.
		- hotplug: echo 1 > /sys/class/firmware/xxx/loading

 3), kernel: Discard any previous partial load.

 4), userspace:
		- hotplug: cat appropriate_firmware_image > \
					/sys/class/firmware/xxx/data

 5), kernel: grows a buffer in PAGE_SIZE increments to hold the image as it
	 comes in.

 6), userspace:
		- hotplug: echo 0 > /sys/class/firmware/xxx/loading

 7), kernel: request_firmware() returns and the driver has the firmware
	 image in fw_entry->{data,size}. If something went wrong
	 request_firmware() returns non-zero and fw_entry is set to
	 NULL.

 8), kernel(driver): Driver code calls release_firmware(fw_entry) releasing
		 the firmware image and any related resource.

 High level behavior (driver code):
 ==================================

	 if(request_firmware(&fw_entry, $FIRMWARE, device) == 0)
	 	copy_fw_to_device(fw_entry->data, fw_entry->size);
	 release(fw_entry);

 Sample/simple hotplug script:
 ============================

	# Both $DEVPATH and $FIRMWARE are already provided in the environment.

	HOTPLUG_FW_DIR=/usr/lib/hotplug/firmware/

	echo 1 > /sys/$DEVPATH/loading
	cat $HOTPLUG_FW_DIR/$FIRMWARE > /sysfs/$DEVPATH/data
	echo 0 > /sys/$DEVPATH/loading

 Random notes:
 ============

 - "echo -1 > /sys/class/firmware/xxx/loading" will cancel the load at
   once and make request_firmware() return with error.

 - firmware_data_read() and firmware_loading_show() are just provided
   for testing and completeness, they are not called in normal use.

 - There is also /sys/class/firmware/timeout which holds a timeout in
   seconds for the whole load operation.

 - request_firmware_nowait() is also provided for convenience in
   user contexts to request firmware asynchronously, but can't be called
   in atomic contexts.


 about in-kernel persistence:
 ---------------------------
 Under some circumstances, as explained below, it would be interesting to keep
 firmware images in non-swappable kernel memory or even in the kernel image
 (probably within initramfs).

 Note that this functionality has not been implemented.

 - Why OPTIONAL in-kernel persistence may be a good idea sometimes:
 
	- If the device that needs the firmware is needed to access the
	  filesystem. When upon some error the device has to be reset and the
	  firmware reloaded, it won't be possible to get it from userspace.
	  e.g.:
		- A diskless client with a network card that needs firmware.
		- The filesystem is stored in a disk behind an scsi device
		  that needs firmware.
	- Replacing buggy DSDT/SSDT ACPI tables on boot.
	  Note: this would require the persistent objects to be included
	  within the kernel image, probably within initramfs.
	  
   And the same device can be needed to access the filesystem or not depending
   on the setup, so I think that the choice on what firmware to make
   persistent should be left to userspace.
Commit	Line	Data
1da177e4 LT	1
	2	request_firmware() hotplug interface:
	3	------------------------------------
87d37a4f	4	Copyright (C) 2003 Manuel Estrada Sainz
1da177e4 LT	5
	6	Why:
	7	---
	8
	9	Today, the most extended way to use firmware in the Linux kernel is linking
	10	it statically in a header file. Which has political and technical issues:
	11
	12	1) Some firmware is not legal to redistribute.
	13	2) The firmware occupies memory permanently, even though it often is just
	14	used once.
	15	3) Some people, like the Debian crowd, don't consider some firmware free
	16	enough and remove entire drivers (e.g.: keyspan).
	17
	18	High level behavior (mixed):
	19	============================
	20
10bd4c75 ML	21	1), kernel(driver):
	22	- calls request_firmware(&fw_entry, $FIRMWARE, device)
	23	- kernel searchs the fimware image with name $FIRMWARE directly
	24	in the below search path of root filesystem:
	25	"/lib/firmware/updates/" UTS_RELEASE,
	26	"/lib/firmware/updates",
	27	"/lib/firmware/" UTS_RELEASE,
	28	"/lib/firmware"
	29	- If found, goto 7), else goto 2)
	30
	31	2), userspace:
1da177e4 LT	32	- /sys/class/firmware/xxx/{loading,data} appear.
	33	- hotplug gets called with a firmware identifier in $FIRMWARE
	34	and the usual hotplug environment.
	35	- hotplug: echo 1 > /sys/class/firmware/xxx/loading
	36
10bd4c75	37	3), kernel: Discard any previous partial load.
1da177e4	38
10bd4c75	39	4), userspace:
1da177e4 LT	40	- hotplug: cat appropriate_firmware_image > \
	41	/sys/class/firmware/xxx/data
	42
10bd4c75	43	5), kernel: grows a buffer in PAGE_SIZE increments to hold the image as it
1da177e4 LT	44	comes in.
1da177e4 LT	45
10bd4c75	46	6), userspace:
1da177e4 LT	47	- hotplug: echo 0 > /sys/class/firmware/xxx/loading
1da177e4 LT	48
10bd4c75	49	7), kernel: request_firmware() returns and the driver has the firmware
1da177e4 LT	50	image in fw_entry->{data,size}. If something went wrong
	51	request_firmware() returns non-zero and fw_entry is set to
	52	NULL.
	53
10bd4c75	54	8), kernel(driver): Driver code calls release_firmware(fw_entry) releasing
1da177e4 LT	55	the firmware image and any related resource.
	56
	57	High level behavior (driver code):
	58	==================================
	59
	60	if(request_firmware(&fw_entry, $FIRMWARE, device) == 0)
	61	copy_fw_to_device(fw_entry->data, fw_entry->size);
	62	release(fw_entry);
	63
	64	Sample/simple hotplug script:
	65	============================
	66
	67	# Both $DEVPATH and $FIRMWARE are already provided in the environment.
	68
	69	HOTPLUG_FW_DIR=/usr/lib/hotplug/firmware/
	70
	71	echo 1 > /sys/$DEVPATH/loading
	72	cat $HOTPLUG_FW_DIR/$FIRMWARE > /sysfs/$DEVPATH/data
	73	echo 0 > /sys/$DEVPATH/loading
	74
	75	Random notes:
	76	============
	77
	78	- "echo -1 > /sys/class/firmware/xxx/loading" will cancel the load at
	79	once and make request_firmware() return with error.
	80
	81	- firmware_data_read() and firmware_loading_show() are just provided
	82	for testing and completeness, they are not called in normal use.
	83
	84	- There is also /sys/class/firmware/timeout which holds a timeout in
	85	seconds for the whole load operation.
	86
	87	- request_firmware_nowait() is also provided for convenience in
7fcab099 ML	88	user contexts to request firmware asynchronously, but can't be called
7fcab099 ML	89	in atomic contexts.
1da177e4 LT	90
	91
	92	about in-kernel persistence:
	93	---------------------------
	94	Under some circumstances, as explained below, it would be interesting to keep
	95	firmware images in non-swappable kernel memory or even in the kernel image
	96	(probably within initramfs).
	97
	98	Note that this functionality has not been implemented.
	99
	100	- Why OPTIONAL in-kernel persistence may be a good idea sometimes:
	101
	102	- If the device that needs the firmware is needed to access the
	103	filesystem. When upon some error the device has to be reset and the
	104	firmware reloaded, it won't be possible to get it from userspace.
	105	e.g.:
	106	- A diskless client with a network card that needs firmware.
	107	- The filesystem is stored in a disk behind an scsi device
	108	that needs firmware.
	109	- Replacing buggy DSDT/SSDT ACPI tables on boot.
	110	Note: this would require the persistent objects to be included
	111	within the kernel image, probably within initramfs.
	112
	113	And the same device can be needed to access the filesystem or not depending
	114	on the setup, so I think that the choice on what firmware to make
	115	persistent should be left to userspace.
	116