report + documentation

Author: cs-t1

docs/report/report.md

@@ -6,6 +6,10 @@ toc: true
 numbersections: true
 ---
 
+# Preliminaries
+
+Any reader is strongly encouraged to have the code of the kernel available when reading this report. Rust also provides a **very** well-done documentation tool. The command `make doc` at the root of the repo should build the documentation and open it in the browser. We have put some effort into making a documentation clear and explicit!
+
 # Motivation
 
 ## Language
@@ -198,4 +202,8 @@ This mode, as well as the file type, is stored inside the header. A directory is
 
 # Reliability
 
-This is sort of the elephant in the room. From the very beginning, we built FerrOS to be a proof of concept of a feature-rich OS that, the code of which remains understandable. In any case we wanted it to be reliable in any way. This means that it should work fine as long as the user follows the guidelines but will panic (i.e. crash on purpose) on multiple occasions. The ustar driver is a great example of that : each step of the ustar pipeline has a lot of data checks that cause the OS to crahs if something invalid gets detected. A real OS would obviously catch this error and returns it to the userprogram, possibly killing it.
+This is sort of the elephant in the room. From the very beginning, we built FerrOS to be a proof of concept of a feature-rich OS that, the code of which remains understandable. The goal was not for it to be reliable in any way. This means that it should work fine as long as the user follows the guidelines but will panic (i.e. crash on purpose) on multiple occasions. The ustar driver is a great example of that : each step of the ustar pipeline has a lot of data checks that cause the OS to crahs if something invalid gets detected. A real OS would obviously catch this error and returns it to the userprogram, possibly killing it.
+
+# Conclusion
+
+This project has been a lot of fun and taught us a lot about operating systems, ranging from paging to userspace and standard libraries. Using Rust for this project has been, in our humble opinion, a success, as it enabled us to build some complex structures relatively easily (such as the VFS).

src/allocator/linked_list.rs

@@ -1,3 +1,5 @@
+//! Linked-list logic
+
 use super::{align_up, Locked};
 
 use crate::errorln;

src/allocator/mod.rs

@@ -1,3 +1,5 @@
+//! Heap allocator. This is a clone of the one inside the `librust`
+
 //use alloc::alloc::{GlobalAlloc, Layout};
 use linked_list::LinkedListAllocator;
 use x86_64::{
@@ -55,6 +57,7 @@ pub fn init(
     Ok(())
 }
 
+/// Contains locked data
 pub struct Locked<A> {
     inner: spin::Mutex<A>,
 }

src/data_storage/mod.rs

@@ -1,3 +1,5 @@
+//! Contains some custom general-purpose data-structures.
+
 pub mod path;
 pub mod queue;
 pub mod random;

src/data_storage/path.rs

@@ -1,3 +1,5 @@
+//! Kernelspace representation of paths.
+
 use alloc::string::String;
 use alloc::vec::Vec;
 

src/data_storage/queue.rs

@@ -1,5 +1,6 @@
 //! Here we define a basic bounded queue (fixed size) supporting creation, push and pop
 
+/// Maximam size of a queue
 const MAX_SIZE: usize = 32;
 
 /// Queue error.

src/data_storage/random.rs

@@ -1,3 +1,6 @@
+//! A very basic pseudo-RNG
+
+/// Initital seed
 static mut RAND_SEED: u8 = 42_u8;
 
 /// Returns a pseudo-random `u8`, using a simple and naive algorihm.

src/data_storage/registers.rs

@@ -1,3 +1,5 @@
+//! Data-structures holdign registers states
+
 /// Holds the value of a complete set of the `x86-64` GP registers.
 /// It is used to read from/write into a process' registers during a syscall.
 #[repr(C)]

src/data_storage/screen.rs

@@ -1,3 +1,5 @@
+//! Abstraction of screen coordinates
+
 /// Abstraction for coordinates on the screen. It is only partly useful.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct Coord {

src/filesystem/descriptor/mod.rs

@@ -1,3 +1,5 @@
+//! All the logic around file descriptors and `OpenFileTable`s
+
 use crate::data_storage::path::Path;
 
 use crate::scheduler::process;

src/filesystem/drivers/mod.rs

@@ -1,3 +1,5 @@
+//! Drivers that can be attached to the `VFS`
+
 pub mod clock_driver;
 pub mod disk_operations;
 pub mod hardware;

src/filesystem/fifo.rs

@@ -1,3 +1,5 @@
+//! FIFO used for inter-process communication
+
 use super::partition::Partition;
 
 use crate::data_storage::path::Path;

src/filesystem/fsflags.rs

@@ -1,3 +1,5 @@
+//! Flags
+
 #![allow(clippy::upper_case_acronyms)]
 
 use alloc::collections::BTreeSet;

src/filesystem/host_shell.rs

@@ -1,3 +1,5 @@
+//! host shell accessed by the serial interface
+
 use super::partition::Partition;
 
 use crate::{data_storage::path::Path, print};

src/filesystem/mod.rs

@@ -1,3 +1,5 @@
+//! All the logic of the filesystem, ranging from the drivers to the `VFS` pipeline
+
 #![allow(dead_code)]
 
 use crate::data_storage::path::Path;

src/filesystem/partition.rs

@@ -1,3 +1,5 @@
+//! Defines the `Partition` trait, implemented by all drivers and uniting them into a `VFS`!
+
 use crate::data_storage::path::Path;
 use alloc::vec::Vec;
 

src/filesystem/screen_partition.rs

@@ -1,3 +1,5 @@
+//! Give a process access to a screen.
+
 use super::partition::Partition;
 use crate::data_storage::screen::Coord;
 

src/filesystem/test.rs

@@ -1,3 +1,5 @@
+//! ATA test routines
+
 use crate::{print, println};
 use x86_64::instructions::interrupts::{disable, enable};
 use x86_64::instructions::port::Port;

src/filesystem/vfs.rs

@@ -1,3 +1,5 @@
+//! Heart of the kernel-user interraction. Defines the logic used by the `VFS`
+
 #![allow(clippy::upper_case_acronyms)]
 
 use alloc::boxed::Box;

src/hardware/mod.rs

@@ -1,3 +1,5 @@
+//! Some basic hardware drivers for use from within the kernel only.
+
 pub mod clock;
 pub mod mouse;
 pub mod power;

src/keyboard/mod.rs

@@ -1,3 +1,5 @@
+//! Kernel keyboard logic.
+
 use crate::println;
 use conquer_once::spin::OnceCell;
 use crossbeam_queue::{ArrayQueue, PopError, PushError};

src/programs/mod.rs

@@ -1,2 +1,4 @@
+//! Small kernel-space program examples.
+
 pub mod ascii_fluid;
 pub mod shell;

src/scheduler/mod.rs

@@ -1,3 +1,5 @@
+//! Contains all the logic used to create, manage, switch and kill processes.
+
 pub mod process;
 
 /// Maximum number of co-existing processes.

src/serial.rs

@@ -1,3 +1,5 @@
+//! Serial communication with the host shell. The way the kernel debugs informations.
+
 use lazy_static::lazy_static;
 use spin::Mutex;
 use uart_16550::SerialPort;

src/sound/mod.rs

@@ -1,3 +1,5 @@
+//! Sound driver and logic. Used by the VFS.
+
 use lazy_static::lazy_static;
 use spin::Mutex;