linux/Documentation/firmware_class
Zhang Rui 91a6902958 sysfs: add parameter "struct bin_attribute *" in .read/.write methods for sysfs binary attributes
Well, first of all, I don't want to change so many files either.

What I do:
Adding a new parameter "struct bin_attribute *" in the
.read/.write methods for the sysfs binary attributes.

In fact, only the four lines change in fs/sysfs/bin.c and
include/linux/sysfs.h do the real work.
But I have to update all the files that use binary attributes
to make them compatible with the new .read and .write methods.
I'm not sure if I missed any. :(

Why I do this:
For a sysfs attribute, we can get a pointer pointing to the
struct attribute in the .show/.store method,
while we can't do this for the binary attributes.
I don't know why this is different, but this does make it not
so handy to use the binary attributes as the regular ones.
So I think this patch is reasonable. :)

Who benefits from it:
The patch that exposes ACPI tables in sysfs
requires such an improvement.
All the table binary attributes share the same .read method.
Parameter "struct bin_attribute *" is used to get
the table signature and instance number which are used to
distinguish different ACPI table binary attributes.

Without this parameter, we need to offer different .read methods
for different ACPI table binary attributes.
This is impossible as there are various ACPI tables on different
platforms, and we don't know what they are until they are loaded.

Signed-off-by: Zhang Rui <rui.zhang@intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
2007-07-11 16:09:09 -07:00
..
README firmware: remove orphaned Email 2007-06-08 12:41:08 -07:00
firmware_sample_driver.c firmware: remove orphaned Email 2007-06-08 12:41:08 -07:00
firmware_sample_firmware_class.c sysfs: add parameter "struct bin_attribute *" in .read/.write methods for sysfs binary attributes 2007-07-11 16:09:09 -07:00
hotplug-script Linux-2.6.12-rc2 2005-04-16 15:20:36 -07:00

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):
 ============================

 kernel(driver): calls request_firmware(&fw_entry, $FIRMWARE, device)

 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

 kernel: Discard any previous partial load.

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

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

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

 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.

 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
   non-user 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.