Crate memory

This crate implements the main memory management subsystem for Theseus.

The primary type of interest is MappedPages, which offers a robust interface that unifies the usage of arbitrary memory regions with that of Rust’s safe type system and lifetimes.

Acknowledgments

Some of the internal page table management code was based on Philipp Oppermann’s blog_os, but has since changed significantly.

Macros

• chunk_sized_expr
  A macro for applying the same field/method accessors to all variants in an enum based on the three possible PageSizes.

Structs

• AllocatedPages
  Represents a range of allocated VirtualAddresses, specified in Pages.
• BorrowedMappedPages
  A borrowed MappedPages object that derefs to &T and optionally also &mut T.
• BorrowedSliceMappedPages
  A borrowed MappedPages object that derefs to a slice &[T] and optionally also &mut [T].
• EarlyIdentityMappedPages
  The set of identity mappings that should be dropped before starting the first application.
• Frame
  A Frame is a chunk of physical memory aligned to a page boundary (default 4KiB) given by the P parameter.
• FrameRange
  A range of Frames that are contiguous in physical memory.
• Immutable
  A marker type used to indicate that a BorrowedMappedPages or BorrowedSliceMappedPages is borrowed immutably.
• InitialMemoryMappings
  Information returned after initialising the memory subsystem.
• MappedPages
  Represents a contiguous range of virtual memory pages that are currently mapped. A MappedPages object can only have a single range of contiguous pages, not multiple disjoint ranges. This does not guarantee that its pages are mapped to frames that are contiguous in physical memory.
• Mapper
• MemoryManagementInfo
  This holds all the information for a Task’s memory mappings and address space (this is basically the equivalent of Linux’s mm_struct)
• Mutable
  A marker type used to indicate that a BorrowedMappedPages or BorrowedSliceMappedPages is borrowed mutably.
• Page
  A Page is a chunk of virtual memory aligned to a page boundary (default 4KiB) given by the P parameter.
• Page1G
  Marker struct used to indicate a page size of 1GiB.
• Page2M
  Marker struct used to indicate a page size of 2MiB.
• Page4K
  Marker struct used to indicate the default page size of 4KiB.
• PageRange
  A range of Pages that are contiguous in virtual memory.
• PageTable
  A top-level root (P4) page table.
• PhysicalAddress
  A physical memory address, which is a usize under the hood.
• PteFlags
  Common, architecture-independent flags for a page table entry (PTE) that define how a page is mapped.
• PteFlagsArchx86-64
  Page table entry (PTE) flags on x86_64.
• PteFlagsX86_64x86-64
  Page table entry (PTE) flags on x86_64.
• VirtualAddress
  A virtual memory address, which is a usize under the hood.

Enums

• AllocationRequest
  Possible options when requesting pages from the page allocator.
• MemChunkSize
  Enum used to indicate the size of a page or frame.
• MemoryState
  The possible states that a range of exclusively-owned pages or frames can be in.

Constants

• DMA_FLAGS
  Mapping flags that can be used to map DMA (Direct Memory Access) memory.
• MMIO_FLAGS
  Mapping flags that can be used to map MMIO registers.
• PAGE_SIZE
  Page size is 4096 bytes, 4KiB pages.
• PTE_FRAME_MASK
  A mask for the bits of a page table entry that contain the physical frame address.

Traits

• Mutability
  A trait for parameterizing a BorrowedMappedPages or BorrowedSliceMappedPages as mutably or immutably borrowed.
• PageSize
  Trait that represents the size of a page or frame, i.e., for normal or huge pages.

Functions

• allocate_frames
  Allocates the given number of frames with no constraints on the starting physical address.
• allocate_frames_at
  Allocates the given number of frames starting at (inclusive of) the frame containing the given PhysicalAddress.
• allocate_frames_by_bytes
  Allocates frames with no constraints on the starting physical address, with a size given by the number of bytes.
• allocate_frames_by_bytes_at
  Allocates frames starting at the given PhysicalAddress with a size given in number of bytes.
• allocate_frames_by_bytes_deferred
  Similar to allocated_frames_deferred(), but accepts a size value for the allocated frames in number of bytes instead of number of frames.
• allocate_frames_deferred
  The core frame allocation routine that allocates the given number of physical frames, optionally at the requested starting PhysicalAddress.
• allocate_pages
  Allocates the given number of pages with no constraints on the starting virtual address.
• allocate_pages_at
  Allocates the given number of pages starting at (inclusive of) the page containing the given VirtualAddress.
• allocate_pages_by_bytes
  Allocates pages with no constraints on the starting virtual address, with a size given by the number of bytes.
• allocate_pages_by_bytes_at
  Allocates pages starting at the given VirtualAddress with a size given in number of bytes.
• allocate_pages_by_bytes_deferred
  Similar to allocated_pages_deferred(), but accepts a size value for the allocated pages in number of bytes instead of number of pages.
• allocate_pages_by_bytes_in_range
  Allocates pages with a size given in number of bytes with the constraint that they must be within the given inclusive range of pages.
• allocate_pages_deferred
  The core page allocation routine that allocates the given number of virtual pages, optionally at the requested starting VirtualAddress.
• allocate_pages_in_range
  Allocates the given number of pages with the constraint that they must be within the given inclusive range of pages.
• create_contiguous_mapping
  A convenience function that creates a new memory mapping by allocating frames that are contiguous in physical memory. If contiguous frames are not required, then see create_mapping(). Returns a tuple containing the new MappedPages and the starting PhysicalAddress of the first frame, which is a convenient way to get the physical address without walking the page tables.
• create_identity_mapping
  Creates an identity mapping at a random available virtual and physical address.
• create_mapping
  A convenience function that creates a new memory mapping. The pages allocated are contiguous in memory but there’s no guarantee that the frames they are mapped to are also contiguous in memory. If contiguous frames are required then see create_contiguous_mapping(). Returns the new MappedPages.
• get_kernel_mmi_ref
  Returns a reference to the kernel’s MemoryManagementInfo, if initialized. If not, it returns None.
• init
  Initializes the virtual memory management system. Consumes the given BootInformation, because after the memory system is initialized, the original BootInformation will be unmapped and inaccessible.
• init_post_heap
  Finishes initializing the memory management system after the heap is ready.
• map_frame_range
  A convenience function that maps randomly-allocated pages to the given range of frames.
• set_broadcast_tlb_shootdown_cb
  Set the function callback that will be invoked every time a TLB shootdown is necessary, i.e., during page table remapping and unmapping operations.
• translate
  A convenience function to translate the given virtual address into a physical address using the currently-active page table.

Type Aliases

• AllocatedFrames
  A type alias for Frames in the Allocated state.
• MmiRef
  A shareable reference to a MemoryManagementInfo struct wrapper in a lock.
• UnmappedFrames
  A type alias for Frames in the Unmapped state.