firmware loader: document kernel direct loading
authorMing Lei <ming.lei@canonical.com>
Wed, 24 Oct 2012 02:49:33 +0000 (10:49 +0800)
committerGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Thu, 25 Oct 2012 18:53:36 +0000 (11:53 -0700)
This patch adds description on recently introduced direct firmware
loading by Linus.

Cc: Linus Torvalds <torvalds@linux-foundation.org>
Signed-off-by: Ming Lei <ming.lei@canonical.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Documentation/firmware_class/README

index 7eceaff..815b711 100644 (file)
  High level behavior (mixed):
  ============================
 
- kernel(driver): calls request_firmware(&fw_entry, $FIRMWARE, device)
-
- userspace:
+ 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
 
- kernel: Discard any previous partial load.
3), kernel: Discard any previous partial load.
 
- userspace:
4), 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
5), kernel: grows a buffer in PAGE_SIZE increments to hold the image as it
         comes in.
 
- userspace:
6), userspace:
                - hotplug: echo 0 > /sys/class/firmware/xxx/loading
 
- kernel: request_firmware() returns and the driver has the firmware
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.
 
- kernel(driver): Driver code calls release_firmware(fw_entry) releasing
8), kernel(driver): Driver code calls release_firmware(fw_entry) releasing
                 the firmware image and any related resource.
 
  High level behavior (driver code):