Init the ch8

Author: Azure-stars

.github/workflows/build.yml

@@ -7,6 +7,23 @@ env:
   rust_toolchain: nightly
 
 jobs:
+  build-doc:
+    if: github.repository == 'LearningOS/rCore-Tutorial-Code'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build doc
+        run: |
+          git clone https://github.com/LearningOS/rCore-Tutorial-Test.git user
+          cd os
+          make
+          cargo doc --no-deps --verbose
+      - name: Push to gh-pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./os/target/riscv64gc-unknown-none-elf/doc
+          destination_dir: ${{ github.ref_name }}
   basic-test:
     runs-on: ubuntu-latest
     outputs:
@@ -25,11 +42,11 @@ jobs:
           ID=`git rev-parse --abbrev-ref HEAD | grep -oP 'ch\K[0-9]'`
           cd ci-user && make test CHAPTER=$ID passwd=${{ secrets.BASE_TEST_TOKEN }} > ../output.txt
           cat ../output.txt
-      - name: end
+      - name: end 
         id: end
         run: |
-          cat output.txt | grep "Test passed" | grep -oP "\d{1,}/\d{1,}" | xargs -i echo "points={}"
-          cat output.txt | grep "Test passed" | grep -oP "\d{1,}/\d{1,}" | xargs -i echo "points={}" >> $GITHUB_OUTPUT
+          cat output.txt | grep -a "Test passed" | grep -oP "\d{1,}/\d{1,}" | xargs -i echo "points={}"
+          cat output.txt | grep -a "Test passed" | grep -oP "\d{1,}/\d{1,}" | xargs -i echo "points={}" >> $GITHUB_OUTPUT
   deploy:
     if: github.repository != 'LearningOS/rCore-Tutorial-Code'
     name: Deploy to pages

.gitignore

@@ -1,19 +1,23 @@
 .*/*
 !.github/*
 !.vscode/settings.json
-.idea
-Cargo.lock
-target
+.idea/*
+os/target/*
+os/.idea/*
 os/src/link_app.S
 os/last-*
 os/Cargo.lock
 os/.gdb_history
+user/target/*
+user/.idea/*
+user/Cargo.lock
 easy-fs/Cargo.lock
 easy-fs/target/*
 easy-fs-fuse/Cargo.lock
 easy-fs-fuse/target/*
 tools/
 pushall.sh
+.vscode/*.log
 *.bak
 ci-user/
 user/

easy-fs/src/bitmap.rs

@@ -1,30 +1,34 @@
+//! Disk layout & data structure layer: about bitmaps
+//!
+//! There are two different types of [`Bitmap`] in the easy-fs layout that manage inodes and blocks, respectively. Each bitmap consists of several blocks, each of which is 512 bytes, or 4096 bits. Each bit represents the allocation status of an inode/data block, 0 means unallocated, and 1 means allocated. What the bitmap does is allocate and de-allocate inodes/data blocks via bit-based allocation (looking for a bit of 0 and setting it to 1) and de-allocation (clearing the bit).
 use super::{get_block_cache, BlockDevice, BLOCK_SZ};
 use alloc::sync::Arc;
-
+/// A bitmap block
 type BitmapBlock = [u64; 64];
-
+/// Number of bits in a block
 const BLOCK_BITS: usize = BLOCK_SZ * 8;
-
+/// bitmap struct for disk block management
 pub struct Bitmap {
     start_block_id: usize,
     blocks: usize,
 }
 
-/// Return (block_pos, bits64_pos, inner_pos)
+/// Decompose bits into (block_pos, bits64_pos, inner_pos)
 fn decomposition(mut bit: usize) -> (usize, usize, usize) {
     let block_pos = bit / BLOCK_BITS;
     bit %= BLOCK_BITS;
     (block_pos, bit / 64, bit % 64)
 }
 
 impl Bitmap {
+    /// Create new bitmap blocks
     pub fn new(start_block_id: usize, blocks: usize) -> Self {
         Self {
             start_block_id,
             blocks,
         }
     }
-
+    /// Allocate a block according to the bitmap info
     pub fn alloc(&self, block_device: &Arc<dyn BlockDevice>) -> Option<usize> {
         for block_id in 0..self.blocks {
             let pos = get_block_cache(
@@ -52,7 +56,7 @@ impl Bitmap {
         }
         None
     }
-
+    /// Deallocate a block according to the bitmap info
     pub fn dealloc(&self, block_device: &Arc<dyn BlockDevice>, bit: usize) {
         let (block_pos, bits64_pos, inner_pos) = decomposition(bit);
         get_block_cache(block_pos + self.start_block_id, Arc::clone(block_device))
@@ -62,7 +66,7 @@ impl Bitmap {
                 bitmap_block[bits64_pos] -= 1u64 << inner_pos;
             });
     }
-
+    /// bitmap max size in bits(the max number of blocks according to the bitmap size)
     pub fn maximum(&self) -> usize {
         self.blocks * BLOCK_BITS
     }

easy-fs/src/block_cache.rs

@@ -1,11 +1,13 @@
+//! Block Cache Layer
+//! Implements about the disk block cache functionality
 use super::{BlockDevice, BLOCK_SZ};
 use alloc::collections::VecDeque;
 use alloc::sync::Arc;
 use alloc::vec;
 use alloc::vec::Vec;
 use lazy_static::*;
 use spin::Mutex;
-
+/// BlockCache is a cache for a block in disk.
 pub struct BlockCache {
     cache: Vec<u8>,
     block_id: usize,
@@ -26,11 +28,11 @@ impl BlockCache {
             modified: false,
         }
     }
-
+    /// Get the slice in the block cache according to the offset.
     fn addr_of_offset(&self, offset: usize) -> usize {
         &self.cache[offset] as *const _ as usize
     }
-
+    /// Get a immutable reference to the data in the block cache according to the offset.
     pub fn get_ref<T>(&self, offset: usize) -> &T
     where
         T: Sized,
@@ -40,7 +42,7 @@ impl BlockCache {
         let addr = self.addr_of_offset(offset);
         unsafe { &*(addr as *const T) }
     }
-
+    /// Get a mutable reference to the data in the block cache according to the offset.
     pub fn get_mut<T>(&mut self, offset: usize) -> &mut T
     where
         T: Sized,
@@ -51,15 +53,15 @@ impl BlockCache {
         let addr = self.addr_of_offset(offset);
         unsafe { &mut *(addr as *mut T) }
     }
-
+    /// Read the data from the block cache according to the offset.
     pub fn read<T, V>(&self, offset: usize, f: impl FnOnce(&T) -> V) -> V {
         f(self.get_ref(offset))
     }
-
+    /// Write the data into the block cache according to the offset.
     pub fn modify<T, V>(&mut self, offset: usize, f: impl FnOnce(&mut T) -> V) -> V {
         f(self.get_mut(offset))
     }
-
+    /// Sync(write) the block cache to disk.
     pub fn sync(&mut self) {
         if self.modified {
             self.modified = false;
@@ -76,17 +78,20 @@ impl Drop for BlockCache {
 
 const BLOCK_CACHE_SIZE: usize = 16;
 
+/// BlockCacheManager is a manager for BlockCache.
 pub struct BlockCacheManager {
+    /// (block_id, block_cache)
     queue: VecDeque<(usize, Arc<Mutex<BlockCache>>)>,
 }
 
 impl BlockCacheManager {
+    /// Create a new BlockCacheManager with an empty queue (block_id, block_cache)
     pub fn new() -> Self {
         Self {
             queue: VecDeque::new(),
         }
     }
-
+    /// Get a block cache from the queue. according to the block_id.
     pub fn get_block_cache(
         &mut self,
         block_id: usize,
@@ -121,10 +126,11 @@ impl BlockCacheManager {
 }
 
 lazy_static! {
+    /// BLOCK_CACHE_MANAGER: Glocal instance of BlockCacheManager.
     pub static ref BLOCK_CACHE_MANAGER: Mutex<BlockCacheManager> =
         Mutex::new(BlockCacheManager::new());
 }
-
+/// Get a block cache from the queue. according to the block_id.
 pub fn get_block_cache(
     block_id: usize,
     block_device: Arc<dyn BlockDevice>,
@@ -133,7 +139,7 @@ pub fn get_block_cache(
         .lock()
         .get_block_cache(block_id, block_device)
 }
-
+/// Sync(write) all the block cache to disk.
 pub fn block_cache_sync_all() {
     let manager = BLOCK_CACHE_MANAGER.lock();
     for (_, cache) in manager.queue.iter() {

easy-fs/src/block_dev.rs

@@ -1,6 +1,12 @@
+//! Block device interface.
+//!
+//! Define the block read-write interface [BlockDevice] that the device driver needs to implement
+
 use core::any::Any;
 
 pub trait BlockDevice: Send + Sync + Any {
+    /// Read a block from the block device.
     fn read_block(&self, block_id: usize, buf: &mut [u8]);
+    /// Write a block to the block device.
     fn write_block(&self, block_id: usize, buf: &[u8]);
 }

easy-fs/src/efs.rs

@@ -1,3 +1,8 @@
+//! Disk block manager layer
+//!
+//! Disk block manager  knows the disk location of each layout area, and the allocation and reclamation of disk blocks need to be completed through it.
+//!
+//! NOTICE: from this level, all data structures are in memory.
 use super::{
     block_cache_sync_all, get_block_cache, Bitmap, BlockDevice, DiskInode, DiskInodeType, Inode,
     SuperBlock,
@@ -6,17 +11,24 @@ use crate::BLOCK_SZ;
 use alloc::sync::Arc;
 use spin::Mutex;
 
+/// EasyFileSystem struct
 pub struct EasyFileSystem {
+    /// The block device
     pub block_device: Arc<dyn BlockDevice>,
+    /// The bitmap of inode blocks
     pub inode_bitmap: Bitmap,
+    /// The bitmap of data blocks
     pub data_bitmap: Bitmap,
+    /// The start block id of inode area
     inode_area_start_block: u32,
+    /// The start block id of data area
     data_area_start_block: u32,
 }
 
 type DataBlock = [u8; BLOCK_SZ];
 
 impl EasyFileSystem {
+    /// Create a new EasyFileSystem
     pub fn create(
         block_device: Arc<dyn BlockDevice>,
         total_blocks: u32,
@@ -35,6 +47,7 @@ impl EasyFileSystem {
             (1 + inode_bitmap_blocks + inode_area_blocks) as usize,
             data_bitmap_blocks as usize,
         );
+        //
         let mut efs = Self {
             block_device: Arc::clone(&block_device),
             inode_bitmap,
@@ -77,7 +90,7 @@ impl EasyFileSystem {
         block_cache_sync_all();
         Arc::new(Mutex::new(efs))
     }
-
+    /// Open an existing EasyFileSystem
     pub fn open(block_device: Arc<dyn BlockDevice>) -> Arc<Mutex<Self>> {
         // read SuperBlock
         get_block_cache(0, Arc::clone(&block_device))
@@ -99,15 +112,15 @@ impl EasyFileSystem {
                 Arc::new(Mutex::new(efs))
             })
     }
-
+    /// Get the root inode
     pub fn root_inode(efs: &Arc<Mutex<Self>>) -> Inode {
         let block_device = Arc::clone(&efs.lock().block_device);
         // acquire efs lock temporarily
         let (block_id, block_offset) = efs.lock().get_disk_inode_pos(0);
         // release efs lock
         Inode::new(block_id, block_offset, Arc::clone(efs), block_device)
     }
-
+    /// Get inode block position (the block id and offset in this block) according to the inode id
     pub fn get_disk_inode_pos(&self, inode_id: u32) -> (u32, usize) {
         let inode_size = core::mem::size_of::<DiskInode>();
         let inodes_per_block = (BLOCK_SZ / inode_size) as u32;
@@ -117,20 +130,20 @@ impl EasyFileSystem {
             (inode_id % inodes_per_block) as usize * inode_size,
         )
     }
-
+    /// Get data block position according to the data block id
     pub fn get_data_block_id(&self, data_block_id: u32) -> u32 {
         self.data_area_start_block + data_block_id
     }
-
+    /// allocate a new inode, return its inode_id
     pub fn alloc_inode(&mut self) -> u32 {
         self.inode_bitmap.alloc(&self.block_device).unwrap() as u32
     }
 
-    /// Return a block ID not ID in the data area.
+    /// allocate a new data block, return its block position (block_id)
     pub fn alloc_data(&mut self) -> u32 {
         self.data_bitmap.alloc(&self.block_device).unwrap() as u32 + self.data_area_start_block
     }
-
+    /// deallocate a data block according to its block id
     pub fn dealloc_data(&mut self, block_id: u32) {
         get_block_cache(block_id as usize, Arc::clone(&self.block_device))
             .lock()