From d74936964ecd5e5c961b90feb9323ca999ce9026 Mon Sep 17 00:00:00 2001 From: Felix Morgner Date: Wed, 3 Dec 2025 17:23:12 +0100 Subject: x86_64/memory: improve scoped_mapping docs --- .../include/x86_64/memory/scoped_mapping.hpp | 35 ++++++++++++++++++---- 1 file changed, 30 insertions(+), 5 deletions(-) (limited to 'arch') diff --git a/arch/x86_64/include/x86_64/memory/scoped_mapping.hpp b/arch/x86_64/include/x86_64/memory/scoped_mapping.hpp index 5737bb0..dff54ec 100644 --- a/arch/x86_64/include/x86_64/memory/scoped_mapping.hpp +++ b/arch/x86_64/include/x86_64/memory/scoped_mapping.hpp @@ -8,26 +8,51 @@ namespace teachos::memory::x86_64 { + //! A page mapping that, if established, maps a given frame to a given unused page, unmapping it on destruction. It + //! allows for an easy way to quickly map a page that is not required to be mapped forever. When mapping a frame, new + //! page tables may be allocated. On destruction, these pages tables, or rather their respective frames, will be + //! released again. struct scoped_mapping { - scoped_mapping(scoped_mapping const &) = delete; - scoped_mapping(scoped_mapping &&); + //! Copying a scoped mapping would be meaningless. + scoped_mapping(scoped_mapping const &) noexcept = delete; + + //! Adopt an existing scoped mapping, transferring mapping ownership to this new object. + scoped_mapping(scoped_mapping &&) noexcept; + + //! Construct a new scoped mapping, which can be used to map a frame to the given unused page. + //! @param page An unused page. If the page is already mapped, this constructor will panic. + //! @param allocator An allocator to be used to allocate any page maps required to map the frame. scoped_mapping(page page, frame_allocator & allocator); - ~scoped_mapping(); + //! Unmap the mapped frame if one was mapped. + //! @note Any page tables that were allocated to support the mapping will be released. + ~scoped_mapping() noexcept; + //! Copying a scoped mapping would be meaningless. auto operator=(scoped_mapping const &) -> scoped_mapping = delete; - auto operator=(scoped_mapping &&) -> scoped_mapping &; + //! Adopt an existing scoped mapping, swapping mapping ownerships between the objects. + auto operator=(scoped_mapping &&) noexcept -> scoped_mapping &; + + //! Map the given frame with the given flags. + //! @note If a mapping has already been established, this function will panic + //! @param frame A frame to map. + //! @param flags The flags, besides the present flag, to apply to the mapping. + //! @return A pointer to the first byte of the mapped frame. auto map(frame frame, page_table::entry::flags flags) -> std::byte *; - auto unmap() -> void; + //! Map the given frame, returning a typed pointer. template auto map_as(frame frame, page_table::entry::flags flags) -> DataType * { return std::bit_cast(map(frame, flags)); } + //! Unmap the mapped frame. + //! @note If no frame was ever mapped, this function will panic. + auto unmap() -> void; + private: page m_page; frame_allocator * m_allocator; -- cgit v1.2.3