buninu-linux 0.2.1 → 0.3.0

package/initramfs/init.js

@@ -37,6 +37,10 @@ const libc = dlopen("/lib/libc.musl-x86_64.so.1", {
     args: [FFIType.i32],
     returns: FFIType.i32,
   },
+  mkdir: {
+    args: [FFIType.ptr, FFIType.i32],
+    returns: FFIType.i32,
+  },
 });
 
 const cString = (value) => new TextEncoder().encode(`${value}\0`);
@@ -63,18 +67,23 @@ const errno = () => read.i32(errnoLocation);
 //
 // EBUSY is tolerated so this still works if something else mounted them first.
 const mountFilesystems = () => {
-  for (const [source, target, type] of [
+  for (const [source, target, type, data] of [
     ["proc", "/proc", "proc"],
     ["sysfs", "/sys", "sysfs"],
     ["devtmpfs", "/dev", "devtmpfs"],
     ["tmpfs", "/tmp", "tmpfs"],
+    // Since Linux 4.7 open("/dev/ptmx") resolves through /dev/pts/ptmx, so
+    // without this mount every pty open fails with ENODEV. The directory is
+    // created on the devtmpfs mounted just above.
+    ["devpts", "/dev/pts", "devpts", "gid=5,mode=620,ptmxmode=666"],
   ]) {
+    if (type === "devpts") libc.symbols.mkdir(ptr(cString(target)), 0o755);
     const result = libc.symbols.mount(
       ptr(cString(source)),
       ptr(cString(target)),
       ptr(cString(type)),
       0n,
-      null,
+      data === undefined ? null : ptr(cString(data)),
     );
     if (result === 0) continue;
     if (errno() === 16) continue; // EBUSY: already mounted
@@ -83,13 +92,23 @@ const mountFilesystems = () => {
 };
 
 mountFilesystems();
-console.log("init.js: mounted /proc, /sys, /dev, /tmp");
+console.log("init.js: mounted /proc, /sys, /dev, /tmp, /dev/pts");
 
 const { default: repl } = await import("node:repl");
 const { mkdirSync, writeFileSync } = await import("node:fs");
 
 global.repl = repl;
 
+// QEMU user networking exposes its DNS proxy at 10.0.2.3. A real-machine
+// image instead starts with public resolvers until the user configures DNS
+// for the local network.
+writeFileSync(
+  "/etc/resolv.conf",
+  process.env.REAL_MACHINE === "1"
+    ? "nameserver 1.1.1.1\nnameserver 8.8.8.8\n"
+    : "nameserver 10.0.2.3\n",
+);
+
 
 const loadModule = (path) => {
   const name = cString(path);
@@ -203,6 +222,36 @@ const configureRealKeyboard = () => {
   ]) loadModule(`/lib/modules/${release}/kernel/${module}`);
 };
 
+// ACPI battery, AC adapter, power button and thermal zones are modules on
+// Alpine's kernels; until they are loaded /sys/class/power_supply is empty.
+// Loaded on demand from the REPL as cfg.power, through /lib/modprobe.js (a
+// require() is fine here: /proc exists by the time anyone can type it). The
+// modules are only in the image when it was built with --real.
+const configureBattery = () => {
+  const { modprobe } = require("/lib/modprobe.js");
+  for (const module of ["battery", "ac", "button", "thermal"]) {
+    try {
+      const inserted = modprobe(module);
+      console.log(`acpi: ${module} ${inserted.length ? "loaded" : "already loaded"}`);
+    } catch (error) {
+      console.error(`acpi: ${module}: ${error.message}`);
+    }
+  }
+  const { readdirSync, readFileSync } = require("node:fs");
+  const read = (path) => { try { return readFileSync(path, "utf8").trim(); } catch { return "-"; } };
+  const supplies = (() => { try { return readdirSync("/sys/class/power_supply"); } catch { return []; } })();
+  if (supplies.length === 0) console.log("power_supply: nothing registered (no ACPI battery or AC adapter on this machine)");
+  for (const name of supplies) {
+    const base = `/sys/class/power_supply/${name}`;
+    const type = read(`${base}/type`);
+    const detail = type === "Battery"
+      ? `${read(`${base}/status`)} ${read(`${base}/capacity`)}%`
+      : `online=${read(`${base}/online`)}`;
+    console.log(`power_supply: ${name} ${type} ${detail}`);
+  }
+  return supplies;
+};
+
 const reapChildren = () => {
   const status = new Int32Array(1);
   while (libc.symbols.waitpid(-1, ptr(status), 1) > 0) {}
@@ -213,6 +262,13 @@ process.on("SIGCHLD", reapChildren);
 process.on("SIGTERM", () => console.log("PID 1 received SIGTERM"));
 process.on("SIGINT", () => console.log("PID 1 received SIGINT"));
 
+// The REPL catches what its eval throws, but not a rejection or a throw
+// from a timer or callback: Bun then exits, and PID 1 exiting is a kernel
+// panic ("Attempted to kill init!"). With a listener installed Bun only
+// reports, so a stray `Promise.reject()` at the prompt stays a message.
+process.on("uncaughtException", (error) => console.error("PID 1 uncaught exception (ignored):", error));
+process.on("unhandledRejection", (reason) => console.error("PID 1 unhandled rejection (ignored):", reason));
+
 
 try {
   bringUpLoopback();
@@ -228,6 +284,7 @@ try {
   console.error("USB keyboard setup failed:", error);
 }
 
+
 try {
   configureQemuNetwork();
   console.log("network: eth0 10.0.2.15/24 via 10.0.2.2");
@@ -289,7 +346,8 @@ const launchBuninu = () => {
   const shell = Bun.spawnSync([
     "/bin/bun", entry, "--local"
   ], {
-    env: { 
+    env: {
+      ...process.env,
       PATH:"/bin:/usr/bin:/buninu/bin",
       HOME:"/buninu"
     },
@@ -309,19 +367,109 @@ const launchBuninu = () => {
 //  Configuration complete
 
 
+globalThis.bunmsh = launchBunmsh;
+//console.log("Type bunmsh() to install and enter the bunmsh shell.");
+
+globalThis.start = launchBuninu;
+
+// cfg.net loads every packaged network module, including PHY and bus support
+// that a kernel userspace modprobe helper would normally load on demand. It
+// then reports the device matches and lists the resulting interfaces. The
+// address and route are still yours to set with `ip`.
+const configureEthernet = () => {
+  const { autoload, modprobeAll } = require("/lib/modprobe.js");
+  const { readdirSync, readFileSync } = require("node:fs");
+  const read = (path) => { try { return readFileSync(path, "utf8").trim(); } catch { return "-"; } };
+  const all = modprobeAll({ accept: (_module, path) => path.startsWith("kernel/drivers/net/") });
+  console.log(`eth: loaded all packaged network modules (${all.inserted.length} newly loaded, ${all.errors.length} failed)`);
+  for (const { module, error } of all.errors) console.log(`eth: ${module}: ${error}`);
+  const report = autoload({
+    // PCI class 02 (network), virtio device id 1 (net), every USB device —
+    // but only network drivers, so a USB keyboard does not show up as usbhid.
+    accept: (modalias) => /^usb:/.test(modalias) || /^virtio:d00000001v/.test(modalias) || /bc02sc/.test(modalias),
+    acceptModule: (module, path) => path.startsWith("kernel/drivers/net/"),
+  });
+  if (report.length === 0) console.log("eth: no network device matched a module in the image (driver built in, or not built with --real)");
+  // Network devices nothing in the image claims, so the chip is at least named.
+  try {
+    for (const device of readdirSync("/sys/bus/pci/devices")) {
+      const modalias = read(`/sys/bus/pci/devices/${device}/modalias`);
+      if (!/bc02sc/.test(modalias) || report.some((entry) => entry.device === device)) continue;
+      const [, vendor, id] = /^pci:v0000([0-9A-F]{4})d0000([0-9A-F]{4})/.exec(modalias) ?? [];
+      const kind = /bc02sc80/.test(modalias) ? "wireless" : "network";
+      console.log(`eth: pci ${device} ${kind} controller ${vendor}:${id} has no driver in the image`);
+    }
+  } catch {}
+  for (const { bus, device, modules, loaded, error } of report) {
+    const status = error ?? (loaded.length ? `loaded ${loaded.join(" ")}` : "already loaded");
+    console.log(`eth: ${bus} ${device} -> ${modules.join(" ")}: ${status}`);
+  }
+  const interfaces = (() => { try { return readdirSync("/sys/class/net").filter((name) => name !== "lo"); } catch { return []; } })();
+  for (const name of interfaces) {
+    const carrier = read(`/sys/class/net/${name}/carrier`);
+    console.log(`eth: ${name} ${read(`/sys/class/net/${name}/address`)} ${read(`/sys/class/net/${name}/operstate`)}${carrier === "1" ? " carrier" : ""}`);
+  }
+  if (interfaces.length) console.log(`eth:
+  Next steps in shell( after start() ):
+  ip link set ${interfaces[0]} up
+  ip addr add A.B.C.D/24 dev ${interfaces[0]};
+  ip route add default via GATEWAY
+`);
+  return interfaces;
+};
 
+// Explicit full coldplug for this deliberately tiny system: load every .ko
+// represented in modules.dep, recursively including each module's declared
+// dependencies. Failures are reported individually without stopping the rest.
+const configureModules = () => {
+  const { modprobeAll } = require("/lib/modprobe.js");
+  const report = modprobeAll();
+  console.log(`modules: ${report.inserted.length} newly loaded, ${report.errors.length} failed`);
+  for (const { module, error } of report.errors) console.log(`modules: ${module}: ${error}`);
+  return report;
+};
 
+// Load the packaged storage stack so devtmpfs can expose disks before the
+// user has a concrete /dev path to pass to mount. This covers virtio block,
+// SATA/PATA/SCSI, NVMe behind VMD, and USB mass-storage/UAS.
+const configureDisks = () => {
+  const { modprobeAll } = require("/lib/modprobe.js");
+  const { readdirSync } = require("node:fs");
+  const storagePath = /^kernel\/drivers\/(?:ata\/|block\/virtio_blk\.ko$|nvme\/|pci\/controller\/vmd\.ko$|scsi\/|usb\/storage\/)/;
+  const report = modprobeAll({ accept: (_module, path) => storagePath.test(path) });
+  console.log(`disk: ${report.inserted.length} newly loaded, ${report.errors.length} failed`);
+  for (const { module, error } of report.errors) console.log(`disk: ${module}: ${error}`);
+  const devices = (() => { try { return readdirSync("/sys/class/block"); } catch { return []; } })();
+  console.log(`disk: ${devices.length ? devices.map((name) => `/dev/${name}`).join(" ") : "no block devices registered"}`);
+  return devices;
+};
 
-console.log(`
+globalThis.cfg = Object.freeze(Object.defineProperties({}, {
+  all: { enumerable: true, get: configureModules },
+  disk: { enumerable: true, get: configureDisks },
+  net: { enumerable: true, get: configureEthernet },
+  power: { enumerable: true, get: configureBattery },
+}));
+
+// Compatibility aliases for images and notes that used the original API.
+globalThis.cfgEth = configureEthernet;
+globalThis.cfgNet = configureEthernet;
+globalThis.cfgDisk = configureDisks;
+globalThis.cfgMod = configureModules;
+globalThis.cfgBat = configureBattery;
+
+const showWelcome = () => {
+  console.log(`
 Welcome to Buninu Linux!
 Bun ${Bun.version} is now PID ${process.pid}
-`);
-
-globalThis.bunmsh = launchBunmsh;
-//console.log("Type bunmsh() to install and enter the bunmsh shell.");
+Type start() to run buninu --local`);
+  if (process.env.REAL_MACHINE === "1") {
+    console.log(`Configuration getters: ${Object.keys(globalThis.cfg).map((name) => `cfg.${name}`).join(", ")}`);
+  }
+  console.log();
+};
 
-globalThis.start = launchBuninu;
-console.log("Type start() to run buninu --local");
+showWelcome();
 
 const startRepl = () => {
   const server = repl.start({
@@ -330,6 +478,11 @@ const startRepl = () => {
     output: process.stdout,
     terminal: true,
   });
+  // Run before REPL's own line listener so its next prompt is printed after
+  // the repeated welcome. Empty and whitespace-only lines both trigger it.
+  server.prependListener("line", (line) => {
+    if (line.trim() === "") showWelcome();
+  });
   server.on("exit", () => {
     console.log("REPL exited; restarting it to keep PID 1 alive.");
     setTimeout(startRepl, 0);

package/initramfs/lib/dlopen.js

@@ -0,0 +1,130 @@
+// /lib/dlopen.js — the shared libc binding for Buninu Linux commands.
+//
+// init.js opens musl on its own because it runs before /proc exists and must
+// not import anything. Every other command imports this module instead, so
+// the symbol table, the errno plumbing and the error messages live in one
+// place. The library is located relative to this file (/lib in the guest),
+// which also lets the commands run from a checkout for testing.
+
+import { dlopen, FFIType, ptr, read, CString } from "bun:ffi";
+
+export { ptr, read };
+
+// Everything that differs per CPU lives in this table: the musl file name
+// and the syscall numbers musl has no wrapper for. Struct layouts used by
+// the commands (ifreq, rtentry) are the LP64 ones and hold on both.
+const architectures = {
+  x64: { libc: "libc.musl-x86_64.so.1", SYS_finit_module: 313 },
+  arm64: { libc: "libc.musl-aarch64.so.1", SYS_finit_module: 273 },
+};
+export const arch = architectures[process.arch]
+  ?? (() => { throw new Error(`unsupported CPU architecture ${process.arch}`); })();
+
+// BUNINU_LIBC lets the commands run on a glibc host for testing:
+//   BUNINU_LIBC=/lib/aarch64-linux-gnu/libc.so.6 bun initramfs/bin/ip addr
+export const libcPath = process.env.BUNINU_LIBC ?? `${import.meta.dir}/${arch.libc}`;
+
+export const libc = dlopen(libcPath, {
+  mount: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.u64, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  umount2: {
+    args: [FFIType.ptr, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  reboot: {
+    args: [FFIType.i32],
+    returns: FFIType.i32,
+  },
+  sync: {
+    args: [],
+    returns: FFIType.void,
+  },
+  __errno_location: {
+    args: [],
+    returns: FFIType.ptr,
+  },
+  strerror: {
+    args: [FFIType.i32],
+    returns: FFIType.ptr,
+  },
+  open: {
+    args: [FFIType.ptr, FFIType.i32, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  close: {
+    args: [FFIType.i32],
+    returns: FFIType.i32,
+  },
+  ioctl: {
+    args: [FFIType.i32, FFIType.u64, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  socket: {
+    args: [FFIType.i32, FFIType.i32, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  syscall: {
+    args: [FFIType.i64, FFIType.i64, FFIType.ptr, FFIType.i64],
+    returns: FFIType.i32,
+  },
+  waitpid: {
+    args: [FFIType.i32, FFIType.ptr, FFIType.i32],
+    returns: FFIType.i32,
+  },
+});
+
+export const cString = (value) => new TextEncoder().encode(`${value}\0`);
+
+// musl reports failure as -1 plus errno; the raw syscall() wrapper does too.
+const errnoLocation = libc.symbols.__errno_location();
+export const errno = () => read.i32(errnoLocation);
+export const strerror = (code) => new CString(libc.symbols.strerror(code)).toString();
+
+export const Errno = {
+  EPERM: 1, ENOENT: 2, ESRCH: 3, EIO: 5, ENXIO: 6, EBADF: 9, EAGAIN: 11, ENOMEM: 12,
+  EACCES: 13, EBUSY: 16, EEXIST: 17, ENODEV: 19, ENOTDIR: 20, EISDIR: 21,
+  EINVAL: 22, EROFS: 30, ENOTEMPTY: 39, ENOPKG: 65, ENOTSUP: 95,
+  EADDRNOTAVAIL: 99, ENETUNREACH: 101,
+};
+
+export class SysError extends Error {
+  constructor(operation, code = errno()) {
+    super(`${operation}: ${strerror(code)}`);
+    this.name = "SysError";
+    this.operation = operation;
+    this.errno = code;
+  }
+}
+
+// Wraps a libc call: throws SysError on -1 unless errno is in `allowed`,
+// in which case the negated errno comes back so the caller can tell.
+export const check = (operation, result, allowed = []) => {
+  if (result !== -1) return result;
+  const code = errno();
+  if (allowed.includes(code)) return -code;
+  throw new SysError(operation, code);
+};
+
+// An AF_INET datagram socket is the handle every SIOC* interface and route
+// ioctl wants. `use` receives an ioctl(request, buffer, operation) closure.
+export const withInetSocket = (use) => {
+  const fd = check("socket(AF_INET, SOCK_DGRAM)", libc.symbols.socket(2, 2, 0));
+  try {
+    const ioctl = (request, buffer, operation, allowed) =>
+      check(operation, libc.symbols.ioctl(fd, request, ptr(buffer)), allowed);
+    return use(ioctl, fd);
+  } finally {
+    libc.symbols.close(fd);
+  }
+};
+
+// Renders /usr/share/doc/buninu-linux/<name>.md for --help. Hyperlinks are
+// on so the references at the end of each page are clickable in terminals
+// that support OSC 8.
+export const showDocument = async (name) => {
+  const path = `${import.meta.dir}/../usr/share/doc/buninu-linux/${name}.md`;
+  const rendered = Bun.markdown.ansi(await Bun.file(path).text(), { hyperlinks: true });
+  process.stdout.write(rendered.endsWith("\n") ? rendered : `${rendered}\n`);
+};

package/initramfs/lib/modprobe.js

@@ -0,0 +1,235 @@
+// /lib/modprobe.js — kernel module loading shared by the Buninu Linux commands.
+//
+// There is no /sbin/modprobe for the kernel to call, so anything that needs a
+// driver (a filesystem, a block device, a NIC) has to load it, and its
+// dependencies, itself. fetch-alpine.sh ships the modules under
+// /lib/modules/<release>/ together with a modules.dep trimmed to that set and
+// the `fs-*` lines of modules.alias, and this module reads those.
+
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { libc, cString, check, ptr, Errno, arch } from "./dlopen.js";
+
+export const kernelRelease = () => {
+  if (process.env.KERNEL_RELEASE) return process.env.KERNEL_RELEASE;
+  try {
+    return readFileSync("/proc/sys/kernel/osrelease", "utf8").trim();
+  } catch {
+    return "unknown";
+  }
+};
+
+// /lib/modules/<release> in the guest; resolved relative to this file so a
+// checkout can be tested the same way.
+export const modulesDirectory = () => `${import.meta.dir}/modules/${kernelRelease()}`;
+
+// Module names are canonical with underscores: usb-common.ko is usb_common in
+// /proc/modules.
+const canonical = (name) => name.replaceAll("-", "_");
+
+const readIndex = (file) => {
+  try {
+    return readFileSync(`${modulesDirectory()}/${file}`, "utf8");
+  } catch {
+    return "";
+  }
+};
+
+// name -> { path, dependencies: [names] } from modules.dep.
+let dependencyTable;
+const dependencies = () => {
+  if (dependencyTable) return dependencyTable;
+  dependencyTable = new Map();
+  for (const line of readIndex("modules.dep").split("\n")) {
+    const separator = line.indexOf(":");
+    if (separator < 0) continue;
+    const path = line.slice(0, separator);
+    const deps = line.slice(separator + 1).trim().split(/\s+/).filter(Boolean);
+    dependencyTable.set(canonical(moduleName(path)), {
+      path,
+      dependencies: deps.map((dep) => canonical(moduleName(dep))),
+    });
+  }
+  return dependencyTable;
+};
+
+const moduleName = (path) => path.slice(path.lastIndexOf("/") + 1).replace(/\.ko(\.gz)?$/, "");
+
+// modules.alias: exact names (fs-ntfs -> ntfs3) in a map, and the device
+// patterns (pci:v000010ECd00008168sv*sd*bc*sc*i* -> r8169) as regexps.
+let aliasTable;
+const aliases = () => {
+  if (aliasTable) return aliasTable;
+  aliasTable = { exact: new Map(), patterns: [] };
+  for (const line of readIndex("modules.alias").split("\n")) {
+    const [keyword, pattern, target] = line.trim().split(/\s+/);
+    if (keyword !== "alias" || !target) continue;
+    const module = canonical(target);
+    if (/[*?]/.test(pattern)) {
+      const source = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*").replaceAll("?", ".");
+      aliasTable.patterns.push({ regexp: new RegExp(`^${source}$`), module });
+    } else {
+      aliasTable.exact.set(pattern, module);
+    }
+  }
+  return aliasTable;
+};
+
+export const resolveAlias = (alias) => {
+  const { exact } = aliases();
+  return exact.get(alias) ?? exact.get(canonical(alias)) ?? canonical(alias);
+};
+
+// The modules whose alias patterns match a device's modalias string.
+export const modulesForModalias = (modalias) => {
+  const found = [];
+  for (const { regexp, module } of aliases().patterns) {
+    if (regexp.test(modalias) && !found.includes(module)) found.push(module);
+  }
+  return found;
+};
+
+// What udev's coldplug does: read each device's modalias under
+// /sys/bus/<bus>/devices and load the drivers that claim it. `accept`
+// filters by modalias (e.g. PCI class 02 = network: /bc02/), `acceptModule`
+// by module name and path (e.g. only kernel/drivers/net/). A driver built
+// into the kernel has no alias line, so its device simply goes unreported.
+// Returns one
+// entry per device with the modules loaded, or the error, for it.
+export const modulePath = (name) => dependencies().get(resolveAlias(name))?.path ?? null;
+
+export const autoload = ({ buses = ["pci", "virtio", "usb"], accept = () => true, acceptModule = () => true } = {}) => {
+  const report = [];
+  for (const bus of buses) {
+    let devices;
+    try {
+      devices = readdirSync(`/sys/bus/${bus}/devices`);
+    } catch {
+      continue;
+    }
+    for (const device of devices) {
+      let modalias;
+      try {
+        modalias = readFileSync(`/sys/bus/${bus}/devices/${device}/modalias`, "utf8").trim();
+      } catch {
+        continue;
+      }
+      if (!accept(modalias, device)) continue;
+      const modules = modulesForModalias(modalias).filter((module) => acceptModule(module, modulePath(module) ?? ""));
+      if (modules.length === 0) continue;
+      const entry = { bus, device, modalias, modules, loaded: [], error: null };
+      for (const module of modules) {
+        try {
+          entry.loaded.push(...modprobe(module));
+        } catch (error) {
+          entry.error = error.message;
+        }
+      }
+      report.push(entry);
+    }
+  }
+  return report;
+};
+
+export const loadedModules = () => {
+  const loaded = new Set();
+  try {
+    for (const line of readFileSync("/proc/modules", "utf8").split("\n")) {
+      const name = line.split(" ")[0];
+      if (name) loaded.add(name);
+    }
+  } catch {}
+  return loaded;
+};
+
+export const isLoaded = (name) => loadedModules().has(canonical(name));
+
+// Built-in drivers are absent from /proc/modules and from modules.dep, so
+// the ones that matter to callers are listed in modules.builtin.
+let builtinTable;
+export const isBuiltin = (name) => {
+  if (!builtinTable) {
+    builtinTable = new Set(
+      readIndex("modules.builtin").split("\n").filter(Boolean).map((path) => canonical(moduleName(path))),
+    );
+  }
+  return builtinTable.has(canonical(name));
+};
+
+// finit_module(2) on one .ko file. EEXIST (loaded meanwhile, or built in
+// and registered under the same name) is not an error.
+export const insertModule = (path, parameters = "") => {
+  const fd = check(`open(${path})`, libc.symbols.open(ptr(cString(path)), 0, 0));
+  try {
+    const flags = path.endsWith(".gz") ? 4 : 0; // MODULE_INIT_COMPRESSED_FILE
+    // musl has no finit_module wrapper, so use its generic syscall(2).
+    const result = check(
+      `finit_module(${path})`,
+      libc.symbols.syscall(arch.SYS_finit_module, fd, ptr(cString(parameters)), flags),
+      [Errno.EEXIST],
+    );
+    return result === 0;
+  } finally {
+    libc.symbols.close(fd);
+  }
+};
+
+export class ModuleNotFound extends Error {
+  constructor(name) {
+    super(`module ${name} not found in ${modulesDirectory()}`);
+    this.name = "ModuleNotFound";
+    this.module = name;
+  }
+}
+
+// Loads `name` (a module name or a modules.alias key) and, first, whatever
+// modules.dep says it needs. Returns the list of modules actually inserted.
+export const modprobe = (name, parameters = "", { loaded = loadedModules(), inserted = [] } = {}) => {
+  const module = resolveAlias(name);
+  if (loaded.has(module) || isBuiltin(module)) return inserted;
+
+  const entry = dependencies().get(module);
+  if (!entry) throw new ModuleNotFound(module);
+
+  // modules.dep lists dependencies in reverse load order; recursing on each
+  // one covers the deps-of-deps case no matter how the line is ordered.
+  for (const dependency of [...entry.dependencies].reverse()) {
+    modprobe(dependency, "", { loaded, inserted });
+  }
+
+  const path = `${modulesDirectory()}/${entry.path}`;
+  if (!existsSync(path)) throw new ModuleNotFound(module);
+  if (insertModule(path, parameters)) inserted.push(module);
+  loaded.add(module);
+  return inserted;
+};
+
+// Load every selected module shipped in the initramfs (all modules by
+// default). This is useful on the small real-machine image, where there is no
+// userspace modprobe helper to satisfy a driver's later request for an
+// optional PHY or bus module. Keep going after an individual failure: a
+// module for absent hardware commonly rejects initialization, and that must
+// not prevent the remaining modules loading.
+export const modprobeAll = ({ accept = () => true } = {}) => {
+  const loaded = loadedModules();
+  const inserted = [];
+  const errors = [];
+  for (const [module, entry] of dependencies()) {
+    if (!accept(module, entry.path)) continue;
+    try {
+      modprobe(module, "", { loaded, inserted });
+    } catch (error) {
+      errors.push({ module, error: error.message });
+    }
+  }
+  return { inserted, errors };
+};
+
+// Best-effort variant for optional drivers: a missing module is not an error.
+export const tryModprobe = (name, parameters = "") => {
+  try {
+    return modprobe(name, parameters);
+  } catch (error) {
+    if (error instanceof ModuleNotFound) return null;
+    throw error;
+  }
+};