[linux-2.6-block.git] / Documentation / riscv / boot-image-header.rst

=================================
Boot image header in RISC-V Linux
=================================

:Author: Atish Patra <atish.patra@wdc.com>
:Date:   20 May 2019

This document only describes the boot image header details for RISC-V Linux.

TODO:
  Write a complete booting guide.

The following 64-byte header is present in decompressed Linux kernel image::

	u32 code0;		  /* Executable code */
	u32 code1;		  /* Executable code */
	u64 text_offset;	  /* Image load offset, little endian */
	u64 image_size;		  /* Effective Image size, little endian */
	u64 flags;		  /* kernel flags, little endian */
	u32 version;		  /* Version of this header */
	u32 res1 = 0;		  /* Reserved */
	u64 res2 = 0;		  /* Reserved */
	u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */
	u32 magic2 = 0x05435352;  /* Magic number 2, little endian, "RSC\x05" */
	u32 res3;		  /* Reserved for PE COFF offset */

This header format is compliant with PE/COFF header and largely inspired from
ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common
header in future.

Notes
=====

- This header can also be reused to support EFI stub for RISC-V in future. EFI
  specification needs PE/COFF image header in the beginning of the kernel image
  in order to load it as an EFI application. In order to support EFI stub,
  code0 should be replaced with "MZ" magic string and res3(at offset 0x3c) should
  point to the rest of the PE/COFF header.

- version field indicate header version number

	==========  =============
	Bits 0:15   Minor version
	Bits 16:31  Major version
	==========  =============

  This preserves compatibility across newer and older version of the header.
  The current version is defined as 0.2.

- The "magic" field is deprecated as of version 0.2.  In a future
  release, it may be removed.  This originally should have matched up
  with the ARM64 header "magic" field, but unfortunately does not.
  The "magic2" field replaces it, matching up with the ARM64 header.

- In current header, the flags field has only one field.

	=====  ====================================
	Bit 0  Kernel endianness. 1 if BE, 0 if LE.
	=====  ====================================

- Image size is mandatory for boot loader to load kernel image. Booting will
  fail otherwise.
Commit	Line	Data
638b642f MCC	1	=================================
	2	Boot image header in RISC-V Linux
	3	=================================
0f327f2a	4
638b642f MCC	5	:Author: Atish Patra <atish.patra@wdc.com>
638b642f MCC	6	:Date: 20 May 2019
0f327f2a AP	7
0f327f2a AP	8	This document only describes the boot image header details for RISC-V Linux.
0f327f2a	9
638b642f MCC	10	TODO:
	11	Write a complete booting guide.
	12
	13	The following 64-byte header is present in decompressed Linux kernel image::
0f327f2a AP	14
0f327f2a AP	15	u32 code0; /* Executable code */
638b642f	16	u32 code1; /* Executable code */
0f327f2a AP	17	u64 text_offset; /* Image load offset, little endian */
	18	u64 image_size; /* Effective Image size, little endian */
	19	u64 flags; /* kernel flags, little endian */
	20	u32 version; /* Version of this header */
638b642f MCC	21	u32 res1 = 0; /* Reserved */
638b642f MCC	22	u64 res2 = 0; /* Reserved */
0f327f2a	23	u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */
185271a1	24	u32 magic2 = 0x05435352; /* Magic number 2, little endian, "RSC\x05" */
1d5c17e4	25	u32 res3; /* Reserved for PE COFF offset */
0f327f2a AP	26
	27	This header format is compliant with PE/COFF header and largely inspired from
	28	ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common
	29	header in future.
	30
638b642f MCC	31	Notes
	32	=====
	33
0f327f2a AP	34	- This header can also be reused to support EFI stub for RISC-V in future. EFI
	35	specification needs PE/COFF image header in the beginning of the kernel image
	36	in order to load it as an EFI application. In order to support EFI stub,
1d5c17e4	37	code0 should be replaced with "MZ" magic string and res3(at offset 0x3c) should
0f327f2a AP	38	point to the rest of the PE/COFF header.
0f327f2a AP	39
638b642f MCC	40	- version field indicate header version number
	41
	42	========== =============
	43	Bits 0:15 Minor version
	44	Bits 16:31 Major version
	45	========== =============
0f327f2a AP	46
0f327f2a AP	47	This preserves compatibility across newer and older version of the header.
474efecb	48	The current version is defined as 0.2.
0f327f2a	49
474efecb PW	50	- The "magic" field is deprecated as of version 0.2. In a future
	51	release, it may be removed. This originally should have matched up
	52	with the ARM64 header "magic" field, but unfortunately does not.
	53	The "magic2" field replaces it, matching up with the ARM64 header.
0f327f2a	54
474efecb	55	- In current header, the flags field has only one field.
638b642f MCC	56
	57	===== ====================================
	58	Bit 0 Kernel endianness. 1 if BE, 0 if LE.
	59	===== ====================================
0f327f2a AP	60
	61	- Image size is mandatory for boot loader to load kernel image. Booting will
	62	fail otherwise.