Messages in this thread Patch in this message | | | Date | Tue, 12 Aug 2003 03:43:28 +0200 | From | Manuel Estrada Sainz <> | Subject | [PATCH] more documentation for request_firmware() |
| |
ChangeLog:
Add some higher level docs to Documentation/firmware_class/README.
README | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 66 insertions(+)
diff --exclude=CVS -urN linux-2.5.orig/Documentation/firmware_class/README linux-2.5.mine/Documentation/firmware_class/README --- linux-2.5.orig/Documentation/firmware_class/README 2003-08-12 03:34:05.000000000 +0200 +++ linux-2.5.mine/Documentation/firmware_class/README 2003-08-12 03:31:55.000000000 +0200 @@ -15,6 +15,71 @@ 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 > /sysfs/$DEVPATH/loading + cat $HOTPLUG_FW_DIR/$FIRMWARE > /sysfs/$DEVPATH/data + echo 0 > /sysfs/$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 @@ -56,3 +121,4 @@ Note: If persistence is implemented on top of initramfs, register_firmware() may not be appropriate. + -- --- Manuel Estrada Sainz <ranty@debian.org> <ranty@bigfoot.com> <ranty@users.sourceforge.net> ------------------------ <manuel.estrada@hispalinux.es> ------------------- Let us have the serenity to accept the things we cannot change, courage to change the things we can, and wisdom to know the difference. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
| |