From 5117ee7b57f7e349d35c88d31b0d3714a2afbcc6 Mon Sep 17 00:00:00 2001 From: Felix Morgner Date: Thu, 20 Aug 2026 16:04:48 +0200 Subject: docs: draft new documentation structure --- docs/briefs/tb0002-x86_64_bootstrap.rst | 4 ++-- docs/conf.py | 10 +++++++++- docs/kapi/capabilities.rst | 13 +++++++++++++ docs/kapi/cio.rst | 27 +++++++++++++++++---------- docs/kapi/cpu.rst | 27 +++++++++++++++++---------- docs/kapi/devices.rst | 27 ++++++++++++++++----------- docs/kapi/devices/busses.rst | 2 ++ docs/kapi/interrupts.rst | 16 +++------------- kapi/kapi.dox | 12 ------------ kapi/kapi/cio.hpp | 8 ++------ kapi/kapi/cio/output_device.hpp | 5 ----- kapi/kapi/cpu.hpp | 9 ++------- kapi/kapi/devices.hpp | 4 ++-- 13 files changed, 85 insertions(+), 79 deletions(-) create mode 100644 docs/kapi/capabilities.rst create mode 100644 docs/kapi/devices/busses.rst delete mode 100644 kapi/kapi.dox diff --git a/docs/briefs/tb0002-x86_64_bootstrap.rst b/docs/briefs/tb0002-x86_64_bootstrap.rst index b7a6c2a9..26b5db18 100644 --- a/docs/briefs/tb0002-x86_64_bootstrap.rst +++ b/docs/briefs/tb0002-x86_64_bootstrap.rst @@ -39,7 +39,7 @@ Component Analysis ------------------ C++/Assembly Interface (``boot.hpp``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A single header file serves as the definitive interface between assembly code and C++. This is achieved through the use of the ``__ASSEMBLER__`` preprocessor macro. @@ -106,7 +106,7 @@ Key Implementation Decisions ---------------------------- ``lret`` Stack Frame Construction -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The transition to 64-bit mode is initiated by executing an ``lret`` instruction from 32-bit protected mode. The behavior of this instruction is determined by the characteristics of the destination code segment descriptor referenced by the selector on the stack. diff --git a/docs/conf.py b/docs/conf.py index 47863a06..1712f2a7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,7 +13,10 @@ author = "Felix Morgner" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ["breathe"] +extensions = [ + "sphinx.ext.todo", + "breathe", +] templates_path = ["_templates"] exclude_patterns = ["pre/**"] @@ -25,6 +28,11 @@ breathe_projects = {"kernel": "../build/doxygen/xml"} breathe_default_project = "kernel" breathe_default_members = ('members', 'undoc-members', 'protected-members', 'private-members') +# -- Options todo --------------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html + +todo_include_todos = True + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/docs/kapi/capabilities.rst b/docs/kapi/capabilities.rst new file mode 100644 index 00000000..a4d7d999 --- /dev/null +++ b/docs/kapi/capabilities.rst @@ -0,0 +1,13 @@ +Capability Dispatch +=================== + +.. todo:: + Document the facet based capability dispatch mechanism. + +API Reference +------------- + +Classes +------- + +.. doxygenstruct:: kapi::capabilities::facet_id \ No newline at end of file diff --git a/docs/kapi/cio.rst b/docs/kapi/cio.rst index 62a36398..15b322fa 100644 --- a/docs/kapi/cio.rst +++ b/docs/kapi/cio.rst @@ -1,17 +1,24 @@ Character I/O Interface ======================= -.. doxygengroup:: kapi-cio - :content-only: +The character I/O interface defines a simple API allowing the kernel to write characters to a platform's output device. -Kernel-defined API ------------------- +API Reference +------------- -.. doxygengroup:: kapi-cio-kernel-defined - :content-only: +Functions +--------- -Platform-defined API --------------------- +.. doxygenfunction:: kapi::cio::init +.. doxygenfunction:: kapi::cio::set_output_device +.. doxygenfunction:: kapi::cio::write -.. doxygengroup:: kapi-cio-platform-defined - :content-only: +Classes +------- + +.. doxygenstruct:: kapi::cio::output_device + +Enums +----- + +.. doxygenenum:: kapi::cio::output_stream diff --git a/docs/kapi/cpu.rst b/docs/kapi/cpu.rst index 0793dd8c..ab5d182f 100644 --- a/docs/kapi/cpu.rst +++ b/docs/kapi/cpu.rst @@ -1,17 +1,24 @@ CPU Interface ============= -.. doxygengroup:: kapi-cpu - :content-only: +.. todo:: + Write an introduction to the CPU interface. -Kernel-defined API ------------------- +Functions +--------- -.. doxygengroup:: kapi-cpu-kernel-defined - :content-only: +.. doxygenfunction:: kapi::cpu::dispatch +.. doxygenfunction:: kapi::cpu::halt +.. doxygenfunction:: kapi::cpu::init +.. doxygenfunction:: kapi::cpu::current_id -Platform-defined API --------------------- +Classes +------- -.. doxygengroup:: kapi-cpu-platform-defined - :content-only: +.. doxygenstruct:: kapi::cpu::exception +.. doxygenstruct:: kapi::cpu::id + +Constants +--------- + +.. doxygenvariable:: kapi::cpu::invalid_id \ No newline at end of file diff --git a/docs/kapi/devices.rst b/docs/kapi/devices.rst index c9853a1c..8b674e6e 100644 --- a/docs/kapi/devices.rst +++ b/docs/kapi/devices.rst @@ -1,17 +1,22 @@ Device Interface ================ -.. doxygengroup:: kapi-devices - :content-only: +.. toctree:: + :maxdepth: 1 + :caption: Contents: + :glob: -Kernel-defined API ------------------- + devices/* -.. doxygengroup:: kapi-devices-kernel-defined - :content-only: +API Reference +------------- -Platform-defined API --------------------- - -.. doxygengroup:: kapi-devices-platform-defined - :content-only: +.. doxygenfunction:: kapi::devices::init +.. doxygenfunction:: kapi::devices::get_root_bus +.. doxygenfunction:: kapi::devices::remove_device +.. doxygenfunction:: kapi::devices::publish_facet(kstd::shared_ptr, kstd::string) +.. doxygenfunction:: kapi::devices::publish_facet(kstd::shared_ptr, kstd::string, Facet *) +.. doxygenfunction:: kapi::devices::init_platform_drivers +.. doxygenfunction:: kapi::devices::init_platform_devices +.. doxygenfunction:: kapi::devices::discover_cpu_topology +.. doxygenfunction:: kapi::devices::get_cpu_bus \ No newline at end of file diff --git a/docs/kapi/devices/busses.rst b/docs/kapi/devices/busses.rst new file mode 100644 index 00000000..22b3a79e --- /dev/null +++ b/docs/kapi/devices/busses.rst @@ -0,0 +1,2 @@ +Busses +====== \ No newline at end of file diff --git a/docs/kapi/interrupts.rst b/docs/kapi/interrupts.rst index 7150f076..f921b77e 100644 --- a/docs/kapi/interrupts.rst +++ b/docs/kapi/interrupts.rst @@ -1,17 +1,7 @@ Interrupt Interface =================== -.. doxygengroup:: kapi-interrupts - :content-only: +API Reference +------------- -Kernel-defined API ------------------- - -.. doxygengroup:: kapi-interrupts-kernel-defined - :content-only: - -Platform-defined API --------------------- - -.. doxygengroup:: kapi-interrupts-platform-defined - :content-only: +.. doxygenfile:: kapi/interrupts.hpp \ No newline at end of file diff --git a/kapi/kapi.dox b/kapi/kapi.dox deleted file mode 100644 index 09b06e44..00000000 --- a/kapi/kapi.dox +++ /dev/null @@ -1,12 +0,0 @@ -//! @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 - -//! @defgroup kapi-boot-modules Boot Modules API - -//! @defgroup kapi-boot_modules-kernel-defined Boot Modules API (kernel defined) diff --git a/kapi/kapi/cio.hpp b/kapi/kapi/cio.hpp index 5c4cc8b7..f6906673 100644 --- a/kapi/kapi/cio.hpp +++ b/kapi/kapi/cio.hpp @@ -11,11 +11,7 @@ namespace kapi::cio { - //! @addtogroup kapi-cio - //! @{ - //! @} - - //! @addtogroup kapi-cio-kernel-defined + //! @name Kernel-defined API //! @{ //! Set the currently active output device. @@ -32,7 +28,7 @@ namespace kapi::cio //! @} - //! @addtogroup kapi-cio-platform-defined + //! @name Platform-defined API //! @{ //! Initialize the character I/O subsystem. diff --git a/kapi/kapi/cio/output_device.hpp b/kapi/kapi/cio/output_device.hpp index c241a10c..9fe25577 100644 --- a/kapi/kapi/cio/output_device.hpp +++ b/kapi/kapi/cio/output_device.hpp @@ -8,9 +8,6 @@ namespace kapi::cio { - //! @addtogroup kapi-cio - //! @{ - enum struct output_stream { stdout, @@ -37,8 +34,6 @@ namespace kapi::cio output_device() = default; }; - //! @} - } // namespace kapi::cio #endif diff --git a/kapi/kapi/cpu.hpp b/kapi/kapi/cpu.hpp index 7337a45a..ce35c18b 100644 --- a/kapi/kapi/cpu.hpp +++ b/kapi/kapi/cpu.hpp @@ -12,9 +12,6 @@ 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 @@ -74,9 +71,7 @@ namespace kapi::cpu //! The invalid CPU id. constexpr auto static invalid_id = id{std::numeric_limits::max()}; - //! @} - - //! @addtogroup kapi-cpu-kernel-defined + //! @name Kernel-defined API //! @{ //! Dispatch an exception to the appropriate handler. @@ -87,7 +82,7 @@ namespace kapi::cpu //! @} - //! @addtogroup kapi-cpu-platform-defined + //! @name Platform-defined API //! @{ //! Halt the CPU. diff --git a/kapi/kapi/devices.hpp b/kapi/kapi/devices.hpp index 0781357c..21ecde14 100644 --- a/kapi/kapi/devices.hpp +++ b/kapi/kapi/devices.hpp @@ -21,7 +21,7 @@ namespace kapi::devices { - //! @addtogroup kapi-devices-kernel-defined + //! @name Kernel-defined API //! @{ //! Initialize the kernel's device management subsystem. @@ -65,7 +65,7 @@ namespace kapi::devices //! @} - //! @addtogroup kapi-devices-platform-defined + //! @name Platform-defined API //! @{ //! Initialize the platform's drivers. -- cgit v1.2.3