diff options
6 files changed, 187 insertions, 1 deletions
diff --git a/kernel/devices/include/devices/block_device.hpp b/kernel/devices/include/devices/block_device.hpp index 240cb3b..78a2606 100644 --- a/kernel/devices/include/devices/block_device.hpp +++ b/kernel/devices/include/devices/block_device.hpp @@ -7,15 +7,49 @@ namespace devices { + /** + * @brief Base interface for block-addressable devices. + */ struct block_device : device { + /** + * @brief Create a block device descriptor. + * @param major Device major number. + * @param minor Device minor number. + * @param block_size Size of one logical block in bytes. + */ block_device(size_t major, size_t minor, size_t block_size); + + /** + * @brief Virtual destructor for block device. + */ virtual ~block_device() = default; + /** + * @brief Read data from the block at @p block_index into @p buffer. + * @param block_index Zero-based block index. + * @param buffer Destination buffer. + * @warning Panics if @p buffer is null. + * @note Reads up to one logical block (see constructor @p block_size). Implementations may perform a partial + * transfer for the final block when fewer than @p block_size bytes remain. + */ virtual auto read_block(size_t block_index, void * buffer) const -> void = 0; + + /** + * @brief Write data to the block at @p block_index. + * @param block_index Zero-based block index. + * @param buffer Source buffer, must not be null. + * @warning Panics if @p buffer is null. + * @note Writes up to one logical block (see constructor @p block_size). + * Implementations may perform a partial transfer for the final block when + * fewer than @p block_size bytes remain. + */ virtual auto write_block(size_t block_index, void const * buffer) -> void = 0; protected: + /** + * @brief Information describing the transfer window for one block index. + */ struct transfer_info { size_t offset; @@ -23,7 +57,17 @@ namespace devices size_t remainder; }; + /** + * @brief Return total device size in bytes. + * @return Total number of addressable bytes. + */ virtual auto size() const -> size_t = 0; + + /** + * @brief Compute transfer information for @p block_index. + * @param block_index Zero-based block index. + * @return Computed transfer information for one logical block access. + */ auto calculate_transfer(size_t block_index) const -> transfer_info; size_t m_block_size; diff --git a/kernel/devices/include/devices/device.hpp b/kernel/devices/include/devices/device.hpp index 0f93bff..cbf77c2 100644 --- a/kernel/devices/include/devices/device.hpp +++ b/kernel/devices/include/devices/device.hpp @@ -5,17 +5,39 @@ namespace devices { + /** + * @brief Base device identified by a major and minor number. + */ struct device { + /** + * @brief Create a device identifier from @p major and @p minor. + * @param major Device major number. + * @param minor Device minor number. + */ device(size_t major, size_t minor); + + /** + * @brief Virtual destructor for device. + */ virtual ~device() = default; + /** + * @brief Returns the major number of the device. + * @return Device major number. + */ auto major() const -> size_t; + + /** + * @brief Returns the minor number of the device. + * @return Device minor number. + */ auto minor() const -> size_t; private: size_t m_major; size_t m_minor; + // TODO BA-FS26 add name }; } // namespace devices diff --git a/kernel/devices/include/devices/storage/ram_disk/ram_disk_controller.hpp b/kernel/devices/include/devices/storage/ram_disk/ram_disk_controller.hpp index f050ba0..05cac88 100644 --- a/kernel/devices/include/devices/storage/ram_disk/ram_disk_controller.hpp +++ b/kernel/devices/include/devices/storage/ram_disk/ram_disk_controller.hpp @@ -12,17 +12,39 @@ namespace devices::storage::ram_disk { + /** + * @brief Storage controller that exposes boot modules as RAM-disk devices. + */ struct ram_disk_controller : storage_controller { + /** + * @brief Create a RAM-disk controller. + * @param registry Boot module registry as device source. + */ explicit ram_disk_controller(kapi::boot_modules::boot_module_registry const * registry); + /** + * @brief Probe boot modules and create RAM-disk devices. + */ auto probe() -> void override; + /** + * @brief Return the number of managed RAM-disk devices. + * @return Number of managed devices. + */ auto devices_count() -> size_t override; + + /** + * @brief Look up a RAM-disk device by major/minor numbers. + * @param major Device major number. + * @param minor Device minor number. + * @return Matching block device, or nullptr if no device matches. + */ auto device_by_major_minor(size_t major, size_t minor) -> block_device * override; private: kapi::boot_modules::boot_module_registry const * m_boot_module_registry; + std::array<ram_disk_device, 1> m_devices{}; // TODO BA-FS26 use kstd::vector when available }; } // namespace devices::storage::ram_disk diff --git a/kernel/devices/include/devices/storage/ram_disk/ram_disk_device.hpp b/kernel/devices/include/devices/storage/ram_disk/ram_disk_device.hpp index 1f0292f..eebbcd7 100644 --- a/kernel/devices/include/devices/storage/ram_disk/ram_disk_device.hpp +++ b/kernel/devices/include/devices/storage/ram_disk/ram_disk_device.hpp @@ -9,15 +9,42 @@ namespace devices::storage::ram_disk { + /** + * @brief Block device for a boot module. + */ struct ram_disk_device : block_device { ram_disk_device(); // TODO BA-FS26 remove when kstd::vector is available + + /** + * @brief Create a RAM disk for the @p module. + * @param module Boot module providing the memory region. + * @param major Device major number. + * @param minor Device minor number. + */ ram_disk_device(kapi::boot_modules::boot_module const & module, size_t major, size_t minor); + /** + * @brief Read one logical block into @p buffer. + * @param block_index Zero-based block index. + * @param buffer Destination buffer, must not be null. + * @note If the request reaches the module end, only available bytes are copied and the rest of the + * logical block is filled with zeros. + */ auto read_block(size_t block_index, void * buffer) const -> void override; + + /** + * @brief Write one logical block from @p buffer. + * @param block_index Zero-based block index. + * @param buffer Source buffer, must not be null. + * @note If the request reaches the module end, only the bytes in the module range are written. + */ auto write_block(size_t block_index, void const * buffer) -> void override; private: + /** + * @brief Return module size in bytes. + */ auto size() const -> size_t override; kapi::boot_modules::boot_module m_boot_module{}; diff --git a/kernel/devices/include/devices/storage/storage_controller.hpp b/kernel/devices/include/devices/storage/storage_controller.hpp index 0c09815..18c7232 100644 --- a/kernel/devices/include/devices/storage/storage_controller.hpp +++ b/kernel/devices/include/devices/storage/storage_controller.hpp @@ -7,16 +7,49 @@ namespace devices::storage { + /** + * @brief Base interface for storage controllers. + * + * A storage controller probes for devices and resolves devices by major/minor + * numbers. + */ struct storage_controller { + /** + * @brief Virtual destructor. + */ virtual ~storage_controller() = default; + /** + * @brief Probe the controller and register discovered devices. + */ virtual auto probe() -> void = 0; + /** + * @brief Assign the major number and minor stride for this controller. + * @param major Major number assigned to this controller. + * @param minors_per_dev Minor number stride between devices. + */ auto set_ids(size_t major, size_t minors_per_dev) -> void; + + /** + * @brief Return the assigned major number. + * @return Assigned major number. + */ auto major() const -> size_t; + /** + * @brief Return the number of devices managed by this controller. + * @return Number of managed devices. + */ virtual auto devices_count() -> size_t = 0; + + /** + * @brief Find a managed device by major/minor numbers. + * @param major Device major number. + * @param minor Device minor number. + * @return Matching block device, or nullptr if no device matches. + */ virtual auto device_by_major_minor(size_t major, size_t minor) -> block_device * = 0; protected: diff --git a/kernel/devices/include/devices/storage/storage_management.hpp b/kernel/devices/include/devices/storage/storage_management.hpp index c4f5679..2bed459 100644 --- a/kernel/devices/include/devices/storage/storage_management.hpp +++ b/kernel/devices/include/devices/storage/storage_management.hpp @@ -9,19 +9,57 @@ namespace devices::storage { - // TODO BA-FS26 add documentation + /** + * @brief Global storage subsystem manager. + * + * Owns registered storage controllers and provides device lookup by + * major/minor numbers. + */ struct storage_management { + /** + * @brief Initialize global storage management. + * + * Creates the singleton instance, registers controllers and probes + * them for devices. + * + * @warning Panics if called more than once. + */ auto static init() -> void; + /** + * @brief Return the active storage manager singleton. + * @return Reference to the active storage manager. + * @warning Panics if storage management has not been initialized. + */ auto static get() -> storage_management &; + /** + * @brief Register a storage controller. + * @param controller Controller to register. + * + * Assigns controller IDs (major number range and minors per device). + */ auto add_controller(storage_controller * controller) -> void; + /** + * @brief Find a block device by major/minor numbers. + * @param major Device major number. + * @param minor Device minor number. + * @return Matching block device, or nullptr if no device matches. + */ auto device_by_major_minor(size_t major, size_t minor) -> block_device *; + + /** + * @brief Determine the boot device. + * @return Boot device, or nullptr if it cannot be determined. + */ auto determine_boot_device() -> block_device *; private: + /** + * @brief Private default constructor for storage management singleton. + */ storage_management() = default; std::array<storage_controller *, 1> m_controllers{}; // TODO BA-FS26 use kstd::vector when available |