merge branch documentation

This commit is contained in:
Rémi Rativel 2023-05-25 14:16:59 +02:00
commit 638f96336b
17 changed files with 200 additions and 41 deletions

12
build.rs Normal file
View File

@ -0,0 +1,12 @@
//! Build script for BurritOS.
//!
//! Moves files from the assets folder to the target directory
//! and runs `make all`.
use std::process::Command;
fn main() {
let mut make_all = Command::new("make");
make_all.arg("all");
println!("{:?}", make_all.output().unwrap());
}

View File

@ -1,3 +1,8 @@
//! # Exceprions
//!
//! This module Enum the constant values of the exceptions.
//! They are used to stop the system to execute some opperation
use std::{cell::RefCell, rc::Rc};
use crate::{simulator::{machine::{ExceptionType, Machine}, error::{MachineOk, MachineError}}};
@ -292,6 +297,7 @@ fn sc_new_thread(machine: &mut Machine, system: &mut System) -> Result<MachineOk
} else {
return Err("Process owner of current thread is none")?;
}
}
fn sc_join(machine: &mut Machine, system: &mut System) -> Result<MachineOk, MachineError> {

View File

@ -1,3 +1,11 @@
//! # Error Code
//!
//! This module enumerate the possibles error code who could get in a function
//!
//! **Basic Usage:*
//!
//! Result<YourSuccessStruct, **ErrorCode**
#![allow(unused, clippy::missing_docs_in_private_items)]
/// Error enum, use it with Result<YourSucessStruct, **ErrorCode**>
pub enum ErrorCode {

View File

@ -1,3 +1,9 @@
//! # Kernel
//!
//! This module contains all the tool required for the kernel to work.
//!
//! Currently it contains the scheduling and synchroisation tools, but it will contains the tools
//! required Memory gestion, Files gestion and peripheral pilots.
pub mod process;
pub mod thread;
pub mod mgerror;

View File

@ -1,3 +1,11 @@
//! # Synchronisation
//!
//! This module contains some scheduling and synchronisation utilities:
//! - **Semaphore**
//! - **Lock**
//!
//! Conditions aren't implemented currently
use crate::utility::list::List;
use crate::kernel::thread::Thread;
use crate::simulator::interrupt::InterruptStatus::InterruptOff;
@ -6,20 +14,21 @@ use std::cell::RefCell;
use std::rc::Rc;
use super::thread_manager::ThreadManager;
/// Structure of a Semaphore used for synchronisation
/// Structure of a Semaphore used for synchronisation.
/// It use a counter to determine the number of thread that can be executed simultaneously.
#[derive(PartialEq)]
pub struct Semaphore {
/// Counter of simultanous Semaphore
/// Counter of simultaneous Semaphore
pub counter:i32,
/// QUeue of Semaphore waiting to be exucated
/// QUeue of Semaphore waiting to be executed
pub waiting_queue:List<Rc<RefCell<Thread>>>,
}
impl Semaphore {
/// Initializes a semaphore, so that it can be used for synchronization.
/// Initializes a semaphore, so that it can be used for synchronization.
///
/// ### Parameters
/// - *counter* initial value of counter
@ -49,7 +58,7 @@ pub struct Lock {
impl Lock {
/// Initialize a Lock, so that it can be used for synchronization.
/// The lock is initialy free
/// The lock is initially free
///
/// ### Parameters
/// - **thread_manager** Thread manager which managing threads
@ -72,7 +81,7 @@ impl Lock {
let old_status = machine.interrupt.set_status(InterruptOff);
if self.free {
self.free = false;
self.owner = Option::Some(match thread_manager.get_g_current_thread() {
self.owner = Some(match thread_manager.get_g_current_thread() {
Some(th) => {
Rc::clone(&th)
},
@ -128,8 +137,14 @@ impl Lock {
machine.interrupt.set_status(old_status);
}
/// True if the current thread holds this lock.
/// Say if the lock is held by the current thread
/// Useful for checking in Release, and in Condition operations below.
/// ### Parameters
/// - **self** The current lock
/// - **thread-manager** The thread manager present in the system
/// ### Return
/// True if the current thread holds this lock.
pub fn held_by_current_thread(&mut self, thread_manager: &mut ThreadManager) -> bool {
match &self.owner {
Some(x) =>

View File

@ -1,3 +1,6 @@
//! # Thread
//!
//!
use std::{rc::Rc, cell::RefCell};
use super::{process::Process, thread_manager::ThreadRef};

View File

@ -226,7 +226,7 @@ impl ThreadManager {
}
/// Relinquish the CPU if any other thread is runnable.
///
///
/// If so, put the current thread at the end of the ready list, so it'll be re-scheduled in the future.
///
/// **Returns** immediately if there's no other thread ready or return when the current thread has been switched.

View File

@ -1,4 +1,7 @@
#![doc(
html_logo_url = "https://gitlab.istic.univ-rennes1.fr/simpleos/burritos/-/raw/main/assets/logo/logo.svg",
html_favicon_url = "https://gitlab.istic.univ-rennes1.fr/simpleos/burritos/-/raw/main/assets/logo/logo.svg")
]
#![warn(missing_docs)]
#![warn(clippy::missing_docs_in_private_items)]
@ -7,10 +10,8 @@
//! Burritos is an educational operating system written in Rust
//! running on RISC-V emulator.
/// Contain hardware simulated part of the machine
mod simulator;
mod kernel;
/// module containing useful tools which can be use in most part of the OS to ease the development of the OS
pub mod utility;
use std::{rc::Rc, cell::RefCell};
@ -59,7 +60,6 @@ fn main() {
system.get_thread_manager().set_sp_max(sp_max);
system.get_thread_manager().start_thread(Rc::clone(&thread_exec), owner1, loader.elf_header.entrypoint, sp_max, -1);
let to_run = system.get_thread_manager().find_next_to_run().unwrap();
system.get_thread_manager().switch_to(&mut machine, Rc::clone(&to_run));

View File

@ -1,17 +1,38 @@
//! # Interrupt
//!
//! This module contains an interrupt Handler.
//! The methodes one_trick and idle aren't implemented for now
/// # Interrupt
///
/// Interrupt Handler
#[derive(PartialEq)]
pub struct Interrupt {
/// Current Status
level: InterruptStatus
}
impl Interrupt {
/// Interrupt constructor
///
/// ### Return
/// Interrupt with status Off
pub fn new() -> Self {
Self {
level: InterruptStatus::InterruptOff
}
}
/// Interrupt setter
/// Change the value of the Interrupt
///
/// ### Parameters
/// - **self** the interupt handler
/// - **new_status** the new status value
///
/// ### return
/// The previus status
pub fn set_status(&mut self, new_status: InterruptStatus) -> InterruptStatus {
let old = self.level;
self.level = new_status;
@ -25,6 +46,7 @@ impl Interrupt {
todo!();
}
/// Interupt getter
pub fn get_status(&self) -> InterruptStatus {
self.level
}

View File

@ -1,9 +1,25 @@
//! # Loader
//!
//! This module contains a loader for file section.
//! Following the common standard file format for executable files
//! [ELF (Executable and Linkable Format)](https://en.wikipedia.org/wiki/Executable_and_Linkable_Forma)
//!
//! It's used to charge a programme into the machine from a binary file (.guac files)
//!
//! Basic usage:
//!
//! ```
//! let args = Args::parse();
//! let mut machine = Machine::new(args.debug & 1 != 0, read_settings().unwrap());
//! let (loader, ptr) = loader::Loader::new(args.executable.as_str(), &mut machine, 0).expect("An error occured while parsing the program");
//! ```
use crate::Machine;
use std::fs;
use std::io::Read;
/// The elf header defines principes aspects of the binary files, it's place at the start of the file
/// see <https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header> for more informations
/// see [ELF file Header](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header) for more informations
pub struct ElfHeader {
/// Defines whether the file is big or little endian
/// true correspond to big endian, false otherwise

View File

@ -1,14 +1,31 @@
///! FILE.TXT FORMAT Representing machine memory memory
/// - PC
/// - SP
/// - Section_1
/// - Section_2
/// - ...
/// - Section_n
///
/// Each section is divided in 3 parts, on two lines of text
/// addr SPACE len
/// content
//! # Memory Comparator
//!
//! This module contains a MemChecker.
//!
//! It's used to compare state memory obtained after a dump memory from NachOS and BurritOS.
//!
//! This module is used exclusively for testing the instruction simulator.
//!
//! Basic usage:
//!
//! ```
//! let mut m = Machine::new(true, get_debug_configuration());
//! let mut MemChecker = mem_cmp::MemChecker::from(get_full_path!("memory", expr));
//! mem_cmp::MemChecker::fill_memory_from_mem_checker(&MemChecker, &mut m);
//! ```
//!
//!
//! ! FILE.TXT FORMAT Representing machine memory memory
//! - PC
//! - SP
//! - Section_1
//! - Section_2
//! - ...
//! - Section_n
//!
//! Each section is divided in 3 parts, on two lines of text
//! addr SPACE len
//! content
use std::{fs, io::{BufRead, BufReader, Lines, Error}};
use crate::Machine;
@ -102,7 +119,7 @@ impl MemChecker {
/// Extract the values of pc, sp and sections
///
/// ### Parameter
/// -**path** addr to the file
/// - **path** addr to the file
///
/// ### Return
/// Mem-checker filled

View File

@ -1,18 +1,38 @@
//! # MMU
//!
//! This module contains a MMU implementation
//!
//! This part isn't tested nor integrated to BurritOS because of the lack of pagination implementation
//!
//!
use crate::simulator::translationtable::*;
use crate::simulator::machine::*;
/// # Memory Management Unit
/// An MMU possesses a single reference to a translation table
/// This table is associated to the current process
pub struct MMU <'a>{
/* Un MMU possède une seule référence vers une table des pages à un instant donné
* Cette table est associée au processus courant
* Cette référence peut etre mise a jour par exemple lors d'un switchTo
*/
/// Reference to a page table
translationTable : Option<&'a mut TranslationTable>,
/// The number of physique pages
numPhyPages : u64,
/// Size of each page
pageSize : u64
}
impl <'a>MMU <'_>{
/// Create a MMU with a None reference for the translation table
///
/// ### Parameters
///
/// - **numPhyPages** the number of physique pages
/// - **pageSize** the size of a page
///
/// ### Return
///
/// MMU with None reference and the value for the number of physical pages and pae size associated
fn create(numPhyPages: u64, pageSize: u64) -> MMU <'a>{
MMU {
translationTable : None,

View File

@ -1,3 +1,12 @@
//! This module implement an Instruction simulator
//! with all the simulated hardware requested to run the Machine :
//! - **MMU**
//! - **Processor**
//! - **RAM**
//! - **Interruption Controler**
//!
//! The disk, the console and the serial coupler aren't implmented for now
//!
pub mod machine;
pub mod error;
pub mod instruction;

View File

@ -1,23 +1,35 @@
//Nombre maximum de correspondances dans une table des pages
//Cette donnée devra a terme etre recupérée depuis un fichier de configuration
//! # Translation Table
//!
//! This module implement a trnslation table used for fot the MMU Emulator
//!
//! This part isn't tested nor integrated to BurritOS,
//! but will be useful in the futur when the pagination will be implemented.
//!
//! It contains:
//! - all the setters and getters for translation table
//! - modificaters of table values
/// Maximum number in a Page Table
/// For a futur evolution of program, this value should be load from a configuration file
const MaxVirtPages : u64 = 200000;
/* Une table de correspondance propre à un processus
* Une variable de type TranslationTable devra etre possédée par un objet de type Process
*/
/// Translation Table corresponding to a process
/// An iteration of type TranslationTable should be possesses by an oject of type Process
pub struct TranslationTable{
//capacité de cette table <=> nombre de correspondances possibles
//A voir si cette donnée doit etre immuable
/// Table size <=> nb of possible translation
pub maxNumPages : u64,
//la table en question
//Vec implemente le trait Index, donc un bon choix
///The table *Vec impemente Index Trait*
pub pageTable : Vec<PageTableEntry>
}
impl TranslationTable {
/// TranslationTable constructor
///
/// ### Return
/// TranslationTable with an empty Vector
pub fn create() -> TranslationTable {
let mut tmp_vec : Vec<PageTableEntry> = Vec::new();

View File

@ -104,6 +104,10 @@ pub fn get_debug_configuration() -> Settings {
}
/// Removes comments and empty lines
/// Filters out empty lines and comments from the reader `BufReader`.
///
/// Returns a [`Vec<String>`], each entry containing a valid
/// line from the input file.
fn filter_garbage<R: std::io::Read>(reader: BufReader<R>) -> Vec<String> {
reader.lines()
.map(|l| l.unwrap())
@ -111,11 +115,13 @@ fn filter_garbage<R: std::io::Read>(reader: BufReader<R>) -> Vec<String> {
.collect()
}
/// Inserts user settings into setting map
/// Adds a <K, V> pair to a [`Settings`] map.
///
/// Returns the updated [`Settings`].
fn update_settings_map(mut settings_map: Settings, key: &str, setting: &str) -> Settings {
let key = MachineSettingKey::from(key);
let setting = setting.parse::<u64>().unwrap_or(0);
let setting = str::parse::<u64>(setting).unwrap_or(0);
settings_map.insert(key, setting);
settings_map
}

View File

@ -1,3 +1,6 @@
//! This module contains data type definitions used in other parts the BurritOS
//! They are separated from the rest of the operating system so as to promote
//! reusability and to separate data constructs proper from state and actions.
pub mod list;
pub mod objaddr;
pub mod cfg;

View File

@ -17,9 +17,13 @@ use crate::kernel::{synch::{ Semaphore, Lock }, thread::Thread};
/// calls.
#[derive(PartialEq)]
pub struct ObjAddr {
/// Id of the last added object
last_id: i32,
/// List of [Semaphore] added in this struct. Each is keyed with a unique i32 id.
semaphores: HashMap<i32, Semaphore>,
/// List of [Lock] added in this struct. Each is keyed with a unique i32 id.
locks: HashMap<i32, Lock>,
/// List of threads known by this instance of ObjAddr (useful for managing lock ownership)
threads: HashMap<i32, Rc<RefCell<Thread>>>,
}