| // Copyright 2023 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| library zbi; |
| |
| // TODO(https://fxbug.dev/42062786): Figure out documentation convention. |
| |
| /// The kernel image. In a bootable ZBI this item must always be first, |
| /// immediately after the ZBI_TYPE_CONTAINER header. The contiguous memory |
| /// image of the kernel is formed from the ZBI_TYPE_CONTAINER header, the |
| /// ZBI_TYPE_KERNEL_{ARCH} header, and the payload. |
| /// |
| /// The boot loader loads the whole image starting with the container header |
| /// through to the end of the kernel item's payload into contiguous physical |
| /// memory. It then constructs a partial ZBI elsewhere in memory, which has |
| /// a ZBI_TYPE_CONTAINER header of its own followed by all the other items |
| /// that were in the booted ZBI plus other items synthesized by the boot |
| /// loader to describe the machine. This partial ZBI must be placed at an |
| /// address (where the container header is found) that is aligned to the |
| /// machine's page size. The precise protocol for transferring control to |
| /// the kernel's entry point varies by machine. |
| /// |
| /// On all machines, the kernel requires some amount of scratch memory to be |
| /// available immediately after the kernel image at boot. It needs this |
| /// space for early setup work before it has a chance to read any memory-map |
| /// information from the boot loader. The `reserve_memory_size` field tells |
| /// the boot loader how much space after the kernel's load image it must |
| /// leave available for the kernel's use. The boot loader must place its |
| /// constructed ZBI or other reserved areas at least this many bytes after |
| /// the kernel image. |
| /// |
| /// x86-64 |
| /// |
| /// The kernel assumes it was loaded at a fixed physical address of |
| /// 0x100000 (1MB). zbi_kernel_t.entry is the absolute physical address |
| /// of the PC location where the kernel will start. |
| /// TODO(https://fxbug.dev/42098994): Perhaps this will change?? |
| /// The processor is in 64-bit mode with direct virtual to physical |
| /// mapping covering the physical memory where the kernel and |
| /// bootloader-constructed ZBI were loaded. |
| /// The %rsi register holds the physical address of the |
| /// bootloader-constructed ZBI. |
| /// All other registers are unspecified. |
| /// |
| /// ARM64 |
| /// |
| /// zbi_kernel_t.entry is an offset from the beginning of the image |
| /// (i.e., the ZBI_TYPE_CONTAINER header before the ZBI_TYPE_KERNEL_ARM64 |
| /// header) to the PC location in the image where the kernel will |
| /// start. The processor is in physical address mode at EL1 or |
| /// above. The kernel image and the bootloader-constructed ZBI each |
| /// can be loaded anywhere in physical memory. The x0 register |
| /// holds the physical address of the bootloader-constructed ZBI. |
| /// All other registers are unspecified. |
| /// |
| /// RISCV64 |
| /// |
| /// zbi_kernel_t.entry is an offset from the beginning of the image (i.e., |
| /// the ZBI_TYPE_CONTAINER header before the ZBI_TYPE_KERNEL_RISCV64 header) |
| /// to the PC location in the image where the kernel will start. The |
| /// processor is in S mode, satp is zero, sstatus.SIE is zero. The kernel |
| /// image and the bootloader-constructed ZBI each can be loaded anywhere in |
| /// physical memory, aligned to 4KiB. The a0 register holds the HART ID, |
| /// and the a1 register holds the 4KiB-aligned physical address of the |
| /// bootloader-constructed ZBI. All other registers are unspecified. |
| /// |
| type Kernel = struct { |
| /// Entry-point address. The interpretation of this differs by machine. |
| entry uint64; |
| |
| /// Minimum amount (in bytes) of scratch memory that the kernel requires |
| /// immediately after its load image. |
| reserve_memory_size uint64; |
| }; |