From 4cce84317474dd14da806d3ddc7f69ef11356b5f Mon Sep 17 00:00:00 2001 From: Felix Morgner Date: Thu, 2 Apr 2026 20:04:07 +0200 Subject: docs: begin breathe documentation --- kapi/include/kapi/cio.hpp | 27 +++++++++++++++++++-------- kapi/include/kapi/cpu.hpp | 28 ++++++++++++++++++++-------- kapi/include/kapi/devices.hpp | 4 ++-- kapi/include/kapi/devices/bus.hpp | 7 +++++++ kapi/include/kapi/devices/device.hpp | 7 +++++++ kapi/include/kapi/devices/manager.hpp | 2 +- kapi/include/kapi/interrupts.hpp | 31 ++++++++++++++++++++++--------- kapi/include/kapi/memory.hpp | 33 +++++++++++++++++---------------- kapi/include/kapi/system.hpp | 12 ++++++++++-- kapi/kapi.dox | 8 ++++++++ 10 files changed, 113 insertions(+), 46 deletions(-) create mode 100644 kapi/kapi.dox (limited to 'kapi') diff --git a/kapi/include/kapi/cio.hpp b/kapi/include/kapi/cio.hpp index 71b5b02..8941a9f 100644 --- a/kapi/include/kapi/cio.hpp +++ b/kapi/include/kapi/cio.hpp @@ -11,27 +11,38 @@ namespace kapi::cio { - //! @qualifier platform-defined - //! Initialize the character I/O subsystem. - //! - //! @note If a platform support character output, it shall ensure that when this function returns, basic character - //! output can be performed on the system. - auto init() -> void; + //! @addtogroup kapi-cio + //! @{ + //! @} + + //! @addtogroup kapi-cio-kernel-defined + //! @{ - //! @qualifier kernel-defined //! Set the currently active output device. //! //! @param device A new output device. //! @return The previously active output device. auto set_output_device(output_device & device) -> std::optional; - //! @qualifier kernel-defined //! Write a string to the given output stream. //! //! @param stream The output stream to write to. //! @param text The text to write to the stream. auto write(output_stream stream, std::string_view text) -> void; + //! @} + + //! @addtogroup kapi-cio-platform-defined + //! @{ + + //! Initialize the character I/O subsystem. + //! + //! If a platform support character output, it shall ensure that when this function returns, basic character + //! output can be performed on the system. + auto init() -> void; + + //! @} + } // namespace kapi::cio #endif diff --git a/kapi/include/kapi/cpu.hpp b/kapi/include/kapi/cpu.hpp index c6aa6ff..d90365a 100644 --- a/kapi/include/kapi/cpu.hpp +++ b/kapi/include/kapi/cpu.hpp @@ -10,6 +10,9 @@ namespace kapi::cpu { + //! @addtogroup kapi-cpu + //! @{ + //! An exception originating from the CPU directly. //! //! Exception generally model interrupts that are synchronous to the instruction stream. This means that they do not @@ -58,25 +61,34 @@ namespace kapi::cpu bool is_user_mode{}; }; - //! @qualifier platform-defined + //! @} + + //! @addtogroup kapi-cpu-kernel-defined + //! @{ + + //! Dispatch an exception to the appropriate handler. + //! + //! @param context The exception context. + //! @return Whether the exception was handled. + [[nodiscard]] auto dispatch(exception const & context) -> bool; + + //! @} + + //! @addtogroup kapi-cpu-platform-defined + //! @{ + //! Halt the CPU. //! //! This function terminates execution of the kernel. [[noreturn]] auto halt() -> void; - //! @qualifier platform-defined //! Perform early CPU initialization. //! //! When this function returns, the CPU is in a state where interrupt could be enabled. This function must not enable //! interrupts itself. auto init() -> void; - //! @qualifier kernel-defined - //! Dispatch an exception to the appropriate handler. - //! - //! @param context The exception context. - //! @return Whether the exception was handled. - [[nodiscard]] auto dispatch(exception const & context) -> bool; + //! @} } // namespace kapi::cpu diff --git a/kapi/include/kapi/devices.hpp b/kapi/include/kapi/devices.hpp index 5c01b2f..c26efb9 100644 --- a/kapi/include/kapi/devices.hpp +++ b/kapi/include/kapi/devices.hpp @@ -8,7 +8,7 @@ namespace kapi::devices { - //! @addtogroup kernel-defined + //! @addtogroup kapi-devices-kernel-defined //! @{ //! Initialize the kernel's device management subsystem. @@ -23,7 +23,7 @@ namespace kapi::devices //! @} - //! @addtogroup platform-defined + //! @addtogroup kapi-devices-platform-defined //! @{ //! Initialize the platform's device tree. diff --git a/kapi/include/kapi/devices/bus.hpp b/kapi/include/kapi/devices/bus.hpp index ee774b7..052c062 100644 --- a/kapi/include/kapi/devices/bus.hpp +++ b/kapi/include/kapi/devices/bus.hpp @@ -17,6 +17,10 @@ namespace kapi::devices { + + //! @addtogroup kapi-devices + //! @{ + //! A bus device that represents a logical/physical tree of devices and busses. struct bus : device { @@ -90,6 +94,9 @@ namespace kapi::devices kstd::vector> m_observers; std::atomic_flag m_initialized{}; }; + + //! @} + } // namespace kapi::devices #endif \ No newline at end of file diff --git a/kapi/include/kapi/devices/device.hpp b/kapi/include/kapi/devices/device.hpp index a049cf5..b7b6bba 100644 --- a/kapi/include/kapi/devices/device.hpp +++ b/kapi/include/kapi/devices/device.hpp @@ -7,6 +7,10 @@ namespace kapi::devices { + + //! @addtogroup kapi-devices + //! @{ + /** * @brief Base device identified by a major, minor number and name. */ @@ -76,6 +80,9 @@ namespace kapi::devices size_t m_minor; kstd::string m_name; }; + + //! @} + } // namespace kapi::devices #endif \ No newline at end of file diff --git a/kapi/include/kapi/devices/manager.hpp b/kapi/include/kapi/devices/manager.hpp index 7817fbc..f19366e 100644 --- a/kapi/include/kapi/devices/manager.hpp +++ b/kapi/include/kapi/devices/manager.hpp @@ -13,7 +13,7 @@ namespace kapi::devices { - //! @addtogroup kernel-defined + //! @addtogroup kapi-devices-kernel-defined //! @{ //! Ask the kernel to allocate a new major number. diff --git a/kapi/include/kapi/interrupts.hpp b/kapi/include/kapi/interrupts.hpp index f72ef8c..4ba0684 100644 --- a/kapi/include/kapi/interrupts.hpp +++ b/kapi/include/kapi/interrupts.hpp @@ -6,9 +6,15 @@ namespace kapi::interrupts { + //! @addtogroup kapi-interrupts + //! @{ + + //! A status that indicates whether an interrupt was handled by a handler. enum class status : bool { + //! The interrupt was not handled by any handler. unhandled, + //! The interrupt was handled by at least one handler. handled, }; @@ -27,35 +33,42 @@ namespace kapi::interrupts virtual auto handle_interrupt(std::uint32_t irq_number) -> status = 0; }; - //! @qualifier platform-defined - //! Enable external interrupts. - auto enable() -> void; + //! @} - //! @qualifier platform-defined - //! Disable external interrupts. - auto disable() -> void; + //! @addtogroup kapi-interrupts-kernel-defined + //! @{ - //! @qualifier kernel-defined //! Register an interrupt handler for the given IRQ number. //! //! @param irq_number The IRQ number to register the handler for. //! @param handler The interrupt handler to register. auto register_handler(std::uint32_t irq_number, handler & handler) -> void; - //! @qualifier kernel-defined //! Unregister a previously registered interrupt handler. //! //! @param irq_number The IRQ number to unregister the handler for. //! @param handler The interrupt handler to unregister. auto unregister_handler(std::uint32_t irq_number, handler & handler) -> void; - //! @qualifier kernel-defined //! Dispatch an interrupt to all registered handlers. //! //! @param irq_number The IRQ number to dispatch. //! @return status::handled if the interrupt was handled by at least one handler, status::unhandled otherwise. auto dispatch(std::uint32_t irq_number) -> status; + //! @} + + //! @addtogroup kapi-interrupts-platform-defined + //! @{ + + //! Enable external interrupts. + auto enable() -> void; + + //! Disable external interrupts. + auto disable() -> void; + + //! @} + } // namespace kapi::interrupts #endif \ No newline at end of file diff --git a/kapi/include/kapi/memory.hpp b/kapi/include/kapi/memory.hpp index e31fa34..914ca61 100644 --- a/kapi/include/kapi/memory.hpp +++ b/kapi/include/kapi/memory.hpp @@ -16,16 +16,9 @@ namespace kapi::memory { - //! @qualifier platform-defined - //! Initialize the memory subsystem. - //! - //! @note This function must be implemented by the target platform. - //! - //! This function initializes the memory subsystem and activates the platform-specific frame allocator and page - //! mapper. When this function returns, a valid frame allocator and page mapper are expected to have been registered. - auto init() -> void; + //! @addtogroup kapi-memory-kernel-defined + //! @{ - //! @qualifier kernel-defined //! Initialize the physical memory manager. //! //! This function initializes the kernel-wide physical memory manager. The function will invoke the handoff handler to @@ -39,25 +32,21 @@ namespace kapi::memory //! allocator to hand off to is passed to the handler. auto init_pmm(std::size_t frame_count, void (&handoff_handler)(frame_allocator &)) -> void; - //! @qualifier kernel-defined //! Get the currently active frame allocator. auto get_frame_allocator() -> frame_allocator &; - //! @qualifier kernel-defined //! Set the currently active frame allocator. //! //! @param allocator A new frame allocator. //! @return The previously active frame allocator. auto set_frame_allocator(frame_allocator & allocator) -> std::optional; - //! @qualifier kernel-defined //! Set the currently active page mapper. //! //! @param mapper A new page mapper. //! @return The previously active page mapper. auto set_page_mapper(page_mapper & mapper) -> std::optional; - //! @qualifier kernel-defined //! Allocate a new frame of physical memory //! //! @warning This function will panic if no frame allocator has been registered. @@ -65,7 +54,6 @@ namespace kapi::memory //! @return An engaged std::optional iff. a frame could be allocated, std::nullopt otherwise. auto allocate_frame() -> std::optional; - //! @qualifier kernel-defined //! Allocate multiple new frames of physical memory //! //! @warning This function will panic if no frame allocator has been registered. @@ -73,7 +61,6 @@ namespace kapi::memory //! @return An engaged std::optional iff. @p count frames could be allocated, std::nullopt otherwise. auto allocate_many_frames(std::size_t count) -> std::optional>; - //! @qualifier kernel-defined //! Map a page onto a frame. //! //! @warning This function will panic if no page mapper has been registered, or the page has already been mapped. @@ -85,7 +72,6 @@ namespace kapi::memory //! @return A pointer to the first byte of the mapped page. auto map(page page, frame frame, page_mapper::flags flags = page_mapper::flags::empty) -> std::byte *; - //! @qualifier kernel-defined //! Unmap a page. //! //! @warning This function will panic if no page mapper has been registered, or the page is not mapped. @@ -93,6 +79,21 @@ namespace kapi::memory //! @param page The page to unmap auto unmap(page page) -> void; + //! @} + + //! @addtogroup kapi-memory-platform-defined + //! @{ + + //! Initialize the memory subsystem. + //! + //! @note This function must be implemented by the target platform. + //! + //! This function initializes the memory subsystem and activates the platform-specific frame allocator and page + //! mapper. When this function returns, a valid frame allocator and page mapper are expected to have been registered. + auto init() -> void; + + //! @} + } // namespace kapi::memory #endif diff --git a/kapi/include/kapi/system.hpp b/kapi/include/kapi/system.hpp index e5c43c5..8a20af9 100644 --- a/kapi/include/kapi/system.hpp +++ b/kapi/include/kapi/system.hpp @@ -7,7 +7,9 @@ namespace kapi::system { - //! @qualifier kernel-defined + //! @addtogroup kapi-system-kernel-defined + //! @{ + //! Terminate kernel execution with the given error message. //! //! This function terminates the execution of the kernel and attempts to issue the given error message to the user. @@ -15,10 +17,16 @@ namespace kapi::system //! @param message The message associated with the panic [[noreturn]] auto panic(std::string_view message, std::source_location = std::source_location::current()) -> void; - //! @qualifier platform-defined + //! @} // end group kernel-defined + + //! @addtogroup kapi-system-platform-defined + //! @{ + //! A hook that runs once the memory subsystem has been initialized. auto memory_initialized() -> void; + //! @} // end group platform-defined + } // namespace kapi::system #endif diff --git a/kapi/kapi.dox b/kapi/kapi.dox new file mode 100644 index 0000000..929fc1f --- /dev/null +++ b/kapi/kapi.dox @@ -0,0 +1,8 @@ +//! @namespace kapi +//! The Kernel/Platform API +//! +//! This namespace defines the interface between the platform independent kernel and each supported platform. + +//! @defgroup kapi-kernel-defined Kernel-defined API + +//! @defgroup kapi-platform-defined Platform-defined API -- cgit v1.2.3