Damien Le Moal | 808fe4b | 2019-01-23 23:48:42 +0900 | [diff] [blame] | 1 | OpenSBI Platform Firmwares |
| 2 | ========================== |
| 3 | |
| 4 | OpenSBI provides firmware builds for specific platforms. Different types of |
| 5 | firmwares are supported to deal with the differences between different platforms |
| 6 | early boot stage. All firmwares will execute the same initialization procedure |
| 7 | of the platform hardware according to the platform specific code as well as |
Atish Patra | 0db4377 | 2019-02-18 23:17:16 -0800 | [diff] [blame] | 8 | OpenSBI generic library code. The supported firmwares type will differ in how |
Damien Le Moal | 808fe4b | 2019-01-23 23:48:42 +0900 | [diff] [blame] | 9 | the arguments passed by the platform early boot stage are handled, as well as |
| 10 | how the boot stage following the firmware will be handled and executed. |
| 11 | |
Bin Meng | a4555e5 | 2021-07-10 22:28:21 +0800 | [diff] [blame] | 12 | The previous booting stage will pass information via the following registers |
| 13 | of RISC-V CPU: |
| 14 | |
| 15 | * hartid via *a0* register |
| 16 | * device tree blob address in memory via *a1* register. The address must |
| 17 | be aligned to 8 bytes. |
| 18 | |
Anup Patel | 392749f | 2019-04-29 12:50:33 +0530 | [diff] [blame] | 19 | OpenSBI currently supports three different types of firmwares. |
| 20 | |
| 21 | Firmware with Dynamic Information (*FW_DYNAMIC*) |
| 22 | ------------------------------------------------ |
| 23 | |
| 24 | The *FW_DYNAMIC* firmware gets information about the next booting stage entry, |
| 25 | e.g. a bootloader or an OS kernel, from previous booting stage at runtime. |
| 26 | |
| 27 | A *FW_DYNAMIC* firmware is particularly useful when the booting stage executed |
| 28 | prior to OpenSBI firmware is capable of loading both the OpenSBI firmware |
| 29 | and the booting stage binary to follow OpenSBI firmware. |
Damien Le Moal | 808fe4b | 2019-01-23 23:48:42 +0900 | [diff] [blame] | 30 | |
| 31 | Firmware with Jump Address (*FW_JUMP*) |
| 32 | -------------------------------------- |
| 33 | |
Anup Patel | 392749f | 2019-04-29 12:50:33 +0530 | [diff] [blame] | 34 | The *FW_JUMP* firmware assumes a fixed address of the next booting stage |
Damien Le Moal | 808fe4b | 2019-01-23 23:48:42 +0900 | [diff] [blame] | 35 | entry, e.g. a bootloader or an OS kernel, without directly including the |
| 36 | binary code for this next stage. |
| 37 | |
| 38 | A *FW_JUMP* firmware is particularly useful when the booting stage executed |
| 39 | prior to OpenSBI firmware is capable of loading both the OpenSBI firmware |
| 40 | and the booting stage binary to follow OpenSBI firmware. |
| 41 | |
| 42 | Firmware with Payload (*FW_PAYLOAD*) |
| 43 | ------------------------------------ |
| 44 | |
| 45 | The *FW_PAYLOAD* firmware directly includes the binary code for the booting |
| 46 | stage to follow OpenSBI firmware execution. Typically, this payload will be a |
| 47 | bootloader or an OS kernel. |
| 48 | |
| 49 | A *FW_PAYLOAD* firmware is particularly useful when the booting stage executed |
| 50 | prior to OpenSBI firmware is not capable of loading both OpenSBI firmware and |
| 51 | the booting stage to follow OpenSBI firmware. |
| 52 | |
| 53 | A *FW_PAYLOAD* firmware is also useful for cases where the booting stage prior |
| 54 | to OpenSBI firmware does not pass a *flattened device tree (FDT file)*. In such |
| 55 | case, a *FW_PAYLOAD* firmware allows embedding a flattened device tree in the |
Yangjie Zhang | 51acd49 | 2022-10-20 22:41:08 +0800 | [diff] [blame] | 56 | .rodata section of the final firmware. |
Damien Le Moal | 808fe4b | 2019-01-23 23:48:42 +0900 | [diff] [blame] | 57 | |
| 58 | Firmware Configuration and Compilation |
| 59 | -------------------------------------- |
| 60 | |
Anup Patel | 6ca0969 | 2020-10-14 16:03:35 +0530 | [diff] [blame] | 61 | All firmware types support the following common compile time configuration |
| 62 | parameters: |
Damien Le Moal | 808fe4b | 2019-01-23 23:48:42 +0900 | [diff] [blame] | 63 | |
Anup Patel | 96f0a2e | 2024-05-15 09:55:50 +0530 | [diff] [blame] | 64 | * **FW_TEXT_START** - Defines the compile time address of the OpenSBI |
| 65 | firmware. This configuration parameter is optional and assumed to be |
| 66 | `0` if not specified. |
Anup Patel | 6ca0969 | 2020-10-14 16:03:35 +0530 | [diff] [blame] | 67 | * **FW_FDT_PATH** - Path to an external flattened device tree binary file to |
| 68 | be embedded in the *.rodata* section of the final firmware. If this option |
| 69 | is not provided then the firmware will expect the FDT to be passed as an |
| 70 | argument by the prior booting stage. |
| 71 | * **FW_FDT_PADDING** - Optional zero bytes padding to the embedded flattened |
| 72 | device tree binary file specified by **FW_FDT_PATH** option. |
Damien Le Moal | 808fe4b | 2019-01-23 23:48:42 +0900 | [diff] [blame] | 73 | |
| 74 | Additionally, each firmware type as a set of type specific configuration |
Anup Patel | 392749f | 2019-04-29 12:50:33 +0530 | [diff] [blame] | 75 | parameters. Detailed information for each firmware type can be found in the |
Damien Le Moal | 808fe4b | 2019-01-23 23:48:42 +0900 | [diff] [blame] | 76 | following documents. |
| 77 | |
Anup Patel | 392749f | 2019-04-29 12:50:33 +0530 | [diff] [blame] | 78 | * *[FW_DYNAMIC]*: The *Firmware with Dynamic Information (FW_DYNAMIC)* is |
| 79 | described in more details in the file *fw_dynamic.md*. |
Damien Le Moal | 808fe4b | 2019-01-23 23:48:42 +0900 | [diff] [blame] | 80 | * *[FW_JUMP]*: The *Firmware with Jump Address (FW_JUMP)* is described in more |
| 81 | details in the file *fw_jump.md*. |
| 82 | * *[FW_PAYLOAD]*: The *Firmware with Payload (FW_PAYLOAD)* is described in more |
| 83 | details in the file *fw_payload.md*. |
| 84 | |
Anup Patel | 392749f | 2019-04-29 12:50:33 +0530 | [diff] [blame] | 85 | [FW_DYNAMIC]: fw_dynamic.md |
Damien Le Moal | 808fe4b | 2019-01-23 23:48:42 +0900 | [diff] [blame] | 86 | [FW_JUMP]: fw_jump.md |
| 87 | [FW_PAYLOAD]: fw_payload.md |
Atish Patra | 0db4377 | 2019-02-18 23:17:16 -0800 | [diff] [blame] | 88 | |
| 89 | Providing different payloads to OpenSBI Firmware |
| 90 | ------------------------------------------------ |
| 91 | OpenSBI firmware can accept various payloads using a compile time option. |
| 92 | Typically, these payloads refer to the next stage boot loader (e.g. U-Boot) |
| 93 | or operating system kernel images (e.g. Linux). By default, OpenSBI |
| 94 | automatically provides a test payload if no specific payload is specified |
| 95 | at compile time. |
| 96 | |
| 97 | To specify a payload at compile time, the make variable _FW_PAYLOAD_PATH_ is |
| 98 | used. |
| 99 | ``` |
| 100 | make PLATFORM=<platform_subdir> FW_PAYLOAD_PATH=<payload path> |
| 101 | ``` |
| 102 | The instructions to build each payload is different and the details can |
| 103 | be found in the |
| 104 | *docs/firmware/payload_<payload_name>.md* files. |
Bin Meng | f9cfe30 | 2019-03-27 22:58:49 +0800 | [diff] [blame] | 105 | |
| 106 | Options for OpenSBI Firmware behaviors |
| 107 | -------------------------------------- |
| 108 | An optional compile time flag FW_OPTIONS can be used to control the OpenSBI |
| 109 | firmware run-time behaviors. |
| 110 | |
| 111 | ``` |
| 112 | make PLATFORM=<platform_subdir> FW_OPTIONS=<options> |
| 113 | ``` |
| 114 | |
| 115 | FW_OPTIONS is a bitwise or'ed value of various options, eg: *FW_OPTIONS=0x1* |
| 116 | stands for disabling boot prints from the OpenSBI library. |
| 117 | |
| 118 | For all supported options, please check "enum sbi_scratch_options" in the |
| 119 | *include/sbi/sbi_scratch.h* header file. |