From 6f8721b37679072a1d23f8eb276544268496687b Mon Sep 17 00:00:00 2001 From: antifallobst Date: Wed, 15 Mar 2023 21:08:02 +0100 Subject: [PATCH] noxos (docs): merged 'drivers/elf' docs from .wiki --- .../noxos/docs/codebase/drivers/elf.md | 5 ++ .../noxos/docs/codebase/drivers/elf/_index.md | 4 ++ .../noxos/docs/codebase/drivers/elf/elf.h.md | 33 ++++++++++++ .../docs/codebase/drivers/elf/header.h.md | 54 +++++++++++++++++++ .../docs/codebase/drivers/elf/mapping.h.md | 19 +++++++ .../docs/codebase/drivers/elf/section.h.md | 35 ++++++++++++ .../docs/codebase/drivers/elf/segment.h.md | 29 ++++++++++ .../docs/codebase/drivers/elf/symbol.h.md | 27 ++++++++++ 8 files changed, 206 insertions(+) create mode 100644 content/projects/noxos/docs/codebase/drivers/elf.md create mode 100644 content/projects/noxos/docs/codebase/drivers/elf/_index.md create mode 100644 content/projects/noxos/docs/codebase/drivers/elf/elf.h.md create mode 100644 content/projects/noxos/docs/codebase/drivers/elf/header.h.md create mode 100644 content/projects/noxos/docs/codebase/drivers/elf/mapping.h.md create mode 100644 content/projects/noxos/docs/codebase/drivers/elf/section.h.md create mode 100644 content/projects/noxos/docs/codebase/drivers/elf/segment.h.md create mode 100644 content/projects/noxos/docs/codebase/drivers/elf/symbol.h.md diff --git a/content/projects/noxos/docs/codebase/drivers/elf.md b/content/projects/noxos/docs/codebase/drivers/elf.md new file mode 100644 index 0000000..a8d245e --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/elf.md @@ -0,0 +1,5 @@ +--- +title: "elf" +summary: "ELF executable parser" +--- + diff --git a/content/projects/noxos/docs/codebase/drivers/elf/_index.md b/content/projects/noxos/docs/codebase/drivers/elf/_index.md new file mode 100644 index 0000000..a72de5d --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/elf/_index.md @@ -0,0 +1,4 @@ +--- +title: "elf" +--- + diff --git a/content/projects/noxos/docs/codebase/drivers/elf/elf.h.md b/content/projects/noxos/docs/codebase/drivers/elf/elf.h.md new file mode 100644 index 0000000..0b3fac8 --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/elf/elf.h.md @@ -0,0 +1,33 @@ +--- +title: "elf.h" +summary: "The ELF-parsers' heart" +--- + +#### `elf_executable_T` - struct +This struct holds the parsed data of an ELF executable. + +| Name | Type | Description | +|--------------|-------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| +| header | [elf_header_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_header_t---struct) | The header of the elf file | +| num_symbols | uint64_t | The size of _symbols_ | +| symbols | symbol_T* | An array containing all symbols of the elf file | +| num_mappings | uint64_t | The size of _mappings_ | +| mappings | [elf_mapping_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/mapping.h/#elf_mapping_t---struct)* | An array containing the mappings needed to load the elf file | +| string_table | void* | A copy of the elf files `.strtab` section, all strings are referenced here to have them available even if the elf file is closed | + +#### `elf_executable_temp_T` - struct +This struct is used while generating an [elf_executable_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/elf.h/#elf_executable_t---struct). +It holds parse-time information about the elf file. + +| Name | Type | Description | +|-----------------------------|---------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| executable | [elf_executable_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/elf.h/#elf_executable_t---struct)* | A pointer to the final [elf_executable_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/elf.h/#elf_executable_t---struct) | +| symbol_table | [elf_section_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/section.h/#elf_section_t---struct)* | A pointer to `.symtab` in _buffer_ | +| section_header_string_table | [elf_section_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/section.h/#elf_section_t---struct)* | A pointer to `.shstrtab` in _buffer_ | +| buffer | uint8_t* | The buffer where the executable is loaded from | + +#### `elf_executable_create(buffer)` - function (elf_executable_T*) +Generates an [elf_executable_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/elf.h/#elf_executable_t---struct) from an elf file loaded to **_buffer_** and returns a pointer to it. + +#### `elf_executable_destruct(executable)` - function (void) +Frees all memory allocated for [**_executable_**](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/elf.h/#elf_executable_t---struct). \ No newline at end of file diff --git a/content/projects/noxos/docs/codebase/drivers/elf/header.h.md b/content/projects/noxos/docs/codebase/drivers/elf/header.h.md new file mode 100644 index 0000000..8022414 --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/elf/header.h.md @@ -0,0 +1,54 @@ +--- +title: "header.h" +summary: "definitions needed to parse the ELF Header" +--- + +# `elf_target_architecture_E` - enum +Field in [header](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_header_t---struct): **identity[4]** + +# `elf_endianness_E` - enum +Field in [header](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_header_t---struct): **identity[5]** + +# `elf_sysabi_E` - enum +Field in [header](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_header_t---struct): **identity[7]** + +# `elf_object_type_E` - enum +Field in [header](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_header_t---struct): **type** + +# `elf_instruction_set_E` - enum +Field in [header](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_header_t---struct): **isa** + +# `elf_header_T` - struct + +| Name | Type | Description | +|----------------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| +| identity | uint8_t[16] | Information like the used endian and the SysABI is stored in here | +| type | uint16_t | The type of the elf file -> [elf_object_type_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_object_type_e---enum) | +| isa | uint16_t | The used instruction set -> [elf_instruction_set_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_instruction_set_e---enum) | +| version | uint32_t | ELF version | +| address_entry_point | uint64_t | The start point for program execution | +| offset_program_header | uint64_t | The position of the program header array in the file | +| offset_section_header | uint64_t | The position of the section header array in the file | +| flags | uint32_t | Architecture dependent, can be ignored | +| len_header | uint16_t | The size of this header | +| len_program_header_entry | uint16_t | The size of one program header | +| num_program_header_entries | uint16_t | The amount of program headers | +| len_section_header_entry | uint16_t | The size of one section header | +| num_section_header_entries | uint16_t | The amount of section headers | +| string_section_index | uint16_t | The section header index of the `.shstrtab` section | + + +# `g_elf_target_architecture_strings` - global variable +An array of strings matching [elf_target_architecture_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_target_architecture_e---enum). + +# `g_elf_endianness_strings` - global variable +An array of strings matching [elf_endianess_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_endianess_e---enum). + +# `g_elf_sysabi_strings` - global variable +An array of strings matching [elf_sysabi_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_sysabi_e---enum). + +# `g_elf_object_type_strings` - global variable +An array of strings matching [elf_object_type_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_object_type_e---enum). + +# `g_elf_instruction_set_strings` - global variable +An array of strings matching [elf_instruction_set_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/header.h/#elf_instruction_set_e---enum). \ No newline at end of file diff --git a/content/projects/noxos/docs/codebase/drivers/elf/mapping.h.md b/content/projects/noxos/docs/codebase/drivers/elf/mapping.h.md new file mode 100644 index 0000000..f0ca60c --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/elf/mapping.h.md @@ -0,0 +1,19 @@ +--- +title: "mapping.h" +summary: "handles the memory mappings that an ELF file can request" +--- + +# `elf_mapping_T` - struct +A mapping describes an area of memory, +that should be copied from the elf file into the RAM and how/where it should be mapped. + +| Name | Type | Description | +|----------------|----------|------------------------------------------------------------------------------------------------------------------| +| offset_file | uint64_t | The mappings' start in the elf file | +| offset_virtual | uint64_t | The mappings' start in memory | +| length_file | uint64_t | The mappings' size in the elf file | +| length_virtual | uint64_t | The mappings' size in memory, if this is bigger than _length_file_ the remaining space will be filled with zeros | + +# `elf_mappings_apply(mappings, num_mappings, buffer, base, page_map)` - function (void) +Maps all **_mappings_** into **_page_map_** and copies the related data from **_buffer_** (elf file) to the mapped memory. +**_base_** specifies where the mappings should start in the virtual address space. diff --git a/content/projects/noxos/docs/codebase/drivers/elf/section.h.md b/content/projects/noxos/docs/codebase/drivers/elf/section.h.md new file mode 100644 index 0000000..b6bf7a4 --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/elf/section.h.md @@ -0,0 +1,35 @@ +--- +title: "section.h" +summary: "definitions needed to parse the elf section headers" +--- + +# `elf_section_type_E` - enum +- **Null** - These sections can be ignored +- **Program Data** - These link to segments, if I remember right +- **Symbol Table** - Here are all the executables' symbols stored +- **String Table** - Here are all strings stored +- **RelocationA** - Contains relocation information +- **Hash** - Symbol Table hash table +- **Dynamic Link** - This provides information for the dynamic linker +- **Note** - notes that were created by the compiler / toolchain +- **Nobits** - Nulled data like `.bss` + +# `elf_section_T` - struct + +| Name | Type | Description | +|-----------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| name_offset | uint32_t | The offset of the sections name in `.shstrtab` | +| type | uint32_t | The type of the section -> [elf_section_type_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/section.h/#elf_section_type_e---enum) | +| flags | uint64_t | Sections attribute flags | +| virtual_address | uint64_t | The address where the section should be mapped to (if it's not 0) | +| offset | uint64_t | The sections offset in the file | +| length | uint64_t | The size of the section | +| link | uint32_t | Type specific link to another section | +| info | uint32_t | Type specific information | +| alignment | uint64_t | If the section is aligned, this value specifies the alignment | +| entry_size | uint64_t | The size of the sections entries | + + +# `g_elf_section_type_strings` - global variable +An array of strings matching [elf_section_type_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/section.h/#elf_section_type_e---enum). + diff --git a/content/projects/noxos/docs/codebase/drivers/elf/segment.h.md b/content/projects/noxos/docs/codebase/drivers/elf/segment.h.md new file mode 100644 index 0000000..ae76543 --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/elf/segment.h.md @@ -0,0 +1,29 @@ +--- +title: "segment.h" +summary: "definitions needed to parse the elf program/segment headers" +--- + +# `elf_segment_type_E` - enum +- **Null** - Unused segment +- **Load** - Segment that should be included into mappings +- **Dynamic** - Segments of this type contain dynamic linking information +- **Interpreter** - This holds a path to an interpreter +- **Note** - These segments hold notes by the compiler / toolchain +- **Program Header Table** - This points to the table that is holding the segment headers +- **TLS** - This holds a Thread Local Storage template + +# `elf_segment_T` - struct + +| Name | Type | Description | +|------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------| +| type | uint32_t | The segments type -> [elf_segment_type_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/segment.h/#elf_segment_type_e---enum) | +| flags | uint32_t | The segments flags (Read / Write / Execute) | +| offset | uint64_t | The segments position in the elf file | +| address_virtual | uint64_t | Where the segment should be mapped in the virtual address space | +| address_physical | uint64_t | Not used in the `System V` ABI | +| length_file | uint64_t | The segments size in the file | +| length_memory | uint64_t | The size of the area that should be mapped for the segment | +| align | uint64_t | The segments alignment (has to be a power of 2) | + +# `g_elf_segment_type_strings` - global variable +An array of strings matching [elf_segment_type_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/segment.h/#elf_segment_type_e---enum). diff --git a/content/projects/noxos/docs/codebase/drivers/elf/symbol.h.md b/content/projects/noxos/docs/codebase/drivers/elf/symbol.h.md new file mode 100644 index 0000000..2cda660 --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/elf/symbol.h.md @@ -0,0 +1,27 @@ +--- +title: "symbol.h" +summary: "stuff needed to extract symbols from an ELFs `.symtab` section" +--- + +# `ELF_SYMBOL_TYPE(info)` - macro +Extracts the [elf_symbol_type_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/symbol.h/#elf_symbol_type_e---enum) from the symbols info value. + +# `elf_symbol_type_E` - enum +- **None** - Unspecified type +- **Object** - Data objects like variables, arrays, etc. +- **Func** - Function +- **Section** - Associated section +- **File** - The path to the source file associated with the object +- **Common** - Uninitialized common blocks +- **TLS** - Thread Local Storage + +# `elf_symbol_T` - struct + +| Name | Type | Description | +|-----------------------|-------------------------------------------------------------------|-------------| +| name_offset | The offset of the symbols name in `.strtab` | | +| info | Information about the symbol (type, bind) | | +| other | Information about the symbol (visibility) | | +| related_section_index | The index of the symbols related section | | +| value | Value, in most cases this is an address | | +| length | The size of the symbol (e.g. num bytes if the symbol is an array) | |