diff options
Diffstat (limited to 'Documentation/firmware_class/README')
| -rw-r--r-- | Documentation/firmware_class/README | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/Documentation/firmware_class/README b/Documentation/firmware_class/README new file mode 100644 index 000000000000..43e836c07ae8 --- /dev/null +++ b/Documentation/firmware_class/README @@ -0,0 +1,124 @@ + + request_firmware() hotplug interface: + ------------------------------------ + Copyright (C) 2003 Manuel Estrada Sainz <ranty@debian.org> + + 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. + + - Why register_firmware()+__init can be useful: + - For boot devices needing firmware. + - To make the transition easier: + The firmware can be declared __init and register_firmware() + called on module_init. Then the firmware is warranted to be + there even if "firmware hotplug userspace" is not there yet or + it doesn't yet provide the needed firmware. + Once the firmware is widely available in userspace, it can be + removed from the kernel. Or made optional (CONFIG_.*_FIRMWARE). + + In either case, if firmware hotplug support is there, it can move the + firmware out of kernel memory into the real filesystem for later + usage. + + Note: If persistence is implemented on top of initramfs, + register_firmware() may not be appropriate. + |