summaryrefslogtreecommitdiff
path: root/share
diff options
context:
space:
mode:
Diffstat (limited to 'share')
-rw-r--r--share/docs/ideas/kport.txt79
-rw-r--r--share/man/man1/omar.155
-rw-r--r--share/man/man9/dcdr.92
-rw-r--r--share/man/man9/dynalloc.92
-rw-r--r--share/man/man9/kconf.981
-rw-r--r--share/man/man9/mmio.966
-rw-r--r--share/man/man9/panic.92
-rw-r--r--share/man/man9/pci_conf.978
-rw-r--r--share/man/man9/spinlock.92
-rw-r--r--share/man/man9/timer.92
-rw-r--r--share/man/man9/vm.946
-rw-r--r--share/man/man9/vm_map.997
-rw-r--r--share/misc/contrib189
-rw-r--r--share/misc/pdn14
-rw-r--r--share/misc/tmpfs15
15 files changed, 725 insertions, 5 deletions
diff --git a/share/docs/ideas/kport.txt b/share/docs/ideas/kport.txt
new file mode 100644
index 0000000..de3a4b0
--- /dev/null
+++ b/share/docs/ideas/kport.txt
@@ -0,0 +1,79 @@
+Copyright(c) Mon Apr 14 02:17:02 AM EDT 2025 Ian M. Moffett, OSMORA
+---------------------------------------------------------------------------
+***************************************************************************
+All use of any articles/subjects from this doucment MUST retain ALL and ANY
+forms of credit included. ALL Corporate and Government entities MUST
+contact ian@osmora.org WITH intent of use BEFORE consideration of usage.
+***************************************************************************
+
+Author: Ian M. Moffett
+Description: KPORT facilitates seamless low-latency access to dedicated
+ kernel structures securely, while bypassing the need for
+ syscalls.
+---------------------------------------------------------------------------
+ ubuf
+ |
+ kport
+ |
+ shadow
+ |
+ scache [write-through shadow cache]
+ |
+ resource
+
+
+
+ resource (write)
+ \
+ \
+ [write]
+ \
+ \
+ scache
+ /
+ /
+ shadow
+ /
+ /
+ kport [r/w]
+ /
+ ubuf
+
+
+ struct resource_ops {
+ void(*read)(...);
+ void(*write)(...)
+ };
+
+
+ struct resource {
+ void *data;
+ size_t size;
+ ...
+ struct resource_ops rops; /* not the spooky kind! */
+ };
+
+---------------------------------------------------------------------------
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+ capitals, as shown here.
+---------------------------------------------------------------------------
+ * configurable in sys/arch/<arch>/conf/ *
+ |
+ |
+ kport_allocz(page_count)
+ \
+ [pool]
+
+ Semantics:
+ - All accesses MUST be aligned by the machine word size (-EFAULT otherwise)
+ - The size of each access MUST be compared with the kport pool size (-EFAULT otherwise)
+ - The kport pool MUST have no low-level memory caching
+ Notes:
+ The shadow layer exists as a sandbox to isolate the backing resource
+ between itself and the kport layer. It SHOULD contain a "shadow byte region"
+ (SBR), that is, an area reserved for shadow bytes used to detect clobbering
+ and allowing the kernel to respond accordingly (i.e., defer next write-back
+ and kill the process, among other things...)
diff --git a/share/man/man1/omar.1 b/share/man/man1/omar.1
new file mode 100644
index 0000000..611b6da
--- /dev/null
+++ b/share/man/man1/omar.1
@@ -0,0 +1,55 @@
+.\" Copyright (c) 2025 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 May 2 2025
+.Dt OMAR 1
+.Os HYRA
+.Sh NAME
+.Nm omar - OSMORA Archive Format
+.Sh SYNOPSIS
+omar -i [input] -o [output]
+
+.Sh DESCRIPTION
+Prepare files for use in an initramfs
+
+.Ft -i
+ input path directory
+
+.Ft -o
+ output path
+
+Upon creation of the archive image, OMAR will
+produce pathnames through stdout with the following
+types in square brackets ([])
+
+.Ft [f]
+ Regular file
+
+.Ft [d]
+ Directory
+
+.Sh AUTHORS
+.An Ian Moffett Aq Mt ian@osmora.org
diff --git a/share/man/man9/dcdr.9 b/share/man/man9/dcdr.9
index 1b8995a..37d7622 100644
--- a/share/man/man9/dcdr.9
+++ b/share/man/man9/dcdr.9
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2023-2024 Ian Marco Moffett and the Osmora Team.
+.\" Copyright (c) 2023-2025 Ian Marco Moffett and the Osmora Team.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
diff --git a/share/man/man9/dynalloc.9 b/share/man/man9/dynalloc.9
index d1c4723..c59c8b7 100644
--- a/share/man/man9/dynalloc.9
+++ b/share/man/man9/dynalloc.9
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2023-2024 Ian Marco Moffett and the Osmora Team.
+.\" Copyright (c) 2023-2025 Ian Marco Moffett and the Osmora Team.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
diff --git a/share/man/man9/kconf.9 b/share/man/man9/kconf.9
new file mode 100644
index 0000000..0257e9b
--- /dev/null
+++ b/share/man/man9/kconf.9
@@ -0,0 +1,81 @@
+.\" Copyright (c) 2023-2025 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 Jun 7 2025
+.Dt KCONF 9
+.Os Hyra
+.Sh NAME
+.Nm kconf - Hyra kernel configuration
+.Sh SYNOPSIS
+GENERIC configuration:
+.Ft sys/arch/<arch>/conf/GENERIC
+
+Kconf sources:
+.Ft tools/kconf/
+
+.Sh DESCRIPTION
+
+Hyra provides the kconf format for kernel configuration by allowing
+the user to create defines that represent yes/no options and fixed values.
+
+Running kconf on a configuration file results in define flags (-D__KEY=val) to
+be generated so that they may be passed to the compiler of choice.
+
+The
+.Ft option
+keyword allows users to define an option that
+can either be yes or no. For example, the following
+may be used to create an option "FOO" to be set to "yes":
+
+.Ft option FOO yes
+
+This will be given to the kernel as __FOO, for yes/no options the value
+of either 1 (yes) or 0 will be given.
+
+Similarly, a user may create a define that holds a fixed value
+by using the
+.Ft setval
+keyword.
+
+For example, the following may be used to create an option
+"MEOW" set to 0xCA7F00D:
+
+.Ft setval MEOW 0xCA7F00D
+
+These options can be read within the kernel by checking if
+the define exists and potentially falling back to a default
+value if not. This example shows how "MEOW" can be read:
+
+.Bd -literal
+#if defined(__MEOW) /* Option is prefixed with "__" */
+#define MEOW __MEOW
+#else
+#define MEOW 0
+#endif /* __MEOW */
+.Ed
+
+.Sh AUTHORS
+.An Ian Moffett Aq Mt ian@osmora.org
diff --git a/share/man/man9/mmio.9 b/share/man/man9/mmio.9
new file mode 100644
index 0000000..4ede196
--- /dev/null
+++ b/share/man/man9/mmio.9
@@ -0,0 +1,66 @@
+.\" Copyright (c) 2023-2025 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 Feb 18 2025
+.Dt MMIO 9
+.Os Hyra
+.Sh NAME
+.Nm mmio - hyra MMIO interface
+.Sh SYNOPSIS
+.In sys/mmio.h
+
+.Bd -literal
+static inline void mmio_write8(void *addr, uint8_t val);
+static inline void mmio_write16(void *addr, uint16_t val);
+static inline void mmio_write32(void *addr, uint32_t val);
+#if __SIZEOF_SIZE_T__ == 8
+static inline void mmio_write64(void *addr, uint64_t val);
+#endif
+__extension__
+.Ed
+
+.Sh DESCRIPTION
+In short, MMIO is a method of writing to registers
+of an I/O device via a mapped porition of memory. MMIO
+should NOT be done on your own when doing Hyra kernel programming.
+Instead, rely on Hyra's MMIO interface and use
+.Ft mmio_read<n>()
+and
+.Ft mmio_write<n>()
+functions. Where `n` is 8 to 32 on 32-bit machines, and to 64
+on 64-bit machines.
+
+The
+.Ft addr
+argument can be either a physical address or virtual
+address; however, it is recommended to use virtual addresses
+for the sake of consistency.
+
+.Sh SEE ALSO
+.Xr vm_map 9,
+
+.Sh AUTHORS
+.An Ian Moffett Aq Mt ian@osmora.org
diff --git a/share/man/man9/panic.9 b/share/man/man9/panic.9
index bc60547..48a6da4 100644
--- a/share/man/man9/panic.9
+++ b/share/man/man9/panic.9
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2023-2024 Ian Marco Moffett and the Osmora Team.
+.\" Copyright (c) 2023-2025 Ian Marco Moffett and the Osmora Team.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
diff --git a/share/man/man9/pci_conf.9 b/share/man/man9/pci_conf.9
new file mode 100644
index 0000000..4db07f3
--- /dev/null
+++ b/share/man/man9/pci_conf.9
@@ -0,0 +1,78 @@
+.\" 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 Feb 20 2024
+.Dt PCI_CONF 9
+.Os Hyra
+.Sh NAME
+.Nm pci_conf - PCI config space interface
+.Sh SYNOPSIS
+.In dev/pci/pci.h
+
+.Ft pcireg_t
+.Fn pci_readl "struct pci_device *dev" "uint32_t offset"
+
+.Ft void
+.Fn pci_writel "struct pci_device *dev" "uint32_t offset" "pcireg_t val"
+
+.Sh DESCRIPTION
+The PCI configuration space is a 256-byte region implemented
+per device, consisting of registers used for host-to-device
+communication and device-specific configuration.
+
+The Hyra PCI driver provides an API for interfacing
+with a device's configuration space.
+
+The
+.Ft pci_readl()
+function returns a 32-bit value from the
+configuration space of the device pointed
+to by the
+.Ft dev
+argument. The
+.Ft offset
+argument describes how far into the configuration
+space should be read from.
+
+The
+.Ft pci_writel()
+function writes a 32-bit value into the configuration
+space of the device pointed to by the
+.Ft dev
+argument. The
+.Ft offset
+argument describes how far into the configuration space
+.Ft val
+should be written to.
+
+For more information, refer to section 6 of the PCI Local Bus
+Specification 3.0
+
+.Sh AUTHORS
+.An Ian Moffett Aq Mt ian@osmora.org
+
+.Sh HISTORY
+First appeared in Hyra v1.2
diff --git a/share/man/man9/spinlock.9 b/share/man/man9/spinlock.9
index 26cdc31..3d5b941 100644
--- a/share/man/man9/spinlock.9
+++ b/share/man/man9/spinlock.9
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2023-2024 Ian Marco Moffett and the Osmora Team.
+.\" Copyright (c) 2023-2025 Ian Marco Moffett and the Osmora Team.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
diff --git a/share/man/man9/timer.9 b/share/man/man9/timer.9
index d5f3c98..1c456a4 100644
--- a/share/man/man9/timer.9
+++ b/share/man/man9/timer.9
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2023-2024 Ian Marco Moffett and the Osmora Team.
+.\" Copyright (c) 2023-2025 Ian Marco Moffett and the Osmora Team.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
diff --git a/share/man/man9/vm.9 b/share/man/man9/vm.9
new file mode 100644
index 0000000..7601a45
--- /dev/null
+++ b/share/man/man9/vm.9
@@ -0,0 +1,46 @@
+.\" Copyright (c) 2023-2025 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 Jun 6 2024
+.Dt VM 9
+.Os Hyra
+.Sh NAME
+.Nm vm - hyra virtual memory subsystem
+.Sh SYNOPSIS
+.In vm/vm.h
+
+.Sh DESCRIPTION
+The Hyra virtual memory subsystem is a crucial subsystem within the
+kernel. This subsystem facilitates machine independent management of
+per-process virtual address spaces and has many frameworks within that
+allow abstractions over various things such as pages, memory mapping, and
+objects.
+
+.Sh AUTHORS
+.An Ian Moffett Aq Mt ian@osmora.org
+
+.Sh SEE ALSO
+.Xr vm_map 9
diff --git a/share/man/man9/vm_map.9 b/share/man/man9/vm_map.9
new file mode 100644
index 0000000..9c5a3f6
--- /dev/null
+++ b/share/man/man9/vm_map.9
@@ -0,0 +1,97 @@
+.\" Copyright (c) 2023-2025 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 Jun 6 2024
+.Dt VM_MAP 9
+.Os Hyra
+.Sh NAME
+.Nm vm_map - create/destory a virtual memory mapping
+.Sh SYNOPSIS
+.In vm/map.h
+
+.Ft int
+.Fn vm_map "struct vas vas" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" "size_t count"
+
+.Ft int
+.Fn vm_unmap "struct vas vas" "vaddr_t va" "size_t count"
+
+.Sh DESCRIPTION
+
+The Hyra virtual memory mapping framework provides a machine independent
+interface for mapping and unmapping pages to respective page frames.
+
+The
+.Fn vm_map
+function creates a virtual to physical memory mapping.
+
+The
+.Fa vas
+argument specifies the virtual address space for the mapping
+to be created within.
+
+The
+.Fa va
+argument specifies the virtual address to be mapped.
+
+The
+.Fa pa
+argument specifies the physical address that
+.Fa va
+is to be mapped to.
+
+The
+.Fa prot
+argument specifies the virtual memory protection flags.
+
+The
+.Fa count
+argument specifies the number of bytes to be mapped which
+is to be aligned to the machine's page size.
+
+The
+.Fn vm_unmap
+function destroys a virtual to physical memory mapping.
+
+The
+.Fa vas
+argument specifies the virtual address space for the mapping
+to be destroyed within.
+
+
+The
+.Fa va
+argument specifies the virtual address to be unmapped.
+
+The
+.Fa count
+argument specifies the number of bytes to be unmapped which
+is to be aligned to the machine's page size.
+
+.Sh AUTHORS
+.An Ian Moffett Aq Mt ian@osmora.org
+
+.Sh SEE ALSO
+.Xr vm_map 9
diff --git a/share/misc/contrib b/share/misc/contrib
new file mode 100644
index 0000000..39c9c02
--- /dev/null
+++ b/share/misc/contrib
@@ -0,0 +1,189 @@
+==============================
+Hyra Contribution Guidelines
+==============================
+
+!! C PROGRAMMING STYLE !!
+
+The .vimrc file that follows this style can be found in
+share/misc/vimrc
+
+Indent width is 4-spaces (NO TABS)
+
+The typename must go above the function name like so:
+
+static inline bool
+is_power_of_two(uint8_t n)
+{
+ if (g_foo) {
+ ...
+ }
+
+ return ((n & 0x01) == 0);
+}
+
+--
+When defining local variables in functions, they
+must be declared at the top:
+
+static void
+foo(void)
+{
+ uint8_t byte;
+ uint16_t pair;
+ uint32_t quad;
+ uint64_t oct;
+
+ ...
+}
+--
+
+When checking if an integer is 0 or not, *be explicit* unless it is a bool!
+Do not do this:
+
+#define BLAH 1
+
+if (!BLAH) {
+ ...
+}
+
+Do this instead:
+
+if (BLAH == 0) {
+ ...
+}
+
+-- or if it is a bool:
+
+#define BLAH true
+
+if (!blah) {
+ ...
+}
+
+--
+
+When writing switch statements, no indentation is needed
+before the "case" statement, do this:
+
+switch (v) {
+case 0:
+ ...
+ break;
+case 1:
+ ...
+ break;
+case 2:
+ ...
+ break;
+}
+
+Not this:
+
+
+switch (v) {
+case 0:
+ ...
+ break;
+case 1:
+ ...
+ break;
+case 2:
+ ...
+ break;
+}
+
+--
+Now, only use predefined integer types in sys/cdefs.h like so:
+
+uint8_t a;
+uint16_t b;
+uint32_t c;
+--
+
+All includes must be done with '< >':
+
+#include <sys/cdefs.h>
+--
+
+
+When including architecture specific things, it would be stupid
+to include for another architecture. Only include from machine/ which
+points to the architecture specific files for the current architecture.
+For example:
+
+/* AMD64-specific, in sys/include/arch/amd64/lapic.h */
+#include <machine/lapic.h>
+--
+
+Avoid initializing variables to e.g. 0 unless it seems wise to do so.
+Try to avoid this:
+
+uint8_t foo = 0;
+...
+
+It is best to do this instead:
+
+uint8_t foo;
+...
+
+foo = some_calculation();
+--
+
+One of the only times it is best to do that is when you have
+a pointer, like, for example:
+
+uint8_t *ptr = NULL;
+...
+--
+The preferred pointer style is:
+
+void *p = ...;
+
+-- Not:
+
+void* p = ...;
+
+-- or if you have for example, some sort of counter value
+ that must have a start:
+
+uint8_t countdown = COUNTDOWN_START;
+--
+
+!! COMMIT STYLE !!
+
+Keep commits small if possible. Follow commit good practices.
+
+- Commit examples -
+1) Some manpage update:
+ docs: man: Describe foo in foobar(9)
+
+2) Adding a tool in tools/
+ build: tools: Create foo
+
+ This commit adds a new script in tools/
+ that does x and y ...
+
+- Kernel commits -
+An example of a commit title for a non architecture-specific commit:
+ kernel: foo: Fix bar in foobar
+
+An example of an architecture specific commit e.g. for AMD64:
+kernel/amd64: foo: Add foo in bar
+
+- Ready to commit -
+
+(BE SURE TO TEST IT!! IDEALLY ON REAL HW TOO IF POSSIBLE!)
+
+* Commit with `git commit -sv`
+* Create patch with `git format-patch -1 HEAD`
+* Email patch to ian@osmora.org and for better response times,
+ optionally CC to quinn@osmora.org
+
+Done!
+
+------------------------------------------------
+NOTE TO MAINTAINERS
+
+For those who maintain the Hyra repo, when testing a patch, apply it like so:
+`git am -s patchfile.patch`. If all good, create a new patch and email it to
+ian@osmora.org
diff --git a/share/misc/pdn b/share/misc/pdn
new file mode 100644
index 0000000..3187277
--- /dev/null
+++ b/share/misc/pdn
@@ -0,0 +1,14 @@
+--------------------------------------------
+| Peripheral Description Notation Examples |
+--------------------------------------------
+
+hba0 at pci0: HBA instance 0 is connected to PCI bus 0
+
+... can be more specific (with BDF + slot)
+
+hba0 at pci0:2922.00.3
+ ^ ^ ^ ^
+ bus dev func slot
+
+hba* at pci0: (hba<wildcard>) All HBA instances on PCI bus 0
+hba0 at pci?: (* .. <pci:unknown>) HBA instance 0 on PCI bus ? (could be any)
diff --git a/share/misc/tmpfs b/share/misc/tmpfs
new file mode 100644
index 0000000..38eac22
--- /dev/null
+++ b/share/misc/tmpfs
@@ -0,0 +1,15 @@
+----------------------------------------------------
+| Readable + writable in-memory filesystem (tmpfs) |
++--------------------------------------------------+
+| Author: Ian Marco Moffett |
++--------------------------------------------------+
+
+------------------------------------------------------------------------------
+
+ [d] /tmp/ -> [next] -> foo.txt -> [next] -> bar.txt
+ \
+ +> /tmp/noises/ -> [next] -> mrow.txt -> [next] -> squeak.txt
+ \
+ +> /tmp/noises1/ -> [next] -> bark.bin -> [next] -> wrff.txt
+
+------------------------------------------------------------------------------
generated by cgit v1.2.3 (git 2.39.1) at 2025-07-03 17:45:43 +0000