Back to home page

LXR

 
 

    


0001 
0002  request_firmware() hotplug interface:
0003  ------------------------------------
0004         Copyright (C) 2003 Manuel Estrada Sainz
0005 
0006  Why:
0007  ---
0008 
0009  Today, the most extended way to use firmware in the Linux kernel is linking
0010  it statically in a header file. Which has political and technical issues:
0011 
0012   1) Some firmware is not legal to redistribute.
0013   2) The firmware occupies memory permanently, even though it often is just
0014      used once.
0015   3) Some people, like the Debian crowd, don't consider some firmware free
0016      enough and remove entire drivers (e.g.: keyspan).
0017 
0018  High level behavior (mixed):
0019  ============================
0020 
0021  1), kernel(driver):
0022         - calls request_firmware(&fw_entry, $FIRMWARE, device)
0023         - kernel searches the firmware image with name $FIRMWARE directly
0024         in the below search path of root filesystem:
0025                 User customized search path by module parameter 'path'[1]
0026                 "/lib/firmware/updates/" UTS_RELEASE,
0027                 "/lib/firmware/updates",
0028                 "/lib/firmware/" UTS_RELEASE,
0029                 "/lib/firmware"
0030         - If found, goto 7), else goto 2)
0031 
0032         [1], the 'path' is a string parameter which length should be less
0033         than 256, user should pass 'firmware_class.path=$CUSTOMIZED_PATH'
0034         if firmware_class is built in kernel(the general situation)
0035 
0036  2), userspace:
0037         - /sys/class/firmware/xxx/{loading,data} appear.
0038         - hotplug gets called with a firmware identifier in $FIRMWARE
0039           and the usual hotplug environment.
0040                 - hotplug: echo 1 > /sys/class/firmware/xxx/loading
0041 
0042  3), kernel: Discard any previous partial load.
0043 
0044  4), userspace:
0045                 - hotplug: cat appropriate_firmware_image > \
0046                                         /sys/class/firmware/xxx/data
0047 
0048  5), kernel: grows a buffer in PAGE_SIZE increments to hold the image as it
0049          comes in.
0050 
0051  6), userspace:
0052                 - hotplug: echo 0 > /sys/class/firmware/xxx/loading
0053 
0054  7), kernel: request_firmware() returns and the driver has the firmware
0055          image in fw_entry->{data,size}. If something went wrong
0056          request_firmware() returns non-zero and fw_entry is set to
0057          NULL.
0058 
0059  8), kernel(driver): Driver code calls release_firmware(fw_entry) releasing
0060                  the firmware image and any related resource.
0061 
0062  High level behavior (driver code):
0063  ==================================
0064 
0065          if(request_firmware(&fw_entry, $FIRMWARE, device) == 0)
0066                 copy_fw_to_device(fw_entry->data, fw_entry->size);
0067          release_firmware(fw_entry);
0068 
0069  Sample/simple hotplug script:
0070  ============================
0071 
0072         # Both $DEVPATH and $FIRMWARE are already provided in the environment.
0073 
0074         HOTPLUG_FW_DIR=/usr/lib/hotplug/firmware/
0075 
0076         echo 1 > /sys/$DEVPATH/loading
0077         cat $HOTPLUG_FW_DIR/$FIRMWARE > /sys/$DEVPATH/data
0078         echo 0 > /sys/$DEVPATH/loading
0079 
0080  Random notes:
0081  ============
0082 
0083  - "echo -1 > /sys/class/firmware/xxx/loading" will cancel the load at
0084    once and make request_firmware() return with error.
0085 
0086  - firmware_data_read() and firmware_loading_show() are just provided
0087    for testing and completeness, they are not called in normal use.
0088 
0089  - There is also /sys/class/firmware/timeout which holds a timeout in
0090    seconds for the whole load operation.
0091 
0092  - request_firmware_nowait() is also provided for convenience in
0093    user contexts to request firmware asynchronously, but can't be called
0094    in atomic contexts.
0095 
0096 
0097  about in-kernel persistence:
0098  ---------------------------
0099  Under some circumstances, as explained below, it would be interesting to keep
0100  firmware images in non-swappable kernel memory or even in the kernel image
0101  (probably within initramfs).
0102 
0103  Note that this functionality has not been implemented.
0104 
0105  - Why OPTIONAL in-kernel persistence may be a good idea sometimes:
0106  
0107         - If the device that needs the firmware is needed to access the
0108           filesystem. When upon some error the device has to be reset and the
0109           firmware reloaded, it won't be possible to get it from userspace.
0110           e.g.:
0111                 - A diskless client with a network card that needs firmware.
0112                 - The filesystem is stored in a disk behind an scsi device
0113                   that needs firmware.
0114         - Replacing buggy DSDT/SSDT ACPI tables on boot.
0115           Note: this would require the persistent objects to be included
0116           within the kernel image, probably within initramfs.
0117           
0118    And the same device can be needed to access the filesystem or not depending
0119    on the setup, so I think that the choice on what firmware to make
0120    persistent should be left to userspace.
0121 
0122  about firmware cache:
0123  --------------------
0124  After firmware cache mechanism is introduced during system sleep,
0125  request_firmware can be called safely inside device's suspend and
0126  resume callback, and callers needn't cache the firmware by
0127  themselves any more for dealing with firmware loss during system
0128  resume.