Audio leaves soundserver for an hda driver per controller; the matcher takes any prog-if

Cargo.toml

@@ -119,10 +119,12 @@ members = [
     "system/pkg",
     "system/ps2server",
     "system/ps2server/ps2",
+    "system/hda",
+    "system/hda/driver",
     "system/shell",
     "system/soundserver",
-    "system/soundserver/hda",
     "system/soundserver/mixer",
+    "system/soundserver/output",
     "system/soundserver/resample",
     "system/soundserver/virtio-sound",
     "system/sshserver",

images/system.toml

@@ -100,8 +100,17 @@ devices = ["isa:0060,0064:1,12"]
 
 [programs.soundserver]
 service = true
-serves = ["soundserver", "volume"]
-devices = ["pci:04:03:00", "pci:04:01:00/1af4:1059"]
+serves = ["soundserver", "volume", "sound-output"]
+devices = ["pci:04:01:00/1af4:1059"]
+syscap = ["rt"]
+
+# The Intel HD Audio driver: one process per HDA function the kernel does not
+# drive, each walking its own controller's codecs and offering soundserver the
+# output it reaches. A machine with display audio beside an analog codec runs
+# two, and soundserver plays to the one that offers.
+[programs.hda]
+drives = ["pci:04:03:*"]
+receives = ["sound-output"]
 syscap = ["rt"]
 
 # netstack holds the NIC's PCI function and drives it: the virtqueues, the register

issues/a-device-function-is-driven-from-its-arrival-to-its-end.md

@@ -104,6 +104,19 @@ started. Nothing reaches userland when a device arrives or leaves.
 3. **Drivers leave the shared services.** netstack, soundserver and diskserver
    each become a driver per function plus the service its clients use. The
    client port carries a per-device source and `gone`.
+   - **Done for HDA.** `hda` is a `drives` row on `pci:04:03:*`, one process
+     per controller; each walks its own codecs and offers soundserver the
+     output it reaches on `sound-output` (`toyos-sound-output`), and one that
+     reaches none ends by name. soundserver plays to the first offer it can
+     mix into, beginning when no stream is open; it is the null sink until
+     then, and refuses every later offer. A driver gone after soundserver
+     began playing to it ends soundserver. QEMU's two-controller row is
+     `hda_plays_to_the_controller_that_reaches_an_output`.
+   - Next: virtio-sound is still driven inside soundserver
+     (`system/soundserver/src/virtio.rs`); it becomes a driver on the same
+     port. Then the output set: a second output offered while one plays, a
+     driver's `gone`, and a stream moved to another output, none of which
+     soundserver serves yet; and netstack and diskserver.
 4. **usbd drives every xHCI**, one per controller, started by stage 1's `drives` rows.
    This is step 10 of
    `issues/the-kernel-is-small-interrupts-post-and-threads-wait.md`, whose

issues/cpals-close-bound-is-one-ring-of-device-time.md

@@ -0,0 +1,28 @@
+---
+status: open
+kind: defect
+opened: 2026-10-20
+---
+
+# cpal's close is bounded by one ring of device time, a verdict rather than a hang ceiling
+
+cpal's ToyOS host (`src/host/toyos/mod.rs` in the cpal fork, branch
+`toyos-0.18.0`, `Stream`'s `Drop`) waits for its stream thread to end, which
+is the event soundserver's release of the closed stream causes, for at most
+`release_within`: the stream's fade and one ring of periods at the device's
+rate, about 29 ms at 44.1 kHz. A release that takes longer is reported through
+the error callback as `soundserver did not let go of the closed stream within
+…`, and `tests/guest/rust-tests/src/tone.rs` fails the job on it.
+
+That bound is the device's playout time, not a hang ceiling. On QEMU 11.1.1's
+`ich9-intel-hda` under TCG, periods complete in bursts of up to a ring paced by
+the host (`max_batch=7`), and the bound failed `test_rs_audio_tone` and
+`test_rs_audio_tone_resampled` at host load averages 22 and 101 with every
+period completed and `underruns=0` (#950's evidence,
+https://github.com/ToyOSOrg/evidence/tree/b0d5671935257fff8fff68c3b7d9d788ee718292/hda-claim/qemu). A loaded metal machine can be late the same
+way. So the QEMU HDA row runs the master job only, and the tone jobs are
+judged on the benches alone.
+
+Owner: the cpal fork. Exit: the close waits for the stream thread's end with a
+failure timeout sized as a hang ceiling, and a release that is merely slow is
+not an error; the QEMU HDA row then runs `test_rs_audio_tone` too.

issues/every-driver-is-still-in-the-kernel.md

@@ -32,10 +32,12 @@ is not built.
 
 What is left of the staged work:
 
-1. Done for HDA: soundserver claims the function as `pci:04:03:00` and
-   drives it whole (`system/soundserver/hda/src/controller.rs`) — controller
-   reset, CORB/RIRB, the stream and its descriptor list in the claim's grant,
-   its interrupt as the claim's record. The `hda-audio` class,
+1. Done for HDA: an `hda` process per function of `pci:04:03:*` (a
+   `drives` row, `system/hda`) drives it whole — controller reset, CORB/RIRB,
+   the stream and its descriptor list, the ring soundserver lends it, its
+   interrupt as the claim's record — and offers soundserver its output
+   (`issues/a-device-function-is-driven-from-its-arrival-to-its-end.md`'s
+   stage 3). The `hda-audio` class,
    `SYS_HDA_BIND`, `SYS_DEVICE_REG_WRITE` and the kernel's HDA vector are
    gone; `SYS_DEVICE_REG_READ` reads a PCI claim's config space alone. Every
    machine's DLL is clocked by a claim's record, and a period read before its

issues/hda-has-no-jack-detection-and-nothing-persists.md

@@ -6,14 +6,14 @@ opened: 2026-08-03
 
 # HDA plays, but there is no jack detection and nothing persists
 
-The driver is soundserver's, whole, through a `pci` claim: the controller,
-codec decoding, output-path selection and the master are a pure crate
-(`system/soundserver/hda`). The master volume and mute are the codec's, served on
-soundserver's `volume` port, and the volume keys set them from the compositor
+The driver is the `hda` program's, one per function, through a `pci` claim:
+the controller, codec decoding, output-path selection and the master are a
+pure crate (`system/hda/driver`). The master volume and mute are the codec's,
+set by the driver for soundserver's `volume` port, and the volume keys set them from the compositor
 (#877). What remains:
 
 - **Jack detection and routing.** `GET_PIN_SENSE` is spelled
-  (`system/soundserver/hda/src/verb.rs`) and nothing issues it. Still wanted: a poll on the
+  (`system/hda/driver/src/verb.rs`) and nothing issues it. Still wanted: a poll on the
   presence bit, a switch between the fixed speaker and the headphone pin, and a
   ramp across the switch so it is not a click.
 - **Persistence** of the chosen output and the master level, blocked on the
@@ -22,12 +22,13 @@ soundserver's `volume` port, and the volume keys set them from the compositor
 **Two pieces of the shipped work are still owed a verdict.** The four HDA
 sections of the audio baseline were never recorded, so the HDA arm asserts harm
 and claims no distribution and has no thorough tier — that is 30 invocations on
-a quiet host. And a shape profile is missing: a codec with no speaker pin (a
-controller with no codec is refused by name in the controller's host tests). Without them the refusal-to-null-sink path is
-asserted only on a machine that has no controller at all.
+a quiet host. And a shape profile is missing: a codec with no speaker pin. A
+controller with no codec is refused by name, and soundserver stays the null
+sink until another offers, on QEMU's two-controller row
+(`hda_plays_to_the_controller_that_reaches_an_output`).
 
 Constraints worth not re-deriving (each already stated at its site in
-`system/soundserver/hda/`, listed here because they are what
+`system/hda/driver/`, listed here because they are what
 the next pass will want):
 
 - **The T14's trap is pin 0x1b, not the display codec.** Four pins claim

lib/manifest/src/device.rs

@@ -3,7 +3,8 @@
 //! A class, a partition or an ISA set is the ABI's own spelling
 //! ([`DeviceRequest::parse`]). A PCI function is matched here, by its class
 //! code and optionally its card: `pci:CC:SS:PP` or `pci:CC:SS:PP/VVVV:DDDD`,
-//! lowercase hex. **Every matcher carries its class**, so whether two entries
+//! lowercase hex, where `PP` may be `*` for every programming interface of the
+//! subclass. **Every matcher carries its class**, so whether two entries
 //! can name one function is decided from their text alone ([`Entry::overlaps`]),
 //! and a claim names the function a matcher found by its arrival.
 
@@ -33,27 +34,45 @@ impl Entry {
     pub fn overlaps(&self, other: &Self) -> bool {
         match (self, other) {
             (Self::Fixed(a), Self::Fixed(b)) => a == b,
-            (Self::Pci(a), Self::Pci(b)) => a.class == b.class && (a.id.is_none() || b.id.is_none() || a.id == b.id),
+            (Self::Pci(a), Self::Pci(b)) => {
+                a.class == b.class && either(a.prog_if, b.prog_if) && either(a.id, b.id)
+            }
             _ => false,
         }
     }
 }
 
+/// Whether two optional fields can hold one value: either is unset, or both
+/// are the same.
+fn either<T: PartialEq>(x: Option<T>, y: Option<T>) -> bool {
+    x.is_none() || y.is_none() || x == y
+}
+
 /// Which PCI functions an entry names: every function of a class code, or of
 /// one card within it.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct PciMatch {
-    /// Base class, subclass and programming interface.
-    pub class: [u8; 3],
+    /// Base class and subclass.
+    pub class: [u8; 2],
+    /// The programming interface, or `None` for every one: a subclass whose
+    /// interfaces are one register model told apart by vendor extensions (HD
+    /// Audio's 00 and 80) is driven alike whichever a function reports.
+    pub prog_if: Option<u8>,
     pub id: Option<PciId>,
 }
 
 impl PciMatch {
     pub const PREFIX: &'static str = "pci:";
 
-    /// Every function of class `class`, of card `id` where it names one.
+    /// Every function of class code `class`, of card `id` where it names one.
     pub const fn new(class: [u8; 3], id: Option<PciId>) -> Self {
-        Self { class, id }
+        Self { class: [class[0], class[1]], prog_if: Some(class[2]), id }
+    }
+
+    /// Every function of `class`'s base class and subclass, whatever its
+    /// programming interface.
+    pub const fn any_interface(class: [u8; 2], id: Option<PciId>) -> Self {
+        Self { class, prog_if: None, id }
     }
 
     pub fn parse(text: &str) -> Option<Self> {
@@ -65,27 +84,33 @@ impl PciMatch {
             }
             None => (rest, None),
         };
-        let mut class = [0u8; 3];
         let mut fields = code.split(':');
-        for byte in &mut class {
-            *byte = hex8(fields.next()?)?;
-        }
+        let class = [hex8(fields.next()?)?, hex8(fields.next()?)?];
+        let prog_if = match fields.next()? {
+            "*" => None,
+            byte => Some(hex8(byte)?),
+        };
         if fields.next().is_some() {
             return None;
         }
-        Some(Self { class, id: card })
+        Some(Self { class, prog_if, id: card })
     }
 
     pub fn matches(&self, pci: &Pci) -> bool {
-        [pci.class, pci.subclass, pci.prog_if] == self.class
+        [pci.class, pci.subclass] == self.class
+            && self.prog_if.is_none_or(|prog_if| prog_if == pci.prog_if)
             && self.id.is_none_or(|id| id.vendor == pci.vendor && id.device == pci.device)
     }
 }
 
 impl fmt::Display for PciMatch {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        let [class, subclass, prog_if] = self.class;
-        write!(f, "{}{class:02x}:{subclass:02x}:{prog_if:02x}", Self::PREFIX)?;
+        let [class, subclass] = self.class;
+        write!(f, "{}{class:02x}:{subclass:02x}:", Self::PREFIX)?;
+        match self.prog_if {
+            Some(prog_if) => write!(f, "{prog_if:02x}")?,
+            None => f.write_str("*")?,
+        }
         match self.id {
             Some(id) => write!(f, "/{:04x}:{:04x}", id.vendor, id.device),
             None => Ok(()),
@@ -135,7 +160,9 @@ mod tests {
 
     #[test]
     fn a_matcher_writes_back_the_text_it_parsed() {
-        for text in ["pci:01:08:02/1b36:0010", "pci:0c:03:30", "pci:ff:00:00/1234:11e8", "pci:00:00:00"] {
+        for text in
+            ["pci:01:08:02/1b36:0010", "pci:0c:03:30", "pci:ff:00:00/1234:11e8", "pci:00:00:00", "pci:04:03:*", "pci:04:03:*/8086:a0c8"]
+        {
             let parsed = PciMatch::parse(text).unwrap_or_else(|| panic!("{text} did not parse"));
             assert_eq!(parsed.to_string(), text);
             assert_eq!(Entry::parse(text), Some(Entry::Pci(parsed)));
@@ -151,7 +178,7 @@ mod tests {
             "pci:1b36:0010", // a card without its class
             "pci:01:08", "pci:01:08:02:00", "pci:1:08:02", "pci:01:08:0A", "pci:01:08:02/",
             "pci:01:08:02/1B36:0010", "pci:01:08:02/1b36", "pci:01:08:02/1b36:0010/x", "pci:+1:08:02",
-            "pci:", "pci",
+            "pci:", "pci", "pci:04:03:**", "pci:04:*:*", "pci:04:03:*:00", "pci:04:03:",
             // The card is four lowercase hex digits each and nothing else: two
             // spellings would be two labels for one claim.
             "pci:02:00:00/1Af4:1041", "pci:02:00:00/1af4:41", "pci:02:00:00/1af4", "pci:02:00:00/1af4:1041:",
@@ -178,6 +205,17 @@ mod tests {
         assert!(any_nvme.matches(&function([0x01, 0x08, 0x02], 0x144d, 0xa808)));
     }
 
+    /// The T14's HD Audio controller reports programming interface 0x80 and
+    /// QEMU's 0x00: one matcher names both, and nothing outside the subclass.
+    #[test]
+    fn a_wildcard_interface_matches_every_interface_of_its_subclass() {
+        let hda = PciMatch::parse("pci:04:03:*").unwrap();
+        assert!(hda.matches(&function([0x04, 0x03, 0x80], 0x8086, 0xa0c8)));
+        assert!(hda.matches(&function([0x04, 0x03, 0x00], 0x8086, 0x293e)));
+        assert!(!hda.matches(&function([0x04, 0x01, 0x00], 0x1af4, 0x1059)));
+        assert!(!PciMatch::parse("pci:04:03:00").unwrap().matches(&function([0x04, 0x03, 0x80], 0x8086, 0xa0c8)));
+    }
+
     /// Whether two entries can name one device, decided from their text: the
     /// build refuses a manifest where they can.
     #[test]
@@ -188,6 +226,8 @@ mod tests {
             ("pci:01:08:02", "pci:01:08:02/1b36:0010"),
             ("pci:01:08:02/1b36:0010", "pci:01:08:02"),
             ("pci:0c:03:30", "pci:0c:03:30"),
+            ("pci:04:03:*", "pci:04:03:80"),
+            ("pci:04:03:00/8086:293e", "pci:04:03:*"),
             ("framebuffer", "framebuffer"),
             ("isa:0060,0064:1,12", "isa:0060,0064:1,12"),
             ("part:0FC63DAF-8483-4772-8E79-3D69D8477DE4", "part:0FC63DAF-8483-4772-8E79-3D69D8477DE4"),
@@ -198,6 +238,7 @@ mod tests {
         let apart = [
             ("pci:01:08:02/1b36:0010", "pci:01:08:02/144d:a808"),
             ("pci:01:08:02", "pci:01:08:01"),
+            ("pci:04:03:*", "pci:04:01:00"),
             ("pci:01:08:02/1b36:0010", "pci:01:08:01/1b36:0010"),
             ("framebuffer", "keyboard"),
             ("pci:0c:03:30", "keyboard"),

lib/manifest/src/lib.rs

@@ -634,7 +634,7 @@ mod tests {
                     name: "soundserver".into(),
                     path: "/system/bin/soundserver".into(),
                     serves: vec!["soundserver".into()],
-                    devices: vec!["pci:04:03:00".into(), "pci:04:01:00/1af4:1059".into()],
+                    devices: vec!["pci:04:01:00/1af4:1059".into()],
                     syscap: vec!["rt".into()],
                     service: true,
                     ..Program::default()

system/hda/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "hda"
+description = "The Intel HD Audio driver: one process per HDA function the kernel does not drive, holding its claim, walking its codecs and offering soundserver the output it reaches."
+edition = "2024"
+license = "MIT OR Apache-2.0"
+
+[dependencies]
+toyos-abi = { path = "../../sdk/abi" }
+toyos = { path = "../../sdk/toyos" }
+toyos-hda = { path = "driver" }
+toyos-manifest = { path = "../../lib/manifest" }
+toyos-pci-claim = { path = "../../lib/pci-claim" }
+toyos-sound-output = { path = "../soundserver/output" }
+
+[package.metadata.toyos.host]
+exempt.owns = "one Intel HD Audio function, claimed from the kernel, and its output offered on soundserver's sound-output port"