diff options
| -rw-r--r-- | kernel/kernel/devices/block_device_utils.hpp | 10 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/devfs/filesystem.hpp | 2 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/devfs/inode.hpp | 23 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/device_inode.hpp | 15 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/ext2/block_group_descriptor.hpp | 4 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/ext2/filesystem.hpp | 129 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/ext2/inode.hpp | 86 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/ext2/linked_directory_entry.hpp | 4 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/ext2/superblock.hpp | 4 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/filesystem.cpp | 2 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/filesystem.hpp | 82 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/mount.hpp | 70 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/mount_table.hpp | 38 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/open_file_descriptor.hpp | 56 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/open_file_table.hpp | 56 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/path.hpp | 57 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/rootfs/inode.hpp | 20 | ||||
| -rw-r--r-- | kernel/kernel/filesystem/vfs.hpp | 110 |
18 files changed, 283 insertions, 485 deletions
diff --git a/kernel/kernel/devices/block_device_utils.hpp b/kernel/kernel/devices/block_device_utils.hpp index 03fee8cc..b9c8c416 100644 --- a/kernel/kernel/devices/block_device_utils.hpp +++ b/kernel/kernel/devices/block_device_utils.hpp @@ -10,18 +10,10 @@ #include <cstddef> #include <span> -/** -@brief Utility functions for block devices, such as reading/writing data at specific offsets. These functions handle -the necessary logic to interact with block devices, such as calculating block boundaries and ensuring proper access -patterns. They abstract away the details of block device interactions, providing a simple interface for reading and -writing data to block devices. -*/ namespace kernel::devices::block_device_utils { - /** - * @brief Information describing the transfer window for one block index. - */ + //! Information describing the transfer window for one block index. struct transfer_info { kstd::bytes offset; diff --git a/kernel/kernel/filesystem/devfs/filesystem.hpp b/kernel/kernel/filesystem/devfs/filesystem.hpp index 3a4e7ec6..50a87de9 100644 --- a/kernel/kernel/filesystem/devfs/filesystem.hpp +++ b/kernel/kernel/filesystem/devfs/filesystem.hpp @@ -31,10 +31,8 @@ namespace kernel::filesystem::devfs kstd::enable_shared_from_this<filesystem>, device_number_registry_observer { - //! @copydoc kernel::filesystem::filesystem::mount auto mount(kstd::shared_ptr<kernel::filesystem::inode> const & backing_inode) -> kstd::result<void> override; - //! @copydoc kernel::filesystem::filesystem::lookup [[nodiscard]] auto lookup(kstd::shared_ptr<kernel::filesystem::inode> const & parent, std::string_view name) const -> kstd::result<kstd::shared_ptr<kernel::filesystem::inode>> override; diff --git a/kernel/kernel/filesystem/devfs/inode.hpp b/kernel/kernel/filesystem/devfs/inode.hpp index d2f5291e..e907c02e 100644 --- a/kernel/kernel/filesystem/devfs/inode.hpp +++ b/kernel/kernel/filesystem/devfs/inode.hpp @@ -11,33 +11,16 @@ namespace kernel::filesystem::devfs { - /** - @brief Inode implementation for the devfs filesystem. - This inode represents root device node in the /dev directory. - */ + //! Inode implementation for the devfs filesystem. + //! + //! This inode represents root device node in the /dev directory. struct inode : kernel::filesystem::inode { - /** - @brief Reads from the devfs directory inode. - @param buffer Destination buffer. - @param offset Read offset in bytes. - @return Number of bytes read (always 0 because this inode does not expose file data). - */ [[nodiscard]] auto read(std::span<std::byte> buffer, kstd::bytes offset) const -> kstd::result<kstd::bytes> override; - /** - @brief Writes to the devfs directory inode. - @param buffer Source buffer. - @param offset Write offset in bytes. - @return Number of bytes written (always 0 because writes are not supported for this inode). - */ auto write(std::span<std::byte const> buffer, kstd::bytes offset) -> kstd::result<kstd::bytes> override; - /** - @brief Check if this inode represents a directory. - @return returns true, since this inode represents the /dev directory in the devfs filesystem. - */ [[nodiscard]] auto is_directory() const -> bool override; }; } // namespace kernel::filesystem::devfs diff --git a/kernel/kernel/filesystem/device_inode.hpp b/kernel/kernel/filesystem/device_inode.hpp index 5c26266e..49b17d89 100644 --- a/kernel/kernel/filesystem/device_inode.hpp +++ b/kernel/kernel/filesystem/device_inode.hpp @@ -60,16 +60,8 @@ namespace kernel::filesystem //! @name Property Queries //! @{ - /** - @brief Check if this inode represents a block device. - @return true iff. the underlying device is a block device, false otherwise. - */ [[nodiscard]] auto is_block_device() const -> bool override; - /** - @brief Check if this inode represents a character device. - @return true iff. the underlying device is a character device, false otherwise. - */ [[nodiscard]] auto is_character_device() const -> bool override; //! @} @@ -86,10 +78,9 @@ namespace kernel::filesystem //! @name Device Access //! @{ - /** - @brief Get the associated device. - @return A reference to the associated device. - */ + //! @brief Get the device, if any, associated with this inode. + //! + //! @return The associated device, of nullptr if no such device exists. [[nodiscard]] auto device() const -> kstd::shared_ptr<kapi::devices::device> const &; //! @} diff --git a/kernel/kernel/filesystem/ext2/block_group_descriptor.hpp b/kernel/kernel/filesystem/ext2/block_group_descriptor.hpp index f7a7ce9e..16f6d6e2 100644 --- a/kernel/kernel/filesystem/ext2/block_group_descriptor.hpp +++ b/kernel/kernel/filesystem/ext2/block_group_descriptor.hpp @@ -6,9 +6,7 @@ namespace kernel::filesystem::ext2 { - /** - @brief Represents a block group descriptor in the ext2 filesystem. - */ + //! A block group descriptor in the ext2 filesystem. struct [[gnu::packed]] block_group_descriptor { uint32_t block_bitmap; diff --git a/kernel/kernel/filesystem/ext2/filesystem.hpp b/kernel/kernel/filesystem/ext2/filesystem.hpp index c61eadd1..6a066f25 100644 --- a/kernel/kernel/filesystem/ext2/filesystem.hpp +++ b/kernel/kernel/filesystem/ext2/filesystem.hpp @@ -24,9 +24,7 @@ namespace kernel::filesystem::ext2 { - /** - @brief Constants related to the ext2 filesystem. - */ + //! Constants related to the ext2 filesystem. namespace constants { constexpr kstd::bytes inline base_block_size = kstd::bytes{1024}; @@ -51,118 +49,85 @@ namespace kernel::filesystem::ext2 constexpr uint16_t inline mode_character_device = 0x2000; } // namespace constants - /** - @brief A filesystem implementation for the ext2 filesystem format. This class provides methods for mounting an ext2 - filesystem, and looking up inodes. - */ + //! The Second Extended Filesystem (ext2) struct filesystem final : kernel::filesystem::filesystem { - /** - @brief Initializes the ext2 filesystem with the given @p backing_inode. - @param backing_inode The backing inode to mount. - @return The result of the mount operation. - */ auto mount(kstd::shared_ptr<kernel::filesystem::inode> const & backing_inode) -> kstd::result<void> override; - /** - @brief Looks up an inode by @p name within a @p parent directory. - @param parent The parent directory inode. - @param name The name of the inode to look up. - @return A pointer to the found inode, or a null pointer if not found. - */ [[nodiscard]] auto lookup(kstd::shared_ptr<kernel::filesystem::inode> const & parent, std::string_view name) const -> kstd::result<kstd::shared_ptr<kernel::filesystem::inode>> override; - /** - @brief Creates a new inode with @p name within a @p parent directory. - @param parent The parent directory inode. - @param name The name of the inode to create. - @param inode_type The type of inode to be created. - @param raw_device The number of the device represented by the new inode, if any. - @return A pointer to the created inode, or a null pointer if creation failed. - */ [[nodiscard]] auto create_inode(kstd::shared_ptr<kernel::filesystem::inode> const & parent, std::string_view name, vfs_types::inode_type inode_type, std::optional<kapi::filesystem::device_number> raw_device = std::nullopt) -> kstd::result<kstd::shared_ptr<kernel::filesystem::inode>> override; - /** - @brief Gets the size of a block in the filesystem. - @return The size of a block in bytes. - */ + //! Get the size of a block in the filesystem. + //! + //! @return The size of a block in bytes. [[nodiscard]] auto block_size() const -> kstd::bytes; - /** - @brief Gets the revision level of the filesystem. - @return The revision level. - */ + //! Get the revision level of the filesystem. + //! + //! @return The revision level. [[nodiscard]] auto revision_level() const -> uint32_t; - /** - @brief Reads a block from the backing device into the provided buffer. - @param block_number The number of the block to read. - @param buffer The buffer to read the block data into. - @return The number of bytes read. - */ + //! Read a block from the backing inode into the provided buffer. + //! + //! @param block_number The number of the block to read. + //! @param buffer The buffer to read the block data into. + //! @return The number of bytes read. auto read_block(uint32_t block_number, void * buffer) const -> kstd::result<kstd::bytes>; - /** - @brief Writes a block of data from the provided buffer to the backing device. - @param block_number The number of the block to write. - @param buffer The buffer containing the data to write. - @return The number of bytes written. - */ + //! Write a block of data from the provided buffer to the backing inode. + //! + //! @param block_number The number of the block to write. + //! @param buffer The buffer containing the data to write. + //! @return The number of bytes written. auto write_block(uint32_t block_number, void const * buffer) -> kstd::result<kstd::bytes>; - /** - @brief Allocates a specified number of blocks. - @param count The number of blocks to allocate. - @return An optional vector of the allocated block numbers, or a nullopt if allocation fails. - */ + //! Allocate a specified number of blocks. + //! + //! @param count The number of blocks to allocate. + //! @return A vector of the allocated block numbers. auto allocate_blocks(size_t count) -> kstd::result<kstd::vector<uint32_t>>; - /** - @brief Gets the size of an inode in the filesystem. - @return The size of an inode in bytes. - */ + //! Get the size of an inode in the filesystem. + //! + //! @return The size of an inode in bytes. [[nodiscard]] auto inode_size() const -> kstd::bytes; - /** - @brief Gets the number of blocks allocated to an inode. - @param data The inode data. - @return The number of blocks allocated to the inode. - */ + //! Get the number of blocks allocated to an inode. + //! + //! @param data The inode data. + //! @return The number of blocks allocated to the inode. [[nodiscard]] auto inode_block_count(inode_data const & data) const -> uint32_t; - /** - @brief Updates the number of blocks allocated to an inode. - @param data The inode data. - @param delta The change in the number of blocks. - */ + //! Update the number of blocks allocated to an inode. + //! + //! @param data The inode data. + //! @param delta The change in the number of blocks. auto update_inode_block_count(inode_data & data, uint32_t delta) -> void; - /** - @brief Writes an inode to the backing device. - @param inode_number The number of the inode to write. - @param data The inode data to write. - */ + //! Write an inode to the backing inode. + //! + //! @param inode_number The number of the inode to write. + //! @param data The inode data to write. auto write_inode(uint32_t inode_number, inode_data const & data) -> kstd::result<void>; - /** - @brief Maps an inode block index to a global block number. - @param inode_block_index The index of the block within the inode. - @param data The inode data. - @return The global block number on success, an error otherwise. - */ + //! Map an inode block index to a global block number. + //! + //! @param inode_block_index The index of the block within the inode. + //! @param data The inode data. + //! @return The global block number on success, an error otherwise. [[nodiscard]] auto map_inode_block_index_to_global_block_number(size_t inode_block_index, inode_data data) const -> kstd::result<std::size_t>; - /** - @brief Writes a global block number to an inode block index. - @param block_index The index of the block within the inode. - @param data The inode data. - @param global_block_number The global block number to write. - */ + //! Write a global block number to an inode block index. + //! + //! @param block_index The index of the block within the inode. + //! @param data The inode data. + //! @param global_block_number The global block number to write. auto write_global_block_number_to_inode_block_index(size_t block_index, inode_data & data, uint32_t global_block_number) -> kstd::result<void>; diff --git a/kernel/kernel/filesystem/ext2/inode.hpp b/kernel/kernel/filesystem/ext2/inode.hpp index 51508c0d..61961f6c 100644 --- a/kernel/kernel/filesystem/ext2/inode.hpp +++ b/kernel/kernel/filesystem/ext2/inode.hpp @@ -19,9 +19,7 @@ namespace kernel::filesystem::ext2 { struct filesystem; - /** - @brief Represents the data associated with an ext2 inode. - */ + //! The data for a single ext2 inode. struct [[gnu::packed]] inode_data { uint16_t mode; @@ -46,66 +44,38 @@ namespace kernel::filesystem::ext2 struct inode : kernel::filesystem::inode { - /** - @brief Create an ext2 inode associated with the given filesystem. - @param fs The ext2 filesystem that this inode belongs to. - @param inode_number The inode number on disk. - @param data The data associated with this inode, read from the disk. - */ + //! Create an ext2 inode associated with the given filesystem. + //! + //! @param fs The ext2 filesystem that this inode belongs to. + //! @param inode_number The inode number on disk. + //! @param data The data associated with this inode, read from the disk. explicit inode(filesystem * fs, uint32_t inode_number, inode_data const & data); - /** - @brief Reads from the ext2 inode into a @p buffer, starting at the specified @p offset and for a given @p size. - @param buffer Destination buffer. - @param offset Read offset in bytes. - @return Number of bytes read. - */ [[nodiscard]] auto read(std::span<std::byte> buffer, kstd::bytes offset) const -> kstd::result<kstd::bytes> override; - /** - @brief Writes to the ext2 inode into a @p buffer, starting at the specified @p offset and for a given @p size. - @param buffer Source buffer. - @param offset Write offset in bytes. - @return Number of bytes written. - */ auto write(std::span<std::byte const> buffer, kstd::bytes offset) -> kstd::result<kstd::bytes> override; - /** - @brief Appends the specified number of blocks to the inode. - @param count The number of blocks to append. - @return true if the blocks were successfully appended, false otherwise. - */ + //! Append the specified number of blocks to this inode. + //! + //! @param count The number of blocks to append. + //! @return true if the blocks were successfully appended, false otherwise. auto append_blocks(size_t count) -> bool; - /** - @brief Get the data associated with this inode. - @return A const reference to the inode data. - */ + //! Get the data associated with this inode. + //! + //! @return A const reference to the inode data. [[nodiscard]] auto data() const -> inode_data const &; - /** - @brief Get the data associated with this inode. - @return A reference to the inode data. - */ + //! Get the data associated with this inode. + //! + //! @return A reference to the inode data. [[nodiscard]] auto data_mutable() -> inode_data &; - /** - @brief Check if this inode represents a directory. - @return returns true if this inode represents a directory, false otherwise. - */ [[nodiscard]] auto is_directory() const -> bool override; - /** - @brief Check if this inode represents a regular file. - @return returns true if this inode represents a regular file, false otherwise. - */ [[nodiscard]] auto is_regular() const -> bool override; - /** - @brief Check if this inode represents a symbolic link. - @return returns true if this inode represents a symbolic link, false otherwise. - */ [[nodiscard]] auto is_symbolic_link() const -> bool override; [[nodiscard]] auto is_block_device() const -> bool override; @@ -116,27 +86,27 @@ namespace kernel::filesystem::ext2 [[nodiscard]] auto raw_device() const -> std::optional<kapi::filesystem::device_number> override; - /** - @brief Get the size of the file represented by this inode. - @return The size of the file in bytes. - */ + //! Get the size of the file represented by this inode. + //! + //! @return The size of the file in bytes. [[nodiscard]] auto size() const -> kstd::bytes; - /** - @brief Set the size of the file represented by this inode. - @param new_size The new size of the file in bytes. - */ + //! Set the size of the file represented by this inode. + //! + //! @param new_size The new size of the file in bytes. auto set_size(kstd::bytes new_size) -> void; - /** - @brief Get the inode number of this inode. - @return The inode number. - */ + //! @brief Get the inode number of this inode. + //! + //! @return The inode number. [[nodiscard]] auto number() const -> uint32_t; private: + //! The filesystem this inode belongs to. filesystem * m_filesystem; + //! The inode number on disk. uint32_t m_inode_number{}; + //! The inode data. inode_data m_data{}; }; } // namespace kernel::filesystem::ext2 diff --git a/kernel/kernel/filesystem/ext2/linked_directory_entry.hpp b/kernel/kernel/filesystem/ext2/linked_directory_entry.hpp index 2dfa507d..9c9d162d 100644 --- a/kernel/kernel/filesystem/ext2/linked_directory_entry.hpp +++ b/kernel/kernel/filesystem/ext2/linked_directory_entry.hpp @@ -6,9 +6,7 @@ namespace kernel::filesystem::ext2 { - /** - @brief Represents a linked directory entry in the ext2 filesystem. - */ + //! A linked directory entry in the ext2 filesystem. struct [[gnu::packed]] linked_directory_entry { uint32_t inode; diff --git a/kernel/kernel/filesystem/ext2/superblock.hpp b/kernel/kernel/filesystem/ext2/superblock.hpp index 73fd4b5e..0fe5d4e5 100644 --- a/kernel/kernel/filesystem/ext2/superblock.hpp +++ b/kernel/kernel/filesystem/ext2/superblock.hpp @@ -6,9 +6,7 @@ namespace kernel::filesystem::ext2 { - /** - @brief Represents the superblock in the ext2 filesystem. - */ + //! The superblock in the ext2 filesystem. struct [[gnu::packed]] superblock { uint32_t inodes_count; diff --git a/kernel/kernel/filesystem/filesystem.cpp b/kernel/kernel/filesystem/filesystem.cpp index ac0d0ebc..5cd7f9d5 100644 --- a/kernel/kernel/filesystem/filesystem.cpp +++ b/kernel/kernel/filesystem/filesystem.cpp @@ -16,6 +16,7 @@ namespace kernel::filesystem { namespace { + // TODO: replace with filesystem type registry. constexpr auto static filesystem_factories = std::array{ []() { return kstd::make_shared<ext2::filesystem>(); }, }; @@ -29,6 +30,7 @@ namespace kernel::filesystem kapi::system::panic("[FILESYSTEM] cannot mount filesystem: backing inode is null."); } + // TODO: replace with filesystem type registry lookup. for (auto & factory : filesystem_factories) { auto fs = factory(); diff --git a/kernel/kernel/filesystem/filesystem.hpp b/kernel/kernel/filesystem/filesystem.hpp index b5017c24..668fd06e 100644 --- a/kernel/kernel/filesystem/filesystem.hpp +++ b/kernel/kernel/filesystem/filesystem.hpp @@ -16,68 +16,64 @@ namespace kernel::filesystem { - /** - @brief A base class for implementing filesystems in the kernel. This class provides a common interface for managing - files and directories within the virtual filesystem. - */ + //! The base class for all filesystems. + //! + //! This class provides a common interface for managing files and directories within the virtual filesystem. + //! Filesystem implementations must derive from this class. struct filesystem { - /** - @brief Virtual destructor for the filesystem. - */ + //! Virtual destructor enabling polymorphic destruction. virtual ~filesystem() = default; - /** - @brief Probes the given @p backing_inode to determine if it contains a recognizable filesystem, and if so, mounts it - and returns a pointer to the mounted filesystem instance. This method iterates through known filesystem types and - attempts to initialize it with the backing inode until the mount was successful or all types have been tried. - @param backing_inode The inode to probe and mount. - @return A pointer to the mounted filesystem instance if successful, an error otherwise. - @warning Panics if @p backing_inode is null. - */ + //! Probes the given inode to determine if it contains a recognizable filesystem, and if so, mount it. + //! + //! @warning This function panics if @p backing_inode is null. + //! + //! @param backing_inode The inode to probe and mount. + //! @return A pointer to the mounted filesystem instance on success, an error otherwise. auto static probe_and_mount(kstd::shared_ptr<inode> const & backing_inode) -> kstd::result<kstd::shared_ptr<filesystem>>; - /** - @brief Initializes the filesystem with the given @p backing_inode. - @param backing_inode The inode to use as the backing inode for the filesystem. (This is typically the inode - representing the block device or another inode which contains the filesystem data.) - @return Nothing on success, and error otherwise. - */ + //! Initializes the filesystem with the given inode. + //! + //! Typically, the backing inode is the inode representing the block device or another inode which contains the + //! filesystem data (e.g. a file on an already mounted filesystem). + //! + //! @param backing_inode The inode to use as the backing inode for the filesystem. + //! @return Nothing on success, and error otherwise. virtual auto mount(kstd::shared_ptr<inode> const & backing_inode) -> kstd::result<void>; - /** - @brief Looks up a child inode within the given @p parent inode with the specified @p name. This method must be - implemented by concrete filesystem subclasses to provide the logic for traversing the filesystem structure and - finding the requested inode. - @param parent The parent inode. - @param name The name of the child inode to look up. - @return A pointer to the requested child inode, an error otherwise. - */ + //! Find a child inode below the given parent inode with the specified name. + //! + //! This method must be implemented by concrete filesystem subclasses to provide the logic for traversing the + //! filesystem structure and finding the requested inode. + //! + //! @param parent The parent inode. + //! @param name The name of the child inode to look up. + //! @return A pointer to the requested child inode on success, an error otherwise. [[nodiscard]] virtual auto lookup(kstd::shared_ptr<inode> const & parent, std::string_view name) const -> kstd::result<kstd::shared_ptr<inode>> = 0; - /** - @brief Creates a new inode with @p name within a @p parent directory. - @param parent The parent directory inode. - @param name The name of the inode to create. - @param inode_type The type of inode to be created. - @param raw_device The device number the new inode should represent. - @return A pointer to the created inode, or a null pointer if creation failed. - */ + //! Create a new inode with the given name below a given parent inode. + //! + //! @param parent The parent inode. + //! @param name The name of the inode to create. + //! @param inode_type The type of inode to be created. + //! @param raw_device The device number the new inode should represent, if any. + //! @return A pointer to the created inode on success, an error otherwise. [[nodiscard]] virtual auto create_inode(kstd::shared_ptr<inode> const & parent, std::string_view name, vfs_types::inode_type inode_type, std::optional<kapi::filesystem::device_number> raw_device = std::nullopt) -> kstd::result<kstd::shared_ptr<inode>> = 0; - /** - @brief Returns a reference to the root inode of the filesystem. - */ + //! Get the root inode of the file system. + //! + //! @return A reference to the root inode. [[nodiscard]] auto root_inode() const -> kstd::shared_ptr<inode> const &; - /** - @brief Returns a reference to the backing inode of the filesystem. - */ + //! Get the backing inode of the file system. + //! + //! @return A reference to the backing inode. [[nodiscard]] auto backing_inode() const -> kstd::shared_ptr<inode> const &; protected: diff --git a/kernel/kernel/filesystem/mount.hpp b/kernel/kernel/filesystem/mount.hpp index aff43c78..b906def5 100644 --- a/kernel/kernel/filesystem/mount.hpp +++ b/kernel/kernel/filesystem/mount.hpp @@ -12,76 +12,54 @@ namespace kernel::filesystem { - /** - @brief Represents a mounted filesystem in the kernel. - */ + //! A mounted filesystem struct mount { - /** - @brief Creates a mount for the given @p filesystem at the specified @p mount_path. The @p mount_dentry represents - the dentry where the filesystem is mounted, and the @p root_dentry represents the root dentry of the mounted - filesystem. - @param mount_dentry The dentry where the filesystem is mounted. - @param root_dentry The root dentry of the mounted filesystem. - @param fs The filesystem instance being mounted. - @param parent_mount The mount that contains the mount_dentry. - @param source_mount The mount that the filesystem originates from. - */ + //! Create a new mount with the given parameters. + //! + //! @param mount_dentry The directory entry where the filesystem is mounted. + //! @param root_dentry The root directory entry of the mounted filesystem. + //! @param fs The filesystem instance being mounted. + //! @param parent_mount The parent mount which contains the mount_dentry. + //! @param source_mount The mount that the filesystem originates from. mount(kstd::shared_ptr<dentry> const & mount_dentry, kstd::shared_ptr<dentry> const & root_dentry, kstd::shared_ptr<filesystem> const & fs, kstd::shared_ptr<mount> const & parent_mount, kstd::shared_ptr<mount> const & source_mount); - /** - @brief Get the dentry where the filesystem is mounted. - */ + //! Get the directory entry where the filesystem is mounted. [[nodiscard]] auto mount_dentry() const -> kstd::shared_ptr<dentry> const &; - /** - @brief Get the root dentry of the mounted filesystem. - */ + //! Get the root directory entry of the mounted filesystem. [[nodiscard]] auto root_dentry() const -> kstd::shared_ptr<dentry> const &; - /** - @brief Get the filesystem instance being mounted. - */ + //! Get the filesystem instance being mounted. [[nodiscard]] auto get_filesystem() const -> kstd::shared_ptr<filesystem> const &; - /** - @brief Get the path at which the filesystem is mounted. - */ + //! Get the path at which the filesystem is mounted. [[nodiscard]] auto mount_path() const -> kstd::string; - /** - @brief Get the parent mount that this mount was attached beneath. - */ + //! Get the parent mount that this mount was attached beneath. [[nodiscard]] auto parent_mount() const -> kstd::shared_ptr<mount> const &; - /** - @brief Get the source mount where this mount originates from. - */ + //! Get the source mount where this mount originates from. [[nodiscard]] auto source_mount() const -> kstd::shared_ptr<mount>; - /** - @brief Increment the reference count for this mount. - */ + //! Increment the reference count for this mount. auto increment_ref_count() -> void; - /** - @brief Decrement the reference count for this mount. - @warning Throws if ref_count is zero. - */ + //! Decrement the reference count for this mount. + //! + //! @warning This function panics if the reference count is already zero. auto decrement_ref_count() -> void; - /** - @brief Check if the mount is ready to be unmounted. - @return True if the mount is ready to be unmounted, false otherwise. - */ + //! Check if the mount is ready to be unmounted. + //! + //! @return True if the mount is ready to be unmounted, false otherwise. [[nodiscard]] auto is_ready_to_unmount() const -> bool; - /** - @brief Get the current reference count for this mount. - @return The current reference count. - */ + //! Get the current reference count for this mount. + //! + //! @return The current reference count. [[nodiscard]] auto ref_count() const -> size_t; private: diff --git a/kernel/kernel/filesystem/mount_table.hpp b/kernel/kernel/filesystem/mount_table.hpp index f1c2050d..678a5927 100644 --- a/kernel/kernel/filesystem/mount_table.hpp +++ b/kernel/kernel/filesystem/mount_table.hpp @@ -10,14 +10,10 @@ namespace kernel::filesystem { - /** - @brief A table for managing mounted filesystems in the kernel. - */ + //! A table managing all mounted filesystems. struct mount_table { - /** - @brief Results for mount table operations. - */ + //! Results for mount table operations. enum class operation_result : int { removed = 0, @@ -26,24 +22,22 @@ namespace kernel::filesystem cannot_be_unmounted = -3 }; - /** - @brief Adds a mount to the table. - @param mount The mount to add. - */ + //! Add a mount to the table. + //! + //! @param mount The mount to add. auto add_mount(kstd::shared_ptr<mount> const & mount) -> void; - /** - @brief Removes the topmost mount at the given @p path. - @param path The mount path to remove. - @return The result of the removal operation. - */ - [[nodiscard]] auto remove_mount(std::string_view path) -> operation_result; - - /** - @brief Finds the mount with the exact mount path matching the given @p path. - @param path The path to match against the mount paths in the table. - @return A pointer to the mount with the exact matching path, or a null pointer if no mount matches the path. - */ + //! Remove the topmost mount at the given @p path. + //! + //! @param path The mount path to remove. + //! @return The result of the removal operation. + [[nodiscard]] auto remove_mount(std::string_view path) + -> operation_result; // TODO: replace return type with kstd::result + + //! Find the mount with the exact mount path matching the given path. + //! + //! @param path The path to match against the mount paths in the table. + //! @return A pointer to the mount with the exact matching path on success, nullpointer otherwise. [[nodiscard]] auto find_mount(std::string_view path) const -> kstd::shared_ptr<mount>; private: diff --git a/kernel/kernel/filesystem/open_file_descriptor.hpp b/kernel/kernel/filesystem/open_file_descriptor.hpp index a39dbab8..735ea7a2 100644 --- a/kernel/kernel/filesystem/open_file_descriptor.hpp +++ b/kernel/kernel/filesystem/open_file_descriptor.hpp @@ -14,39 +14,27 @@ namespace kernel::filesystem { - /** - @brief Represents an open file descriptor in the filesystem. This class encapsulates the state of an open file, - including a reference to the associated dentry and the current file offset. - */ + //! An open file. + //! + //! This class encapsulates the state of an open file, including a reference to the associated directory and the + //! current byte offset within the file. struct open_file_descriptor { - /** - @brief Constructs an open file descriptor for the given @p dentry. - @param dentry The dentry to associate with the open file descriptor. - */ + //! Create an new open file descriptor for a given directory entry. + //! + //! @param dentry The directory entry to associate with the open file descriptor. explicit open_file_descriptor(kstd::shared_ptr<dentry> const & dentry); - /** - @brief Destructor for the open file descriptor. - */ - ~open_file_descriptor() = default; - - /** - @brief Reads data from the open file descriptor into a @p buffer, starting at the current file offset and for a - given - @p size. The file offset is advanced by the number of bytes read. - @param buffer The buffer to read data into. - @return The number of bytes read. - */ + //! Read data from the open file descriptor into a buffer. + //! + //! @param buffer The buffer to read data into. + //! @return The number of bytes read on success, an error otherwise. auto read(std::span<std::byte> buffer) -> kstd::result<kstd::bytes>; - /** - @brief Writes data to the open file descriptor from a @p buffer, starting at the current file offset and for a - given - @p size. The file offset is advanced by the number of bytes written. - @param buffer The buffer to write data from. - @return The number of bytes written. - */ + //! Write data to the open file descriptor from a buffer. + //! + //! @param buffer The buffer to write data from. + //! @return The number of bytes written on success, an error otherwise. auto write(std::span<std::byte const> buffer) -> kstd::result<kstd::bytes>; //! Move the read/write offset of the file. @@ -56,16 +44,14 @@ namespace kernel::filesystem //! @return the new offset on success, an error otherwise. auto seek(kstd::offset offset, kapi::filesystem::seek_origin origin) -> kstd::result<kstd::bytes>; - /** - @brief Returns the current file offset for this open file descriptor. - @return The current file offset in bytes. - */ + //! Get the current file offset for this open file descriptor. + //! + //! @return The current file offset in bytes. [[nodiscard]] auto offset() const -> kstd::bytes; - /** - @brief Return a reference to the dentry associated with this open file descriptor. - @return A reference to the associated dentry. - */ + //! Get a reference to the directory entry associated with this open file descriptor. + //! + //! @return A reference to the associated directory entry. [[nodiscard]] auto get_dentry() const -> kstd::shared_ptr<dentry> const &; private: diff --git a/kernel/kernel/filesystem/open_file_table.hpp b/kernel/kernel/filesystem/open_file_table.hpp index fe42c2bb..ddc1ea16 100644 --- a/kernel/kernel/filesystem/open_file_table.hpp +++ b/kernel/kernel/filesystem/open_file_table.hpp @@ -12,49 +12,39 @@ namespace kernel::filesystem { - /** - @brief A table for managing file descriptors in the filesystem. This class provides methods for adding, retrieving, - and removing open file descriptors. - */ + //! @brief A table for managing file descriptors in the filesystem. + //! + //! This class provides methods for adding, retrieving, and removing open file descriptors. struct open_file_table { - /** - @brief Initialize the global open file table. This method creates the singleton instance of the open file table. - @warning Panics if called more than once. - */ + //! Initialize the global open file table. + //! + //! @warning This function panics if called more than once. auto static init() -> void; - /** - @brief Get the global open file table instance. - @return A reference to the global open file table. - @warning Panics if the open file table has not been initialized. - */ + //! Get the global open file table instance. + //! + //! @warning Panics if the open file table has not been initialized. + //! + //! @return A reference to the global open file table. auto static get() -> open_file_table &; - /** - @brief Destructor for the open file table. - */ - ~open_file_table() = default; - - /** - @brief Add a file to the open file table. - @param fd The file descriptor to add. - @return The file descriptor index assigned to the file, or -1 on failure. - */ + //! Add a file to the open file table. + //! + //! @param fd The file descriptor to add. + //! @return The file descriptor index assigned to the file on success, an error otherwise. auto add_file(kstd::shared_ptr<open_file_descriptor> const & fd) -> kstd::result<std::size_t>; - /** - @brief Get a file from the open file table. - @param fd The file descriptor index to retrieve. - @return A pointer to the requested file descriptor, or a null pointer if not found. - */ + //! Get a file from the open file table. + //! + //! @param fd The file descriptor index to retrieve. + //! @return The requested file descriptor on success, an error otherwise. [[nodiscard]] auto file(size_t fd) const -> kstd::result<kstd::shared_ptr<open_file_descriptor>>; - /** - @brief Remove a file from the open file table. - @param fd The file descriptor index to remove. - @return 0 on success, or -1 on failure. - */ + //! Remove a file from the open file table. + //! + //! @param fd The file descriptor index to remove. + //! @return Nothin on success, an error otherwise. auto remove_file(size_t fd) -> kstd::result<void>; private: diff --git a/kernel/kernel/filesystem/path.hpp b/kernel/kernel/filesystem/path.hpp index a9d4cbd9..4dc0dbce 100644 --- a/kernel/kernel/filesystem/path.hpp +++ b/kernel/kernel/filesystem/path.hpp @@ -11,55 +11,47 @@ namespace kernel::filesystem::path { - /** - @brief Provides utilities for handling filesystem paths, including validation and splitting into components. - */ - /** - @brief Checks if the given path is within the maximum allowed length. - @param path The path to check. - @return true if the path length is valid, false otherwise. - */ + //! Check if the given path is within the maximum allowed length. + //! + //! @param path The path to check. + //! @return @c true if the path length is valid, @c false otherwise. auto inline is_valid_path_length(std::string_view path) -> bool { return path.length() < kernel::filesystem::constants::max_path_length; } - /** - @brief Checks if the given path is a valid absolute path (starts with '/'). - @param path The path to check. - @return true if the path is a valid absolute path, false otherwise. - */ + //! Check if the given path is an absolute path. + //! + //! @param path The path to check. + //! @return @c true if the path is an absolute path, @c false otherwise. auto inline is_valid_absolute_path(std::string_view path) -> bool { return !path.empty() && path.front() == '/' && is_valid_path_length(path); } - /** - @brief Checks if the given path is a valid relative path (doesn't start with '/'). - @param path The path to check. - @return true if the path is a valid relative path, false otherwise. - */ + //! Check if the given path is a relative path. + //! + //! @param path The path to check. + //! @return @c true if the path is a relative path, @c false otherwise. auto inline is_valid_relative_path(std::string_view path) -> bool { return !path.empty() && path.front() != '/' && is_valid_path_length(path); } - /** - @brief Checks if the given path is a valid path (either absolute or relative). - @param path The path to check. - @return true if the path is a valid path, false otherwise. - */ + //! Check if the given path is a valid path. + //! + //! @param path The path to check. + //! @return @c true if the path is a valid path, @c false otherwise. auto inline is_valid_path(std::string_view path) -> bool { return is_valid_absolute_path(path) || is_valid_relative_path(path); } - /** - @brief Splits the given path into its components. - @param path The path to split. - @return A range of strings representing the components of the path. - */ + //! Split the given path into its components. + //! + //! @param path The path to split. + //! @return A range of strings representing the components of the path. auto inline split(std::string_view path) { return std::views::split(path, '/') | std::views::filter([](auto const & part) { return !part.empty(); }) | @@ -67,11 +59,10 @@ namespace kernel::filesystem::path [](auto const & part) { return kstd::string(std::string_view(part.begin(), part.end())); }); } - /** - @brief Splits the given path into its parent path and filename components. - @param path The path to split. - @return A pair of string views representing the parent path and filename. - */ + //! Split the given path into its parent path and filename components. + //! + //! @param path The path to split. + //! @return A pair of string views representing the parent path and filename. auto inline split_into_path_and_filename(std::string_view path) -> std::pair<std::string_view, std::string_view> { if (path.empty()) diff --git a/kernel/kernel/filesystem/rootfs/inode.hpp b/kernel/kernel/filesystem/rootfs/inode.hpp index e9e85d7d..2a1c3858 100644 --- a/kernel/kernel/filesystem/rootfs/inode.hpp +++ b/kernel/kernel/filesystem/rootfs/inode.hpp @@ -14,32 +14,14 @@ namespace kernel::filesystem::rootfs { - /** - @brief Represents an inode in the rootfs filesystem. - */ + //! An inode in the rootfs filesystem. struct inode : kernel::filesystem::inode { - /** - @brief Reads from the rootfs directory inode. - @param buffer Destination buffer. - @param offset Read offset in bytes. - @return Number of bytes read (always 0 because this inode does not expose file data). - */ [[nodiscard]] auto read(std::span<std::byte> buffer, kstd::bytes offset) const -> kstd::result<kstd::bytes> override; - /** - @brief Writes to the rootfs directory inode. - @param buffer Source buffer. - @param offset Write offset in bytes. - @return Number of bytes written (always 0 because writes are not supported for this inode). - */ auto write(std::span<std::byte const> buffer, kstd::bytes offset) -> kstd::result<kstd::bytes> override; - /** - @brief Check if this inode represents a directory. - @return returns true, since this inode represents the / directory in the rootfs filesystem. - */ [[nodiscard]] auto is_directory() const -> bool override; }; } // namespace kernel::filesystem::rootfs diff --git a/kernel/kernel/filesystem/vfs.hpp b/kernel/kernel/filesystem/vfs.hpp index b2b7e3a8..f4f5b477 100644 --- a/kernel/kernel/filesystem/vfs.hpp +++ b/kernel/kernel/filesystem/vfs.hpp @@ -22,12 +22,13 @@ namespace kernel::filesystem { - /** - @brief The virtual filesystem (VFS) is responsible for managing mounted filesystems and providing a unified interface - for file operations across different filesystem types. The VFS maintains a mount table to keep track of mounted - filesystems and their associated mount points. It provides methods for opening files by path, which involves resolving - the path to the appropriate mounted filesystem and delegating the file operation to that filesystem's implementation. - */ + //! The virtual filesystem interface. + //! + //! The virtual filesystem (VFS) is responsible for managing mounted filesystems and providing a unified interface + //! for file operations across different filesystem types. The VFS maintains a mount table to keep track of mounted + //! filesystems and their associated mount points. It provides methods for opening files by path, which involves + //! resolving the path to the appropriate mounted filesystem and delegating the file operation to that filesystem's + //! implementation. struct vfs { using dentry_ptr = kstd::shared_ptr<dentry>; @@ -36,66 +37,54 @@ namespace kernel::filesystem vfs(); - /** - @brief Initialize the virtual filesystem. - @warning Panics if the VFS has already been initialized. - */ + //! Initialize the virtual filesystem. + //! + //! @warning This function panics if the VFS has already been initialized. auto static init() -> void; - /** - @brief Get the singleton instance of the virtual filesystem. - @return A reference to the VFS instance. - @warning Panics if the VFS has not been initialized yet. - */ + //! Get the singleton instance of the virtual filesystem. + //! + //! @warning This function panics if the VFS has not been initialized yet. + //! + //! @return A reference to the VFS instance. auto static get() -> vfs &; - /** - @brief Destructor for the VFS. - */ - ~vfs() = default; - - /** - @brief Open a file by its @p path. This method resolves the path and returns the corresponding dentry. - @param path The path to the file to open. - @return A shared pointer to the dentry on success or an error code on failure. - */ + //! Open a file by its path. + //! + //! @param path The path to the file to open. + //! @return A shared pointer to the dentry on success or an error code on failure. auto open(std::string_view path) -> kstd::result<dentry_ptr>; - /** - @brief Close a file by its associated @p path. - @param path The path to the file to close. - @return Nothing on success or an error code on failure. - */ + //! Close a file by its associated path. + //! + //! @param path The path to the file to close. + //! @return Nothing on success or an error code on failure. auto close(std::string_view path) -> kstd::result<void>; - /** - @brief Mount a @p source path to a specific @p target path. - @param source The source of the filesystem to mount. - @param target The path where the filesystem should be mounted. - @return Nothing on success or an error code on failure. - */ + //! Mount a source path to a specific target path. + //! + //! @param source The source of the filesystem to mount. + //! @param target The path where the filesystem should be mounted. + //! @return Nothing on success or an error code on failure. auto mount(std::string_view source, std::string_view target) -> kstd::result<void>; - /** - @brief Unmount the filesystem mounted at the specified @p path. - @param path The path where the filesystem is mounted. - @return Nothing on success or an error code on failure. - */ + //! Unmount the filesystem mounted at the specified path. + //! + //! @param path The path where the filesystem is mounted. + //! @return Nothing on success or an error code on failure. auto unmount(std::string_view path) -> kstd::result<void>; - /** - @brief Create a new directory at the specified @p path. - @param path The path where the new directory should be created. - @return The result of the mkdir operation. - */ + //! Create a new directory at the specified path. + //! + //! @param path The path where the new directory should be created. + //! @return Nothing on success, an error otherwise. auto mkdir(std::string_view path) -> kstd::result<void>; - /** - @brief Create a new file at the specified @p path. - @param path The path where the new file should be created. - @return The result of the create operation. - */ - // TODO remove again after the open method supports an optional create flag + //! Create a new file at the specified path. + //! + //! @param path The path where the new file should be created. + //! @return Nothing on success, an error otherwise. + // TODO remove after the open method supports flags. auto create(std::string_view path) -> kstd::result<void>; //! Get the status of the file at a given path. @@ -110,16 +99,13 @@ namespace kernel::filesystem -> kstd::result<void>; private: - /** - * Note: Resolving a dentry requires traversing mount points; since the - * associated 'mount' object is discovered as a byproduct of this - * traversal, we return it alongside the dentry to avoid redundant - * lookups in callers that require mount context. - * - * If only one component is needed, the convenience wrappers can be used: - * - resolve_path() for the dentry only. - * - find_mount() for the mount context only. - */ + // Note: Resolving a dentry requires traversing mount points; since the associated 'mount' object is discovered as a + // byproduct of this traversal, we return it alongside the dentry to avoid redundant lookups in callers that require + // mount context. + // + // If only one component is needed, the convenience wrappers can be used: + // - resolve_path() for the dentry only. + // - find_mount() for the mount context only. [[nodiscard]] auto resolve_path_internal(std::string_view path) const -> kstd::result<std::pair<dentry_ptr, mount_ptr>>; |