finish rust-os chapter 2

Signed-off-by: Henry Gressmann <[email protected]>

Author: explodingcamera

content/rust-os/1-hello-riscv/index.md

@@ -13,7 +13,7 @@ series = ["rust-os"]
 
 {% quote (class="info")%}
 
-This is a series of posts about my journey creating a kernel in rust. You can find the code for this project [here](https://github.com/explodingcamera/pogos/tree/part-1) and all of the posts in this series [here](/series/os-dev/).
+This is a series of posts about my journey creating a kernel in rust. You can find the code for this project [here](https://github.com/explodingcamera/pogos/tree/part-1) and all of the posts in this series [here](/series/rust-os/).
 
 {% end %}
 

content/rust-os/2-shell/index.md

@@ -1,8 +1,8 @@
 +++
 transparent = true
-title = "Creating a Kernel in Rust #2: Shell [Work in Progress]"
+title = "Creating a Kernel in Rust #2: Shell"
 description = "Creating a simple shell for our kernel to run commands and help us debug"
-date = 2023-05-14
+date = 2023-07-08
 
 [taxonomies]
 tags = ["rust", "riscv", "kernel"]
@@ -11,9 +11,7 @@ series = ["rust-os"]
 
 {% quote (class="info")%}
 
-This is a series of posts about my journey creating a kernel in rust. You can find the code for this project [here](https://github.com/explodingcamera/pogos/tree/part-1) and all of the posts in this series [here](/series/os-dev/).
-
-This post isn't finished yet, but I wanted to get it out so I stop procrastinating on it. More content will follow next week.
+This is a series of posts about my journey creating a kernel in rust. You can find the code for this project [here](https://github.com/explodingcamera/pogos/tree/part-2) and all of the posts in this series [here](/series/rust-os/).
 
 {% end %}
 
@@ -24,7 +22,7 @@ Like I mentioned in the previous post, we can't yet use heap allocated data stru
 
 {{toc}}
 
-# Global Allocator
+# Memory Allocators
 
 To better understand what a global allocator is, we'll create a simple linear allocator that will allocate memory from a fixed size buffer. This allocator will only be able to allocate memory, not free it, but it will be enough to get us started.
 
@@ -67,7 +65,9 @@ impl LinearAllocator {
 }
 ```
 
-We'll also need to implement the `GlobalAlloc` trait, so Rust's `#[global_allocator]` compile built-in knows how to use our allocator. This trait has two methods: `alloc` and `dealloc`. We'll only implement `alloc` for now, since we won't be able to free memory until we implement a more complex allocator.
+## Global Allocator
+
+We'll also need to implement the `GlobalAlloc` trait, so Rust's `#[global_allocator]` compile time built-in knows how to use our allocator. This trait has two methods: `alloc` and `dealloc`. We'll only implement `alloc` for now, since we won't be able to free memory with our implementation.
 
 The trait also requires that we mark our implementation as `unsafe` since we are dealing with raw pointers and memory addresses.
 
@@ -114,7 +114,7 @@ unsafe impl GlobalAlloc for LinearAllocator {
 }
 ```
 
-Now that we have our allocator, we can use it to allocate memory in our kernel. We'll start by allocating a buffer for it to use:
+Before we can start using our allocator, we need to initialize it and allocate some memory for it to use. We'll do this in our `src/heap.rs` file:
 
 {{ file(name = "src/heap.rs") }}
 
@@ -166,3 +166,123 @@ fn main(a0: usize) -> ! {
     utils::shutdown();
 }
 ```
+
+Now, we can use our allocator to allocate some memory! Let's create a `Vec` and push some values to it to make sure everything works as expected:
+
+{{ file(name = "src/main.rs") }}
+
+```rust
+
+let mut v = Vec::new();
+
+v.push(1);
+v.push(2);
+v.push(3);
+
+println!("{:?}", v);
+
+// [1, 2, 3]
+```
+
+This is great, but we can't really do much with this allocator since we can't free memory. Alternative allocators are, for example, [linked list allocators](https://os.phil-opp.com/allocator-designs/#linked-list-allocator), [binary buddy allocators](https://www.kernel.org/doc/gorman/html/understand/understand009.html), and [slab allocators](https://www.kernel.org/doc/gorman/html/understand/understand011.html). We won't be implementing any of these in here, but I encourage you to read about them and try to implement them yourself! Some of these are also available as crates on crates.io to use them as drop-in replacements for our naive implementation here ([linked_list_allocator](https://crates.io/crates/linked-list-allocator), [buddy_system_allocator](https://crates.io/crates/buddy_system_allocator) and [slabmalloc](https://crates.io/crates/slabmalloc)).
+
+# Shell
+
+With most essential rust features available, we can now start working on our shell. This shell will allow us to interact with our kernel and inspect its state.
+
+The shell will be a simple loop for now, that reads characters from SBIs `console_getchar` function, and executes some basic commands.
+
+{{ file(name = "src/main.rs") }}
+
+```rust
+
+pub const ENTER: u8 = 13;
+pub const BACKSPACE: u8 = 127;
+
+pub fn shell() {
+    print!("> ");
+
+    let mut command = String::new(); // finnaly, we can use heap allocated strings!
+
+    loop {
+        match sbi::legacy::console_getchar() {
+            Some(ENTER) => {
+                println!();
+                process_command(&command);
+                command.clear();
+                print!("> ");
+            }
+            Some(BACKSPACE) => {
+                if command.len() > 0 {
+                    command.pop();
+                    print!("{}", BACKSPACE as char)
+                }
+            }
+        }
+    }
+}
+
+
+fn process_command(command: &str) {
+    match command {
+        "help" | "?" | "h" => {
+            println!("available commands:");
+            println!("  help      print this help message  (alias: h, ?)");
+            println!("  shutdown  shutdown the machine     (alias: sd, exit)");
+        }
+        "shutdown" | "sd" | "exit" => util::shutdown(),
+        "" => {}
+        _ => {
+            println!("unknown command: {command}");
+        }
+    };
+}
+
+```
+
+```
+> help
+available commands:
+  help      print this help message  (alias: h, ?)
+  shutdown  shutdown the machine     (alias: sd, exit)
+> exit
+```
+
+## Debugging
+
+Being able to shutdown the machine is great and all, but let's add some more functionality. We'll start by adding some commands to trigger different exceptions, so we can test our exception handler from the previous chapter.
+
+{{ file(name = "src/main.rs") }}
+
+```rust
+
+    match command {
+        // ...
+        "pagefault" => {
+            // read from an invalid address to trigger a page fault
+            unsafe { core::ptr::read_volatile(0xdeadbeef as *mut u64); }
+        }
+        "breakpoint" => {
+            // ebreak triggers a breakpoint exception, a trap that can be used for debugging with gdb or similar tools
+            unsafe { asm!("ebreak") };
+        }
+        // ...
+    }
+```
+
+When we now run the `pagefault` command, we'll see that - well - nothing happens. This is because we haven't set up a page table yet, and the kernel is still running in physical memory, something we want to change in the next chapter.
+
+Our breakpoint command, however, will trigger a breakpoint exception, and we'll see the following output:
+
+```
+Exception handler called
+Trap frame: TrapFrame { ra: 2149605116, t0: 9, t1: 2149632682, t2: 22, t3: 5760, t4: 48, t5: 12288, t6: 1, a0: 8, a1: 0, a2: 2149663232, a3: 2149593222, a4: 110, a5: 2149663744, a6: 4, a7: 1 }
+panicked at 'Exception cause: Exception(Breakpoint)', kernel/src/trap.rs:33:5
+```
+
+This is great, we can now see the trap frame and the exception cause, so we can start debugging our kernel! To make use of this, you can also use an external debugger like [gdb](https://www.gnu.org/software/gdb/), which allows you to set breakpoints, inspect memory, step through code, and much more.
+Setting up gdb is a bit more involved, so if you run into issues check out this [guide](https://os.phil-opp.com/set-up-gdb/). I'm more of a print-debugging and hit my head against the wall until it works kind of guy, so I won't be covering this in detail here.
+
+There's a lot of improvements we can make to this shell, for some ideas, check out my `simple_shell` crate on [crates.io](https://crates.io/crates/simple_shell). I recommend you try to implement some of these yourself, as it's a fun exercise. Something that might be helpful is this ANSI escape code [cheat sheet](https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797) for processing user input like arrow keys, backspace, etc.
+
+After this fairly short chapter, we'll add multi-tasking to our kernel using async rust, so we can run multiple programs at the same time and explore paging and virtual memory.