From 025ede6080b3e92a876cbdea058cbe28f5c6b99c Mon Sep 17 00:00:00 2001 From: Quentin Legot Date: Mon, 3 Apr 2023 15:26:55 +0200 Subject: [PATCH] Add some comments --- src/simulator/loader.rs | 194 +++++++++++++++++++++++++++++++++------- 1 file changed, 164 insertions(+), 30 deletions(-) diff --git a/src/simulator/loader.rs b/src/simulator/loader.rs index a3350e9..3952013 100644 --- a/src/simulator/loader.rs +++ b/src/simulator/loader.rs @@ -1,5 +1,4 @@ use crate::Machine; -use std::fmt::Error; use std::fs; use std::io::Read; @@ -24,65 +23,117 @@ pub fn load(path: &str, machine: &mut Machine, start_index: usize) -> Result<(), instructions.push(u32::from_le_bytes(buf)); } } - for i in 0..instructions.len() { - machine.write_memory(4, 4 * i + start_index, instructions[i] as u64); + for (i, inst) in instructions.iter().enumerate() { + machine.write_memory(4, 4 * i + start_index, inst.to_owned() as u64); } // #[cfg(debug_assertions)] // println!("{:04x?}", instructions); // only print loaded program in debug build Ok(()) } +/// The elf header defines principes aspects of the binary files, it's place at the start of the file +/// see for more informations pub struct ElfHeader { + /// Defines whether the file is big or little endian + /// true correspond to big endian, false otherwise + /// + /// Offset: 0x05, size: 1 byte pub endianess: bool, + /// Defines whether the file is 32 bits or 64 bits + /// + /// Offset: 0x04, size: 1 byte pub is_32bits: bool, + /// Version of the elf file, current version is 1 + /// + /// Offset: 0x06, size: 1 byte pub version: u8, + /// Identifies the target ABI. + /// + /// In this implementation: Defines if the target abi is system V compliant + /// + /// Offset: 0x07, size: 1 byte pub sys_v_abi: bool, + /// Identifies target ISA, 0xF3 correspond to RISC-V + /// + /// In this implementatio, true if target isa is RISC-V, false otherwise + /// + /// Offset: 0x12, size: 2 bytes pub is_riscv_target: bool, + /// Memory address of the entry point from w) -> bool { + fn is_elf(instructions: &[u8]) -> bool { instructions.get(0..4) == Option::Some(&[0x7f, 0x45, 0x4c, 0x46]) } /// return true if big endian, false otherwise - fn check_endianess(instructions: &Vec) -> bool { + fn check_endianess(instructions: &[u8]) -> bool { instructions.get(5) == Option::Some(&2) } /// return true if file is 32 bits, false if 64 bits - fn is_32bits(instructions: &Vec) -> bool { + fn is_32bits(instructions: &[u8]) -> bool { instructions.get(4) == Option::Some(&1) } /// return the version of the elf file (should be 1) /// Can be None if the file is smaller than 7 bytes -> the file is invalid - fn get_version(instructions: &Vec) -> Option { + fn get_version(instructions: &[u8]) -> Option { instructions.get(6).copied() // work as primitives implements Copy } /// return true if target abi of the binary file is System V, false otherwise - fn is_system_v_elf(instructions: &Vec) -> bool { + fn is_system_v_elf(instructions: &[u8]) -> bool { instructions.get(7) == Option::Some(&0) } /// return true if specified target instruction set architecture is RISCV - fn is_riscv_isa(instructions: &Vec) -> bool { + fn is_riscv_isa(instructions: &[u8]) -> bool { Self::get_u16_value(instructions, 0x12) == Option::Some(0xf3) } /// memory address of the entry point from where the process starts its execution - fn get_entrypoint(instructions: &Vec, is_32bits: bool) -> Option { + /// + /// ## Arguments: + /// + /// **instructions** List of bytes of the loaded binary file + /// **is_32bits** defines whether the binary file is 32 bits or 64 bits + fn get_entrypoint(instructions: &[u8], is_32bits: bool) -> Option { if is_32bits { get_address_point(instructions, 0x18, true) } else { @@ -91,7 +142,12 @@ impl ElfHeader { } /// Memory address of the start of the program header table - fn get_program_header_table_location(instructions: &Vec, is_32bits: bool) -> Option { + /// + /// ## Arguments: + /// + /// **instructions** List of bytes of the loaded binary file + /// **is_32bits** defines whether the binary file is 32 bits or 64 bits + fn get_program_header_table_location(instructions: &[u8], is_32bits: bool) -> Option { if is_32bits { get_address_point(instructions, 0x1c, true) } else { @@ -99,8 +155,13 @@ impl ElfHeader { } } - /// Memory address of the start of the section header table - fn get_section_header_table_location(instructions: &Vec, is_32bits: bool) -> Option { + /// Memory address of the start of the section header table + /// + /// ## Arguments: + /// + /// **instructions** List of bytes of the loaded binary file + /// **is_32bits** defines whether the binary file is 32 bits or 64 bits + fn get_section_header_table_location(instructions: &[u8], is_32bits: bool) -> Option { if is_32bits { get_address_point(instructions, 0x20, true) } else { @@ -109,37 +170,69 @@ impl ElfHeader { } /// Return the size of the header, normally, 0x40 for 64 bits bin and 0x34 for 32 bits - fn get_elf_header_size(instructions: &Vec, is_32bits: bool) -> Option { + /// + /// ## Arguments: + /// + /// **instructions** List of bytes of the loaded binary file + /// **is_32bits** defines whether the binary file is 32 bits or 64 bits + fn get_elf_header_size(instructions: &[u8], is_32bits: bool) -> Option { let address = if is_32bits { 0x28 } else { 0x34 }; Self::get_u16_value(instructions, address) } /// return the size of a program header table entry - fn get_program_header_size(instructions: &Vec, is_32bits: bool) -> Option { + /// + /// ## Arguments: + /// + /// **instructions** List of bytes of the loaded binary file + /// **is_32bits** defines whether the binary file is 32 bits or 64 bits + fn get_program_header_size(instructions: &[u8], is_32bits: bool) -> Option { let address = if is_32bits { 0x2a } else { 0x36 }; Self::get_u16_value(instructions, address) } /// return the number of entries in the program header - fn get_number_entries_program_header(instructions: &Vec, is_32bits: bool) -> Option { + /// + /// ## Arguments: + /// + /// **instructions** List of bytes of the loaded binary file + /// **is_32bits** defines whether the binary file is 32 bits or 64 bits + fn get_number_entries_program_header(instructions: &[u8], is_32bits: bool) -> Option { let address = if is_32bits { 0x2c } else { 0x38 }; Self::get_u16_value(instructions, address) } /// Return the size of a section header table entry - fn get_section_header_size(instructions: &Vec, is_32bits: bool) -> Option { + /// + /// ## Arguments: + /// + /// **instructions** List of bytes of the loaded binary file + /// **is_32bits** defines whether the binary file is 32 bits or 64 bits + fn get_section_header_size(instructions: &[u8], is_32bits: bool) -> Option { let address = if is_32bits { 0x2e } else { 0x3a }; Self::get_u16_value(instructions, address) } /// Return the number of entries in the section header - fn get_section_header_num_entries(instructions: &Vec, is_32bits: bool) -> Option { + /// + /// ## Arguments: + /// + /// **instructions** List of bytes of the loaded binary file + /// **is_32bits** defines whether the binary file is 32 bits or 64 bits + fn get_section_header_num_entries(instructions: &[u8], is_32bits: bool) -> Option { let address = if is_32bits { 0x30 } else { 0x3c }; Self::get_u16_value(instructions, address) } /// Return a u16 value, usually for the size or the number of entries inside a header - fn get_u16_value(instructions: &Vec, address: usize) -> Option { + /// + /// This method retrieve 2 bytes and concatenate them assuming the file is little endian + /// + /// ## Arguments: + /// + /// **instructions** List of bytes of the loaded binary file + /// **address** Position of the first byte + fn get_u16_value(instructions: &[u8], address: usize) -> Option { let mut bytes: [u8; 2] = [0; 2]; bytes[0] = instructions.get(address).copied()?; bytes[1] = instructions.get(address + 1).copied()?; @@ -188,27 +281,63 @@ impl TryFrom<&Vec> for ElfHeader { } +/// Flag of a section, a section can have multiples flags by adding the values +#[allow(clippy::enum_variant_names)] +#[allow(dead_code)] pub enum FlagValue { + /// The section is writable ShfWrite = 0x1, + /// The section need to be allocate/occupe memory during execution ShfAlloc = 0x2, + /// The section need to be executable ShfExecinstr = 0x4, + /// Section might ber merged ShfMerge = 0x10, + /// Contain null-terminated (\0) strings ShfStrings = 0x20, - ShfInfoLink = 0x40, - ShfLinkOrder = 0x80, // There is others but are unrelevant (I think) } + +/// Section header entry, contains useful informations for each sections of the binary file +/// +/// see #[derive(Debug)] pub struct SectionHeader { + /// Offset to a string in .shstrtab section that represent the name of this section + /// + /// Offset: 0x0, size: 4 bytes pub name_offset: u32, + /// Identify the type of this header + /// + /// Offset: 0x4, size: 4 bytes pub header_type: u32, + /// Identify the atributes of this section + /// + /// see `Self::does_flag_contains_key(self, FlagValue)` + /// + /// Offset: 0x8, size: 4 (32 bits) or 8 (64 bits) bytes pub flags: u64, + /// Virtual address of the section in memory if section is loaded, 0x0 otherwise + /// + /// Offset: 0x0C (32 bits) or 0x10 (64 bits), size: 4 (32 bits) or 8 (64 bits) bytes pub virt_addr: u64, + /// Offset of the section in the file image (binary file) + /// + /// Offset: 0x10 (32 bits) or 0x18 (64 bits), size: 4 (32 bits) or 8 (64 bits) bytes pub image_offset: u64, + /// Size of the section in the file image, may be 0 + /// + /// Offset: 0x14 (32 bits) or 0x20 (64 bits), size: 4 (32 bits) or 8 (64 bits) bytes pub section_size: u64, pub section_link: u32, pub section_info: u32, + /// Contain the required alignment of the section, must be a power of 2 + /// + /// Offset: 0x20 (32 bits) or 0x30 (64 bits), size: 4 (32 bits) or 8 (64 bits) bytes pub required_align: u64, + /// Contain the size of each entry, for sections that contain fixed size entries, otherwise 0 + /// + /// Offset: 0x24 (32 bits) or 0x38 (64 bits), size: 4 (32 bits) or 8 (64 bits) bytes pub entry_size: u64 } @@ -219,20 +348,25 @@ impl SectionHeader { self.flags & key as u64 != 0 } - fn get_name_offset(instructions: &Vec, address: usize) -> Option { + /// Return the offset to a string in .shstrtab that represents the name of this section + fn get_name_offset(instructions: &[u8], address: usize) -> Option { get_address_point(instructions, address, true).map(|v| { v as u32 }) // set true to return a u32 } - fn get_header_type(instructions: &Vec, address: usize) -> Option { + /// Return the type of header of the section + fn get_header_type(instructions: &[u8], address: usize) -> Option { get_address_point(instructions, address + 0x4, true).map(|v| { v as u32 }) } - fn get_flags(instructions: &Vec, address: usize, is_32bits: bool) -> Option { + /// Return the flags of the section, can hold multiples values, see [`FlagValue`] + fn get_flags(instructions: &[u8], address: usize, is_32bits: bool) -> Option { get_address_point(instructions, address + 0x8, is_32bits) } - fn get_virtual_address(instructions: &Vec, address: usize, is_32bits: bool) -> Option { + + /// Return the virtual address of the section in memory if the sectino is loaded(see section flag), otherwise 0 + fn get_virtual_address(instructions: &[u8], address: usize, is_32bits: bool) -> Option { get_address_point(instructions, address + if is_32bits { 0x0C } else { 0x10 }, is_32bits) } @@ -398,7 +532,7 @@ impl Loader { /// return the memory address of something stored at address /// Can return None if the file is smaller than adress + 3 (or 7 if 64 bits), in this case, the elf header is incorrect -fn get_address_point(instructions: &Vec, address: usize, is_32bits: bool) -> Option { +fn get_address_point(instructions: &[u8], address: usize, is_32bits: bool) -> Option { if is_32bits { let mut bytes: [u8; 4] = [0; 4]; bytes[0] = instructions.get(address).copied()?; @@ -431,10 +565,10 @@ mod test { let mut machine = Machine::init_machine(); let loader = Loader::load_and_parse("./test/riscv_instructions/simple_arithmetics/unsigned_addition").expect("IO Error"); loader.load_into_machine(&mut machine, 0).expect("Parsing error"); - assert_eq!(false, loader.elf_header.is_32bits); - assert_eq!(false, loader.elf_header.endianess); - assert_eq!(true, loader.elf_header.sys_v_abi); - assert_eq!(true, loader.elf_header.is_riscv_target); + assert!(!loader.elf_header.is_32bits); + assert!(!loader.elf_header.endianess); + assert!(loader.elf_header.sys_v_abi); + assert!(loader.elf_header.is_riscv_target); assert_eq!(1, loader.elf_header.version); assert_eq!(0x4000, loader.elf_header.entrypoint); assert_eq!(64, loader.elf_header.elf_header_size);