diff --git a/framework/aster-frame/src/mm/dma/dma_stream.rs b/framework/aster-frame/src/mm/dma/dma_stream.rs index e54e7b4f1..96aa17a40 100644 --- a/framework/aster-frame/src/mm/dma/dma_stream.rs +++ b/framework/aster-frame/src/mm/dma/dma_stream.rs @@ -125,10 +125,10 @@ impl DmaStream { /// /// This method should be called under one of the two conditions: /// 1. The data of the stream DMA mapping has been updated by the device side. - /// The CPU side needs to call the `sync` method before reading data (e.g., using [`read_bytes`]). + /// The CPU side needs to call the `sync` method before reading data (e.g., using [`read_bytes`]). /// 2. The data of the stream DMA mapping has been updated by the CPU side - /// (e.g., using [`write_bytes`]). - /// Before the CPU side notifies the device side to read, it must call the `sync` method first. + /// (e.g., using [`write_bytes`]). + /// Before the CPU side notifies the device side to read, it must call the `sync` method first. /// /// [`read_bytes`]: Self::read_bytes /// [`write_bytes`]: Self::write_bytes diff --git a/framework/aster-frame/src/mm/page_table/node.rs b/framework/aster-frame/src/mm/page_table/node.rs index a3ebe557e..f16a3d2dd 100644 --- a/framework/aster-frame/src/mm/page_table/node.rs +++ b/framework/aster-frame/src/mm/page_table/node.rs @@ -15,6 +15,7 @@ //! - a parent page table node, //! - or a handle to a page table node, //! - or a processor. +//! //! This is implemented by using a reference counter in the frame metadata. If the above //! conditions are not met, the page table node is ensured to be freed upon dropping the last //! reference. diff --git a/framework/libs/ktest/src/lib.rs b/framework/libs/ktest/src/lib.rs index 6cf3bcd7b..af7ca465a 100644 --- a/framework/libs/ktest/src/lib.rs +++ b/framework/libs/ktest/src/lib.rs @@ -12,7 +12,8 @@ //! By all means, ktest is an individule crate that only requires: //! - a custom linker script section `.ktest_array`, //! - and an alloc implementation. -//! to work. And the frame happens to provide both of them. Thus, any crates depending +//! +//! And the frame happens to provide both of them. Thus, any crates depending //! on the frame can use ktest without any extra dependency. //! //! ## Usage diff --git a/framework/libs/linux-bzimage/setup/src/x86/amd64_efi/paging.rs b/framework/libs/linux-bzimage/setup/src/x86/amd64_efi/paging.rs index 68f92fa36..c66703fe3 100644 --- a/framework/libs/linux-bzimage/setup/src/x86/amd64_efi/paging.rs +++ b/framework/libs/linux-bzimage/setup/src/x86/amd64_efi/paging.rs @@ -8,6 +8,7 @@ //! - Level-3: Page Directory Pointer Table (PDPT); //! - Level-2: Page Directory (PD); //! - Level-1: Page Table (PT). +//! //! We sometimes use "level-n" page table to refer to the page table described //! above, avoiding the use of complicated names in the Intel manual. diff --git a/kernel/aster-nix/src/process/process/mod.rs b/kernel/aster-nix/src/process/process/mod.rs index 6274f2a43..fe0adfd83 100644 --- a/kernel/aster-nix/src/process/process/mod.rs +++ b/kernel/aster-nix/src/process/process/mod.rs @@ -337,8 +337,8 @@ impl Process { /// and moves the process to the session, returning the new session. /// /// This method may return the following errors: - /// * `EPERM`, if the process is a process group leader, or some existing session - /// or process group has the same ID as the process. + /// * `EPERM`, if the process is a process group leader, or some existing session + /// or process group has the same ID as the process. pub fn to_new_session(self: &Arc) -> Result> { if self.is_session_leader() { return Ok(self.session().unwrap()); @@ -405,14 +405,14 @@ impl Process { /// Moves the process to other process group. /// - /// * If the group already exists, the process and the group should belong to the same session. - /// * If the group does not exist, this method creates a new group for the process and move the - /// process to the group. The group is added to the session of the process. + /// * If the group already exists, the process and the group should belong to the same session. + /// * If the group does not exist, this method creates a new group for the process and move the + /// process to the group. The group is added to the session of the process. /// /// This method may return `EPERM` in following cases: - /// * The process is session leader; - /// * The group already exists, but the group does not belong to the same session as the process; - /// * The group does not exist, but `pgid` is not equal to `pid` of the process. + /// * The process is session leader; + /// * The group already exists, but the group does not belong to the same session as the process; + /// * The group does not exist, but `pgid` is not equal to `pid` of the process. pub fn to_other_group(self: &Arc, pgid: Pgid) -> Result<()> { // if the process already belongs to the process group if self.pgid() == pgid { diff --git a/kernel/aster-nix/src/process/process_vm/init_stack/aux_vec.rs b/kernel/aster-nix/src/process/process_vm/init_stack/aux_vec.rs index 409281e22..ff6511abd 100644 --- a/kernel/aster-nix/src/process/process_vm/init_stack/aux_vec.rs +++ b/kernel/aster-nix/src/process/process_vm/init_stack/aux_vec.rs @@ -10,10 +10,10 @@ use crate::prelude::*; /// /// Here is a concise description of Auxiliary Vector from GNU's manual: /// -/// > When a program is executed, it receives information from the operating system -/// about the environment in which it is operating. The form of this information -/// is a table of key-value pairs, where the keys are from the set of ‘AT_’ -/// values in elf.h. +/// > When a program is executed, it receives information from the operating system +/// > about the environment in which it is operating. The form of this information +/// > is a table of key-value pairs, where the keys are from the set of ‘AT_’ +/// > values in elf.h. #[allow(non_camel_case_types)] #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)] diff --git a/kernel/aster-nix/src/vm/mod.rs b/kernel/aster-nix/src/vm/mod.rs index b4d623ab5..a4970b5e1 100644 --- a/kernel/aster-nix/src/vm/mod.rs +++ b/kernel/aster-nix/src/vm/mod.rs @@ -3,10 +3,10 @@ //! Virtual memory (VM). //! //! There are two primary VM abstractions: -//! * Virtual Memory Address Regions (VMARs) a type of capability that manages -//! user address spaces. -//! * Virtual Memory Objects (VMOs) are are a type of capability that -//! represents a set of memory pages. +//! * Virtual Memory Address Regions (VMARs) a type of capability that manages +//! user address spaces. +//! * Virtual Memory Objects (VMOs) are are a type of capability that +//! represents a set of memory pages. //! //! The concepts of VMARs and VMOs are originally introduced by //! [Zircon](https://fuchsia.dev/fuchsia-src/reference/kernel_objects/vm_object). diff --git a/kernel/aster-nix/src/vm/vmar/dyn_cap.rs b/kernel/aster-nix/src/vm/vmar/dyn_cap.rs index 101df672f..9f819e53f 100644 --- a/kernel/aster-nix/src/vm/vmar/dyn_cap.rs +++ b/kernel/aster-nix/src/vm/vmar/dyn_cap.rs @@ -47,11 +47,11 @@ impl Vmar { /// # Access rights /// /// This method requires the following access rights: - /// 1. The VMAR contains the rights corresponding to the memory permissions of - /// the mapping. For example, if `perms` contains `VmPerms::WRITE`, - /// then the VMAR must have the Write right. - /// 2. Similarly, the VMO contains the rights corresponding to the memory - /// permissions of the mapping. + /// 1. The VMAR contains the rights corresponding to the memory permissions of + /// the mapping. For example, if `perms` contains `VmPerms::WRITE`, + /// then the VMAR must have the Write right. + /// 2. Similarly, the VMO contains the rights corresponding to the memory + /// permissions of the mapping. /// /// Memory permissions may be changed through the `protect` method, /// which ensures that any updated memory permissions do not go beyond diff --git a/kernel/aster-nix/src/vm/vmar/mod.rs b/kernel/aster-nix/src/vm/vmar/mod.rs index e9065570b..bcb495219 100644 --- a/kernel/aster-nix/src/vm/vmar/mod.rs +++ b/kernel/aster-nix/src/vm/vmar/mod.rs @@ -32,12 +32,12 @@ use crate::{prelude::*, vm::perms::VmPerms}; /// whose semantics are explained below. /// /// The semantics of each access rights for VMARs are described below: -/// * The Dup right allows duplicating a VMAR and creating children out of -/// a VMAR. -/// * The Read, Write, Exec rights allow creating memory mappings with -/// readable, writable, and executable access permissions, respectively. -/// * The Read and Write rights allow the VMAR to be read from and written to -/// directly. +/// * The Dup right allows duplicating a VMAR and creating children out of +/// a VMAR. +/// * The Read, Write, Exec rights allow creating memory mappings with +/// readable, writable, and executable access permissions, respectively. +/// * The Read and Write rights allow the VMAR to be read from and written to +/// directly. /// /// VMARs are implemented with two flavors of capabilities: /// the dynamic one (`Vmar`) and the static one (`Vmar). diff --git a/kernel/aster-nix/src/vm/vmar/vm_mapping.rs b/kernel/aster-nix/src/vm/vmar/vm_mapping.rs index 9c79da496..71724493d 100644 --- a/kernel/aster-nix/src/vm/vmar/vm_mapping.rs +++ b/kernel/aster-nix/src/vm/vmar/vm_mapping.rs @@ -384,12 +384,12 @@ impl VmMapping { /// Trim a range from the mapping. /// There are several cases. - /// 1. the trim_range is totally in the mapping. Then the mapping will split as two mappings. - /// 2. the trim_range covers the mapping. Then the mapping will be destroyed. - /// 3. the trim_range partly overlaps with the mapping, in left or right. Only overlapped part is trimmed. - /// If we create a mapping with a new map addr, we will add it to mappings_to_append. - /// If the mapping with map addr does not exist ever, the map addr will be added to mappings_to_remove. - /// Otherwise, we will directly modify self. + /// 1. the trim_range is totally in the mapping. Then the mapping will split as two mappings. + /// 2. the trim_range covers the mapping. Then the mapping will be destroyed. + /// 3. the trim_range partly overlaps with the mapping, in left or right. Only overlapped part is trimmed. + /// If we create a mapping with a new map addr, we will add it to mappings_to_append. + /// If the mapping with map addr does not exist ever, the map addr will be added to mappings_to_remove. + /// Otherwise, we will directly modify self. pub fn trim_mapping( self: &Arc, trim_range: &Range, @@ -674,12 +674,12 @@ impl VmarMapOptions { /// part of the mapping that is not backed by the VMO. /// So you may wonder: what is the point of supporting such _oversized_ /// mappings? The reason is two-fold. - /// 1. VMOs are resizable. So even if a mapping is backed by a VMO whose - /// size is equal to that of the mapping initially, we cannot prevent - /// the VMO from shrinking. - /// 2. Mappings are not allowed to overlap by default. As a result, - /// oversized mappings can serve as a placeholder to prevent future - /// mappings from occupying some particular address ranges accidentally. + /// 1. VMOs are resizable. So even if a mapping is backed by a VMO whose + /// size is equal to that of the mapping initially, we cannot prevent + /// the VMO from shrinking. + /// 2. Mappings are not allowed to overlap by default. As a result, + /// oversized mappings can serve as a placeholder to prevent future + /// mappings from occupying some particular address ranges accidentally. /// /// The default value is the size of the VMO. pub fn size(mut self, size: usize) -> Self { diff --git a/kernel/aster-nix/src/vm/vmo/mod.rs b/kernel/aster-nix/src/vm/vmo/mod.rs index 12f186c97..be7f8f0bb 100644 --- a/kernel/aster-nix/src/vm/vmo/mod.rs +++ b/kernel/aster-nix/src/vm/vmo/mod.rs @@ -31,38 +31,38 @@ use self::options::ChildType; /// /// # Features /// -/// * **I/O interface.** A VMO provides read and write methods to access the -/// memory pages that it contain. -/// * **On-demand paging.** The memory pages of a VMO (except for _contiguous_ -/// VMOs) are allocated lazily when the page is first accessed. -/// * **Tree structure.** Given a VMO, one can create a child VMO from it. -/// The child VMO can only access a subset of the parent's memory, -/// which is a good thing for the perspective of access control. -/// * **Copy-on-write (COW).** A child VMO may be created with COW semantics, -/// which prevents any writes on the child from affecting the parent -/// by duplicating memory pages only upon the first writes. -/// * **Access control.** As capabilities, VMOs restrict the -/// accessible range of memory and the allowed I/O operations. -/// * **Device driver support.** If specified upon creation, VMOs will be -/// backed by physically contiguous memory pages starting at a target address. -/// * **File system support.** By default, a VMO's memory pages are initially -/// all zeros. But if a VMO is attached to a pager (`Pager`) upon creation, -/// then its memory pages will be populated by the pager. -/// With this pager mechanism, file systems can easily implement page caches -/// with VMOs by attaching the VMOs to pagers backed by inodes. +/// * **I/O interface.** A VMO provides read and write methods to access the +/// memory pages that it contain. +/// * **On-demand paging.** The memory pages of a VMO (except for _contiguous_ +/// VMOs) are allocated lazily when the page is first accessed. +/// * **Tree structure.** Given a VMO, one can create a child VMO from it. +/// The child VMO can only access a subset of the parent's memory, +/// which is a good thing for the perspective of access control. +/// * **Copy-on-write (COW).** A child VMO may be created with COW semantics, +/// which prevents any writes on the child from affecting the parent +/// by duplicating memory pages only upon the first writes. +/// * **Access control.** As capabilities, VMOs restrict the +/// accessible range of memory and the allowed I/O operations. +/// * **Device driver support.** If specified upon creation, VMOs will be +/// backed by physically contiguous memory pages starting at a target address. +/// * **File system support.** By default, a VMO's memory pages are initially +/// all zeros. But if a VMO is attached to a pager (`Pager`) upon creation, +/// then its memory pages will be populated by the pager. +/// With this pager mechanism, file systems can easily implement page caches +/// with VMOs by attaching the VMOs to pagers backed by inodes. /// /// # Capabilities /// /// As a capability, each VMO is associated with a set of access rights, /// whose semantics are explained below. /// -/// * The Dup right allows duplicating a VMO and creating children out of -/// a VMO. -/// * The Read, Write, Exec rights allow creating memory mappings with -/// readable, writable, and executable access permissions, respectively. -/// * The Read and Write rights allow the VMO to be read from and written to -/// directly. -/// * The Write right allows resizing a resizable VMO. +/// * The Dup right allows duplicating a VMO and creating children out of +/// a VMO. +/// * The Read, Write, Exec rights allow creating memory mappings with +/// readable, writable, and executable access permissions, respectively. +/// * The Read and Write rights allow the VMO to be read from and written to +/// directly. +/// * The Write right allows resizing a resizable VMO. /// /// VMOs are implemented with two flavors of capabilities: /// the dynamic one (`Vmo`) and the static one (`Vmo). @@ -185,7 +185,7 @@ impl Pages { /// `Vmo_` is the structure that actually manages the content of VMO. /// Broadly speaking, there are two types of VMO: /// 1. File-backed VMO: the VMO backed by a file and resides in the `PageCache`, -/// which includes a pager to provide it with actual pages. +/// which includes a pager to provide it with actual pages. /// 2. Anonymous VMO: the VMO without a file backup, which does not have a pager. pub(super) struct Vmo_ { pager: Option>, diff --git a/kernel/libs/aster-util/src/safe_ptr.rs b/kernel/libs/aster-util/src/safe_ptr.rs index 14a401948..3e5f34f0d 100644 --- a/kernel/libs/aster-util/src/safe_ptr.rs +++ b/kernel/libs/aster-util/src/safe_ptr.rs @@ -24,13 +24,13 @@ pub use typeflags_util::SetContain; /// More specifically, there are three major restrictions. /// /// 1. A safe pointer can only refer to a value of a POD type `T: Pod`, -/// while raw pointers can do to a value of any type `T`. +/// while raw pointers can do to a value of any type `T`. /// 2. A safe pointer can only refer to an address within a virtual memory object -/// of type `M: VmIo` (e.g., VMAR and VMO), while raw pointers can do to -/// an address within any virtual memory space. +/// of type `M: VmIo` (e.g., VMAR and VMO), while raw pointers can do to +/// an address within any virtual memory space. /// 3. A safe pointer only allows one to copy values to/from the target address, -/// while a raw pointer allows one to borrow an immutable or mutable reference -/// to the target address. +/// while a raw pointer allows one to borrow an immutable or mutable reference +/// to the target address. /// /// The expressiveness of safe pointers, although being less than that of /// raw pointers, is sufficient for our purpose of writing an OS kernel in safe diff --git a/kernel/libs/comp-sys/component-macro/src/lib.rs b/kernel/libs/comp-sys/component-macro/src/lib.rs index 04bb06387..5254a8609 100644 --- a/kernel/libs/comp-sys/component-macro/src/lib.rs +++ b/kernel/libs/comp-sys/component-macro/src/lib.rs @@ -1,7 +1,6 @@ // SPDX-License-Identifier: MPL-2.0 //！This crate defines the component system related macros. -//! #![feature(proc_macro_diagnostic)] #![allow(dead_code)] diff --git a/kernel/libs/keyable-arc/src/lib.rs b/kernel/libs/keyable-arc/src/lib.rs index bd753aa1f..7301e2427 100644 --- a/kernel/libs/keyable-arc/src/lib.rs +++ b/kernel/libs/keyable-arc/src/lib.rs @@ -10,9 +10,9 @@ //! //! 1. It implements the `Eq` and `Hash` traits. //! 2. The two values of `k1` and `k2` of type `K` equal to each other, -//! if and only if their hash values equal to each other. +//! if and only if their hash values equal to each other. //! 3. The hashes of a value of `k` of type `K` cannot change while it -//! is in a map. +//! is in a map. //! //! Sometimes we want to use `Arc` as the key type for a hash map but cannot do so //! since `T` does not satisfy the properties above. For example, a lot of types