docs/firmware/fw_header.md

OpenSBI Firmware Header
=======================

Every OpenSBI firmware image, regardless of its type (*FW_DYNAMIC*, *FW_JUMP*
or *FW_PAYLOAD*), starts with a fixed 128-byte header. The header serves two
purposes:

1. it lets the previous booting stage recognize an OpenSBI firmware image and
   find out what it was built for, and
2. it gives the previous booting stage a well-known place inside the image to
   hand over the boot arguments by patching a few words, instead of setting up
   the *a0*, *a1* and *a2* registers.

The second point matters when the previous booting stage cannot set up those
registers at all. A typical example is a system where the previous booting
stage runs on a dedicated boot processor: it can load and patch the OpenSBI
image in DRAM and then release the application hart that runs OpenSBI, but it
can never execute on that hart and therefore cannot place anything in its
registers.

The first word of the header is a jump over the header, so the entry point of
the firmware is unchanged: the previous booting stage still jumps to the first
byte of the image.

Header layout
-------------

| Offset | Size | Field                                             |
|--------|------|---------------------------------------------------|
| 0x00   | 4    | Jump over the header (a 4-byte `j` instruction)   |
| 0x04   | 4    | Magic value, 'OSBI' (0x4942534f)                  |
| 0x08   | 4    | Header version, currently 1                       |
| 0x0c   | 4    | XLEN the firmware was built for, 32 or 64         |
| 0x10   | 4    | Firmware size in bytes                            |
| 0x14   | 4    | Flags, see below                                  |
| 0x18   | 8    | Override value for *a1*                           |
| 0x20   | 8    | Reserved (upper half of the *a1* value on RV128)  |
| 0x28   | 8    | Override value for *a2*                           |
| 0x30   | 8    | Reserved (upper half of the *a2* value on RV128)  |
| 0x38   | 72   | Reserved                                          |

All fields are little-endian. The layout is deliberately the same for RV32 and
RV64, so the previous booting stage can parse the header, and in particular
check the *XLEN* field, without knowing the XLEN of the firmware upfront. The
override values are 8 bytes wide on both; on RV32 only the lower 4 bytes are
used and the upper 4 bytes must be zero. Each override value is followed by a
reserved 8-byte slot so that the same layout can be extended to RV128 later.

There is no override value for *a0*. Every hart runs the header independently
when it enters the firmware, so a header field could only ever hold a single
value shared by all harts, which does not fit *a0*'s role as the current
hart's own hart id. See "Overriding a0, a1 and a2" below for how *a0* is
handled instead.

The *firmware size* field is `_fw_end - _fw_start`, i.e. how much memory the
firmware image occupies once loaded, including the *.bss* section. Note that
this is not the size of the flat binary file, which is smaller because
*.bss* is not stored in the file. OpenSBI also needs some scratch space
beyond the firmware image, so this field alone does not describe everything
the previous booting stage has to reserve.

Overriding a0, a1 and a2
------------------------

The following flags are defined:

| Flag                        | Value | Description                           |
|-----------------------------|-------|---------------------------------------|
| FW_HEADER_FLAGS_OVERRIDE_A0 | 1 << 0| Override *a0* with the hart's mhartid |
| FW_HEADER_FLAGS_OVERRIDE_A1 | 1 << 1| Override *a1* from offset 0x18        |
| FW_HEADER_FLAGS_OVERRIDE_A2 | 1 << 2| Override *a2* from offset 0x28        |

For every flag that is set, OpenSBI replaces the corresponding register
before it looks at the boot arguments. Registers whose flag is clear are used
exactly as passed by the previous booting stage.

*a0* is handled differently from *a1* and *a2*: instead of being patched with
a value from the header, it is set to the value of the *mhartid* CSR read by
the hart that is currently executing the header. This runs once per hart, so
each hart gets its own hart id, which a single shared header field could not
provide.

The flags word is zero in a freshly built image, so a previous booting stage
that already passes *a0*, *a1* and *a2* in registers is unaffected and needs
to know nothing about the header.

The meaning of the registers is unchanged, so the previous booting stage
should:

* set FW_HEADER_FLAGS_OVERRIDE_A0 if it cannot set up *a0* with the hart id
  of the hart that will enter OpenSBI on every hart itself; OpenSBI then
  derives it from *mhartid* directly and no header field needs patching,
* patch *a1* with the device tree blob address, which must be 8-byte
  aligned, and
* patch *a2* with the address of a *struct fw_dynamic_info*, for a
  *FW_DYNAMIC* firmware. The structure itself is not part of the OpenSBI
  image; the previous booting stage has to place it in memory that OpenSBI
  does not overwrite, which notably excludes the OpenSBI *.bss* section and
  the scratch space above the firmware.

Patching the header
-------------------

The header is at the very beginning of the image, so all offsets above are
relative to the address the image was loaded at. For example, on RV64:

```c
#define FW_HEADER_MAGIC_VALUE			0x4942534f
#define FW_HEADER_FLAGS_OVERRIDE_A0		(1 << 0)
#define FW_HEADER_FLAGS_OVERRIDE_A1		(1 << 1)
#define FW_HEADER_FLAGS_OVERRIDE_A2		(1 << 2)

struct fw_header {
	uint32_t	jump;
	uint32_t	magic;
	uint32_t	version;
	uint32_t	xlen;
	uint32_t	size;
	uint32_t	flags;
	uint64_t	override_a1;
	uint64_t	reserved1;
	uint64_t	override_a2;
	uint64_t	reserved2;
	uint64_t	reserved[9];
};

struct fw_header *hdr = (struct fw_header *)opensbi_load_addr;

if (hdr->magic != FW_HEADER_MAGIC_VALUE || hdr->xlen != 64)
	return -EINVAL;

hdr->override_a1 = dtb_addr;
hdr->override_a2 = (uint64_t)dynamic_info;
hdr->flags = FW_HEADER_FLAGS_OVERRIDE_A0 |
	     FW_HEADER_FLAGS_OVERRIDE_A1 |
	     FW_HEADER_FLAGS_OVERRIDE_A2;
```