add os[1-8]-ref for os refereces, add guide, add README

os7-ref/src/fs/inode.rs

@@ -0,0 +1,169 @@
+use easy_fs::{
+    EasyFileSystem,
+    Inode,
+};
+use crate::drivers::BLOCK_DEVICE;
+use crate::sync::UPSafeCell;
+use alloc::sync::Arc;
+use lazy_static::*;
+use bitflags::*;
+use alloc::vec::Vec;
+use super::File;
+use crate::mm::UserBuffer;
+
+/// A wrapper around a filesystem inode
+/// to implement File trait atop
+pub struct OSInode {
+    readable: bool,
+    writable: bool,
+    inner: UPSafeCell<OSInodeInner>,
+}
+
+/// The OS inode inner in 'UPSafeCell'
+pub struct OSInodeInner {
+    offset: usize,
+    inode: Arc<Inode>,
+}
+
+impl OSInode {
+    /// Construct an OS inode from a inode
+    pub fn new(
+        readable: bool,
+        writable: bool,
+        inode: Arc<Inode>,
+    ) -> Self {
+        Self {
+            readable,
+            writable,
+            inner: unsafe { UPSafeCell::new(OSInodeInner {
+                offset: 0,
+                inode,
+            })},
+        }
+    }
+    /// Read all data inside a inode into vector
+    pub fn read_all(&self) -> Vec<u8> {
+        let mut inner = self.inner.exclusive_access();
+        let mut buffer = [0u8; 512];
+        let mut v: Vec<u8> = Vec::new();
+        loop {
+            let len = inner.inode.read_at(inner.offset, &mut buffer);
+            if len == 0 {
+                break;
+            }
+            inner.offset += len;
+            v.extend_from_slice(&buffer[..len]);
+        }
+        v
+    }
+}
+
+lazy_static! {
+    /// The root of all inodes, or '/' in short
+    pub static ref ROOT_INODE: Arc<Inode> = {
+        let efs = EasyFileSystem::open(BLOCK_DEVICE.clone());
+        Arc::new(EasyFileSystem::root_inode(&efs))
+    };
+}
+
+/// List all files in the filesystems
+pub fn list_apps() {
+    println!("/**** APPS ****");
+    for app in ROOT_INODE.ls() {
+        println!("{}", app);
+    }
+    println!("**************/");
+}
+
+bitflags! {
+    /// Flags for opening files
+    pub struct OpenFlags: u32 {
+        const RDONLY = 0;
+        const WRONLY = 1 << 0;
+        const RDWR = 1 << 1;
+        const CREATE = 1 << 9;
+        const TRUNC = 1 << 10;
+    }
+}
+
+impl OpenFlags {
+    /// Get the current read write permission on an inode
+    /// does not check validity for simplicity
+    /// returns (readable, writable)
+    pub fn read_write(&self) -> (bool, bool) {
+        if self.is_empty() {
+            (true, false)
+        } else if self.contains(Self::WRONLY) {
+            (false, true)
+        } else {
+            (true, true)
+        }
+    }
+}
+
+/// Open a file by path
+pub fn open_file(name: &str, flags: OpenFlags) -> Option<Arc<OSInode>> {
+    let (readable, writable) = flags.read_write();
+    if flags.contains(OpenFlags::CREATE) {
+        if let Some(inode) = ROOT_INODE.find(name) {
+            // clear size
+            inode.clear();
+            Some(Arc::new(OSInode::new(
+                readable,
+                writable,
+                inode,
+            )))
+        } else {
+            // create file
+            ROOT_INODE.create(name)
+                .map(|inode| {
+                    Arc::new(OSInode::new(
+                        readable,
+                        writable,
+                        inode,
+                    ))
+                })
+        }
+    } else {
+        ROOT_INODE.find(name)
+            .map(|inode| {
+                if flags.contains(OpenFlags::TRUNC) {
+                    inode.clear();
+                }
+                Arc::new(OSInode::new(
+                    readable,
+                    writable,
+                    inode
+                ))
+            })
+    }
+}
+
+impl File for OSInode {
+    fn readable(&self) -> bool { self.readable }
+    fn writable(&self) -> bool { self.writable }
+    fn read(&self, mut buf: UserBuffer) -> usize {
+        let mut inner = self.inner.exclusive_access();
+        let mut total_read_size = 0usize;
+        for slice in buf.buffers.iter_mut() {
+            let read_size = inner.inode.read_at(inner.offset, *slice);
+            if read_size == 0 {
+                break;
+            }
+            inner.offset += read_size;
+            total_read_size += read_size;
+        }
+        total_read_size
+    }
+    fn write(&self, buf: UserBuffer) -> usize {
+        let mut inner = self.inner.exclusive_access();
+        let mut total_write_size = 0usize;
+        for slice in buf.buffers.iter() {
+            let write_size = inner.inode.write_at(inner.offset, *slice);
+            assert_eq!(write_size, slice.len());
+            inner.offset += write_size;
+            total_write_size += write_size;
+        }
+        total_write_size
+    }
+}

os7-ref/src/fs/mod.rs

@@ -0,0 +1,45 @@
+mod stdio;
+mod inode;
+mod pipe;
+
+use crate::mm::UserBuffer;
+
+/// The common abstraction of all IO resources
+pub trait File : Send + Sync {
+    fn readable(&self) -> bool;
+    fn writable(&self) -> bool;
+    fn read(&self, buf: UserBuffer) -> usize;
+    fn write(&self, buf: UserBuffer) -> usize;
+}
+
+/// The stat of a inode
+#[repr(C)]
+#[derive(Debug)]
+pub struct Stat {
+    /// ID of device containing file
+    pub dev: u64,
+    /// inode number
+    pub ino: u64,
+    /// file type and mode
+    pub mode: StatMode,
+    /// number of hard links
+    pub nlink: u32,
+    /// unused pad
+    pad: [u64; 7],
+}
+
+bitflags! {
+    /// The mode of a inode
+    /// whether a directory or a file
+    pub struct StatMode: u32 {
+        const NULL  = 0;
+        /// directory
+        const DIR   = 0o040000;
+        /// ordinary regular file
+        const FILE  = 0o100000;
+    }
+}    
+
+pub use stdio::{Stdin, Stdout};
+pub use inode::{OSInode, open_file, OpenFlags, list_apps};
+pub use pipe::{Pipe, make_pipe};

os7-ref/src/fs/pipe.rs

@@ -0,0 +1,179 @@
+use super::File;
+use alloc::sync::{Arc, Weak};
+use crate::sync::UPSafeCell;
+use crate::mm::UserBuffer;
+
+use crate::task::suspend_current_and_run_next;
+
+/// One end of a pipe
+pub struct Pipe {
+    readable: bool,
+    writable: bool,
+    buffer: Arc<UPSafeCell<PipeRingBuffer>>,
+}
+
+impl Pipe {
+    /// Create the read end of a pipe from a ring buffer
+    pub fn read_end_with_buffer(buffer: Arc<UPSafeCell<PipeRingBuffer>>) -> Self {
+        Self {
+            readable: true,
+            writable: false,
+            buffer,
+        }
+    }
+    /// Create the write end of a pipe with a ring buffer
+    pub fn write_end_with_buffer(buffer: Arc<UPSafeCell<PipeRingBuffer>>) -> Self {
+        Self {
+            readable: false,
+            writable: true,
+            buffer,
+        }
+    }
+}
+
+const RING_BUFFER_SIZE: usize = 32;
+
+#[derive(Copy, Clone, PartialEq)]
+enum RingBufferStatus {
+    FULL,
+    EMPTY,
+    NORMAL,
+}
+
+/// The underlying ring buffer of a pipe
+pub struct PipeRingBuffer {
+    arr: [u8; RING_BUFFER_SIZE],
+    head: usize,
+    tail: usize,
+    status: RingBufferStatus,
+    write_end: Option<Weak<Pipe>>,
+}
+
+impl PipeRingBuffer {
+    pub fn new() -> Self {
+        Self {
+            arr: [0; RING_BUFFER_SIZE],
+            head: 0,
+            tail: 0,
+            status: RingBufferStatus::EMPTY,
+            write_end: None,
+        }
+    }
+    /// Set the write end bound to this buffer
+    pub fn set_write_end(&mut self, write_end: &Arc<Pipe>) {
+        self.write_end = Some(Arc::downgrade(write_end));
+    }
+    /// Write into the buffer
+    pub fn write_byte(&mut self, byte: u8) {
+        self.status = RingBufferStatus::NORMAL;
+        self.arr[self.tail] = byte;
+        self.tail = (self.tail + 1) % RING_BUFFER_SIZE;
+        if self.tail == self.head {
+            self.status = RingBufferStatus::FULL;
+        }
+    }
+    /// Read from the buffer
+    pub fn read_byte(&mut self) -> u8 {
+        self.status = RingBufferStatus::NORMAL;
+        let c = self.arr[self.head];
+        self.head = (self.head + 1) % RING_BUFFER_SIZE;
+        if self.head == self.tail {
+            self.status = RingBufferStatus::EMPTY;
+        }
+        c
+    }
+    /// Get the length of remaining data in the buffer
+    pub fn available_read(&self) -> usize {
+        if self.status == RingBufferStatus::EMPTY {
+            0
+        } else {
+            if self.tail > self.head {
+                self.tail - self.head
+            } else {
+                self.tail + RING_BUFFER_SIZE - self.head
+            }
+        }
+    }
+    /// Get the length of remaining space in the buffer
+    pub fn available_write(&self) -> usize {
+        if self.status == RingBufferStatus::FULL {
+            0
+        } else {
+            RING_BUFFER_SIZE - self.available_read()
+        }
+    }
+    /// Check if all write ends bounded to this buffer are closed
+    pub fn all_write_ends_closed(&self) -> bool {
+        self.write_end.as_ref().unwrap().upgrade().is_none()
+    }
+}
+
+/// Crate a pipe
+/// return (read_end, write_end)
+pub fn make_pipe() -> (Arc<Pipe>, Arc<Pipe>) {
+    let buffer = Arc::new(unsafe {
+        UPSafeCell::new(PipeRingBuffer::new())
+    });
+    let read_end = Arc::new(
+        Pipe::read_end_with_buffer(buffer.clone())
+    );
+    let write_end = Arc::new(
+        Pipe::write_end_with_buffer(buffer.clone())
+    );
+    buffer.exclusive_access().set_write_end(&write_end);
+    (read_end, write_end)
+}
+
+impl File for Pipe {
+    fn readable(&self) -> bool { self.readable }
+    fn writable(&self) -> bool { self.writable }
+    fn read(&self, buf: UserBuffer) -> usize {
+        assert_eq!(self.readable(), true);
+        let mut buf_iter = buf.into_iter();
+        let mut read_size = 0usize;
+        loop {
+            let mut ring_buffer = self.buffer.exclusive_access();
+            let loop_read = ring_buffer.available_read();
+            if loop_read == 0 {
+                if ring_buffer.all_write_ends_closed() {
+                    return read_size;
+                }
+                drop(ring_buffer);
+                suspend_current_and_run_next();
+                continue;
+            }
+            // read at most loop_read bytes
+            for _ in 0..loop_read {
+                if let Some(byte_ref) = buf_iter.next() {
+                    unsafe { *byte_ref = ring_buffer.read_byte(); }
+                    read_size += 1;
+                } else {
+                    return read_size;
+                }
+            }
+        }
+    }
+    fn write(&self, buf: UserBuffer) -> usize {
+        assert_eq!(self.writable(), true);
+        let mut buf_iter = buf.into_iter();
+        let mut write_size = 0usize;
+        loop {
+            let mut ring_buffer = self.buffer.exclusive_access();
+            let loop_write = ring_buffer.available_write();
+            if loop_write == 0 {
+                drop(ring_buffer);
+                suspend_current_and_run_next();
+                continue;
+            }
+            // write at most loop_write bytes
+            for _ in 0..loop_write {
+                if let Some(byte_ref) = buf_iter.next() {
+                    ring_buffer.write_byte(unsafe { *byte_ref });
+                    write_size += 1;
+                } else {
+                    return write_size;
+                }
+            }
+        }
+    }
+}

os7-ref/src/fs/stdio.rs

@@ -0,0 +1,48 @@
+use super::File;
+use crate::mm::{UserBuffer};
+use crate::sbi::console_getchar;
+use crate::task::suspend_current_and_run_next;
+
+/// The standard input
+pub struct Stdin;
+/// The standard output
+pub struct Stdout;
+
+impl File for Stdin {
+    fn readable(&self) -> bool { true }
+    fn writable(&self) -> bool { false }
+    fn read(&self, mut user_buf: UserBuffer) -> usize {
+        assert_eq!(user_buf.len(), 1);
+        // busy loop
+        let mut c: usize;
+        loop {
+            c = console_getchar();
+            if c == 0 {
+                suspend_current_and_run_next();
+                continue;
+            } else {
+                break;
+            }
+        }
+        let ch = c as u8;
+        unsafe { user_buf.buffers[0].as_mut_ptr().write_volatile(ch); }
+        1
+    }
+    fn write(&self, _user_buf: UserBuffer) -> usize {
+        panic!("Cannot write to stdin!");
+    }
+}
+
+impl File for Stdout {
+    fn readable(&self) -> bool { false }
+    fn writable(&self) -> bool { true }
+    fn read(&self, _user_buf: UserBuffer) -> usize{
+        panic!("Cannot read from stdout!");
+    }
+    fn write(&self, user_buf: UserBuffer) -> usize {
+        for buffer in user_buf.buffers.iter() {
+            print!("{}", core::str::from_utf8(*buffer).unwrap());
+        }
+        user_buf.len()
+    }
+}