D/xomb
1
0
Fork 0
mirror of https://github.com/xomboverlord/xomb.git synced 2026-01-11 18:33:15 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Updates system design docs.

Browse Source
This commit is contained in:
wilkie
2025-12-30 02:26:30 -05:00
parent 3da042e53b
commit ac18e25ddc
3 changed files with 33 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/MEMORY.md
View File

@@ -24,13 +24,14 @@ The kernel system calls related to page allocation and mapping have an enumerate
* `3`: `NOT_ALLOCATED` - The physical page cannot be freed because it was not allocated.
* `4`: `INVALID_SOURCE` - The given virtual address is not a valid virtual address for the current Process.
* `5`: `INVALID_TARGET` - The given virtual address to map to is not a valid virtual address for the current Process.
* `6`: `NOT_EMPTY` - The physical page is a page table structure that represents a Resource or Process and it is not empty.
The kernel provides these basic physical memory primitive functions:
* `ALLOC_PAGE(physicalAddress, virtualAddress, flags) -> MapperError` - Allocates the given physical page to the given virtual address of the Process, if there is no page currently mapped there. `virtualAddress` points to the specific page table entry to modify using the recursive entry (`PML4[510]`) to do so. The kernel will mark that physical page allocated. This returns `NOT_FREE` if that physical page is already allocated. Sets the flags on the leaf PML1 page table entry. The `flags` field is a set of flags that are not in any hardware specific order. They are defined by the system. See the aforemented structure. The `flags` field must indicate the `Present` flag and otherwise returns `INVALID_FLAGS` and fails. If the given `virtualAddress` is not aligned to a page table entry, the page table structure does not exist, or it is not one that is owned by the current Process, then it fails with an `INVALID_TARGET` error. Ownership is decided by whether or not there is an `Owner` flag when walking the page table structure while not seeing a `Grant` flag before getting to the point specified by the given `virtualAddress`. The root of the process is always considered marked `Owner`. Therefore, you can only allocate pages into a Resource or child Process that is 'owned' by the calling Process.
* `REMAP_PAGE(virtualAddress, targetAddress) -> MapperError` - Atomically moves the physical page that is allocated to the page table entry denoted by the given `virtualAddress` to being mapped into the empty page table entry given by `targetAddress`. Fails by returning `INVALID_SOURCE` if the `virtualAddress` is not aligned to a page table entry, is in a non-existing page table structure, is unmapped, or not owned by the current Process. Ownership is known by finding an `Owner` flag set when walking the page table structure. The root of the process is always considered marked `Owner`. Ownership is always void if a `Grant` flag is found when walking the structure instead. Does nothing if `virtualAddress` and `targetAddress` are effectively the same. Fails by returning `INVALID_TARGET` if the `targetAddress` is not aligned to a page table entry, is within a page table structure that does not exist, or it is not one that is owned by the current Process. It keeps the same flags.
* `CHMOD_PAGE(virtualAddress, flags) -> MapperError` - Sets new flags on the given virtual address page table entry. Must be aligned to a page. Userspace processes can use the recursive page index `PML4[510]` in order to target an inner page table entry. Fails by returning `INVALID_SOURCE` if the page table entry to update is not in userspace. Fails by returning `INVALID_FLAGS` if the `flags` provided cannot be accommodated or specify flags that do not exist. Fails by returning `INVALID_SOURCE` if `virtualAddress` is not aligned to a page table entry, is within a non-existant page table structure, or the page table structure is not owned by the calling Process. Ownership is known by finding an `Owner` flag set when walking the page table structure. The root of the process is always considered marked `Owner`. Ownership is always void if a `Grant` flag is found when walking the structure instead.
* `UNMAP_PAGE(virtualAddress) -> MapperError` - Clears the page mapped at the page table entry at the given `virtualAddress`. This frees that physical page while voiding out that page table entry within the Process. Fails by returning `NOT_ALLOCATED` if the physical page is not one that is in the allocatable space tracked by the page allocator. Fails by returning `INVALID_SOURCE` if the virtualAddress is unmapped or not owned by the current Process. Fails by returning `INVALID_SOURCE` if the page table structure is not owned by the calling Process. Ownership is known by finding an `Owner` flag set when walking the page table structure. The root of the process is always considered marked `Owner`. Ownership is always void if a `Grant` flag is found when walking the structure instead.
* `MAP_ZERO(virtualAddress, flags) -> MapperError` - Maps in a kernel maintained 'zero' page which is a page that is prewritten with 0s. The kernel forcibly maps this in read-only. Therefore, this fails by returning `INVALID_FLAGS` if `flags` does not indicate the `ReadOnly` and `Present` flags. This fails with `INVALID_TARGET` if the `virtualAddress` is not aligned to a page table entry, is indicating a page table structure that does not exist, or is not owned by the calling Process. Ownership is known by finding an `Owner` flag set when walking the page table structure. The root of the process is always considered marked `Owner`. Ownership is always void if a `Grant` flag is found when walking the structure instead.
* `UNMAP_PAGE(virtualAddress) -> MapperError` - Clears the page mapped at the page table entry at the given `virtualAddress`. This frees that physical page while voiding out that page table entry within the Process. Fails by returning `NOT_ALLOCATED` if the physical page is not one that is in the allocatable space tracked by the page allocator. Fails by returning `INVALID_SOURCE` if the virtualAddress is unmapped or not owned by the current Process. Fails by returning `INVALID_SOURCE` if the page table structure is not owned by the calling Process. Ownership is known by finding an `Owner` flag set when walking the page table structure. The root of the process is always considered marked `Owner`. Ownership is always void if a `Grant` flag is found when walking the structure instead. If the page table entry in question has the `Owner` flag, this is a Resource or Process. For a `Grant` entry, this will clear the page table entry and decrement the reference count. For an `Owner` entry, this call will fail with `NOT_EMPTY` unless the page table is empty. This call will fail if the `Owner` entry is set but the reference count for the Resource is not zero. The calling Process must revoke all grantees of this Resource to free the page. To then ultimately free a Resource, the owner must free all pages within the Resource including the page table structure itself.
* `MAP_ZERO(virtualAddress, flags) -> MapperError` - Maps in a kernel maintained 'zero' page which is a page that is prewritten with zeros. The kernel forcibly maps this in read-only. Therefore, this fails by returning `INVALID_FLAGS` if `flags` does not indicate the `ReadOnly` and `Present` flags. This fails with `INVALID_TARGET` if the `virtualAddress` is not aligned to a page table entry, is indicating a page table structure that does not exist, or is not owned by the calling Process. Ownership is known by finding an `Owner` flag set when walking the page table structure. The root of the process is always considered marked `Owner`. Ownership is always void if a `Grant` flag is found when walking the structure instead.
The kernel physical page bitmap that shows which pages are allocated and which ones are not is a readable structure at a well-known virtual address. All library OSes can read the bitmap to find a free page. Therefore, a library OS can implement its own page allocator, although it must cooperate with other page allocators on the system.