Adds a way to register devices and device classes.

Signed-off-by: Nathan Ringo <me@remexre.com>

Author: remexre

doc/SUMMARY.md

@@ -10,6 +10,7 @@
 - [Kernel]()
   - [The `print()` and `format()` functions](./kernel/print.md)
   - [Init Functions](./kernel/init.md)
+  - [Devices](./kernel/devices.md)
   - [Threads and Harts](./kernel/threads-and-harts.md)
   - [Memory management]()
     - [Overview](./kernel/mm/overview.md)

doc/kernel/devices.md

@@ -0,0 +1,4 @@
+# Devices
+
+Devices that have been detected are represented as a tree of `struct device` in memory.
+(This should not be confused with the [Devicetree](https://en.wikipedia.org/wiki/Devicetree) standard, which is one of several ways that ukoOS populates this tree.)

src/kernel/device.c

@@ -0,0 +1,100 @@
+/*
+ * SPDX-FileCopyrightText: 2025 ukoOS Contributors
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+#include <device.h>
+#include <init.h>
+
+struct list_head device_classes = LIST_INIT(device_classes);
+
+void register_device_class(struct device_class *device_class) {
+  assert(device_class->name);
+  assert(device_class->description);
+  assert(list_is_empty(&device_class->device_classes));
+  assert(list_is_empty(&device_class->members));
+
+  list_push(&device_classes, &device_class->device_classes);
+}
+
+void register_device(struct device *parent, struct device_class *device_class,
+                     struct device *child) {
+  assert(parent->name);
+  assert(parent->device_class);
+  assert(!list_is_empty(&parent->device_class_members));
+
+  assert(child->name);
+  assert(!child->parent);
+  assert(!child->device_class);
+  assert(list_is_empty(&child->parent_children));
+  assert(list_is_empty(&child->children));
+  assert(list_is_empty(&child->device_class_members));
+
+  child->parent = parent;
+  child->device_class = device_class;
+  list_push(&parent->children, &child->parent_children);
+  list_push(&device_class->members, &child->device_class_members);
+}
+
+void print_devices(void) {
+  struct device *device = &root_device;
+  usize depth = 1;
+
+  print("devices {{");
+
+  assert(list_is_empty(&device->parent_children));
+  for (;;) {
+    assert(device->name);
+    assert(device->device_class);
+    assert(device->device_class->name);
+    print("{indent}{cstr} class={cstr}{cstr}", 2 * depth, device->name,
+          device->device_class->name,
+          list_is_empty(&device->children) ? "" : " {");
+
+    if (!list_is_empty(&device->children)) {
+      // Try to go to our first child.
+      depth++;
+      device =
+          container_of(device->children.next, struct device, parent_children);
+    } else {
+      // Go up the tree until we find a node with a next sibling, or we've
+      // returned to the root.
+      while (device->parent &&
+             device->parent_children.next == &device->parent->children) {
+        device = device->parent;
+        assert(depth > 1);
+        depth--;
+        print("{indent}}}", 2 * depth);
+      }
+
+      // If we're at the root, stop traversing.
+      if (!device->parent) {
+        assert(depth == 1);
+        break;
+      }
+
+      // Otherwise, go to our sibling.
+      device = container_of(device->parent_children.next, struct device,
+                            parent_children);
+    }
+  }
+
+  print("}}");
+}
+
+/**
+ * The device class of the root device. No other device should have this device
+ * class.
+ */
+DEFINE_DEVICE_CLASS(root_device_class, "ukoos-root-device",
+                    "The device class of the root device.");
+
+struct device root_device;
+
+DEFINE_INIT(-10) {
+  root_device = DEVICE_INIT(root_device, "root-device");
+  // This can't use register_device() because it doesn't have a parent.
+  root_device.device_class = &root_device_class;
+  list_push(&root_device_class.members, &root_device.device_class_members);
+}

src/kernel/include.mak

@@ -22,7 +22,7 @@ kernel-cflags += -fdata-sections -ffunction-sections
 kernel-ldflags += -Wl,--gc-sections
 kernel-dir = src/kernel
 kernel-objs-asm =
-kernel-objs-c = devicetree init main panic print random selftest swar_test symbolicate
+kernel-objs-c = device devicetree init main panic print random selftest swar_test symbolicate
 kernel-objs-c += builtins/bzero builtins/explicit_bzero builtins/memcpy builtins/memcmp builtins/memset builtins/strcmp builtins/strlen
 kernel-objs-c += crypto/subtle/rfc7539 crypto/subtle/rfc7693
 kernel-objs-c += mm/alloc mm/alloc/block mm/alloc/heap mm/alloc/init mm/alloc/page mm/alloc/segment mm/physical_alloc mm/virtual_alloc

src/kernel/include/device.h

@@ -0,0 +1,149 @@
+/*
+ * SPDX-FileCopyrightText: 2025 ukoOS Contributors
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+#ifndef UKO_OS_KERNEL__DEVICE_H
+#define UKO_OS_KERNEL__DEVICE_H 1
+
+#include <list.h>
+#include <print.h>
+
+/**
+ * The kind of device. These should be statically allocated.
+ */
+struct device_class {
+  /**
+   * The name of the device class. This should be a short name suitable as a
+   * directory name.
+   */
+  const char *name;
+
+  /**
+   * A short description of the device class in prose.
+   */
+  const char *description;
+
+  /**
+   * The `list_head` for this class's entry in the `device_classes` list.
+   */
+  struct list_head device_classes;
+
+  /**
+   * The list of `struct device`s that have this class.
+   */
+  struct list_head members;
+};
+
+/**
+ * Defines a device class and creates an initializer to register it.
+ */
+#define DEFINE_DEVICE_CLASS(IDENTIFIER, NAME, DESCRIPTION)                     \
+  struct device_class IDENTIFIER;                                              \
+  DEFINE_INIT(-20) { register_device_class(&IDENTIFIER); }                     \
+  struct device_class IDENTIFIER = {                                           \
+      .name = (NAME),                                                          \
+      .description = (DESCRIPTION),                                            \
+      .device_classes = LIST_INIT((IDENTIFIER).device_classes),                \
+      .members = LIST_INIT((IDENTIFIER).members),                              \
+  }
+
+/**
+ * The list of registered `struct device_class`es.
+ */
+extern struct list_head device_classes;
+
+/**
+ * Registers a device class.
+ *
+ * - `name` and `description` must be filled out.
+ * - `device_classes` and `members` must be self-linked.
+ */
+[[gnu::nonnull(1)]]
+void register_device_class(struct device_class *device_class);
+
+/**
+ * A node in the tree of devices attached to the system.
+ */
+struct device {
+  /**
+   * The name of the device. This must be unique amongst its siblings.
+   *
+   * This should be `alloc`-allocated.
+   */
+  char *name;
+
+  /**
+   * The parent of the node. `nullptr` for the root node.
+   */
+  struct device *parent;
+
+  /**
+   * The `list_head` for this device's entry in `parent->children`.
+   */
+  struct list_head parent_children;
+
+  /**
+   * The children of the node.
+   */
+  struct list_head children;
+
+  /**
+   * The kind of device this is.
+   */
+  struct device_class *device_class;
+
+  /**
+   * The `list_head` for this device's entry in `device_class->members`.
+   */
+  struct list_head device_class_members;
+};
+
+/**
+ * Returns an initializer for the `struct device` `DEVICE`.
+ *
+ * ### Example
+ *
+ * ```c
+ * struct my_device {
+ *   // ...
+ *   struct device device;
+ *   // ...
+ * };
+ *
+ * struct my_device *my_device = alloc(sizeof(*my_device));
+ * my_device->device = DEVICE_INIT(my_device->device, "example");
+ * ```
+ */
+#define DEVICE_INIT(DEVICE, NAME_FORMAT, ...)                                  \
+  (struct device) {                                                            \
+    .name = format(NAME_FORMAT __VA_OPT__(, ) __VA_ARGS__), .parent = nullptr, \
+    .parent_children = LIST_INIT((DEVICE).parent_children),                    \
+    .children = LIST_INIT((DEVICE).children), .device_class = nullptr,         \
+    .device_class_members = LIST_INIT((DEVICE).device_class_members),          \
+  }
+
+/**
+ * The root of the tree of devices.
+ */
+extern struct device root_device;
+
+/**
+ * Registers a device in the tree of devices and with its device class.
+ *
+ * - `name` must be filled out.
+ * - `parent` and `device_class` must be `nullptr`.
+ * - `parent_children`, `children`, and `device_class_members` must be
+ *   self-linked.
+ */
+[[gnu::nonnull(1, 2, 3)]]
+void register_device(struct device *parent, struct device_class *device_class,
+                     struct device *child);
+
+/**
+ * Prints the tree of devices.
+ */
+void print_devices(void);
+
+#endif // UKO_OS_KERNEL__DEVICE_H

src/kernel/include/list.h

@@ -65,8 +65,8 @@ struct list_head {
  * void init_parent(struct parent *p) { p->children = LIST_INIT(p->children); }
  * ```
  */
-#define LIST_INIT(name)                                                        \
-  (struct list_head) { .prev = &(name), .next = &(name) }
+#define LIST_INIT(LIST)                                                        \
+  (struct list_head) { .prev = &(LIST), .next = &(LIST) }
 
 /**
  * Returns whether `list` is empty.

src/kernel/main.c

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
+#include <device.h>
 #include <devicetree.h>
 #include <hart_locals.h>
 #include <init.h>
@@ -48,6 +49,9 @@ void main(u64 hart_id, paddr devicetree_start, paddr kernel_start,
   // Run initializers, which include e.g. setting up device classes and drivers.
   run_initializers();
 
+  // Print the devices that have been created.
+  print_devices();
+
   print("Running self-tests...");
   run_selftests();