linux_bzimage_builder/
lib.rs

1// SPDX-License-Identifier: MPL-2.0
2
3//! The linux bzImage builder.
4//!
5//! This crate is responsible for building the bzImage. It contains methods to build
6//! the setup binary (with source provided in another crate) and methods to build the
7//! bzImage from the setup binary and the kernel ELF.
8//!
9//! We should build the asterinas kernel as an ELF file, and feed it to the builder to
10//! generate the bzImage. The builder will generate the PE/COFF header for the setup
11//! code and concatenate it to the ELF file to make the bzImage.
12//!
13//! The setup code should be built into the ELF target and we convert it to a flat binary
14//! in the builder.
15
16#[macro_use]
17extern crate ostd_pod;
18
19pub mod encoder;
20mod mapping;
21mod pe_header;
22
23use std::{
24    fs::File,
25    io::{Read, Seek, SeekFrom, Write},
26    path::Path,
27};
28
29use align_ext::AlignExt;
30pub use encoder::{PayloadEncoding, encode_kernel};
31use mapping::{SetupFileOffset, SetupVA};
32use xmas_elf::{program::SegmentData, sections::SectionData};
33
34/// The type of the bzImage that we are building through `make_bzimage`.
35///
36/// Currently, Legacy32 and Efi64 are mutually exclusive.
37pub enum BzImageType {
38    Legacy32,
39    Efi64,
40}
41
42/// Making a bzImage given the kernel ELF and setup source.
43///
44/// Explanations for the arguments:
45///  - `target_image_path`: The path to the target bzImage;
46///  - `image_type`: The type of the bzImage that we are building;
47///  - `setup_elf_path`: The path to the setup ELF;
48///
49pub fn make_bzimage(target_image_path: &Path, image_type: BzImageType, setup_elf_path: &Path) {
50    let mut setup_elf = Vec::new();
51    File::open(setup_elf_path)
52        .unwrap()
53        .read_to_end(&mut setup_elf)
54        .unwrap();
55    let mut setup = to_flat_binary(&setup_elf);
56    // Align the flat binary to `SECTION_ALIGNMENT`.
57    setup.resize(setup.len().align_up(pe_header::SECTION_ALIGNMENT), 0x00);
58
59    let mut kernel_image = File::create(target_image_path).unwrap();
60    kernel_image.write_all(&setup).unwrap();
61
62    if matches!(image_type, BzImageType::Efi64) {
63        assert_elf64_reloc_supported(&setup_elf);
64
65        // Write the PE/COFF header to the start of the file.
66        // Since the Linux boot header starts at 0x1f1, we can write the PE/COFF header directly to the
67        // start of the file without overwriting the Linux boot header.
68        let pe_header = pe_header::make_pe_coff_header(&setup_elf);
69        assert!(pe_header.len() <= 0x1f1, "PE/COFF header is too large");
70
71        kernel_image.seek(SeekFrom::Start(0)).unwrap();
72        kernel_image.write_all(&pe_header).unwrap();
73    }
74}
75
76/// To build the legacy32 bzImage setup header, the OSDK should use this target.
77pub fn legacy32_rust_target_json() -> &'static str {
78    include_str!("x86_64-i386_pm-none.json")
79}
80
81/// We need a flat binary which satisfies PA delta == File offset delta,
82/// and objcopy does not satisfy us well, so we should parse the ELF and
83/// do our own objcopy job.
84///
85/// Interestingly, the resulting binary should be the same as the memory
86/// dump of the kernel setup header when it's loaded by the bootloader.
87fn to_flat_binary(elf_file: &[u8]) -> Vec<u8> {
88    let elf = xmas_elf::ElfFile::new(elf_file).unwrap();
89    let mut bin = Vec::<u8>::new();
90
91    for program in elf.program_iter() {
92        if program.get_type().unwrap() == xmas_elf::program::Type::Load {
93            let SegmentData::Undefined(header_data) = program.get_data(&elf).unwrap() else {
94                panic!("Unexpected segment data type");
95            };
96            let dst_file_offset = usize::from(SetupFileOffset::from(SetupVA::from(
97                program.virtual_addr() as usize,
98            )));
99
100            // Note that `mem_size` can be greater than `file_size`. The remaining part must be
101            // filled with zeros.
102            let mem_length = program.mem_size() as usize;
103            if bin.len() < dst_file_offset + mem_length {
104                bin.resize(dst_file_offset + mem_length, 0);
105            }
106
107            // Copy the bytes in the `file_size` part.
108            let file_length = program.file_size() as usize;
109            let dest_slice = bin[dst_file_offset..dst_file_offset + file_length].as_mut();
110            dest_slice.copy_from_slice(header_data);
111        }
112    }
113
114    bin
115}
116
117fn assert_elf64_reloc_supported(elf_file: &[u8]) {
118    const R_X86_64_RELATIVE: u32 = 8;
119
120    let elf = xmas_elf::ElfFile::new(elf_file).unwrap();
121
122    let SectionData::Rela64(rela64) = elf
123        .find_section_by_name(".rela")
124        .unwrap()
125        .get_data(&elf)
126        .unwrap()
127    else {
128        panic!("the ELF64 relocation data is not of the correct type");
129    };
130
131    rela64.iter().for_each(|r| {
132        assert_eq!(
133            r.get_type(),
134            R_X86_64_RELATIVE,
135            "the ELF64 relocation type is not supported"
136        )
137    });
138}
linux_bzimage_builder/lib.rs

linux_bzimage_builder/
lib.rs
