Move footnotes to the bottom

phil-opp · phil-opp · commit 7744a08212ad · 2017-06-09T14:51:36.000+02:00
diff --git a/blog/content/posts/01-multiboot-kernel/index.md b/blog/content/posts/01-multiboot-kernel/index.md
@@ -81,8 +81,6 @@ If you don't know x86 assembly, here is some quick guide:
 - `dd` stands for `define double` (32bit) and `dw` stands for `define word` (16bit). They just output the specified 32bit/16bit constant.
 - the additional `0x100000000` in the checksum calculation is a small hack[^fn-checksum_hack] to avoid a compiler warning
 
-[^fn-checksum_hack]: The formula from the table, `-(magic + architecture + header_length)`, creates a negative value that doesn't fit into 32bit. By subtracting from `0x100000000` (= 2^(32)) instead, we keep the value positive without changing its truncated value. Without the additional sign bit(s) the result fits into 32bit and the compiler is happy :).
-
 We can already _assemble_ this file (which I called `multiboot_header.asm`) using `nasm`. It produces a flat binary by default, so the resulting file just contains our 24 bytes (in little endian if you work on a x86 machine):
 
 ```
@@ -167,8 +165,6 @@ Let's translate it:
 - the `.text` output section contains all input sections named `.text`
 - Sections named `.multiboot_header` are added to the first output section (`.boot`) to ensure they are at the beginning of the executable. This is necessary because GRUB expects to find the Multiboot header very early in the file.
 
-[^Linker 1M]: We don't want to load the kernel to e.g. `0x0` because there are many special memory areas below the 1MB mark (for example the so-called VGA buffer at `0xb8000`, that we use to print `OK` to the screen).
-
 So let's create the ELF object files and link them using our new linker script:
 
 ```
@@ -324,3 +320,8 @@ In the [next post] we will create a page table and do some CPU configuration to
 
 [next post]: {{% relref "02-entering-longmode.md" %}}
 [long mode]: https://en.wikipedia.org/wiki/Long_mode
+
+## Footnotes
+[^fn-checksum_hack]: The formula from the table, `-(magic + architecture + header_length)`, creates a negative value that doesn't fit into 32bit. By subtracting from `0x100000000` (= 2^(32)) instead, we keep the value positive without changing its truncated value. Without the additional sign bit(s) the result fits into 32bit and the compiler is happy :).
+
+[^Linker 1M]: We don't want to load the kernel to e.g. `0x0` because there are many special memory areas below the 1MB mark (for example the so-called VGA buffer at `0xb8000`, that we use to print `OK` to the screen).
diff --git a/blog/content/posts/02-entering-longmode/index.md b/blog/content/posts/02-entering-longmode/index.md
@@ -215,10 +215,6 @@ As I don't like these names, I will call them P4, P3, P2, and P1 from now on.
 
 Each page table contains 512 entries and one entry is 8 bytes, so they fit exactly in one page (`512*8 = 4096`). To translate a virtual address to a physical address the CPU[^hardware_lookup] will do the following[^virtual_physical_translation_source]:
 
-[^hardware_lookup]: In the x86 architecture, the page tables are _hardware walked_, so the CPU will look at the table on its own when it needs a translation. Other architectures, for example MIPS, just throw an exception and let the OS translate the virtual address.
-
-[^virtual_physical_translation_source]: Image source: [Wikipedia](https://commons.wikimedia.org/wiki/File:X86_Paging_64bit.svg), with modified font size, page table naming, and removed sign extended bits. The modified file is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported license.
-
 ![translation of virtual to physical addresses in 64 bit mode](/images/X86_Paging_64bit.svg)
 
 1. Get the address of the P4 table from the CR3 register
@@ -259,8 +255,6 @@ To identity map the first gigabyte of our kernel with 512 2MiB pages, we need on
 
 We can add these two tables at the beginning[^page_table_alignment] of the `.bss` section:
 
-[^page_table_alignment]: Page tables need to be page-aligned as the bits 0-11 are used for flags. By putting these tables at the beginning of `.bss`, the linker can just page align the whole section and we don't have unused padding bytes in between.
-
 ```nasm
 ...
 
@@ -524,3 +518,10 @@ It's time to finally leave assembly behind and switch to [Rust]. Rust is a syste
 
 [Rust]: https://www.rust-lang.org/
 [next post]: {{% relref "03-set-up-rust.md" %}}
+
+## Footnotes
+[^hardware_lookup]: In the x86 architecture, the page tables are _hardware walked_, so the CPU will look at the table on its own when it needs a translation. Other architectures, for example MIPS, just throw an exception and let the OS translate the virtual address.
+
+[^virtual_physical_translation_source]: Image source: [Wikipedia](https://commons.wikimedia.org/wiki/File:X86_Paging_64bit.svg), with modified font size, page table naming, and removed sign extended bits. The modified file is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported license.
+
+[^page_table_alignment]: Page tables need to be page-aligned as the bits 0-11 are used for flags. By putting these tables at the beginning of `.bss`, the linker can just page align the whole section and we don't have unused padding bytes in between.
diff --git a/blog/content/posts/04-printing-to-screen/index.md b/blog/content/posts/04-printing-to-screen/index.md
@@ -652,7 +652,6 @@ _Note_: You need to [cross compile binutils] to build it (or you create some sym
 [Rust Bare-Bones Kernel]: https://github.com/thepowersgang/rust-barebones-kernel
 [higher half]: http://wiki.osdev.org/Higher_Half_Kernel
 [cross compile binutils]: {{% relref "cross-compile-binutils.md" %}}
-[^fn-symlink]: You will need to symlink `x86_64-none_elf-XXX` to `/usr/bin/XXX` where `XXX` is in {`as`, `ld`, `objcopy`, `objdump`, `strip`}. The `x86_64-none_elf-XXX` files must be in some folder that is in your `$PATH`. But then you can only build for your x86_64 host architecture, so use this hack only for testing.
 
 - [RustOS]: More advanced kernel that supports allocation, keyboard inputs, and threads. It also has a scheduler and a basic network driver.
 [RustOS]: https://github.com/RustOS-Fork-Holding-Ground/RustOS
@@ -663,3 +662,6 @@ _Note_: You need to [cross compile binutils] to build it (or you create some sym
 - [Redox]: Probably the most complete Rust OS today. It has an active community and over 1000 Github stars. File systems, network, an audio player, a picture viewer, and much more. Just take a look at the [screenshots][redox screenshots].
 [Redox]: https://github.com/redox-os/redox
 [redox screenshots]: https://github.com/redox-os/redox#what-it-looks-like
+
+## Footnotes
+[^fn-symlink]: You will need to symlink `x86_64-none_elf-XXX` to `/usr/bin/XXX` where `XXX` is in {`as`, `ld`, `objcopy`, `objdump`, `strip`}. The `x86_64-none_elf-XXX` files must be in some folder that is in your `$PATH`. But then you can only build for your x86_64 host architecture, so use this hack only for testing.
diff --git a/blog/content/posts/06-page-tables/index.md b/blog/content/posts/06-page-tables/index.md
@@ -346,8 +346,6 @@ _What happens if we call them on a P1 table?_
 
 Well, they would calculate the address of the next table (which does not exist) and treat it as a page table. Either they construct an invalid address (if `XXX < 400`)[^fn-invalid-address] or access the mapped page itself. That way, we could easily corrupt memory or cause CPU exceptions by accident. So these two functions are not _safe_ in Rust terms. Thus we need to make them `unsafe` functions unless we find some clever solution.
 
-[^fn-invalid-address]: If the `XXX` part of the address is smaller than `0o400`, it's binary representation doesn't start with `1`. But the sign extension bits, which should be a copy of that bit, are `1` instead of `0`. Thus the address is not valid.
-
 ## Some Clever Solution
 We can use Rust's type system to statically guarantee that the `next_table` methods can only be called on P4, P3, and P2 tables, but not on a P1 table. The idea is to add a `Level` parameter to the `Table` type and implement the `next_table` methods only for level 4, 3, and 2.
 
@@ -887,4 +885,7 @@ Afterwards, we will use this paging module to build a heap allocator. This will
 
 <small>Image sources: [^virtual_physical_translation_source]</small>
 
+## Footnotes
+[^fn-invalid-address]: If the `XXX` part of the address is smaller than `0o400`, it's binary representation doesn't start with `1`. But the sign extension bits, which should be a copy of that bit, are `1` instead of `0`. Thus the address is not valid.
+
 [^virtual_physical_translation_source]: Image sources: Modified versions of an image from  [Wikipedia](https://commons.wikimedia.org/wiki/File:X86_Paging_64bit.svg). The modified files are licensed under the Creative Commons Attribution-Share Alike 3.0 Unported license.
diff --git a/blog/content/posts/07-remap-the-kernel/index.md b/blog/content/posts/07-remap-the-kernel/index.md
@@ -27,7 +27,6 @@ Also, we will use the [information about kernel sections] to map the various sec
 ## Preparation
 There are many things that can go wrong when we switch to a new table. Therefore it's a good idea to [set up a debugger][set up gdb]. You should not need it when you follow this post, but it's good to know how to debug a problem when it occurs[^fn-debug-notes].
 [set up gdb]: {{% relref "set-up-gdb.md" %}}
-[^fn-debug-notes]: For this post the most useful GDB command is probably `p/x *((long int*)0xfffffffffffff000)@512`. It prints all entries of the recursively mapped P4 table by interpreting it as an array of 512 long ints (the `@512` is GDB's array syntax). Of course you can also print other tables by adjusting the address.
 
 We also update the `Page` and `Frame` types to make our lives easier. The `Page` struct gets some derived traits:
 
@@ -64,9 +63,7 @@ We can't do that for a `Frame`. If we wanted to be sure that a given frame is un
 ## Recap: The Paging Module
 This post builds upon the post about [page tables][previous post], so let's start by quickly recapitulating what we've done there.
 
-We created a `memory::paging` module, which reads and modifies the hierarchical page table through recursive mapping. The owner of the active P4 table and thus all subtables is an `ActivePageTable`[^fn-apt-renamed] struct, which must be instantiated only once.
-
-[^fn-apt-renamed]: It was renamed in [#88](https://github.com/phil-opp/blog_os/pull/88). The previous name was `RecursivePageTable`.
+We created a `memory::paging` module, which reads and modifies the hierarchical page table through recursive mapping. The owner of the active P4 table and thus all subtables is an `ActivePageTable` struct, which must be instantiated only once.
 
 The `ActivePageTable` struct provides the following interface:
 
@@ -1077,3 +1074,6 @@ Now that we have a (mostly) safe kernel stack and a working page table module, w
 [Box]: https://doc.rust-lang.org/nightly/alloc/boxed/struct.Box.html
 [Vec]: https://doc.rust-lang.org/nightly/collections/vec/struct.Vec.html
 [BTreeMap]: https://doc.rust-lang.org/nightly/collections/btree_map/struct.BTreeMap.html
+
+## Footnotes
+[^fn-debug-notes]: For this post the most useful GDB command is probably `p/x *((long int*)0xfffffffffffff000)@512`. It prints all entries of the recursively mapped P4 table by interpreting it as an array of 512 long ints (the `@512` is GDB's array syntax). Of course you can also print other tables by adjusting the address.
diff --git a/blog/content/posts/08-kernel-heap/index.md b/blog/content/posts/08-kernel-heap/index.md
@@ -680,9 +680,7 @@ I created the [linked_list_allocator] crate to handle all of these cases. It con
 [Heap struct]: http://phil-opp.github.io/linked-list-allocator/linked_list_allocator/struct.Heap.html
 [linked_list_allocator source]: https://github.com/phil-opp/linked-list-allocator
 
-So we just need to implement Rust's allocation modules and integrate it into our kernel. We start by creating a new `hole_list_allocator`[^1] crate inside the `libs` directory:
-
-[^1]: The name `linked_list_allocator` is already taken, sorry :P.
+So we just need to implement Rust's allocation modules and integrate it into our kernel. We start by creating a new `hole_list_allocator` crate inside the `libs` directory:
 
 ```shell
 > cd libs
diff --git a/blog/content/posts/09-handling-exceptions/index.md b/blog/content/posts/09-handling-exceptions/index.md
@@ -444,8 +444,6 @@ The answer is that the stored instruction pointer only points to the causing ins
 
 The reason for the diffent instruction pointer values is that the stored value is also the return address. So for faults, the instruction that caused the exception is restarted and might cause the same exception again if it's not resolved. This would not make much sense for traps, since invoking the breakpoint exception again would just cause another breakpoint exception[^fn-breakpoint-restart-use-cases]. Thus the instruction pointer points to the _next_ instruction for these exceptions.
 
-[^fn-breakpoint-restart-use-cases]: There are valid use cases for restarting an instruction that caused a breakpoint. The most common use case is a debugger: When setting a breakpoint on some code line, the debugger overwrites the corresponding instruction with an `int3` instruction, so that the CPU traps when that line is executed. When the user continues execution, the debugger swaps in the original instruction and continues the program from the replaced instruction.
-
 In some cases, the distinction between faults and traps is vague. For example, the [debug exception] behaves like a fault in some cases, but like a trap in others. So to find out the meaning of the saved instruction pointer, it is a good idea to read the official documentation for the exception, which can be found in the [AMD64 manual] in Section 8.2. For example, for the breakpoint exception it says:
 
 [debug exception]: http://wiki.osdev.org/Exceptions#Debug
@@ -468,3 +466,6 @@ We've successfully caught our first exception and returned from it! The next ste
 
 [triple fault]: http://wiki.osdev.org/Triple_Fault
 [double faults]: http://wiki.osdev.org/Double_Fault#Double_Fault
+
+## Footnotes
+[^fn-breakpoint-restart-use-cases]: There are valid use cases for restarting an instruction that caused a breakpoint. The most common use case is a debugger: When setting a breakpoint on some code line, the debugger overwrites the corresponding instruction with an `int3` instruction, so that the CPU traps when that line is executed. When the user continues execution, the debugger swaps in the original instruction and continues the program from the replaced instruction.
