blob: d2980967ede07c188c54d4886ea44d54033a8066 [file] [log] [blame] [view]
Damien Le Moal808fe4b2019-01-23 23:48:42 +09001OpenSBI Platform Firmwares
2==========================
3
4OpenSBI provides firmware builds for specific platforms. Different types of
5firmwares are supported to deal with the differences between different platforms
6early boot stage. All firmwares will execute the same initialization procedure
7of the platform hardware according to the platform specific code as well as
Atish Patra0db43772019-02-18 23:17:16 -08008OpenSBI generic library code. The supported firmwares type will differ in how
Damien Le Moal808fe4b2019-01-23 23:48:42 +09009the arguments passed by the platform early boot stage are handled, as well as
10how the boot stage following the firmware will be handled and executed.
11
Bin Menga4555e52021-07-10 22:28:21 +080012The previous booting stage will pass information via the following registers
13of 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 Patel392749f2019-04-29 12:50:33 +053019OpenSBI currently supports three different types of firmwares.
20
21Firmware with Dynamic Information (*FW_DYNAMIC*)
22------------------------------------------------
23
24The *FW_DYNAMIC* firmware gets information about the next booting stage entry,
25e.g. a bootloader or an OS kernel, from previous booting stage at runtime.
26
27A *FW_DYNAMIC* firmware is particularly useful when the booting stage executed
28prior to OpenSBI firmware is capable of loading both the OpenSBI firmware
29and the booting stage binary to follow OpenSBI firmware.
Damien Le Moal808fe4b2019-01-23 23:48:42 +090030
31Firmware with Jump Address (*FW_JUMP*)
32--------------------------------------
33
Anup Patel392749f2019-04-29 12:50:33 +053034The *FW_JUMP* firmware assumes a fixed address of the next booting stage
Damien Le Moal808fe4b2019-01-23 23:48:42 +090035entry, e.g. a bootloader or an OS kernel, without directly including the
36binary code for this next stage.
37
38A *FW_JUMP* firmware is particularly useful when the booting stage executed
39prior to OpenSBI firmware is capable of loading both the OpenSBI firmware
40and the booting stage binary to follow OpenSBI firmware.
41
42Firmware with Payload (*FW_PAYLOAD*)
43------------------------------------
44
45The *FW_PAYLOAD* firmware directly includes the binary code for the booting
46stage to follow OpenSBI firmware execution. Typically, this payload will be a
47bootloader or an OS kernel.
48
49A *FW_PAYLOAD* firmware is particularly useful when the booting stage executed
50prior to OpenSBI firmware is not capable of loading both OpenSBI firmware and
51the booting stage to follow OpenSBI firmware.
52
53A *FW_PAYLOAD* firmware is also useful for cases where the booting stage prior
54to OpenSBI firmware does not pass a *flattened device tree (FDT file)*. In such
55case, a *FW_PAYLOAD* firmware allows embedding a flattened device tree in the
Yangjie Zhang51acd492022-10-20 22:41:08 +080056.rodata section of the final firmware.
Damien Le Moal808fe4b2019-01-23 23:48:42 +090057
58Firmware Configuration and Compilation
59--------------------------------------
60
Anup Patel6ca09692020-10-14 16:03:35 +053061All firmware types support the following common compile time configuration
62parameters:
Damien Le Moal808fe4b2019-01-23 23:48:42 +090063
Anup Patel96f0a2e2024-05-15 09:55:50 +053064* **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 Patel6ca09692020-10-14 16:03:35 +053067* **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 Moal808fe4b2019-01-23 23:48:42 +090073
74Additionally, each firmware type as a set of type specific configuration
Anup Patel392749f2019-04-29 12:50:33 +053075parameters. Detailed information for each firmware type can be found in the
Damien Le Moal808fe4b2019-01-23 23:48:42 +090076following documents.
77
Anup Patel392749f2019-04-29 12:50:33 +053078* *[FW_DYNAMIC]*: The *Firmware with Dynamic Information (FW_DYNAMIC)* is
79 described in more details in the file *fw_dynamic.md*.
Damien Le Moal808fe4b2019-01-23 23:48:42 +090080* *[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 Patel392749f2019-04-29 12:50:33 +053085[FW_DYNAMIC]: fw_dynamic.md
Damien Le Moal808fe4b2019-01-23 23:48:42 +090086[FW_JUMP]: fw_jump.md
87[FW_PAYLOAD]: fw_payload.md
Atish Patra0db43772019-02-18 23:17:16 -080088
89Providing different payloads to OpenSBI Firmware
90------------------------------------------------
91OpenSBI firmware can accept various payloads using a compile time option.
92Typically, these payloads refer to the next stage boot loader (e.g. U-Boot)
93or operating system kernel images (e.g. Linux). By default, OpenSBI
94automatically provides a test payload if no specific payload is specified
95at compile time.
96
97To specify a payload at compile time, the make variable _FW_PAYLOAD_PATH_ is
98used.
99```
100make PLATFORM=<platform_subdir> FW_PAYLOAD_PATH=<payload path>
101```
102The instructions to build each payload is different and the details can
103be found in the
104*docs/firmware/payload_<payload_name>.md* files.
Bin Mengf9cfe302019-03-27 22:58:49 +0800105
106Options for OpenSBI Firmware behaviors
107--------------------------------------
108An optional compile time flag FW_OPTIONS can be used to control the OpenSBI
109firmware run-time behaviors.
110
111```
112make PLATFORM=<platform_subdir> FW_OPTIONS=<options>
113```
114
115FW_OPTIONS is a bitwise or'ed value of various options, eg: *FW_OPTIONS=0x1*
116stands for disabling boot prints from the OpenSBI library.
117
118For all supported options, please check "enum sbi_scratch_options" in the
119*include/sbi/sbi_scratch.h* header file.