diff options
author | Luis R. Rodriguez | 2016-12-16 12:10:36 +0100 |
---|---|---|
committer | Greg Kroah-Hartman | 2017-01-11 09:42:59 +0100 |
commit | 113ccc38378b6f0b24c0993040c6044e35163a51 (patch) | |
tree | 2a1fbd9a1ad5144dc316834ccf52505a84191cb3 /Documentation/driver-api/firmware/direct-fs-lookup.rst | |
parent | selftests: firmware: send expected errors to /dev/null (diff) | |
download | kernel-qcow2-linux-113ccc38378b6f0b24c0993040c6044e35163a51.tar.gz kernel-qcow2-linux-113ccc38378b6f0b24c0993040c6044e35163a51.tar.xz kernel-qcow2-linux-113ccc38378b6f0b24c0993040c6044e35163a51.zip |
firmware: revamp firmware documentation
Understanding this code is getting out of control without any
notes. Give the firmware_class driver a much needed documentation love,
and while at it convert it to the new sphinx documentation format.
v2: typos and small fixes
Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Diffstat (limited to 'Documentation/driver-api/firmware/direct-fs-lookup.rst')
-rw-r--r-- | Documentation/driver-api/firmware/direct-fs-lookup.rst | 30 |
1 files changed, 30 insertions, 0 deletions
diff --git a/Documentation/driver-api/firmware/direct-fs-lookup.rst b/Documentation/driver-api/firmware/direct-fs-lookup.rst new file mode 100644 index 000000000000..82b4d585a213 --- /dev/null +++ b/Documentation/driver-api/firmware/direct-fs-lookup.rst @@ -0,0 +1,30 @@ +======================== +Direct filesystem lookup +======================== + +Direct filesystem lookup is the most common form of firmware lookup performed +by the kernel. The kernel looks for the firmware directly on the root +filesystem in the paths documented in the section 'Firmware search paths'. +The filesystem lookup is implemented in fw_get_filesystem_firmware(), it +uses common core kernel file loader facility kernel_read_file_from_path(). +The max path allowed is PATH_MAX -- currently this is 4096 characters. + +It is recommended you keep /lib/firmware paths on your root filesystem, +avoid having a separate partition for them in order to avoid possible +races with lookups and avoid uses of the custom fallback mechanisms +documented below. + +Firmware and initramfs +---------------------- + +Drivers which are built-in to the kernel should have the firmware integrated +also as part of the initramfs used to boot the kernel given that otherwise +a race is possible with loading the driver and the real rootfs not yet being +available. Stuffing the firmware into initramfs resolves this race issue, +however note that using initrd does not suffice to address the same race. + +There are circumstances that justify not wanting to include firmware into +initramfs, such as dealing with large firmware firmware files for the +remote-proc subsystem. For such cases using a userspace fallback mechanism +is currently the only viable solution as only userspace can know for sure +when the real rootfs is ready and mounted. |