From 116f5e78581d5fc0c5cd57ae702a3d030c13847a Mon Sep 17 00:00:00 2001 From: Chenzs108 Date: Wed, 23 Oct 2024 00:36:16 +0800 Subject: [PATCH] Docs: Change comment styles --- README.md | 223 ++++++++++++++++++++++ include/kernel/debug/assert.h | 6 +- include/kernel/descriptor/desc.h | 36 ++-- include/kernel/descriptor/gdt/idx.h | 6 +- include/kernel/descriptor/gdt/tab.h | 6 +- include/kernel/interrupt/intr.h | 25 ++- include/kernel/interrupt/pic.h | 6 +- include/kernel/io/disk/disk.h | 31 ++- include/kernel/io/disk/file/dir.h | 15 +- include/kernel/io/disk/file/file.h | 6 +- include/kernel/io/disk/file/inode.h | 19 +- include/kernel/io/disk/file/super_block.h | 16 +- include/kernel/io/disk/ide.h | 13 +- include/kernel/io/file/dir.h | 10 +- include/kernel/io/file/file.h | 14 +- include/kernel/io/file/path.h | 14 +- include/kernel/io/io.h | 10 +- include/kernel/io/keyboard.h | 6 +- include/kernel/io/timer.h | 6 +- include/kernel/io/video/console.h | 6 +- include/kernel/io/video/print.h | 6 +- include/kernel/krnl.h | 6 +- include/kernel/memory/page.h | 20 +- include/kernel/memory/pool.h | 11 +- include/kernel/process/proc.h | 12 +- include/kernel/process/tss.h | 10 +- include/kernel/selector/sel.h | 16 +- include/kernel/syscall/call.h | 14 +- include/kernel/thread/sync.h | 6 +- include/kernel/thread/thd.h | 39 +++- include/kernel/util/bit.h | 6 +- include/kernel/util/bitmap.h | 6 +- include/kernel/util/block_queue.h | 14 +- include/kernel/util/format.h | 6 +- include/kernel/util/metric.h | 8 + include/kernel/util/tag_list.h | 13 +- include/user/io/file/dir.h | 7 +- include/user/io/file/file.h | 7 +- include/user/io/video/console.h | 7 +- include/user/memory/pool.h | 8 +- include/user/process/proc.h | 7 +- include/user/syscall/call.h | 9 +- src/kernel/interrupt/intr.cpp | 5 +- src/kernel/interrupt/pic.cpp | 24 +-- src/kernel/io/disk/disk.cpp | 32 +--- src/kernel/io/disk/part.cpp | 4 +- src/kernel/io/keyboard.cpp | 8 +- src/kernel/io/timer.cpp | 8 +- src/kernel/memory/pool.cpp | 7 + 49 files changed, 602 insertions(+), 198 deletions(-) diff --git a/README.md b/README.md index b9b88cdd..69fa3b44 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,229 @@ This project is a tiny *Intel x86* operating system written in *assembly* and *C - [*《操作系统真象还原》郑钢*](https://github.com/yifengyou/os-elephant) +## Structure + +```console +. +├── CITATION.cff +├── Debugging.md +├── LICENSE +├── Makefile +├── README.md +├── docs +│   ├── Boot +│   │   ├── Images +│   │   │   └── loader +│   │   │   ├── memory-paging.drawio +│   │   │   ├── memory-paging.svg +│   │   │   ├── page-directory-table.drawio +│   │   │   └── page-directory-table.svg +│   │   ├── Loader.md +│   │   └── Master Boot Record.md +│   ├── Getting Started +│   │   ├── Building the System.md +│   │   └── Development Environment.md +│   ├── Kernel +│   │   ├── File System.md +│   │   ├── Images +│   │   │   ├── file-system +│   │   │   │   ├── directory-entries.drawio +│   │   │   │   ├── directory-entries.svg +│   │   │   │   ├── index-node.drawio +│   │   │   │   └── index-node.svg +│   │   │   ├── memory +│   │   │   │   ├── memory-heap.drawio +│   │   │   │   ├── memory-heap.svg +│   │   │   │   ├── memory-pools.drawio +│   │   │   │   └── memory-pools.svg +│   │   │   └── threads +│   │   │   ├── thread-block.drawio +│   │   │   ├── thread-block.svg +│   │   │   ├── thread-lists.drawio +│   │   │   ├── thread-lists.svg +│   │   │   ├── thread-switching.drawio +│   │   │   └── thread-switching.svg +│   │   ├── Interrupts.md +│   │   ├── Memory.md +│   │   ├── System Calls.md +│   │   ├── Threads.md +│   │   └── User Processes.md +│   └── badges +│   ├── C++.svg +│   ├── License-MIT.svg +│   ├── Linux.svg +│   ├── Made-with-GitHub-Actions.svg +│   ├── Made-with-Make.svg +│   └── NASM.svg +├── include +│   ├── boot +│   │   └── boot.inc +│   ├── kernel +│   │   ├── debug +│   │   │   └── assert.h +│   │   ├── descriptor +│   │   │   ├── desc.h +│   │   │   ├── desc.inc +│   │   │   └── gdt +│   │   │   ├── idx.h +│   │   │   └── tab.h +│   │   ├── interrupt +│   │   │   ├── intr.h +│   │   │   └── pic.h +│   │   ├── io +│   │   │   ├── disk +│   │   │   │   ├── disk.h +│   │   │   │   ├── disk.inc +│   │   │   │   ├── file +│   │   │   │   │   ├── dir.h +│   │   │   │   │   ├── file.h +│   │   │   │   │   ├── inode.h +│   │   │   │   │   └── super_block.h +│   │   │   │   └── ide.h +│   │   │   ├── file +│   │   │   │   ├── dir.h +│   │   │   │   ├── file.h +│   │   │   │   └── path.h +│   │   │   ├── io.h +│   │   │   ├── keyboard.h +│   │   │   ├── timer.h +│   │   │   └── video +│   │   │   ├── console.h +│   │   │   ├── print.h +│   │   │   └── print.inc +│   │   ├── krnl.h +│   │   ├── krnl.inc +│   │   ├── memory +│   │   │   ├── page.h +│   │   │   ├── page.inc +│   │   │   └── pool.h +│   │   ├── process +│   │   │   ├── elf.inc +│   │   │   ├── proc.h +│   │   │   └── tss.h +│   │   ├── selector +│   │   │   ├── sel.h +│   │   │   └── sel.inc +│   │   ├── stl +│   │   │   ├── algorithm.h +│   │   │   ├── array.h +│   │   │   ├── cerron.h +│   │   │   ├── cmath.h +│   │   │   ├── cstddef.h +│   │   │   ├── cstdint.h +│   │   │   ├── cstdlib.h +│   │   │   ├── cstring.h +│   │   │   ├── iterator.h +│   │   │   ├── mutex.h +│   │   │   ├── semaphore.h +│   │   │   ├── source_location.h +│   │   │   ├── span.h +│   │   │   ├── string_view.h +│   │   │   ├── type_traits.h +│   │   │   └── utility.h +│   │   ├── syscall +│   │   │   └── call.h +│   │   ├── thread +│   │   │   ├── sync.h +│   │   │   └── thd.h +│   │   └── util +│   │   ├── bit.h +│   │   ├── bitmap.h +│   │   ├── block_queue.h +│   │   ├── format.h +│   │   ├── metric.h +│   │   ├── metric.inc +│   │   └── tag_list.h +│   └── user +│   ├── io +│   │   ├── file +│   │   │   ├── dir.h +│   │   │   └── file.h +│   │   └── video +│   │   └── console.h +│   ├── memory +│   │   └── pool.h +│   ├── process +│   │   └── proc.h +│   ├── stl +│   │   └── cstdint.h +│   └── syscall +│   └── call.h +└── src + ├── boot + │   ├── loader.asm + │   └── mbr.asm + ├── kernel + │   ├── debug + │   │   └── assert.cpp + │   ├── descriptor + │   │   ├── desc.asm + │   │   └── gdt + │   │   └── tab.cpp + │   ├── interrupt + │   │   ├── intr.asm + │   │   ├── intr.cpp + │   │   └── pic.cpp + │   ├── io + │   │   ├── disk + │   │   │   ├── disk.cpp + │   │   │   ├── file + │   │   │   │   ├── dir.cpp + │   │   │   │   ├── file.cpp + │   │   │   │   ├── inode.cpp + │   │   │   │   └── super_block.cpp + │   │   │   ├── ide.cpp + │   │   │   └── part.cpp + │   │   ├── file + │   │   │   ├── dir.cpp + │   │   │   ├── file.cpp + │   │   │   └── path.cpp + │   │   ├── io.asm + │   │   ├── io.cpp + │   │   ├── keyboard.cpp + │   │   ├── timer.cpp + │   │   └── video + │   │   ├── console.cpp + │   │   ├── print.asm + │   │   └── print.cpp + │   ├── krnl.cpp + │   ├── main.cpp + │   ├── memory + │   │   ├── page.asm + │   │   ├── page.cpp + │   │   └── pool.cpp + │   ├── process + │   │   ├── proc.cpp + │   │   ├── tss.asm + │   │   └── tss.cpp + │   ├── stl + │   │   ├── cstring.cpp + │   │   ├── mutex.cpp + │   │   └── semaphore.cpp + │   ├── syscall + │   │   ├── call.asm + │   │   └── call.cpp + │   ├── thread + │   │   ├── sync.cpp + │   │   ├── thd.asm + │   │   └── thd.cpp + │   └── util + │   ├── bitmap.cpp + │   ├── format.cpp + │   └── tag_list.cpp + └── user + ├── io + │   ├── file + │   │   ├── dir.cpp + │   │   └── file.cpp + │   └── video + │   └── console.cpp + ├── memory + │   └── pool.cpp + └── process + └── proc.cpp +``` + ## License Distributed under the *MIT License*. See `LICENSE` for more information. \ No newline at end of file diff --git a/include/kernel/debug/assert.h b/include/kernel/debug/assert.h index dd5dab97..ed27df89 100644 --- a/include/kernel/debug/assert.h +++ b/include/kernel/debug/assert.h @@ -1,5 +1,9 @@ /** - * Diagnostics tools. + * @file assert.h + * @brief * Diagnostics tools. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/descriptor/desc.h b/include/kernel/descriptor/desc.h index fac29241..bd30836f 100644 --- a/include/kernel/descriptor/desc.h +++ b/include/kernel/descriptor/desc.h @@ -1,5 +1,9 @@ /** - * Descriptors. + * @file desc.h + * @brief Descriptors. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -62,7 +66,9 @@ enum class NonSysType { }; /** - * The descriptor attribute. + * @brief The descriptor attribute. + * + * @details * It is located in the bits `40`-`47` of a descriptor. */ class Attribute { @@ -240,7 +246,9 @@ class Descriptor { static_assert(sizeof(Descriptor) == sizeof(stl::uint64_t)); /** - * The gate descriptor. + * @brief The gate descriptor. + * + * @details * There are four types of gate descriptors: * - The task gate descriptor. * - The call gate descriptor. @@ -309,13 +317,13 @@ class GateDesc : public Descriptor { static_assert(sizeof(GateDesc) == sizeof(stl::uint64_t)); /** - * @brief - * The segment descriptor. + * @brief The segment descriptor. + * + * @details * It is a part of memory segmentation, used for translating a logical address into a linear address. * It describes the memory segment referred to in the logical address. * - * @details - * ``` + * @code * --------------------------------------------- High 32 bits --------------------------------------------- * 31-24 23 22 21 20 19-16 15 14-13 12 11-8 7-0 * ┌────────────┬───┬─────┬───┬─────┬─────────────┬───┬─────┬───┬──────┬────────────┐ @@ -338,7 +346,7 @@ static_assert(sizeof(GateDesc) == sizeof(stl::uint64_t)); * ┌───────────┬────────────┐ * │ Base 15-0 │ Limit 15-0 │ * └───────────┴────────────┘ - * ``` + * @endcode */ class SegDesc : public Descriptor { public: @@ -435,7 +443,9 @@ static_assert(sizeof(SegDesc) == sizeof(stl::uint64_t)); #pragma pack(push, 1) /** - * The descriptor table register. + * @brief The descriptor table register. + * + * @details * They store the location of a descriptor table. */ class DescTabReg { @@ -505,9 +515,7 @@ class DescTab { virtual const T& GetDesc(stl::size_t) const noexcept = 0; }; -/** - * The descriptor table that refers to a contiguous sequence of descriptors. - */ +//! The descriptor table that refers to a contiguous sequence of descriptors. template class DescTabSpan : public DescTab { public: @@ -531,9 +539,7 @@ class DescTabSpan : public DescTab { T* descs_; }; -/** - * The descriptor table that uses a built-in array to store descriptors. - */ +//! The descriptor table that uses a built-in array to store descriptors. template class DescTabArray : public DescTab { public: diff --git a/include/kernel/descriptor/gdt/idx.h b/include/kernel/descriptor/gdt/idx.h index af24bc0e..b18d0d3a 100644 --- a/include/kernel/descriptor/gdt/idx.h +++ b/include/kernel/descriptor/gdt/idx.h @@ -1,5 +1,9 @@ /** - * Global descriptor indexes. + * @file idx.h + * @brief Global descriptor indexes. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/descriptor/gdt/tab.h b/include/kernel/descriptor/gdt/tab.h index c232cdb7..7e546341 100644 --- a/include/kernel/descriptor/gdt/tab.h +++ b/include/kernel/descriptor/gdt/tab.h @@ -1,5 +1,9 @@ /** - * The global descriptor table. + * @file tab.h + * @brief The global descriptor table. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/interrupt/intr.h b/include/kernel/interrupt/intr.h index bf34c403..ca87fcda 100644 --- a/include/kernel/interrupt/intr.h +++ b/include/kernel/interrupt/intr.h @@ -1,5 +1,9 @@ /** - * The interrupt. + * @file intr.h + * @brief The interrupt. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -38,9 +42,7 @@ enum class Intr { SysCall = count - 1 }; -/** - * The interrupt descriptor table. - */ +//! The interrupt descriptor table. template class IntrDescTab : public desc::DescTabArray { public: @@ -59,7 +61,9 @@ class IntrDescTab : public desc::DescTabArray { using Handler = void (*)(stl::size_t) noexcept; /** - * The interrupt handler table. + * @brief The interrupt handler table. + * + * @details * It can be regarded as a manager for an array of function pointers. */ template @@ -137,7 +141,7 @@ class IntrHandlerTab { }; /** - * The interrupt stack. + * @brief The interrupt stack. * * @details * When an interrupt occurs, these values are pushed onto the stack. @@ -164,6 +168,7 @@ struct IntrStack { /* These values are automatically pushed by the CPU */ /** + * @details * Some interrupts do not have an error code. * To simplify the code, we push a zero when those interrupts occur. */ @@ -190,7 +195,9 @@ bool IsIntrEnabled() noexcept; void InitIntr() noexcept; /** - * The interrupt guard. + * @brief The interrupt guard. + * + * @details * It provides a convenient RAII-style mechanism for disabling interrupts for the duration of a scoped block. */ class IntrGuard { @@ -206,7 +213,9 @@ class IntrGuard { }; /** - * The default interrupt handler. + * @brief The default interrupt handler. + * + * @details * It prints interrupt information and pauses the system. */ void DefaultIntrHandler(stl::size_t intr_num) noexcept; diff --git a/include/kernel/interrupt/pic.h b/include/kernel/interrupt/pic.h index 39a44dd2..7fb4c30a 100644 --- a/include/kernel/interrupt/pic.h +++ b/include/kernel/interrupt/pic.h @@ -1,5 +1,9 @@ /** - * *Intel 8259A* Programmable Interrupt Controller. + * @file pic.h + * @brief *Intel 8259A* Programmable Interrupt Controller. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/io/disk/disk.h b/include/kernel/io/disk/disk.h index dacd6577..e725d2a7 100644 --- a/include/kernel/io/disk/disk.h +++ b/include/kernel/io/disk/disk.h @@ -1,5 +1,9 @@ /** - * The disk. + * @file disk.h + * @brief The disk. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -37,9 +41,7 @@ class Disk { //! The maximum LBA. static constexpr stl::size_t max_lba {max_size / sector_size - 1}; - /** - * The partition. - */ + //! The partition. class Part { friend class Disk; @@ -78,9 +80,7 @@ class Disk { Disk* disk_ {nullptr}; }; - /** - * The file partition. - */ + //! The file partition. class FilePart : public Part { public: static FilePart& GetByTag(const TagList::Tag&) noexcept; @@ -149,9 +149,7 @@ class Disk { Block, }; - /** - * The track record of a path search. - */ + //! The track record of a path search. struct PathSearchRecord { //! The path already found. Path searched; @@ -319,9 +317,7 @@ class Disk { mutable TagList open_inodes_; }; - /** - * Disk information. - */ + //! Disk information. class Info { public: //! Initialize disk information based on the data returned by identify commands. @@ -345,9 +341,7 @@ class Disk { using PrimaryParts = stl::array; using LogicParts = stl::array; - /** - * Disk commands. - */ + //! Disk commands. enum class Cmd { //! Read data. Read = 0x20, @@ -448,7 +442,8 @@ class Disk { * 2. The LBA of the next current logical partition. * 3. N/A. * 4. N/A. - * ``` + * + * @code * Disk * ┌───────────────────┐ * │ MBR │ @@ -482,7 +477,7 @@ class Disk { * │ ├ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┤ │ │ Logical Partition * │ │ Data │ │ │ * ▼ └───────────────────┘ ▼ ▼ - * ``` + * @endcode * * @param lba The LBA of a boot record. * @param new_disk Whether a new disk is being scanned. diff --git a/include/kernel/io/disk/file/dir.h b/include/kernel/io/disk/file/dir.h index 8ce43969..91946303 100644 --- a/include/kernel/io/disk/file/dir.h +++ b/include/kernel/io/disk/file/dir.h @@ -1,5 +1,9 @@ /** - * Underlying directory storage. + * @file dir.h + * @brief Underlying directory storage. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -40,7 +44,9 @@ struct Directory { void Rewind() noexcept; /** - * The index node for directory entry storage. + * @brief The index node for directory entry storage. + * + * @details * It is @p nullptr when the directory is not open. */ IdxNode* inode {nullptr}; @@ -60,7 +66,8 @@ enum class FileType { Unknown, Regular, Directory }; * * Index nodes @p IdxNode do not indicate their data type. * Instead, we use directory entries to determine whether an item is a file or a directory. - * ``` + * + * @code * Root Directory * ┌──────────────────┬──────────────────┐ * │ │ Name: "file" │ @@ -96,7 +103,7 @@ enum class FileType { Unknown, Regular, Directory }; * ┌────────────────┐ ┌─────────────┐ * │ Index Node (3) │ ──► │ "file" Data │ * └────────────────┘ └─────────────┘ - * ``` + * @endcode */ struct DirEntry { DirEntry() noexcept = default; diff --git a/include/kernel/io/disk/file/file.h b/include/kernel/io/disk/file/file.h index 114bd1a3..46c746a2 100644 --- a/include/kernel/io/disk/file/file.h +++ b/include/kernel/io/disk/file/file.h @@ -1,5 +1,9 @@ /** - * Underlying file storage. + * @file file.h + * @brief Underlying file storage. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/io/disk/file/inode.h b/include/kernel/io/disk/file/inode.h index ccdd2852..9b4f91da 100644 --- a/include/kernel/io/disk/file/inode.h +++ b/include/kernel/io/disk/file/inode.h @@ -1,5 +1,9 @@ /** - * The index node. + * @file inode.h + * @brief The index node. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -20,7 +24,8 @@ namespace io::fs { * In our system, an index node has 12 direct blocks and a single indirect block table. * The size of a single indirect block table is one sector, so it can save 128 block addresses. * Totally, an index node has up to 140 blocks for data storage. - * ``` + * + * @code * Index Node * ┌────────────┬───────────────┬───────────────────────┐ * │ Attributes │ Direct Blocks │ Single Indirect Block │ @@ -36,7 +41,7 @@ namespace io::fs { * ┌───────┐ ┌───────┐ * │ Block │ │ Block │ * └───────┘ └───────┘ - * ``` + * @endcode * * Index nodes do not indicate their data type. * Instead, we use directory entries @p DirEntry to determine whether an item is a file or a directory. @@ -81,7 +86,9 @@ struct IdxNode { stl::size_t idx {npos}; /** - * The data size. + * @brief The data size. + * + * @details * - If the index node refers to a file, it is the size of the file. * - If the index node refers to a directory, it is the total size of all entries in the directory. */ @@ -98,7 +105,9 @@ struct IdxNode { stl::array direct_lbas_; /** - * The LBA of the single indirect block table. + * @brief The LBA of the single indirect block table. + * + * @details * Each entry in the single indirect block table is a block's LBA. */ stl::size_t indirect_tab_lba_; diff --git a/include/kernel/io/disk/file/super_block.h b/include/kernel/io/disk/file/super_block.h index 3a219274..7d9d8088 100644 --- a/include/kernel/io/disk/file/super_block.h +++ b/include/kernel/io/disk/file/super_block.h @@ -1,5 +1,9 @@ /** - * The super block. + * @file super_block.h + * @brief The super block. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -17,7 +21,8 @@ namespace io::fs { * @details * The super block is 4096 bytes in size and starts at offset @p 4096 bytes in a partition, behind the boot sector. * It maintains information about the entire file system. - * ``` + * + * @code * Disk * ┌─────┬───────────┬─────┬───────────┐ * │ MBR │ Partition │ ... │ Partition │ @@ -28,7 +33,7 @@ namespace io::fs { * ┌─────────────┬─────────────┬──────────────┬───────────────────┬─────────────┬────────────────┬────────┐ * │ Boot Sector │ Super Block │ Block Bitmap │ Index Node Bitmap │ Index Nodes │ Root Directory │ Blocks │ * └─────────────┴─────────────┴──────────────┴───────────────────┴─────────────┴────────────────┴────────┘ - * ``` + * @endcode */ struct SuperBlock { private: @@ -77,9 +82,7 @@ struct SuperBlock { stl::size_t root_inode_idx; }; -/** - * The 4096-byte padded super block. - */ +//! The 4096-byte padded super block. class PaddedSuperBlock : public SuperBlock { public: /** @@ -109,6 +112,7 @@ class PaddedSuperBlock : public SuperBlock { PaddedSuperBlock& WriteRootDirNode(Disk& disk, void* io_buf, stl::size_t io_buf_size) noexcept; /** + * @details * Write the entries in the root directory to a disk, including: * - The current directory. * - The parent directory. diff --git a/include/kernel/io/disk/ide.h b/include/kernel/io/disk/ide.h index 717e5ae1..48c7e7bc 100644 --- a/include/kernel/io/disk/ide.h +++ b/include/kernel/io/disk/ide.h @@ -1,5 +1,9 @@ /** - * The IDE channel. + * @file ide.h + * @brief The IDE channel. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -10,9 +14,7 @@ namespace io { -/** - * The IDE channel. - */ +//! The IDE channel. class IdeChnl { public: //! A machine usually has two channels: primary and secondary channels. @@ -123,7 +125,10 @@ class IdeChnl { Disks disks_; /** + * @brief * Whether the channel is waiting for an interrupt. + * + * @details * If an operation is submitted to the disk, we need to wait for an interrupt. */ mutable bool waiting_intr_ {false}; diff --git a/include/kernel/io/file/dir.h b/include/kernel/io/file/dir.h index 7b24725e..583a51f8 100644 --- a/include/kernel/io/file/dir.h +++ b/include/kernel/io/file/dir.h @@ -1,5 +1,9 @@ /** - * Directory management. + * @file dir.h + * @brief Directory management. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -8,9 +12,7 @@ namespace io { -/** - * The wrapper for directory functions of @p Disk::FilePart. - */ +//! The wrapper for directory functions of @p Disk::FilePart. class Directory { public: //! Create a directory. diff --git a/include/kernel/io/file/file.h b/include/kernel/io/file/file.h index fc733d82..50c68a59 100644 --- a/include/kernel/io/file/file.h +++ b/include/kernel/io/file/file.h @@ -1,5 +1,9 @@ /** - * File management. + * @file file.h + * @brief File management. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -10,9 +14,7 @@ namespace io { -/** - * The file descriptor. - */ +//! The file descriptor. class FileDesc { public: constexpr FileDesc(const stl::size_t desc = npos) noexcept : desc_ {desc} {} @@ -36,9 +38,7 @@ class FileDesc { stl::size_t desc_; }; -/** - * The wrapper for file functions of @p Disk::FilePart. - */ +//! The wrapper for file functions of @p Disk::FilePart. class File { public: enum class OpenMode { ReadOnly = 0, WriteOnly = 1, ReadWrite = 2, CreateNew = 4 }; diff --git a/include/kernel/io/file/path.h b/include/kernel/io/file/path.h index 63f4409a..39fb94e1 100644 --- a/include/kernel/io/file/path.h +++ b/include/kernel/io/file/path.h @@ -1,5 +1,9 @@ /** - * File path operations. + * @file path.h + * @brief File path operations. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -38,11 +42,11 @@ class Path { * @brief Get the depth of a path. * * @details - * ```c++ + * @code {.cpp} * Path::GetDepth("/") == 0; * Path::GetDepth("/a") == 1; * Path::GetDepth("/a/b") == 2; - * ``` + * @endcode */ static stl::size_t GetDepth(stl::string_view) noexcept; @@ -50,11 +54,11 @@ class Path { * @brief Get the file name of a path. * * @details - * ```c++ + * @code {.cpp} * Path::GetFileName("/") == ""; * Path::GetFileName("/a") == "a"; * Path::GetFileName("/a/") == ""; - * ``` + * @endcode */ static stl::string_view GetFileName(stl::string_view) noexcept; diff --git a/include/kernel/io/io.h b/include/kernel/io/io.h index de2a1ce2..90fddda8 100644 --- a/include/kernel/io/io.h +++ b/include/kernel/io/io.h @@ -1,5 +1,9 @@ /** - * Port I/O and register control. + * @file io.h + * @brief Port I/O and register control. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -9,9 +13,7 @@ namespace io { -/** - * The @p EFLAGS register. - */ +//! The @p EFLAGS register. class EFlags { public: static EFlags Get() noexcept; diff --git a/include/kernel/io/keyboard.h b/include/kernel/io/keyboard.h index 3a1b8e8c..2cc2bc2a 100644 --- a/include/kernel/io/keyboard.h +++ b/include/kernel/io/keyboard.h @@ -1,5 +1,9 @@ /** - * The *Intel 8042* keyboard controller. + * @file keyboard.h + * @brief The *Intel 8042* keyboard controller. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/io/timer.h b/include/kernel/io/timer.h index 7daff5f5..d3097466 100644 --- a/include/kernel/io/timer.h +++ b/include/kernel/io/timer.h @@ -1,5 +1,9 @@ /** - * *Intel 8253* Programmable Interval Timer. + * @file timer.h + * @brief *Intel 8253* Programmable Interval Timer. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/io/video/console.h b/include/kernel/io/video/console.h index 2329c833..627ae4bb 100644 --- a/include/kernel/io/video/console.h +++ b/include/kernel/io/video/console.h @@ -1,5 +1,9 @@ /** - * The thread-safe text console. + * @file console.h + * @brief The thread-safe text console. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/io/video/print.h b/include/kernel/io/video/print.h index 9ec8f17a..96ecc463 100644 --- a/include/kernel/io/video/print.h +++ b/include/kernel/io/video/print.h @@ -1,5 +1,9 @@ /** - * Text printing. + * @file print.h + * @brief Text printing. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/krnl.h b/include/kernel/krnl.h index 46ac0591..c0c94134 100644 --- a/include/kernel/krnl.h +++ b/include/kernel/krnl.h @@ -1,5 +1,9 @@ /** - * Basic kernel configurations. + * @file krnl.h + * @brief Basic kernel configurations. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/memory/page.h b/include/kernel/memory/page.h index d7bd0128..5e06dce6 100644 --- a/include/kernel/memory/page.h +++ b/include/kernel/memory/page.h @@ -1,5 +1,9 @@ /** - * Memory paging. + * @file page.h + * @brief Memory paging. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -36,7 +40,8 @@ constexpr stl::size_t CalcPageCount(const stl::size_t size) noexcept { * Memory paging is based on memory segmentation, it translates the linear address obtained from segmentation into a physical address. * In the page directory, each entry points to a page table. * In the page table, each entry points to a 4 KB physical page frame. - * ``` + * + * @code * ----------------------------------------------------------------------------------------- * 31-12 11-9 8 7 6 5 4 3 2 1 0 * ┌────────────┬─────┬───┬───┬───┬───┬─────┬─────┬─────┬───┬───┐ @@ -50,10 +55,11 @@ constexpr stl::size_t CalcPageCount(const stl::size_t size) noexcept { * │ │ └─ 1: The page has been accessed. * │ └─ 1: The page is dirty (modified). * └─ 1: The page is global. - * ``` + * @endcode * * In @p src/boot/loader.asm, the page directory table is initialized as follows: - * ``` + * + * @code * ┌─────────────────────────┐ * │ ... │ * ├─────────────────────────┤ @@ -75,7 +81,7 @@ constexpr stl::size_t CalcPageCount(const stl::size_t size) noexcept { * │ ├─────────────────────────┤ * └─► │ Kernel │ * └─────────────────────────┘ - * ``` + * @endcode */ class PageEntry { public: @@ -173,7 +179,7 @@ static_assert(sizeof(PageEntry) == sizeof(stl::uint32_t)); * @brief The virtual address. * * @details - * ``` + * @code * ----------------------------------------------- * 31-22 21-12 11-0 * │ PDE │ PTE │ Offset | @@ -182,7 +188,7 @@ static_assert(sizeof(PageEntry) == sizeof(stl::uint32_t)); * │ └─ The index of the page table entry. * └─ The index of the page directory entry. * ----------------------------------------------- - * ``` + * @endcode */ class VrAddr { public: diff --git a/include/kernel/memory/pool.h b/include/kernel/memory/pool.h index 421893c4..f448b483 100644 --- a/include/kernel/memory/pool.h +++ b/include/kernel/memory/pool.h @@ -1,5 +1,9 @@ /** - * Memory management. + * @file pool.h + * @brief Memory management. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -123,7 +127,8 @@ class PhyMemPagePool { * @details * A memory block descriptor manages fix-sized block @p MemBlock arranged in memory arenas @p MemArena. * A user process has multiple memory block descriptors for heap memory allocations of different sizes. - * ``` + * + * @code * Arena Arena * ┌────────────┐ ┌────────────┐ * │ Descriptor │ ──────┬─── │ Descriptor │ @@ -143,7 +148,7 @@ class PhyMemPagePool { * ├─────────────┤ * │ Size │ * └─────────────┘ - * ``` + * @endcode */ class MemBlockDesc { public: diff --git a/include/kernel/process/proc.h b/include/kernel/process/proc.h index 0633c3a7..509a27d8 100644 --- a/include/kernel/process/proc.h +++ b/include/kernel/process/proc.h @@ -1,5 +1,9 @@ /** - * User process management. + * @file proc.h + * @brief User process management. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -11,9 +15,7 @@ namespace tsk { -/** - * The user process. - */ +//! The user process. class Process { public: //! The priority of the main thread. @@ -108,6 +110,7 @@ class Process { Process& CopyMemTo(Process&, void* buf, stl::size_t buf_size) noexcept; /** + * @details * Each process has its own virtual address space. * Different virtual address pools allow processes to use the same virtual address, * but mapped to various physical addresses with the help of page directory tables. @@ -117,6 +120,7 @@ class Process { mem::MemBlockDescTab mem_block_descs_; /** + * @details * Each process has its own page directory table. * Different page directory tables map the same virtual address in different processes to various physical addresses. */ diff --git a/include/kernel/process/tss.h b/include/kernel/process/tss.h index 10645c7e..c7c1e853 100644 --- a/include/kernel/process/tss.h +++ b/include/kernel/process/tss.h @@ -1,5 +1,9 @@ /** - * The task state segment. + * @file tss.h + * @brief The task state segment. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -61,7 +65,9 @@ struct TaskStateSeg { void InitTaskStateSeg() noexcept; /** - * Get the task state segment. + * @brief Get the task state segment. + * + * @details * It is shared by all tasks. */ TaskStateSeg& GetTaskStateSeg() noexcept; diff --git a/include/kernel/selector/sel.h b/include/kernel/selector/sel.h index d5a4419c..6fe9a06f 100644 --- a/include/kernel/selector/sel.h +++ b/include/kernel/selector/sel.h @@ -1,5 +1,9 @@ /** - * Segment selectors. + * @file sel.h + * @brief Segment selectors. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -19,12 +23,12 @@ enum class DescTabType { }; /** - * @brief - * The segment selector. - * It can identify a descriptor in a descriptor table. + * @brief The segment selector. * * @details - * ``` + * It can identify a descriptor in a descriptor table. + * + * @code * 15-3 2 1-0 * ┌───────┬────┬─────┐ * │ Index │ TI │ RPL │ @@ -32,7 +36,7 @@ enum class DescTabType { * ▲ * └─ 0: The index is for the global descriptor table. * 1: The index is for a local descriptor table. - * ``` + * @endcode */ class Selector { public: diff --git a/include/kernel/syscall/call.h b/include/kernel/syscall/call.h index aad6e426..3a749cf7 100644 --- a/include/kernel/syscall/call.h +++ b/include/kernel/syscall/call.h @@ -1,5 +1,9 @@ /** - * System calls. + * @file call.h + * @brief System calls. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -15,7 +19,9 @@ inline constexpr stl::size_t count {0x60}; using Handler = stl::int32_t (*)(void*) noexcept; /** - * Types of system calls. + * @brief Types of system calls. + * + * @details * Each type corresponds to a kernel function. */ enum class SysCallType { @@ -36,7 +42,9 @@ enum class SysCallType { }; /** - * The system call handler table. + * @brief The system call handler table. + * + * @details * It can be regarded as a manager for an array of function pointers. */ template diff --git a/include/kernel/thread/sync.h b/include/kernel/thread/sync.h index 2cac2815..d4fb009f 100644 --- a/include/kernel/thread/sync.h +++ b/include/kernel/thread/sync.h @@ -1,5 +1,9 @@ /** - * Multi-threading synchronization. + * @file sync.h + * @brief Multi-threading synchronization. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/thread/thd.h b/include/kernel/thread/thd.h index b922acc4..9891e014 100644 --- a/include/kernel/thread/thd.h +++ b/include/kernel/thread/thd.h @@ -1,5 +1,9 @@ /** - * Thread management. + * @file thd.h + * @brief Thread management. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -22,7 +26,9 @@ class Process; inline constexpr stl::size_t max_open_file_count {8}; /** - * Utilities for manipulating the file descriptor table of the current process. + * @brief Utilities for manipulating the file descriptor table of the current process. + * + * @details * They are wrappers for @p FileDescTab. */ class ProcFileDescTab { @@ -146,7 +152,8 @@ class FileDescTab { * @details * Here is the memory layout of a thread block and its stack. * The total size is one memory page. - * ``` + * + * @code * 0xFFF ┌─────────────────┐ `GetKrnlStackBottom` * │ Interrupt Stack │ * ├─────────────────┤ `GetIntrStack` @@ -161,7 +168,7 @@ class FileDescTab { * ├─────────────────┤ * │ Control Block │ * 0x000 └─────────────────┘ `this` - * ``` + * @endcode * * @warning * The compiler might allocate more memory for the control block in a thread, especially with debug options. @@ -206,7 +213,9 @@ class Thread { Process* GetProcess() const noexcept; /** - * Get the bottom address of the kernel thread stack. + * @brief Get the bottom address of the kernel thread stack. + * + * @details * When switching threads, its value corresponds to @p ESP0 of a task state segment. */ stl::uintptr_t GetKrnlStackBottom() const noexcept; @@ -233,16 +242,19 @@ class Thread { void Sleep(stl::size_t milliseconds) noexcept; /** - * Temporarily remove the thread from the CPU and schedule another thread to run. + * @brief Temporarily remove the thread from the CPU and schedule another thread to run. + * + * @details * The removed thread is marked as ready to run and its remaining tick will not be reset. */ void Yield() noexcept; /** - * Remove the thread from the CPU and schedule another thread to run. - * If the removed thread is running, its remaining tick will be reset and it is marked as ready to run. + * @brief Remove the thread from the CPU and schedule another thread to run. * * @details + * If the removed thread is running, its remaining tick will be reset and it is marked as ready to run. + * * The scheduler uses the basic First-In-First-Out algorithm. * The thread priority only represents the maximum number of time slices a thread can run in the CPU at a time. * High-priority threads cannot directly preempt running low-priority threads. @@ -250,6 +262,7 @@ class Thread { void Schedule() noexcept; /** + * @details * Whether the stack guard is valid. * It should be called before manipulating a thread to ensure that the control block is still valid. */ @@ -311,6 +324,7 @@ class Thread { */ struct StartupStack : public SwitchStack { /** + * @details * When @p StartupCallback is called, it assumes that the stack top is a return address. * We have to skip this place. */ @@ -326,6 +340,7 @@ class Thread { //! We use two tags to manage a thread in different lists. struct Tags { /** + * @details * The tag for other lists, for example: * - The list for ready threads. * - The list for waiting threads. @@ -339,12 +354,14 @@ class Thread { static Thread& GetByTag(const TagList::Tag&, TagType) noexcept; /** + * @details * Initialize a thread control block and add the thread to the all-thread list. * Currently it is not ready to be scheduled. */ Thread& Init(stl::string_view name, stl::size_t priority, Process* proc = nullptr) noexcept; /** + * @details * Set a thread callback and add the thread to the ready list. * Now it can be scheduled and run. */ @@ -366,6 +383,7 @@ class Thread { StartupStack& GetStartupStack() noexcept; /** + * @details * Load the thread environment, including: * - The page directory table. * - The task state segment. @@ -402,6 +420,7 @@ class Thread { stl::size_t priority_ {0}; /** + * @details * The number of remaining ticks the thread can run in the CPU at this time. * When time slices run out, the thread is removed from the CPU and waits to be scheduled again. */ @@ -418,7 +437,9 @@ class Thread { }; /** - * The kernel thread. + * @brief The kernel thread. + * + * @details * They are created by the kernel and do not have a parent process. */ class KrnlThread : public Thread { diff --git a/include/kernel/util/bit.h b/include/kernel/util/bit.h index bd33cbeb..1f173730 100644 --- a/include/kernel/util/bit.h +++ b/include/kernel/util/bit.h @@ -1,5 +1,9 @@ /** - * The bit manipulation. + * @file bit.h + * @brief The bit manipulation. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/util/bitmap.h b/include/kernel/util/bitmap.h index 9ef5820a..e612808c 100644 --- a/include/kernel/util/bitmap.h +++ b/include/kernel/util/bitmap.h @@ -1,5 +1,9 @@ /** - * The bitmap. + * @file bitmap.h + * @brief The bitmap. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/util/block_queue.h b/include/kernel/util/block_queue.h index 80c643da..c087342d 100644 --- a/include/kernel/util/block_queue.h +++ b/include/kernel/util/block_queue.h @@ -1,5 +1,9 @@ /** - * The block queue. + * @file block_queue.h + * @brief The block queue. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -45,7 +49,9 @@ class BlockQueue { } /** - * Push an object into the queue. + * @brief Push an object into the queue. + * + * @details * If the queue is full, the current thread will be blocked. * When another consumer thread pops elements, the blocked thread will be resumed. */ @@ -69,7 +75,9 @@ class BlockQueue { } /** - * Push an object into the queue. + * @brief Push an object into the queue. + * + * @details * If the queue is empty, the current thread will be blocked. * When another producer thread pushes elements, the blocked thread will be resumed. */ diff --git a/include/kernel/util/format.h b/include/kernel/util/format.h index a814ec0e..b85f1ed8 100644 --- a/include/kernel/util/format.h +++ b/include/kernel/util/format.h @@ -1,5 +1,9 @@ /** - * String formatting. + * @file format.h + * @brief String formatting. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once diff --git a/include/kernel/util/metric.h b/include/kernel/util/metric.h index 1837b09f..022be6a4 100644 --- a/include/kernel/util/metric.h +++ b/include/kernel/util/metric.h @@ -1,3 +1,11 @@ +/** + * @file metric.h + * @brief Metrics. + * + * @par GitHub + * https://github.com/Zhuagenborn + */ + #pragma once #include "kernel/stl/cstdint.h" diff --git a/include/kernel/util/tag_list.h b/include/kernel/util/tag_list.h index 6911a152..ce92a805 100644 --- a/include/kernel/util/tag_list.h +++ b/include/kernel/util/tag_list.h @@ -1,5 +1,9 @@ /** - * The tag list. + * @file tag_list.h + * @brief The tag list. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -9,17 +13,18 @@ /** * @brief * The doubly linked tag list. - * It connects a number of tags. Each tag is a member of an object. * * @details - * ``` + * It connects a number of tags. Each tag is a member of an object. + * + * @code * Object Object * Head ┌───────┐ ┌───────┐ Tail * ┌───┐ ───► │ ┌───┐ │ ───► │ ┌───┐ │ ───► ┌───┐ * │Tag│ │ │Tag│ │ │ │Tag│ │ │Tag│ * └───┘ ◄─── │ └───┘ │ ◄─── │ └───┘ │ ◄─── └───┘ * └───────┘ └───────┘ - * ``` + * @endcode */ class TagList { public: diff --git a/include/user/io/file/dir.h b/include/user/io/file/dir.h index 82cf61fa..12de8720 100644 --- a/include/user/io/file/dir.h +++ b/include/user/io/file/dir.h @@ -1,11 +1,16 @@ /** - * User-mode directory management. + * @file dir.h + * @brief User-mode directory management. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once namespace usr::io { +//! User-mode directory management. class Directory { public: Directory() = delete; diff --git a/include/user/io/file/file.h b/include/user/io/file/file.h index 3d87cb12..548a441c 100644 --- a/include/user/io/file/file.h +++ b/include/user/io/file/file.h @@ -1,5 +1,9 @@ /** - * User-mode file management. + * @file file.h + * @brief User-mode file management. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -8,6 +12,7 @@ namespace usr::io { +//! User-mode file management. class File { public: File() = delete; diff --git a/include/user/io/video/console.h b/include/user/io/video/console.h index efd359e0..4bb174af 100644 --- a/include/user/io/video/console.h +++ b/include/user/io/video/console.h @@ -1,5 +1,9 @@ /** - * The user-mode thread-safe text console. + * @file console.h + * @brief The user-mode thread-safe text console. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -8,6 +12,7 @@ namespace usr::io { +//! The user-mode thread-safe text console. class Console { public: Console() = delete; diff --git a/include/user/memory/pool.h b/include/user/memory/pool.h index 8008821d..085d749b 100644 --- a/include/user/memory/pool.h +++ b/include/user/memory/pool.h @@ -1,5 +1,9 @@ /** - * User-mode memory management. + * @file pool.h + * @brief User-mode memory management. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -8,8 +12,10 @@ namespace usr::mem { +//! Allocate virtual memory in bytes in user mode. void* Allocate(stl::size_t size) noexcept; +//! Free virtual memory in user mode. void Free(void* base) noexcept; } \ No newline at end of file diff --git a/include/user/process/proc.h b/include/user/process/proc.h index 554fcbc4..2329c03f 100644 --- a/include/user/process/proc.h +++ b/include/user/process/proc.h @@ -1,5 +1,9 @@ /** - * User-mode process management. + * @file proc.h + * @brief User-mode process management. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -8,6 +12,7 @@ namespace usr::tsk { +//! User-mode process management. class Process { public: Process() = delete; diff --git a/include/user/syscall/call.h b/include/user/syscall/call.h index b091c8de..635f3374 100644 --- a/include/user/syscall/call.h +++ b/include/user/syscall/call.h @@ -1,5 +1,9 @@ /** - * User-mode system calls. + * @file call.h + * @brief User-mode system calls. + * + * @par GitHub + * https://github.com/Zhuagenborn */ #pragma once @@ -9,7 +13,7 @@ namespace usr::sc { /** - * Types of system calls. + * @brief Types of system calls. * * @warning * Their order must be the same as @p sc::SysCallType. @@ -32,6 +36,7 @@ enum class SysCallType { }; extern "C" { + /** * @brief Call a kernel method by a system call in user mode. * diff --git a/src/kernel/interrupt/intr.cpp b/src/kernel/interrupt/intr.cpp index 3211158b..3df46b89 100644 --- a/src/kernel/interrupt/intr.cpp +++ b/src/kernel/interrupt/intr.cpp @@ -21,11 +21,10 @@ namespace { extern "C" { /** - * @brief - * The entry points of interrupts, defined in @p src/interrupt/intr.asm. - * They will be registered in the interrupt descriptor table. + * @brief The entry points of interrupts, defined in @p src/interrupt/intr.asm. * * @details + * They will be registered in the interrupt descriptor table. * When an interrupt @p i occurs: * 1. The CPU jumps to the entry point @p intr_entries[i]. * 2. After saving registers, @p intr_entries[i] calls the interrupt handler @p intr_handlers[i]. diff --git a/src/kernel/interrupt/pic.cpp b/src/kernel/interrupt/pic.cpp index 4c71ed13..1157da03 100644 --- a/src/kernel/interrupt/pic.cpp +++ b/src/kernel/interrupt/pic.cpp @@ -60,9 +60,7 @@ class CmdWord { static_assert(sizeof(CmdWord) == sizeof(stl::uint8_t)); -/** - * Initialization Command Word 1. - */ +//! Initialization Command Word 1. class InitCmdWord1 : public CmdWord { public: constexpr InitCmdWord1(const stl::uint8_t val = 0) noexcept : CmdWord {val} { @@ -107,9 +105,7 @@ class InitCmdWord1 : public CmdWord { static constexpr stl::size_t ltim_pos {3}; }; -/** - * Initialization Command Word 2. - */ +//! Initialization Command Word 2. class InitCmdWord2 : public CmdWord { public: using CmdWord::CmdWord; @@ -127,9 +123,7 @@ class InitCmdWord2 : public CmdWord { static constexpr stl::size_t id_len {3}; }; -/** - * Initialization Command Word 3 for the master *Intel 8259A* chip. - */ +//! Initialization Command Word 3 for the master *Intel 8259A* chip. class MasterInitCmdWord3 : public CmdWord { public: using CmdWord::CmdWord; @@ -142,9 +136,7 @@ class MasterInitCmdWord3 : public CmdWord { } }; -/** - * Initialization Command Word 3 for the slave *Intel 8259A* chip. - */ +//! Initialization Command Word 3 for the slave *Intel 8259A* chip. class SlaveInitCmdWord3 : public CmdWord { public: using CmdWord::CmdWord; @@ -157,9 +149,7 @@ class SlaveInitCmdWord3 : public CmdWord { } }; -/** - * Initialization Command Word 4. - */ +//! Initialization Command Word 4. class InitCmdWord4 : public CmdWord { public: using CmdWord::CmdWord; @@ -197,9 +187,7 @@ class InitCmdWord4 : public CmdWord { static constexpr stl::size_t aeoi_pos {x86_pos + 1}; }; -/** - * Operation Command Word 1. - */ +//! Operation Command Word 1. class OpCmdWord1 : public CmdWord { public: using CmdWord::CmdWord; diff --git a/src/kernel/io/disk/disk.cpp b/src/kernel/io/disk/disk.cpp index fb37fa05..4ad96cd5 100644 --- a/src/kernel/io/disk/disk.cpp +++ b/src/kernel/io/disk/disk.cpp @@ -63,9 +63,7 @@ void DiskIntrHandler(const stl::size_t intr_num) noexcept { #pragma pack(push, 1) -/** - * The partition table entry. - */ +//! The partition table entry. struct PartTabEntry { //! Whether the partition is the system boot partition. bool is_bootable; @@ -126,9 +124,7 @@ static_assert(sizeof(BootRecord) == Disk::sector_size); #pragma pack(pop) -/** - * The 8-bit I/O register. - */ +//! The 8-bit I/O register. class Register { public: constexpr Register(const stl::uint8_t val = 0) noexcept : val_ {val} {} @@ -143,9 +139,7 @@ class Register { static_assert(sizeof(Register) == sizeof(stl::uint8_t)); -/** - * The device register. - */ +//! The device register. class DeviceReg : public Register { public: constexpr DeviceReg(const stl::uint8_t val = 0) noexcept : Register {val} { @@ -208,9 +202,7 @@ class DeviceReg : public Register { } }; -/** - * The status register. - */ +//! The status register. class StatusReg : public Register { public: using Register::Register; @@ -238,9 +230,7 @@ class StatusReg : public Register { static constexpr stl::size_t busy_pos {7}; }; -/** - * The LBA byte register. - */ +//! The LBA byte register. template class LbaReg : public Register { public: @@ -255,25 +245,19 @@ class LbaReg : public Register { ~LbaReg() noexcept = default; }; -/** - * The LBA bits `0`-`7` register. - */ +//! The LBA bits `0`-`7` register. class LbaLowReg : public LbaReg<0> { public: using LbaReg::LbaReg; }; -/** - * The LBA bits `8`-`15` register. - */ +//! The LBA bits `8`-`15` register. class LbaMidReg : public LbaReg { public: using LbaReg::LbaReg; }; -/** - * The LBA bits `16`-`23` register. - */ +//! The LBA bits `16`-`23` register. class LbaHighReg : public LbaReg { public: using LbaReg::LbaReg; diff --git a/src/kernel/io/disk/part.cpp b/src/kernel/io/disk/part.cpp index 91c4057b..2e9eaf74 100644 --- a/src/kernel/io/disk/part.cpp +++ b/src/kernel/io/disk/part.cpp @@ -42,9 +42,7 @@ inline constexpr stl::size_t indirect_sector_count_per_inode { inline constexpr stl::size_t sector_count_per_inode {fs::IdxNode::direct_block_count + indirect_sector_count_per_inode}; -/** - * The position of an index node in a partition. - */ +//! The position of an index node in a partition. struct IdxNodePos { IdxNodePos(const Disk::FilePart& part, const fs::IdxNode& inode) noexcept : IdxNodePos {part, inode.idx} {} diff --git a/src/kernel/io/keyboard.cpp b/src/kernel/io/keyboard.cpp index 17c2a5ba..2b6a1efb 100644 --- a/src/kernel/io/keyboard.cpp +++ b/src/kernel/io/keyboard.cpp @@ -45,9 +45,7 @@ inline constexpr stl::uint8_t caps_lock {0x3A}; } // namespace sc -/** - * The scan code generated by a key when it is pressed or released. - */ +//! The scan code generated by a key when it is pressed or released. class ScanCode { public: constexpr ScanCode(const stl::uint16_t code = 0) noexcept : code_ {code} {} @@ -252,7 +250,9 @@ class KeyHandler { }; /** - * The keyboard interrupt handler. + * @brief The keyboard interrupt handler. + * + * @details * It reads pressed keys and processes them. */ void KeyboardIntrHandler(stl::size_t) noexcept { diff --git a/src/kernel/io/timer.cpp b/src/kernel/io/timer.cpp index 3f5f0e65..1a9cd0f7 100644 --- a/src/kernel/io/timer.cpp +++ b/src/kernel/io/timer.cpp @@ -55,9 +55,7 @@ enum class CountMode { enum class DigitalMode { Binary, BinaryCodedDecimal }; -/** - * The control word. - */ +//! The control word. class CtrlWord { public: constexpr CtrlWord(const stl::uint8_t val = 0) noexcept : val_ {val} {} @@ -128,7 +126,9 @@ void InitCounter(const stl::size_t freq_per_second) noexcept { } /** - * The clock interrupt handler. + * @brief The clock interrupt handler. + * + * @details * It increases ticks and schedules threads. */ void ClockIntrHandler(stl::size_t) noexcept { diff --git a/src/kernel/memory/pool.cpp b/src/kernel/memory/pool.cpp index 4f4f7502..65d0c314 100644 --- a/src/kernel/memory/pool.cpp +++ b/src/kernel/memory/pool.cpp @@ -23,7 +23,10 @@ inline constexpr stl::uintptr_t krnl_heap_base {krnl_base + 0x00100000}; class MemArena; /** + * @brief * The fix-sized memory block arranged in a memory arena @p MemArena. + * + * @details * They are linked together in the free block list of a memory block descriptor @p MemBlockDesc. */ class MemBlock { @@ -55,6 +58,9 @@ class MemBlock { }; /** + * @brief The momory arena. + * + * @details * The momory arena is a memory page containing metadata, * and a number of fix-sized memory blocks @p MemBlock, like a storage. */ @@ -72,6 +78,7 @@ class MemArena { } /** + * @details * If the arena is not a large arena, it refers to the block descriptor, * otherwise @p nullptr. */