mvm: Add state management groundwork

Signed-off-by: Chloe M. <chloe@mirocom.org>

mvm/.gitignore

@@ -1 +1 @@
-mvm
+./mvm

mvm/core/balloon_subr.c

@@ -73,3 +73,16 @@ balloon_memcpy(struct mvm_balloon *dest, off_t off, void *source, size_t count)
     memcpy((char *)dest->data + off, source, count);
     return 0;
 }
+
+void
+balloon_free(struct mvm_balloon *bp)
+{
+    if (bp == NULL) {
+        return;
+    }
+
+    if (bp->data != NULL) {
+        free(bp->data);
+        bp->data = NULL;
+    }
+}

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;
+}

mvm/core/rom.c

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2026 Mirocom Laboratories and MSP engineers.
+ * All Rights Reserved.
+ */
+
+#include <stdint.h>
+#include <stddef.h>
+#include <errno.h>
+#include "mvm/rom.h"
+
+int
+mvm_rom_init(struct mvm_rom *rom, size_t cap)
+{
+    if (rom == NULL) {
+        return -1;
+    }
+
+    if (balloon_init(&rom->data, cap) < 0) {
+        return -1;
+    }
+
+    return 0;
+}
+
+void
+mvm_rom_free(struct mvm_rom *rom)
+{
+    if (rom == NULL) {
+        return;
+    }
+
+    balloon_free(&rom->data);
+}

mvm/core/state_subr.c

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2026 Mirocom Laboratories and MSP engineers.
+ * All Rights Reserved.
+ */
+
+#include <stdint.h>
+#include <stddef.h>
+#include <errno.h>
+#include "mvm/state.h"
+#include "mvm/common.h"
+
+int
+mvm_state_init(struct mvm_state *state)
+{
+    if (state == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    if (bus_ctl_init(&state->busctl) < 0) {
+        errno = EIO;
+        return -1;
+    }
+
+    if (mvm_rom_init(&state->bootrom, MVM_BOOTROM_SIZE) < 0) {
+        errno = EIO;
+        return -1;
+    }
+
+    return 0;
+}
+
+void
+mvm_state_free(struct mvm_state *state)
+{
+    if (state == NULL) {
+        return;
+    }
+
+    bus_ctl_free(&state->busctl);
+    mvm_rom_free(&state->bootrom);
+}

mvm/include/mvm/balloon.h

@@ -50,4 +50,11 @@ int balloon_init(struct mvm_balloon *bp, size_t cap);
  */
 int balloon_memcpy(struct mvm_balloon *dest, off_t off, void *source, size_t count);
 
+/*
+ * Release a balloon from memory
+ *
+ * @bp: Balloon to free
+ */
+void balloon_free(struct mvm_balloon *bp);
+
 #endif  /* !MVM_BALLOON_H */

mvm/include/mvm/bus.h

@@ -0,0 +1,104 @@
+/*
+ * 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>
+
+/* Helper macros */
+#define NVM_BUS_FIRST(BUSCTL_P) \
+    (BUSCTL_P)->head
+#define NVM_BUS_NEXT(DEV_P)     \
+    (DEV_P)->next
+
+/*
+ * 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 */

mvm/include/mvm/common.h

@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) 2026 Mirocom Laboratories and MSP engineers.
+ * All Rights Reserved.
+ */
+
+#ifndef MVM_COMMON_H
+#define MVM_COMMON_H 1
+
+/* Maximum boot ROM capacity */
+#define MVM_BOOTROM_SIZE 1024
+
+#endif  /* !MVM_COMMON_H */

mvm/include/mvm/rom.h

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2026 Mirocom Laboratories and MSP engineers.
+ * All Rights Reserved.
+ */
+
+#ifndef MVM_ROM_H
+#define MVM_ROM_H 1
+
+#include <stdint.h>
+#include <stddef.h>
+#include "mvm/balloon.h"
+
+/*
+ * Represents a ROM
+ *
+ * @data: ROM data
+ */
+struct mvm_rom {
+    struct mvm_balloon data;
+};
+
+/*
+ * Initialize the ROM
+ *
+ * @rom:  ROM to initialize
+ *
+ * Returns zero on success
+ */
+int mvm_rom_init(struct mvm_rom *rom, size_t cap);
+
+/*
+ * Free a ROM and its associated resources from memory
+ *
+ * @rom: ROM to free
+ */
+void mvm_rom_free(struct mvm_rom *rom);
+
+#endif  /* !MVM_ROM_H */

mvm/include/mvm/state.h

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2026 Mirocom Laboratories and MSP engineers.
+ * All Rights Reserved.
+ */
+
+#ifndef MVM_STATE_H
+#define MVM_STATE_H 1
+
+#include <stdint.h>
+#include <stddef.h>
+#include "mvm/rom.h"
+#include "mvm/bus.h"
+
+/*
+ * Represents the virtual machine state
+ *
+ * @busctl:  Bus controller
+ * @bootrom: Boot rom
+ */
+struct mvm_state {
+    struct mvm_bus_ctl busctl;
+    struct mvm_rom bootrom;
+};
+
+/*
+ * Initialize the virtual machine state
+ *
+ * @state:  State machine to initialize
+ *
+ * Returns zero on success
+ */
+int mvm_state_init(struct mvm_state *state);
+
+/*
+ * Release a state and its associated resources from memory
+ *
+ * @state: State to deallocate.
+ */
+void mvm_state_free(struct mvm_state *state);
+
+#endif  /* !MVM_STATE_H */