summaryrefslogtreecommitdiff
path: root/share
diff options
context:
space:
mode:
Diffstat (limited to 'share')
-rw-r--r--share/docs/hw/et131x.txt215
-rw-r--r--share/docs/ideas/kport.txt79
-rw-r--r--share/man/man1/omar.155
-rw-r--r--share/man/man9/kconf.981
-rw-r--r--share/man/man9/mmio.93
-rw-r--r--share/man/man9/vm.946
-rw-r--r--share/man/man9/vm_map.997
-rw-r--r--share/misc/contrib55
-rw-r--r--share/misc/tmpfs15
9 files changed, 646 insertions, 0 deletions
diff --git a/share/docs/hw/et131x.txt b/share/docs/hw/et131x.txt
new file mode 100644
index 0000000..43d7c4f
--- /dev/null
+++ b/share/docs/hw/et131x.txt
@@ -0,0 +1,215 @@
+--------------------------------------
+Unofficial ET131X datasheet. If Agere
+doesn't give you shit, OSMORA will
+
+Author: Ian Marco Moffett
+--------------------------------------
+
+-- PCI information
+
+VENDOR ID: 0x11C1 (Agere)
+Device ID: 0xED00
+
+The ET131X exposes its register interface through
+PCI BAR 0.
+
+-- Device register map (register set list)
+|
+++ GLOBAL REGS (GLOBAL):
+ // JAGCore register map (offset BAR[0] + 0x0000)
+ TX_queue_start_addr [dword] (BAR[0] + 0x0000)
+ TX_queue_end_addr [dword] (BAR[0] + 0x0004)
+ RX_queue_start_addr [dword] (BAR[0] + 0x0008)
+ RX_queue_end_addr [dword] (BAR[0] + 0x000C)
+ PM_CSR [dword] (BAR[0] + 0x0010)
+ unused [dword] (BAR[0] + 0x0014)
+ int_status [dword] (BAR[0] + 0x0018)
+ int_mask [dword] (BAR[0] + 0x001C)
+ int_alias_clr_en [dword] (BAR[0] + 0x0020)
+ int_status_alias [dword] (BAR[0] + 0x0024)
+ sw_reset [dword] (BAR[0] + 0x0028)
+ slv_timer [dword] (BAR[0] + 0x002C)
+ msi_config [dword] (BAR[0] + 0x0030)
+ loopback [dword] (BAR[0] + 0x0034)
+ watchdog_timer [dword] (BAR[0] + 0x0038)
+ ----------------------------------------
+ NOTES:
+ [REGISTER INFORMATION]
+ - TX_queue_start_addr:
+ Address of transmit queue start in internal RAM.
+ - TX_queue_end_addr:
+ Address of transmit queue end in internal RAM.
+ - RX_queue_start_addr:
+ Address of receive queue start in internal RAM.
+ - RX_queue_end_addr:
+ Address of receive queue end in internal RAM.
+ - PM_CSR:
+ Power management control/status register.
+ - unused:
+ Not used, leave alone.
+ - int_status:
+ Interrupt status register.
+ - int_mask:
+ Interrupt mask register
+ - int_alias_clr_en:
+ ????
+ - int_status_alias:
+ ????
+ - slv_timer:
+ ???? - for some sort of timeout
+ - loopback:
+ Loopback control register
+ [0x00000001] -> LOOP MAC
+ [0x00000002] -> LOOP DMA
+ - watchdog_timer:
+ Watchdog timer regieter (nanoseconds)
+| [0] -> DISABLED
+++ MAC REGISTERS (MAC_REGS):
+ // JAGCore MAC registers (offset BAR[0] + 0x5000)
+ cfg1 [dword] (BAR[0] + 0x5000)
+ cfg2 [dword] (BAR[0] + 0x5004)
+ ipg [dword] (BAR[0] + 0x5008)
+ hfdp [dword] (BAR[0] + 0x500C)
+ max_fm_len [dword] (BAR[0] + 0x5010)
+ reserved1 [dword] (BAR[0] + 0x5014)
+ reserved2 [dword] (BAR[0] + 0x5018)
+ mac_test [dword] (BAR[0] + 0x501C)
+ mii_mgmt_cfg [dword] (BAR[0] + 0x5020)
+ mii_mgmt_cmd [dword] (BAR[0] + 0x5024)
+ mii_mgmt_addr [dword] (BAR[0] + 0x5028)
+ mii_mgmt_ctrl [dword] (BAR[0] + 0x502C)
+ mii_mgmt_stat [dword] (BAR[0] + 0x5030)
+ mii_mgmt_indicator [dword] (BAR[0] + 0x5034)
+ if_ctrl [dword] (BAR[0] + 0x5038)
+ if_stat [dword] (BAR[0] + 0x503C)
+ station_addr1 [dword] (BAR[0] + 0x5040)
+ station_addr2 [dword] (BAR[0] + 0x5044)
+ NOTES:
+ [REGISTER INFORMATION]
+ - cfg1:
+ First MAC configuration register.
+ - cfg2:
+ Second MAC configuration register.
+ - ipg:
+ MAC Interpacket Gap configuration register.
+ - hfdp:
+ MAC Half Duplex configuration register.
+ - max_fm_len:
+ Max packet length (bytes) sent through MAC without
+ truncation.
+ - mac_test:
+ MAC test registers
+ - mii_mgmt_cfg:
+ MAC MII Management Config register.
+ - mii_mgmt_cmd:
+ MAC MII Management Command register.
+ - mii_mgmt_ctrl:
+ MAC MII Management Control register.
+ - mii_mgmt_stat:
+ MAC MII Management Status register.
+ - mii_mgmt_indicator:
+ MAC MII Management Indicator register.
+ - if_ctrl:
+ MAC interface control register.
+ - station_addr1:
+ First MAC station address register.
+ - station_addr2:
+ Second MAC station address register.
+ [BITS]
+ -------------------------------------
+ @ cfg1:
+ [bits 0]: TX enable
+ [bits 1]: Syncd TX enable
+ [bits 2]: RX enable
+ [bits 3]: Syncd TX enable
+ [bits 4]: TX flow
+ [bits 5]: RX flow
+ [bits 7:6]: Reserved
+ [bits 8]: Loopback
+ [bits 15:9]: Reserved
+ [bits 16]: Reset TX func
+ [bits 17]: Reset RX func
+ [bits 18]: Reset TX MC
+ [bits 19]: Reset RX MC
+ [bits 29:20]: Reserved
+ [bits 30]: Sim reset
+ [bits 31]: Soft reset
+ @ cfg2:
+ [bits 0]: Full-duplex
+ [bits 1]: CRC enable
+ [bits 2]: Pad CRC
+ [bits 3]: Unused (undefined)
+ [bits 4]: Length check
+ [bits 5]: Huge frame
+ [bits 7:6]: Reserved
+ [bits 9:8]: Interface mode
+ [bits 11:10]: Reserved
+ [bits 15:12]: Preamble
+ [bits 31:16]: Reserved
+ @ ipg:
+ [bits 7:0]: B2B IPG
+ [bits 15:8]: Minimum IFG enforce
+ [bits 22:16]: Non B2B IPG 2
+ [bits 23]: Unused (undefined)
+ [bits 30:24]: Non B2B IPG 1
+ [bits 31]: Reserved
+ @ hfdp:
+ [bits 9:0]: Collision window
+ [bits 11:10]: Reserved
+ [bits 15:12]: Re-transmit max
+ [bits 16]: Excess defer
+ [bits 17]: No backoff
+ [bits 18]: BP no backoff
+ [bits 19]: Alt BEB enable [1]
+ [bits 23-20]: Alt BEB trunc [1]
+ [bits 31-24]: Reserved
+ |
+ ++ [1]: BEB refers to Binary Exponential Backoff which is
+ a method to mitigate collisions by doubling the TX
+ backoff window (throttling TX rate) per collision.
+ -------------------------------------
+
+
+------------------------------------------------------------------
+ET131X REGISTER SPACE NOTES:
+------------------------------------------------------------------
+[Padding]:
+ Each register set exists within a 4096 byte region and some
+ register sets do not fully span that full length. Therefore
+ when defining the register space within a struct, one must
+ be sure to account for such gaps by including 'n' bytes of
+ padding after each register set. Where 'n' is how many bytes
+ left to fully span 4096 bytes in other words, '4096 - regset_len'.
+
+------------------------------------------------------------------
+SOFTWARE RESET PROCCESS:
+------------------------------------------------------------------
+#define MAC_CFG1_SOFTRST 0x80000000 /* Soft reset */
+#define MAC_CFG1_SIMRST 0x40000000 /* SIM reset */
+#define MAC_CFG1_RESET_RXMC 0x00080000 /* RX MC reset */
+#define MAC_CFG1_RESET_TXMC 0x00040000 /* TX MC reset */
+#define MAC_CFG1_RESET_RXFUNC 0x00020000 /* RX func reset */
+#define MAC_CFG1_RESET_TXFUNC 0x00010000 /* TX func reset */
+#define GBL_RESET_ALL 0x007F /* Global reset */
+------------------------------------------------------------------
+To perform a software reset, one must write the value of MAC_CFG1_SOFTRST,
+MAC_CFG1_SIMRST, MAC_CFG1_RESET_RXMC, MAC_CFG1_RESET_TXMC, MAC_CFG1_RESET_RXFUNC,
+and MAC_CFG1_RESET_TXMC combined together with a bitwise OR to the 'cfg1' register
+of the 'MAC_REGS' register set.
+
+This results in the MAC core (aka JAGCore) resetting all internal state
+and being brought to halt.
+
+Once the MAC core is reset, you must be sure to also reset the rest of the card,
+(I know, just when you thought you were done). This may be done by writing the
+value of GBL_RESET_ALL to the 'sw_reset' register of the 'GLOBAL' register set.
+This results in the reset of further state such as state machines for TX DMA, RX DMA,
+MAC TX, MAC RX, etc cetera.
+
+To ensure the TX/RX paths of the MAC core are in a known state, one
+must write the value of MAC_CFG1_RESET_RXMC, MAC_CFG1_RESET_TXMC, MAC_CFG1_RESET_RXFUNC,
+and MAC_CFG1_RESET_TXMC combined together with a bitwise OR to the 'cfg1' register
+of the 'MAC_REGS' register set.
+
+And finally, you must also make sure the 'cfg1' register of the 'MAC_REGS' register
+set is also in a known state by clearing it to 0x00000000.
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/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
index 7833cb0..4ede196 100644
--- a/share/man/man9/mmio.9
+++ b/share/man/man9/mmio.9
@@ -59,5 +59,8 @@ 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/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
index 6f93fb7..39c9c02 100644
--- a/share/misc/contrib
+++ b/share/misc/contrib
@@ -21,6 +21,22 @@ is_power_of_two(uint8_t n)
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:
@@ -46,6 +62,37 @@ 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;
@@ -87,6 +134,14 @@ 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:
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-16 11:15:13 +0000