projects / linux-2.6-block.git / blame
| Commit | Line | Data |
|---|---|---|
| 113ccc38 LR |
1 | ==================== |
| 2 | request_firmware API | |
| 3 | ==================== | |
| 4 | ||
| 5 | You would typically load firmware and then load it into your device somehow. | |
| 6 | The typical firmware work flow is reflected below:: | |
| 7 | ||
| 8 | if(request_firmware(&fw_entry, $FIRMWARE, device) == 0) | |
| 9 | copy_fw_to_device(fw_entry->data, fw_entry->size); | |
| 10 | release_firmware(fw_entry); | |
| 11 | ||
| 12 | Synchronous firmware requests | |
| 13 | ============================= | |
| 14 | ||
| 15 | Synchronous firmware requests will wait until the firmware is found or until | |
| 16 | an error is returned. | |
| 17 | ||
| 18 | request_firmware | |
| 19 | ---------------- | |
| df9267f1 | 20 | .. kernel-doc:: drivers/base/firmware_loader/main.c |
| 113ccc38 LR |
21 | :functions: request_firmware |
| 22 | ||
| 23 | request_firmware_direct | |
| 24 | ----------------------- | |
| df9267f1 | 25 | .. kernel-doc:: drivers/base/firmware_loader/main.c |
| 113ccc38 LR |
26 | :functions: request_firmware_direct |
| 27 | ||
| 28 | request_firmware_into_buf | |
| 29 | ------------------------- | |
| df9267f1 | 30 | .. kernel-doc:: drivers/base/firmware_loader/main.c |
| 113ccc38 LR |
31 | :functions: request_firmware_into_buf |
| 32 | ||
| 33 | Asynchronous firmware requests | |
| 34 | ============================== | |
| 35 | ||
| 36 | Asynchronous firmware requests allow driver code to not have to wait | |
| 37 | until the firmware or an error is returned. Function callbacks are | |
| 38 | provided so that when the firmware or an error is found the driver is | |
| 39 | informed through the callback. request_firmware_nowait() cannot be called | |
| 40 | in atomic contexts. | |
| 41 | ||
| 42 | request_firmware_nowait | |
| 43 | ----------------------- | |
| df9267f1 | 44 | .. kernel-doc:: drivers/base/firmware_loader/main.c |
| 113ccc38 LR |
45 | :functions: request_firmware_nowait |
| 46 | ||
| 5d42c96e LR |
47 | Special optimizations on reboot |
| 48 | =============================== | |
| 49 | ||
| 50 | Some devices have an optimization in place to enable the firmware to be | |
| 51 | retained during system reboot. When such optimizations are used the driver | |
| 52 | author must ensure the firmware is still available on resume from suspend, | |
| b93815d0 AR |
53 | this can be done with firmware_request_cache() instead of requesting for the |
| 54 | firmware to be loaded. | |
| 5d42c96e LR |
55 | |
| 56 | firmware_request_cache() | |
| b93815d0 | 57 | ------------------------ |
| df9267f1 | 58 | .. kernel-doc:: drivers/base/firmware_loader/main.c |
| 5d42c96e LR |
59 | :functions: firmware_request_cache |
| 60 | ||
| 113ccc38 LR |
61 | request firmware API expected driver use |
| 62 | ======================================== | |
| 63 | ||
| 64 | Once an API call returns you process the firmware and then release the | |
| 65 | firmware. For example if you used request_firmware() and it returns, | |
| 66 | the driver has the firmware image accessible in fw_entry->{data,size}. | |
| 67 | If something went wrong request_firmware() returns non-zero and fw_entry | |
| 68 | is set to NULL. Once your driver is done with processing the firmware it | |
| 69 | can call call release_firmware(fw_entry) to release the firmware image | |
| 70 | and any related resource. |