Add some comments

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 <https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header> 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<here the process starts its execution.
+    /// If the program doesn't have an entrypoint (i.e. not an executable), the value is 0
+    /// 
+    /// Offset: 0x18, size: 4 (32 bits) or 8 (64 bits)
     pub entrypoint: u64,
+    /// Size of the elf header, 64 bytes for 64 bits and 52 for 32 bits
+    /// 
+    /// Offset: 0x28(32 bits) or 0x34 (64 bits), size: 2 bytes
     pub elf_header_size: u16,
+    /// Position of the first program header entry
+    /// 
+    /// Offset: 0x1C (32 bits) or 0x20 (64 bits), size: 4 (32 bits) or 8 (64 bits) bytes
     pub program_header_location: u64,
+    /// Number of entries in the progream header table
+    /// 
+    /// Offset: 0x2C (32 bits) or 0x38 (64 bits), size: 2 bytes
     pub program_header_entries: u16,
+    /// Size of a program header entry
+    /// 
+    /// Offset: 0x2A (32 bits) or 0x36 (64 bits), size: 2 bytes
     pub program_header_size: u16,
+    /// Position of the first section header entry
+    /// 
+    /// Offset: 0x20 (32 bits) or 0x28 (64 bits), size: 4 (32 bits) or 8 (64 bits) bytes
     pub section_header_location: u64,
+    /// Number of entries in the section header table
+    /// 
+    /// Offset: 0x30 (32 bits) or 0x3C (64 bits), size: 2 bytes
     pub section_header_entries: u16,
+    /// Size of a section header entry
+    /// 
+    /// Offset: 0x2E (32 bits) or 0x36 (64 bits), size: 2 bytes
     pub section_header_size: u16,
 }
 
 impl ElfHeader {
     
     /// return true if the 4 first bytes constitude the elf magic number
-    fn is_elf(instructions: &Vec<u8>) -> 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<u8>) -> 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<u8>) -> 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<u8>) -> Option<u8> {
+    fn get_version(instructions: &[u8]) -> Option<u8> {
         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<u8>) -> 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<u8>) -> 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<u8>, is_32bits: bool) -> Option<u64> {
+    /// 
+    /// ## 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<u64> {
         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<u8>, is_32bits: bool) -> Option<u64> {
+    /// 
+    /// ## 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<u64> {
         if is_32bits {
             get_address_point(instructions, 0x1c, true)
         } else {
@@ -100,7 +156,12 @@ impl ElfHeader {
     }
 
     /// Memory address of the start of the section header table
-    fn get_section_header_table_location(instructions: &Vec<u8>, is_32bits: bool) -> Option<u64> {
+    ///
+    ///  ## 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<u64> {
         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<u8>, is_32bits: bool) -> Option<u16> {
+    /// 
+    /// ## 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<u16> {
         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<u8>, is_32bits: bool) -> Option<u16> {
+    /// 
+    /// ## 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<u16> {
         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<u8>, is_32bits: bool) -> Option<u16> {
+    /// 
+    /// ## 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<u16> {
         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<u8>, is_32bits: bool) -> Option<u16> {
+    /// 
+    /// ## 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<u16> {
         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<u8>, is_32bits: bool) -> Option<u16> {
+    /// 
+    /// ## 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<u16> {
         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<u8>, address: usize) -> Option<u16> {
+    /// 
+    /// 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<u16> {
         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<u8>> 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 <https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#Section_header>
 #[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<u8>, address: usize) -> Option<u32> {
+    /// Return the offset to a string in .shstrtab that represents the name of this section
+    fn get_name_offset(instructions: &[u8], address: usize) -> Option<u32> {
         get_address_point(instructions, address, true).map(|v| { v as u32 })
                                                         // set true to return a u32
     }
 
-    fn get_header_type(instructions: &Vec<u8>, address: usize) -> Option<u32> {
+    /// Return the type of header of the section
+    fn get_header_type(instructions: &[u8], address: usize) -> Option<u32> {
         get_address_point(instructions, address + 0x4, true).map(|v| { v as u32 })
     }
 
-    fn get_flags(instructions: &Vec<u8>, address: usize, is_32bits: bool) -> Option<u64> {
+    /// Return the flags of the section, can hold multiples values, see [`FlagValue`]
+    fn get_flags(instructions: &[u8], address: usize, is_32bits: bool) -> Option<u64> {
         get_address_point(instructions, address + 0x8, is_32bits)
     }
 
-    fn get_virtual_address(instructions: &Vec<u8>, address: usize, is_32bits: bool) -> Option<u64> {
+
+    /// 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<u64> {
         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<u8>, address: usize, is_32bits: bool) -> Option<u64> {
+fn get_address_point(instructions: &[u8], address: usize, is_32bits: bool) -> Option<u64> {
     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);