docs: man: Add pmap(9) page

Signed-off-by: Ian Moffett <ian@osmora.org>

2 files changed, 70 insertions, 1 deletions

diff --git a/share/man/man9/pmap.9 b/share/man/man9/pmap.9
new file mode 100644
index 0000000..f549886
--- /dev/null
+++ b/share/man/man9/pmap.9
@@ -0,0 +1,66 @@
+.\" Copyright (c) 2023-2024 Ian Marco Moffett and the Osmora Team.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright notice,
+.\"    this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of Hyra nor the names of its
+.\"    contributors may be used to endorse or promote products derived from
+.\"    this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.Dd Jan 12 2024
+.Dt PMAP 9
+.Os Hyra
+.Sh NAME
+.Nm pmap - hyra machine dependent virtual memory layer
+.Sh SYNOPSIS
+.In vm/pmap.h
+
+.Ft pmap_map(struct vm_ctx *, vaddr_t, paddr_t, vm_prot_t);
+.Sh DESCRIPTION
+The machine dependent virtual memory layer contains a standard set of
+functions that shall be implemented per architecture and left alone
+outside of vm(9). vm(9) uses pmap routines internally which allows for
+abstracting away machine dependent details.
+
+The
+.Ft pmap_map()
+function is used to map a physical address (paddr_t) to
+a virtual address (vaddr_t). The argument of type
+vm_prot_t is used to give a mapping certain access
+rules. These rules are described below:
+
+The
+.Ft PMAP_WRITABLE
+bit tells pmap_map() to allow writes to the page.
+Writes to pages without this bit will result in an exception,
+on AMD64 a #PF will occur.
+
+The
+.Ft PMAP_EXEC
+bit tells pmap_map() to allow this page to be
+executable. On platforms like AMD64, execution of pages
+without this bit will result in an exception from the
+instruction fetch, for AMD64, a #PF will occur.
+
+.Sh AUTHORS
+.An Ian Moffett Aq Mt ian@osmora.org
+
+.Sh SEE ALSO
+.Xr vm 9
diff --git a/share/man/man9/vm.9 b/share/man/man9/vm.9
index 667b622..d885895 100644
--- a/share/man/man9/vm.9
+++ b/share/man/man9/vm.9
@@ -34,7 +34,9 @@
 .Sh DESCRIPTION
 The Hyra virtual memory subsystem handles various aspects of
 virtual memory like memory mapping, keeping track of the virtual
-memory context per core, etc.
+memory context per core, etc.   It is split up into two layers, the
+machine independent layer (that this manpage describes), and the
+machine dependent layer called the pmap layer.
 
 The term `kernel physical address' will be used to describe physical
 addresses that are mapped to the higher half.
@@ -62,3 +64,4 @@ physical address.
 
 .Sh SEE ALSO
 .Xr dynalloc 9
+.Xr pmap 9