Minor layout fixes (#48)

* Minor layout fixes

* Replace memory manager image

* Fixing indentation and line overflows

* Update yaml headers with margin and image fixes

---------

Co-authored-by: Dean <dean243@hotmail.com>

Author: dreamos82

.pandoc/pandoc.yaml

@@ -5,7 +5,34 @@ author:
   - Dean T.
 header-includes:
  - \usepackage{fvextra}
+ - \usepackage{geometry}
  - \usepackage[page,toc,titletoc,title]{appendix}
+ - \usepackage{fancyhdr}
+ - \pagestyle{fancy}
+ - \fancyhead[LE]{\leftmark}
+ - \fancyhead[RE]{\thepage}
+ - \fancyhead[LO]{\thepage}
+ - \fancyhead[RO]{\rightmark}
+ - \usepackage{float}
+ - |
+  ```{=latex}
+  \let\origfigure\figure
+  \let\endorigfigure\endfigure
+  \renewenvironment{figure}[1][2] {
+     \expandafter\origfigure\expandafter[H]
+  } {
+      \endorigfigure
+  }
+  ```
  - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}
+geometry: 
+ - tmargin=2.5cm
+ - bmargin=2.5cm
+ - lmargin=2.5cm
+ - rmargin=2.5cm
+ - headsep =0.89cm
+ - footskip =0.89cm
+ - columnsep=1.5cm
+ - headheight=1.5cm
 book: true
 ---

02_Architecture/02_Hello_World.md

@@ -55,15 +55,15 @@ static int init_serial() {
    outb(PORT + 2, 0xC7);    // Enable FIFO, clear them, with 14-byte threshold
    outb(PORT + 4, 0x0B);    // IRQs enabled, RTS/DSR set
    outb(PORT + 4, 0x1E);    // Set in loopback mode, test the serial chip
-   outb(PORT + 0, 0xAE);    // Test serial chip (send byte 0xAE and check if serial returns same byte)
+   outb(PORT + 0, 0xAE);    // Send a test byte
  
-   // Check if serial is faulty (i.e: not same byte as sent)
+   // Check that we received the same test byte we sent
    if(inb(PORT + 0) != 0xAE) {
       return 1;
    }
  
-   // If serial is not faulty set it in normal operation mode
-   // (not-loopback with IRQs enabled and OUT#1 and OUT#2 bits enabled)
+   // If serial is not faulty set it in normal operation mode:
+   // not-loopback with IRQs enabled and OUT#1 and OUT#2 bits enabled
    outb(PORT + 4, 0x0F);
    return 0;
 }

02_Architecture/04_GDT.md

@@ -260,18 +260,18 @@ If not familiar with inline assembly, check the appendix on using inline assembl
 void flush_gdt()
 {
     asm volatile("\
-                mov $0x10, %ax \n\
-                mov %ax, %ds \n\
-                mov %ax, %es \n\
-                mov %ax, %fs \n\
-                mov %ax, %gs \n\
-                mov %ax, %ss \n\
-                \n\
-                pop %rdi \n\
-                push $0x8 \n\
-                push %rdi \n\
-                lretq \n\
-            ");
+        mov $0x10, %ax \n\
+        mov %ax, %ds \n\
+        mov %ax, %es \n\
+        mov %ax, %fs \n\
+        mov %ax, %gs \n\
+        mov %ax, %ss \n\
+        \n\
+        pop %rdi \n\
+        push $0x8 \n\
+        push %rdi \n\
+        lretq \n\
+    ");
 }
 ```
 

02_Architecture/06_ACPITables.md

@@ -36,11 +36,11 @@ As already mentioned there are two different version of RSDP, basic data structu
 
 ```c
 struct RSDPDescriptor {
- char Signature[8];
- uint8_t Checksum;
- char OEMID[6];
- uint8_t Revision;
- uint32_t RsdtAddress;
+    char Signature[8];
+    uint8_t Checksum;
+    char OEMID[6];
+    uint8_t Revision;
+    uint32_t RsdtAddress;
 } __attribute__ ((packed));
 ```
 
@@ -55,13 +55,12 @@ Where the fields are:
 The structure for the v2 header is an extension of the previous one, so the fields above are still valid, but in addition it has also the following extra-fields: 
 
 ```c
-struct RSDP2Descriptor
-{
-  //v1 fields
-  uint32_t Length;
-  uint64_t XSDTAddress;
-  uint8_t ExtendedChecksum;
-  uint8_t Reserved[3];
+struct RSDP2Descriptor {
+    //v1 fields
+    uint32_t Length;
+    uint64_t XSDTAddress;
+    uint8_t ExtendedChecksum;
+    uint8_t Reserved[3];
 };
 ```
 
@@ -75,11 +74,11 @@ Before proceeding let's explain little bit better the validation. For both versi
 
 ```c
 bool validate_RSDP(char *byte_array, size_t size) {
- uint32_t sum = 0;
- for(int i = 0; i < size; i++) {
-    sum += byte_array[i];
- }
- return (sum & 0xFF) == 0;
+    uint32_t sum = 0;
+    for(int i = 0; i < size; i++) {
+        sum += byte_array[i];
+    }
+    return (sum & 0xFF) == 0;
 }
 ```
 
@@ -101,15 +100,15 @@ Since every SDT table contains different type of information, they are all diffe
 
 ```c
 struct ACPISDTHeader {
-  char Signature[4];
-  uint32_t Length;
-  uint8_t Revision;
-  uint8_t Checksum;
-  char OEMID[6];
-  char OEMTableID[8];
-  uint32_t OEMRevision;
-  uint32_t CreatorID;
-  uint32_t CreatorRevision;
+    char Signature[4];
+    uint32_t Length;
+    uint8_t Revision;
+    uint8_t Checksum;
+    char OEMID[6];
+    char OEMTableID[8];
+    uint32_t OEMRevision;
+    uint32_t CreatorID;
+    uint32_t CreatorRevision;
 };
 ```
 * The second part is the table itself, every SDT has it's own table
@@ -123,16 +122,14 @@ The RSDT is an SDT header followed by an array of `uint32_t`s, representing the
 The XSDT is the same, except the array is of `uint64_t`s.
 
 ```c
-struct RSDP
-{
-  ACPISDTHeader sdtHeader; //signature "RSDP"
-  uint32_t sdtAddresses[];
+struct RSDP {
+    ACPISDTHeader sdtHeader; //signature "RSDP"
+    uint32_t sdtAddresses[];
 };
 
-struct XSDT
-{
-  ACPISDTHeader sdtHeader; //signature "XSDT"
-  uint64_t sdtAddresses[];
+struct XSDT {
+    ACPISDTHeader sdtHeader; //signature "XSDT"
+    uint64_t sdtAddresses[];
 };
 ```
 

02_Architecture/11_Keyboard_Driver_Implementation.md

@@ -43,8 +43,6 @@ If we want to store just the scancode we don't need much more, so we can already
 ```c
 
 void keyboard_driver_irq_handler() {
-
-    
     uint8_t scancode = inb(0x60); // Read byte from the Keyboard data port
 
     keyboard_buffer[buf_position] = scancode;
@@ -113,20 +111,21 @@ Now by changing the `current_state` variable, we can change how the code will tr
 uint8_t current_state;
 
 void init_keyboard() {
-    // Do other initialization stuff like: clean the keyboard buffer, identify the scancode set, enable the IRQ etc.
+    // You'll want to do other setup here in your own driver:
+    // ensure the input buffer of the keyboard is empty, check which scancode
+    // set is in use, enable irqs.
     current_state = NORMAL_STATE;
 }
 
 void keyboard_driver_irq_handler() {
     int scancode = inb(0x60); // Read byte from the Keyboard data port
     if (scancode == 0xE0) {
         current_state = PREFIX_STATE
-        // We have read a prefix, so let's update the state and finish here
-        // this is a very simple scenario, there could be more needed depending on the design
+        // We have read a prefix, so update the state and exit.
         return;
     }
     if (current_state == PREFIX_STATE) {
-        // Do what you need to store the key_code and eventually translate it to the kernel_code and return to the normal state
+        // Store the next part of the scancode, then return to normal state.
         current_state = NORMAL_STATE;
     }
 }
@@ -214,10 +213,11 @@ We could use the following:
 
 ```c
 
-//an example of our kernel-specific scancodes
+//an example of our kernel-specific scancodes:
+//note that these are totally arbitrary and can be whatever you want.
 typedef enum kernel_scancodes {
     [ ... ]
-    F1 = 0xAABBCCDD, //this can be defined to whatever value you want, the exact value is totally arbitrary.
+    F1 = 0xAABBCCDD, 
     [ ... ]
 };
 

03_Video_Output/02_DrawingTextOnFB.md

@@ -122,8 +122,8 @@ All the fields are 4 bytes in size, so creating a structure that can hold it is
 Let's assume from now on that we have a data structure called PSF_font with all the fields specified above. The first thing that we need of course, is to access to this variable: 
 
 ```C
-// We have linked _binary_font_psf_start from another .o file so we must specify that we are dealing
-// with an external variable 
+// We have linked _binary_font_psf_start from another .o file so we must 
+// specify that we are dealing with an external variable.
 extern char _binary_font_psf_start; 
 PSF_font *default_font = (PSF_font *)&_binary_font_psf_start
 ```
@@ -157,15 +157,18 @@ Below an example of how a glyph is stored:
 The glyphs start right after the psf header, the address of the first character will be then: 
 
 ```C
-uint8_t* first_glyph = (uint8_t*) &_binary_font_psf_start + default_font->headersize
+uint8_t* first_glyph = (uint8_t*) &_binary_font_psf_start + 
+    default_font->headersize
 ```
 
 Since we know that every glyph has the same size, and this is available in the PSF_Header, if we want to access the *i-th* character, we just need to do the following: 
 
 ```C
-uint8_t* selected_glyph_v1 = (uint8_t*) &_binary_font_psf_start + sizeof(PSFv1_Header_Struct) + (i * default_font->bytesperglyph); //psf_v1
+uint8_t* selected_glyph_v1 = (uint8_t*) &_binary_font_psf_start + 
+    sizeof(PSFv1_Header_Struct) + (i * default_font->bytesperglyph);
 
-uint8_t* selected_glyph_v2 = (uint8_t*) &_binary_font_psf_start + default_font->headersize + (i * default_font->bytesperglyph); //psf_v2
+uint8_t* selected_glyph_v2 = (uint8_t*) &_binary_font_psf_start + 
+    default_font->headersize + (i * default_font->bytesperglyph);
 ```
 
 Where in  the v1 case, `PSFv1_Header_Struct` is just the name of the struct containing the PSFv1 definition.

04_Memory_Management/01_Overview.md

@@ -17,13 +17,13 @@ We will cover the following topics:
 
 *Authors note: don't worry, we will try to keep it as simple as possible, using basic algorithms and explaining all the gray areas as we go. The logic may sometimes be hard to follow, you will most likely have to go through several reads of this part multiple times.*
 
-Each of the layers has a dedicated section below, however we'll start with a high level look at how they fit together. Before proceeding let's briefly define the concepts above: 
+Each of the layers has a dedicated chapter, however we'll start with a high level look at how they fit together. Before proceeding let's briefly define the concepts above: 
 
 | Memory Management Layer | Description |
-|---|---|
+|---|------|
 | Physical Memory Manager | Responsible for keeping track of which parts of the available hardware memory (usually ram) are free/in-use. It usually allocates in fixed size blocks, the native page size. This is 4096 bytes on x86.|
 | Paging | It introduces the concepts of *virtual memory* and *virtual addresses*, providing the OS with a bigger address space, protection to the data and code in its pages, and isolation between programs. | 
-| Virtual memory manager | For a lot of projects, the VMM and paging will be the same thing. However the VMM should be seen as the virtual memory *manager*, and paging is just one tool that it uses to accomplish its job: ensuring that a program has memory where it needs it, when it needs it. Often this is just mapping physical ram to the requested virtual address (via paging or segmentation), but it can evolve into stealing pages from other processes. |
+| Virtual memory manager | For a lot of projects, the VMM and paging will be the same thing. However the VMM should be seen as the virtual memory *manager*, and paging is just one tool that it uses to accomplish its job: ensuring that a program has memory where it needs it, when it needs it. Often this is just mapping physical ram to the requested virtual address (via paging or segmentation) |
 | Heap Allocator | The VMM can handle page-sized allocations just fine, but that is not always useful. A heap allocator allows for allocations of any size, big or small. | 
 
 ## PMM - Physical Memory Manager

04_Memory_Management/05_Heap_Allocation.md

@@ -90,7 +90,8 @@ What we have so far is already an allocation algorithm, that's easy to implement
 Its implementation is very simple: 
 
 ```c 
-uint8_t *cur_heap_position = 0; //This is just pseudocode in real world this will be a memory location 
+uint8_t *cur_heap_position = 0; //Just an example, in the real world you would use
+                                //a virtual address allocated from the VMM.
 void *first_alloc(size_t size) {
   uint8_t *addr_to_return = cur_heap_position;
   cur_heap_position= cur_heap_position + size;
@@ -401,7 +402,7 @@ if (prev_node != NULL && prev_node->status == FREE) {
 ```
 What we're describing here is the left node being "swallowed" by the right one, and growing in size. The memory that the left node owns and is responsible for is now part of the right oneTo make it easier to understand, consider the portion of a hypothetical heap in the picture below: 
 
-![heap_example_start](/Images/heapexample.png)
+![Heap initial status](/Images/heapexample.png)
 
 
 Basically the heap starts from address 0, the first node is marked as free and the next two nodes are both used. Now imagine that `free()` is called on the second address (for this exammple we consider size of the heap node structure to be just of 2 bytes): 
@@ -413,7 +414,7 @@ free(0x27); //Remember the overhead
 
 This means that the allocator (before marking this location as free and returning) will check if it is possible to merge first to the left (YES) and then to the right (NO since the next node is still in use) and then will proceed with a merge only on the left side. The final result will be: 
 
-![heap_example_after_merge](/Images/heap_example_after_merge.png)
+![The heap status after the merge](/Images/heap_example_after_merge.png)
 
 The fields in bold are the fields that are changed. The exact implementation of this code is left to the reader.
 

05_Scheduling/03_Processes_And_Threads.md

@@ -65,7 +65,7 @@ Creating a process is pretty trivial. We need a place to store the new `process_
 size_t next_free_pid = 0;
 
 process_t* create_process(char* name, void(*function)(void*), void* arg) {
-    process_t* process = alloc(sizeof(process_t)); // We should have an allocation function available
+    process_t* process = alloc(sizeof(process_t)); 
 
     strncpy(process->name, name, NAME_MAX_LEN);
     process->pid = next_free_pid++;

06_Userspace/05_Example_ABI.md

@@ -41,8 +41,7 @@ We're going to implement a wrapper function for system calls in C, purely for co
 
 ```c
 __attribute__((naked))
-void do_syscall(uint64_t num, uint64_t a0, uint64_t a1, uint64_t a2, uint64_t a3)
-{
+void do_syscall(uint64_t num, uint64_t a0, uint64_t a1, uint64_t a2, uint64_t a3) {
     asm ("int $0x50" ::: "rdi", "rsi", "rdx", "rcx", "r8", "memory");
 }
 ```
@@ -54,8 +53,7 @@ This function also uses the `naked` attribute. If unfamiliar with attributes, th
 Now, let's combine our wrapper function with our example system call from above. We're going to write a `memcpy` function that could be called by another code, but uses the system call internally:
 
 ```c
-void memcpy(void* src, void* dest, size_t count)
-{
+void memcpy(void* src, void* dest, size_t count) {
     return do_syscall(3, (uint64_t)src, (uint64_t)dest, (uint64_t)count, 0, 0);
 }
 ```