diff options
| -rw-r--r-- | README.md | 34 | ||||
| -rw-r--r-- | configure.ac | 2 | ||||
| -rw-r--r-- | share/docs/kernel/ctlfs.md | 125 | ||||
| -rw-r--r-- | share/man/man1/osh.1 | 83 | ||||
| -rw-r--r-- | sys/include/fs/ctlfs.h | 6 |
5 files changed, 240 insertions, 10 deletions
@@ -1,14 +1,22 @@ The Hyra Operating System ========================= -Welcome to the Hyra Operating System project! +Welcome to the Hyra Operating System project! Hyra is an experimental +operating system inspired by BSD and Plan 9 while being entirely written from scratch. +Hyra aims to rethink core fundamentals in modern operating system design in order to +create new and improved architectural ideas. + Project Goal: -------------- -The goal of this project is to redefine what modern operating systems are while taking inspiration from BSD. Hyra does not use -POSIX by default and instead uses the [OSMORA Uniform System Interface (OUSI)](https://osmora.org/oap/oap-0002). Hyra also does +The goal of this project is to redefine what modern operating systems are while taking inspiration from BSD. Hyra does not use CPIO for its initramfs like other operating systems typically would and instead uses the [OSMORA Archive Format (OMAR)](https://osmora.org/oap/oap-0005). +What Hyra is NOT: +-------------- +Hyra is *NOT* Linux, nor does extend or share any sources with any existing +operating systems as it is written entirely from scratch. Hyra is *NOT* intended as a "toy" project as it is aimed to be the used as the main operating system for internal OSMORA operations and infrastructure. + Getting Started: ---------------- To build Hyra you'll need to bootstrap the project which is essentially just fetching dependencies for the project. This can be done by running the bootstrap script within the project root: `./bootstrap`. @@ -31,7 +39,7 @@ password is also `root`. Programs: ---------------- -The Hyra userspace provides the user various programs that they can run, examples of +The Hyra userspace provides the user various programs that they can run. Examples of such programs include: - ``beep`` - Play a tone @@ -47,12 +55,28 @@ such programs include: - ``readcore`` - Read coredump files - ``oasm`` - OSMORA [OSMX64](https://github.com/sigsegv7/OSMX64) Assembler - ``oemu`` - OSMORA [OSMX64](https://github.com/sigsegv7/OSMX64) Emulator +- ``kstat`` - Read kernel statistics +- ``dmidump`` - Dump DMI/SMBios information And more! See ``usr.bin/*`` +Libraries: +---------------- +The Hyra userspace additionally provides the user various libraries that they can +link with. Examples of such libraries include: + +- ``libc`` - C library (link flag: ``-lc``) +- ``libgfx`` - Low-level graphics (link flag: ``-lgfx``) + +And more! See ``lib/*`` + Documentation: -------------- -Documentation will be in the form of comments throughout the codebase and can also be found in the share/ directory within the project root. +Documentation will be in the form of comments throughout the codebase and can also be found in: + +- ``share/man/*``: Man pages +- ``share/contrib``: Information on contributing +- ``share/docs/kernel``: Kernel documentation Hyra running on bare metal: -------------- diff --git a/configure.ac b/configure.ac index ecbeafe..6db3a09 100644 --- a/configure.ac +++ b/configure.ac @@ -1,4 +1,4 @@ -AC_INIT([Hyra], [2.4], [ian@osmora.org]) +AC_INIT([Hyra], [2.5], [ian@osmora.org]) TARGET="amd64" QEMU="qemu-system-x86_64" 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 diff --git a/sys/include/fs/ctlfs.h b/sys/include/fs/ctlfs.h index 90f42f0..29ae358 100644 --- a/sys/include/fs/ctlfs.h +++ b/sys/include/fs/ctlfs.h @@ -42,12 +42,10 @@ struct ctlops { /* * Ctlfs op arguments * - * @devname: Device name. - * @major: Device major - * @minor: Device minor. - * @mode: Access flags. * @devname [1]: Device name (node name) * @ctlname: [1]: Control name (node entry name) + * @ops: Callbacks / fs hooks + * @mode: Access flags. */ struct ctlfs_dev { union { |