Re: [PATCH v4] RISC-V: Add an Image header that boot loader can parse.

From: Atish Patra
Date: Thu Jul 11 2019 - 17:42:37 EST


On Thu, 2019-07-11 at 12:42 -0700, Paul Walmsley wrote:
> On Fri, 28 Jun 2019, Atish Patra wrote:
>
> > On Fri, 2019-06-28 at 12:09 -0700, Paul Walmsley wrote:
> > > On Thu, 6 Jun 2019, Atish Patra wrote:
> > >
> > > > Currently, the last stage boot loaders such as U-Boot can
> > > > accept
> > > > only
> > > > uImage which is an unnecessary additional step in automating
> > > > boot
> > > > process.
> > > >
> > > > Add an image header that boot loader understands and boot Linux
> > > > from
> > > > flat Image directly.
> > >
> > > ...
> > >
> > >
> > > > +#if __riscv_xlen == 64
> > > > + /* Image load offset(2MB) from start of RAM */
> > > > + .dword 0x200000
> > > > +#else
> > > > + /* Image load offset(4MB) from start of RAM */
> > > > + .dword 0x400000
> > > > +#endif
> > >
> > > Is there a rationale behind these load offset values?
> > >
> >
> > 2MB/4MB alignment requirement is mandatory for current RISC-V
> > kernel.
> > Anup had a patch that tried to remove that but not accepted yet.
> >
> > https://patchwork.kernel.org/patch/10868465/
>
> Thanks for doing this work; this should really help. Patch queued
> with a
> few minor tweaks to the documentation file and to the
> comments. (Updated
> patch below)
>

Thank you!

> Not sure if this will make it for v5.3-rc1. If not, we'll try to get
> it
> in as soon as possible afterwards.
>
> Something else to think about: we'll probably want some flag bits
> soon to
> identify whether the kernel binary is a 32-bit, 64-bit, or 128-bit
> binary.
> If two bits are used, and 64-bit is defined as 00, then it should be
> backwards compatible. I would hope that this could be something that
> we'd
> be able to coordinate with the ARM64 folks also;

Sure. We can always any bits from 4-64 (reserved in ARM header). That
will still allow the ARM64/RISC-V headers to merge in future if ARM
maintainers are interested.

> otherwise we may need to
> start using that res3 field.
>
>
> - Paul
>
> From: Atish Patra <atish.patra@xxxxxxx>
> Date: Thu, 6 Jun 2019 16:08:00 -0700
> Subject: [PATCH] RISC-V: Add an Image header that boot loader can
> parse.
>
> Currently, the last stage boot loaders such as U-Boot can accept only
> uImage which is an unnecessary additional step in automating boot
> process.
>
> Add an image header that boot loader understands and boot Linux from
> flat Image directly.
>
> This header is based on ARM64 boot image header and provides an
> opportunity to combine both ARM64 & RISC-V image headers in future.
>
> Also make sure that PE/COFF header can co-exist in the same image so
> that EFI stub can be supported 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 res4(at offset 0x3c)
> should point to the rest of the PE/COFF header (which will be added
> during EFI support).
>
> Tested on both QEMU and HiFive Unleashed using OpenSBI + U-Boot +
> Linux.
>
> Signed-off-by: Atish Patra <atish.patra@xxxxxxx>
> Reviewed-by: Karsten Merker <merker@xxxxxxxxxx>
> Tested-by: Karsten Merker <merker@xxxxxxxxxx> (QEMU+OpenSBI+U-Boot)
> Tested-by: Kevin Hilman <khilman@xxxxxxxxxxxx> (OpenSBI + U-Boot +
> Linux)
> [paul.walmsley@xxxxxxxxxx: fixed whitespace in boot-image-header.txt;
> converted structure comment to kernel-doc format and added some
> detail]
> Signed-off-by: Paul Walmsley <paul.walmsley@xxxxxxxxxx>
> ---
> Documentation/riscv/boot-image-header.txt | 50 +++++++++++++++++
> arch/riscv/include/asm/image.h | 65
> +++++++++++++++++++++++
> arch/riscv/kernel/head.S | 32 +++++++++++
> 3 files changed, 147 insertions(+)
> create mode 100644 Documentation/riscv/boot-image-header.txt
> create mode 100644 arch/riscv/include/asm/image.h
>
> diff --git a/Documentation/riscv/boot-image-header.txt
> b/Documentation/riscv/boot-image-header.txt
> new file mode 100644
> index 000000000000..1b73fea23b39
> --- /dev/null
> +++ b/Documentation/riscv/boot-image-header.txt
> @@ -0,0 +1,50 @@
> + Boot image header in RISC-V Linux
> + =============================================
> +
> +Author: Atish Patra <atish.patra@xxxxxxx>
> +Date : 20 May 2019
> +
> +This document only describes the boot image header details for RISC-
> V Linux.
> +The complete booting guide will be available at
> Documentation/riscv/booting.txt.
> +
> +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 res3; /* Reserved for additional RISC-V specific
> header */
> + u32 res4; /* 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 res5(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.1.
> +
> +- res3 is reserved for offset to any other additional fields. This
> makes the
> + header extendible in future. One example would be to accommodate
> ISA
> + extension for RISC-V in future. For current version, it is set to
> be zero.
> +
> +- In current header, the flag 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.
> diff --git a/arch/riscv/include/asm/image.h
> b/arch/riscv/include/asm/image.h
> new file mode 100644
> index 000000000000..ef28e106f247
> --- /dev/null
> +++ b/arch/riscv/include/asm/image.h
> @@ -0,0 +1,65 @@
> +/* SPDX-License-Identifier: GPL-2.0 */
> +
> +#ifndef __ASM_IMAGE_H
> +#define __ASM_IMAGE_H
> +
> +#define RISCV_IMAGE_MAGIC "RISCV"
> +
> +#define RISCV_IMAGE_FLAG_BE_SHIFT 0
> +#define RISCV_IMAGE_FLAG_BE_MASK 0x1
> +
> +#define RISCV_IMAGE_FLAG_LE 0
> +#define RISCV_IMAGE_FLAG_BE 1
> +
> +#ifdef CONFIG_CPU_BIG_ENDIAN
> +#error conversion of header fields to LE not yet implemented
> +#else
> +#define __HEAD_FLAG_BE RISCV_IMAGE_FLAG_LE
> +#endif
> +
> +#define __HEAD_FLAG(field) (__HEAD_FLAG_##field << \
> + RISCV_IMAGE_FLAG_##field##_SHIFT)
> +
> +#define __HEAD_FLAGS (__HEAD_FLAG(BE))
> +
> +#define RISCV_HEADER_VERSION_MAJOR 0
> +#define RISCV_HEADER_VERSION_MINOR 1
> +
> +#define RISCV_HEADER_VERSION (RISCV_HEADER_VERSION_MAJOR << 16 | \
> + RISCV_HEADER_VERSION_MINOR)
> +
> +#ifndef __ASSEMBLY__
> +/**
> + * struct riscv_image_header - riscv kernel image header
> + * @code0: Executable code
> + * @code1: Executable code
> + * @text_offset: Image load offset (little endian)
> + * @image_size: Effective Image size (little endian)
> + * @flags: kernel flags (little endian)
> + * @version: version
> + * @res1: reserved
> + * @res2: reserved
> + * @magic: Magic number
> + * @res3: reserved (will be used for additional RISC-V
> specific
> + * header)
> + * @res4: reserved (will be used for PE COFF offset)
> + *
> + * The intention is for this header format to be shared between
> multiple
> + * architectures to avoid a proliferation of image header formats.
> + */
> +
> +struct riscv_image_header {
> + u32 code0;
> + u32 code1;
> + u64 text_offset;
> + u64 image_size;
> + u64 flags;
> + u32 version;
> + u32 res1;
> + u64 res2;
> + u64 magic;
> + u32 res3;
> + u32 res4;
> +};
> +#endif /* __ASSEMBLY__ */
> +#endif /* __ASM_IMAGE_H */
> diff --git a/arch/riscv/kernel/head.S b/arch/riscv/kernel/head.S
> index e368106f2228..0f1ba17e476f 100644
> --- a/arch/riscv/kernel/head.S
> +++ b/arch/riscv/kernel/head.S
> @@ -11,9 +11,41 @@
> #include <asm/thread_info.h>
> #include <asm/page.h>
> #include <asm/csr.h>
> +#include <asm/image.h>
>
> __INIT
> ENTRY(_start)
> + /*
> + * Image header expected by Linux boot-loaders. The image
> header data
> + * structure is described in asm/image.h.
> + * Do not modify it without modifying the structure and all
> bootloaders
> + * that expects this header format!!
> + */
> + /* jump to start kernel */
> + j _start_kernel
> + /* reserved */
> + .word 0
> + .balign 8
> +#if __riscv_xlen == 64
> + /* Image load offset(2MB) from start of RAM */
> + .dword 0x200000
> +#else
> + /* Image load offset(4MB) from start of RAM */
> + .dword 0x400000
> +#endif
> + /* Effective size of kernel image */
> + .dword _end - _start
> + .dword __HEAD_FLAGS
> + .word RISCV_HEADER_VERSION
> + .word 0
> + .dword 0
> + .asciz RISCV_IMAGE_MAGIC
> + .word 0
> + .balign 4
> + .word 0
> +
> +.global _start_kernel
> +_start_kernel:
> /* Mask all interrupts */
> csrw CSR_SIE, zero
> csrw CSR_SIP, zero

--
Regards,
Atish