2 files changed, 208 insertions, 0 deletions
diff --git a/share/docs/kernel/ctlfs.md b/share/docs/kernel/ctlfs.md
new file mode 100644
index 0000000..3087f60
--- /dev/null
+++ b/share/docs/kernel/ctlfs.md
@@ -0,0 +1,125 @@
+# The Hyra control filesystem (ctlfs)
+
+Written by Ian M. Moffett
+
+## Rationale
+
+Historically, Operating Systems of the Unix family typically relied
+on syscalls like ``ioctl()`` or similar to perform operations (e.g., making calls through a driver)
+via some file descriptor. Let's say for example, one wanted to acquire the framebuffer
+dimensions of a given framebuffer device. To start, they'd acquire a file descriptor
+by calling ``open()`` or similar on it. Then they'd make their ``ioctl()`` call.
+
+```c
+int fd = ...;
+
+ioctl(fd, IOCTL_FBINFO, &fb_info);
+...
+```
+
+While this works fine and is relatively simple to use from the user's
+perspective, it is very clunky when you pop the hood and peer into the
+inner-workings of it within the kernel. The number of possible requests
+that can be passed through a file descriptor can grow quite rapidly which
+can require really large switch statements within the drivers that implement
+an ``ioctl()`` interface.
+
+## Replacing ``ioctl()``
+
+Hyra provides ctlfs, an abstract in-memory filesystem designed for
+setting/getting various kernel / driver parameters and state via
+the filesystem API. The control filesystem consists of several
+instances of two fundamentals: "control nodes" and "control entries".
+
+### Control nodes
+
+Control nodes are simply directories within the ``/ctl`` root. For example,
+console specific control files are in the ``/ctl/console`` node.
+
+### Control entries
+
+Control entries are simply files within specific control nodes. For example
+console features may be find in the ``consfeat`` entry of the ``console`` node
+(i.e., ``/ctl/console/consfeat``).
+
+See ``sys/include/sys/console.h`` and ``sys/fs/ctlfs.h`` for more
+information.
+
+## The ctlfs API
+
+The Hyra kernel provides an API for subsystems and drivers
+to create their own ctlfs entries and nodes. This may be found
+in sys/include/fs/ctlfs.h
+
+### Control operations
+
+Each control entry must define their own set of
+"control operations" described by the ``ctlops`` structure:
+
+```c
+struct ctlops {
+    int(*read)(struct ctlfs_dev *cdp, struct sio_txn *sio);
+    int(*write)(struct ctlfs_dev *cdp, struct sio_txn *sio);
+    ...
+};
+```
+
+NOTE: Callbacks defined as ``NULL`` will be
+ignored and unused.
+
+## "Meow World": Creating a ctlfs entry
+
+```c
+#include <sys/types.h>
+#include <sys/sio.h>
+#include <fs/ctlfs.h>
+
+static const struct ctlops meow_ctl;
+
+/*
+ * Ctlfs read callback - this will be called
+ * when "/ctl/meow/hii" is read.
+ */
+static int
+ctl_meow_read(struct ctlfs_dev *cdp, struct sio_txn *sio)
+{
+    char data[] = "Meow World!""
+
+    /* Clamp the input length */
+    if (sio->len > sizeof(data)) {
+        sio->len = sizeof(data)
+    }
+
+    /* End of the data? */
+    if ((sio->offset + sio->len) > sizeof(data)) {
+        return 0;
+    }
+
+    /* Copy the data and return the length */
+    memcpy(sio->buf, &data[sio->offset], sio->len);
+    return sio->len;
+}
+
+static int
+foo_init(void)
+{
+    char ctlname[] = "meow";
+    struct ctlfs_dev ctl;
+
+    /*
+     * Here we create the "/ctl/meow" node.
+     */
+    ctl.mode = 0444;
+    ctl.devname = devname;
+    ctlfs_create_node(devname, &ctl);
+
+    ctl.ops = &fb_size_ctl;
+    ctlfs_create_entry("attr", &ctl);
+    return 0;
+}
+
+static const struct ctlops meow_ctl = {
+    .read = ctl_meow_read,
+    .write = NULL,
+};
+```
diff --git a/share/man/man1/osh.1 b/share/man/man1/osh.1
new file mode 100644
index 0000000..1b2744c
--- /dev/null
+++ b/share/man/man1/osh.1
@@ -0,0 +1,83 @@
+.\" 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 Aug 2 2025
+.Dt OSH 1
+.Os HYRA
+.Sh NAME
+.Nm osh - OSMORA shell
+.Sh SYNOPSIS
+osh [optional file]
+
+.Sh DESCRIPTION
+
+OSH is a simple shell interpreter that is capable of executing commands
+from the user via stdin or a shell script file passed as an argument.
+
+.Sh COMMENTS
+OSH supports the use of comments (i.e., pieces of text ignored by the shell)
+denoted by '@'. The following is an example of using comments:
+
+.Bd -literal
+echo hello !!    @ Echos the text "hello !!"
+.Ed
+
+.Sh DEFINITIONS
+OSH defines "control operators" as any character(s) reserved by OSH for
+representing specific operations (e.g., background jobs, command repetition, etc):
+
+The
+.Ft '&'
+control operator is used after a command or binary path
+in order to run the executable as a background job, allowing
+the shell to continue immediately. Here is an example of running "sleep" in the background:
+.Bd -literal
+--
+@
+@ Usually this will hang the shell for 5
+@ seconds until sleep wakes up. However,
+@ when we postpend '&', the shell executes
+@ 'sleep' as a background job and continues
+@ as usual.
+@
+sleep 5  &
+--
+.Ed
+
+The
+.Ft '!!'
+control operator is used to repeat the most recently used
+command. This is simply written by itself like this:
+
+.Bd -literal
+--
+echo "hewwo"    @ Echo "hewwo"
+!!              @ Do it again...
+--
+.Ed
+
+.Sh AUTHORS
+.An Ian Moffett Aq Mt ian@osmora.org