1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
// Copyright (c) 2019 Intel Corporation. All rights reserved.
// Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
//
// Copyright 2017 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE-BSD-3-Clause file.
//
// SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
//! A Linux kernel image loading crate.
//!
//! This crate offers support for loading raw ELF (vmlinux), compressed
//! big zImage (bzImage) and PE (Image) kernel images.
//! ELF support includes the Linux and PVH boot protocols.
//! Support for any other kernel image format can be added by implementing
//! the [`KernelLoader`] and [`BootConfigurator`].
//!
//! # Platform support
//!
//! - `x86_64`
//! - `ARM64`
//! - `RISC-V64`
//!
//! # Example - load an ELF kernel and configure boot params with the PVH protocol
//!
//! This example shows how to prepare a VM for booting with an ELF kernel, following the PVH
//! boot protocol.
//!
//! ```rust
//! # extern crate linux_loader;
//! # extern crate vm_memory;
//! # use std::{io::{Cursor, Read}, fs::File};
//!
//! # #[cfg(all(
//! # any(target_arch = "x86", target_arch = "x86_64"),
//! # any(feature = "elf", feature = "pe", feature = "bzimage")
//! # ))]
//! # mod imports {
//! # pub use linux_loader::configurator::{BootConfigurator, BootParams};
//! # pub use linux_loader::configurator::pvh::PvhBootConfigurator;
//! # pub use linux_loader::loader::elf::start_info::{hvm_memmap_table_entry, hvm_start_info};
//! # pub use linux_loader::loader::elf::Elf;
//! # }
//!
//! # #[cfg(all(
//! # any(target_arch = "x86", target_arch = "x86_64"),
//! # any(feature = "elf", feature = "pe", feature = "bzimage")
//! # ))]
//! # pub use imports::*;
//!
//! # use linux_loader::loader::KernelLoader;
//! # use vm_memory::{Address, GuestAddress, GuestMemoryMmap};
//! # const E820_RAM: u32 = 1;
//! # const MEM_SIZE: usize = 0x100_0000;
//! # const XEN_HVM_START_MAGIC_VALUE: u32 = 0x336ec578;
//!
//! # #[cfg(all(
//! # any(target_arch = "x86", target_arch = "x86_64"),
//! # any(feature = "elf", feature = "pe", feature = "bzimage")
//! # ))]
//! fn build_boot_params() -> (hvm_start_info, Vec<hvm_memmap_table_entry>) {
//! let mut start_info = hvm_start_info::default();
//! let memmap_entry = hvm_memmap_table_entry {
//! addr: 0x7000,
//! size: 0,
//! type_: E820_RAM,
//! reserved: 0,
//! };
//! start_info.magic = XEN_HVM_START_MAGIC_VALUE;
//! start_info.version = 1;
//! start_info.nr_modules = 0;
//! start_info.memmap_entries = 0;
//! (start_info, vec![memmap_entry])
//! }
//!
//! # #[cfg(all(
//! # any(target_arch = "x86", target_arch = "x86_64"),
//! # any(feature = "elf", feature = "pe", feature = "bzimage")
//! # ))]
//! fn main() {
//! let guest_mem = GuestMemoryMmap::from_ranges(&[(GuestAddress(0x0), MEM_SIZE)]).unwrap();
//!
//! let mut elf_pvh_image = Vec::new();
//! let path = concat!(
//! env!("CARGO_MANIFEST_DIR"),
//! "/src/loader/elf/test_elfnote.bin"
//! );
//! let mut file = File::open(path).unwrap();
//! file.read_to_end(&mut elf_pvh_image).unwrap();
//!
//! // Load the kernel image.
//! let loader_result =
//! Elf::load(&guest_mem, None, &mut Cursor::new(&elf_pvh_image), None).unwrap();
//!
//! // Build boot parameters.
//! let (mut start_info, memmap_entries) = build_boot_params();
//! // Address in guest memory where the `start_info` struct will be written.
//! let start_info_addr = GuestAddress(0x6000);
//! // Address in guest memory where the memory map will be written.
//! let memmap_addr = GuestAddress(0x7000);
//! start_info.memmap_paddr = memmap_addr.raw_value();
//!
//! // Write boot parameters in guest memory.
//! let mut boot_params = BootParams::new::<hvm_start_info>(&start_info, start_info_addr);
//! boot_params.set_sections::<hvm_memmap_table_entry>(&memmap_entries, memmap_addr);
//! PvhBootConfigurator::write_bootparams::<GuestMemoryMmap>(&boot_params, &guest_mem).unwrap();
//! }
//!
//! # #[cfg(all(
//! # any(target_arch = "aarch64", target_arch = "riscv64"),
//! # any(feature = "elf", feature = "pe", feature = "bzimage")
//! # ))]
//! # fn main() {}
//!
//! # #[cfg(not(any(feature = "elf", feature = "pe", feature = "bzimage")))]
//! # fn main() {}
//! ```
//!
//! [`BootConfigurator`]: trait.BootConfigurator.html
//! [`KernelLoader`]: trait.KernelLoader.html
pub use *;
extern crate vm_memory;