From 791dcb4e2bd20e29e86242a131b2a6cd1916a1f1 Mon Sep 17 00:00:00 2001
From: "Chloe M." <chloe@mirocom.org>
Date: Sun, 24 May 2026 04:56:46 -0500
Subject: [PATCH] mvm: core: Add bus control groundwork

Signed-off-by: Chloe M. <chloe@mirocom.org>
---
 mvm/core/bus_ctl.c    | 104 ++++++++++++++++++++++++++++++++++++++++++
 mvm/include/mvm/bus.h |  98 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 202 insertions(+)
 create mode 100644 mvm/core/bus_ctl.c
 create mode 100644 mvm/include/mvm/bus.h

diff --git a/mvm/core/bus_ctl.c b/mvm/core/bus_ctl.c
new file mode 100644
index 0000000..4810481
--- /dev/null
+++ b/mvm/core/bus_ctl.c
@@ -0,0 +1,104 @@
+/*
+ * Copyright (c) 2026 Mirocom Laboratories and MSP engineers.
+ * All Rights Reserved.
+ */
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <errno.h>
+#include "mvm/bus.h"
+
+int
+bus_ctl_init(struct mvm_bus_ctl *busctl)
+{
+    if (busctl == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    busctl->head = NULL;
+    busctl->tail = NULL;
+    busctl->dev_count = 0;
+    return 0;
+}
+
+int
+bus_dev_alloc(mvm_devtype_t type, void *data, struct mvm_bus_dev **res)
+{
+    struct mvm_bus_dev *dev;
+
+    if (type == BUS_DEV_NONE || data == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    if (res == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    if ((dev = malloc(sizeof(*dev))) == NULL) {
+        errno = ENOMEM;
+        return -1;
+    }
+
+    dev->type = type;
+    dev->data = data;
+    dev->next = NULL;
+    *res = dev;
+    return 0;
+}
+
+void
+bus_dev_free(struct mvm_bus_dev *dev)
+{
+    if (dev == NULL) {
+        return;
+    }
+
+    free(dev);
+}
+
+int
+bus_ctl_append(struct mvm_bus_ctl *busctl, struct mvm_bus_dev *dev)
+{
+    if (busctl == NULL || dev == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    if (busctl->head == NULL || busctl->tail == NULL) {
+        busctl->head = dev;
+        busctl->tail = dev;
+    } else {
+        busctl->tail->next = dev;
+        busctl->tail = dev;
+    }
+
+    ++busctl->dev_count;
+    return 0;
+}
+
+void
+bus_ctl_free(struct mvm_bus_ctl *busctl)
+{
+    struct mvm_bus_dev *dev, *tmp;
+
+    if (busctl == NULL) {
+        return;
+    }
+
+    if ((dev = busctl->head) == NULL) {
+        return;
+    }
+
+    while (dev != NULL) {
+        tmp = dev;
+        bus_dev_free(tmp);
+        dev = dev->next;
+    }
+
+    busctl->head = NULL;
+    busctl->tail = NULL;
+}
diff --git a/mvm/include/mvm/bus.h b/mvm/include/mvm/bus.h
new file mode 100644
index 0000000..a515068
--- /dev/null
+++ b/mvm/include/mvm/bus.h
@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2026 Mirocom Laboratories and MSP engineers.
+ * All Rights Reserved.
+ */
+
+#ifndef MVM_BUS_H
+#define MVM_BUS_H 1
+
+#include <stdint.h>
+#include <stddef.h>
+
+/*
+ * Represents valid device types that can be
+ * on the bus.
+ *
+ * @BUS_DEV_NONE:  No associated type
+ * @BUS_DEV_ROM:   This device is a ROM module
+ */
+typedef enum {
+    BUS_DEV_NONE,
+    BUS_DEV_ROM
+} mvm_devtype_t;
+
+/*
+ * Represents a device on the bus
+ *
+ * @type:  Device type
+ * @data:  Device specific descriptor
+ * @next:  Next device in list
+ */
+struct mvm_bus_dev {
+    mvm_devtype_t type;
+    void *data;
+    struct mvm_bus_dev *next;
+};
+
+/*
+ * Represents the bus control / management structure
+ * that keeps track of all registered devices.
+ *
+ * @head:       Dequeue point
+ * @tail:       Enqueue point
+ * @dev_count:  Number of devices attached
+ *
+ */
+struct mvm_bus_ctl {
+    struct mvm_bus_dev *head;
+    struct mvm_bus_dev *tail;
+    size_t dev_count;
+};
+
+/*
+ * Append a device to a bus control descriptor
+ *
+ * @busctl:  Bus control descriptor to append to
+ * @dev:     Device to append
+ *
+ * Returns zero on success
+ */
+int bus_ctl_append(struct mvm_bus_ctl *busctl, struct mvm_bus_dev *dev);
+
+/*
+ * Allocate a new bus device
+ *
+ * @type:  Device type
+ * @data:  Device specific data
+ * @res:   Result is written here
+ *
+ * Returns zero on success
+ */
+int bus_dev_alloc(mvm_devtype_t type, void *data, struct mvm_bus_dev **res);
+
+/*
+ * Deallocate resources associated with a bus device
+ * descriptor
+ *
+ * @dev: Device descriptor to release
+ */
+void bus_dev_free(struct mvm_bus_dev *dev);
+
+/*
+ * Deallocate resources associated with a bus control
+ * descriptor
+ *
+ * @busctl: Bus control descriptor to release
+ */
+void bus_ctl_free(struct mvm_bus_ctl *busctl);
+
+/*
+ * Initialize a bus control descriptor
+ *
+ * @busctl: Descriptor to initialize
+ *
+ * Returns zero on success
+ */
+int bus_ctl_init(struct mvm_bus_ctl *busctl);
+
+#endif  /* !MVM_BUS_H */