audio: /dev/dsp, AudioEngine, and an AC'97 under it

A program that wants to make a sound opens /dev/dsp, writes PCM, and closes
it. That is what UNIX audio has always been and it now exists here:

    tone 440 2

Three pieces, in the order a sample passes through them. **/dev/dsp** is a
character device where write() is audio and a handful of OSS ioctls say what
the samples are. **AudioEngine** is everything above a driver that is not
specific to a chip -- the format, whether there is room, and what a write does
when there is not. **A driver** is bound by class, exactly as a display driver
is: device_find_class(DEVCLASS_AUDIO).

OSS numbering rather than something new, because every UNIX audio program ever
written already knows it and the only thing a different set would achieve is
making ports harder. They are read/write ioctls, which is the part that
matters: a program asks for 44100, the device sets 48000 and writes 48000
back, the program resamples. One that ignores the answer plays 9% fast, and
that is its bug rather than the driver's.

**The engine is deliberately one stream.** Mixing several programs is a real
feature with a real design behind it, and building it before anything had
played a single sound would be exactly what docs/plan/1.0.md keeps a register
for: work that exists and is connected to nothing. The second program that
wants to play at the same time is what should cause it to be written.

**audio_wait() sleeps on the timer tick, not on the device.** That looks like
the lazy choice and is not: a ring that drains is a ring with room, so asking
again in ten milliseconds always makes progress, whereas sleeping on the card
makes audio depend on an interrupt arriving. On a machine whose line is
misrouted that is not a stutter, it is a writer that never wakes. The handler
still accounts for finished buffers -- deleting it would cost efficiency, not
correctness -- and it retires descriptors through the same `tail` pointer
queue() uses, so the two cannot disagree about what is in flight.

**AC'97 first because HDA is two unproven things at once.** It is the simplest
audio device that exists on real machines and in QEMU both. Intel HDA is what
the laptop actually has and is a much larger driver; writing it against an
interface nothing had ever played through would have meant debugging the
driver and the interface simultaneously. HDA arrives as a second
struct audio_ops and nothing above it changes -- which is the entire point of
the class.

Two things the wiring needed: PCI class 0x04 now maps to DEVCLASS_AUDIO (the
driver bound and /proc/devices showed it, but audio_get() found nothing,
because the class byte had never been translated), and include/x86.h grew
inw() -- AC'97's mixer is all 16-bit registers and reading one a byte at a
time returns the low half twice on some codecs.

**Tested by measuring what came out, not by not crashing.** QEMU's wav backend
writes the guest's audio to a file; `tone 440 2` produced 1.97 seconds of
44.1 kHz stereo with peak amplitude 14177 against the generator's table
maximum of 14178, and 880 zero crossings per second -- 440 Hz exactly. wav is
on every QEMU target rather than a host backend, because a build machine may
have no sound card and it is the only backend whose output can be checked.

Both supported configurations: one boot each, no traps, no panics, socktest
and memfdtest green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Makefile

@@ -26,7 +26,7 @@ KERN_CORE = $(addprefix $(BUILD)/kernel/core/, \
 KERN_DEV  = $(addprefix $(BUILD)/kernel/dev/, \
               bio.o cdev.o device.o disk.o fb.o ide.o input.o irq.o kbd.o keymap.o mouse.o \
               pci.o pciuser.o text.o ttf.o uart.o gfx.o vt.o ramdisk.o procfs.o \
-              dbg.o netuser.o)
+              dbg.o netuser.o audio.o)
 
 # Drivers for hardware that has to be *found* rather than assumed. Anything
 # discovered by walking a bus belongs here; the fixed-address legacy devices
@@ -43,6 +43,7 @@ KERN_DRIVERS += $(BUILD)/kernel/drivers/gpu/vga/vga_pci.o
 KERN_DRIVERS += $(BUILD)/kernel/drivers/gpu/vga/vga_fb.o
 KERN_DRIVERS += $(BUILD)/kernel/drivers/gpu/virtio_gpu/virtio_gpu.o
 KERN_DRIVERS += $(BUILD)/kernel/drivers/net/e1000/e1000.o
+KERN_DRIVERS += $(BUILD)/kernel/drivers/audio/ac97.o
 KERN_DRIVERS += $(BUILD)/kernel/drivers/bus/xhci/xhci.o
 KERN_DRIVERS += $(BUILD)/kernel/drivers/usb/core/usb.o
 KERN_DRIVERS += $(BUILD)/kernel/drivers/usb/hid/usb_hid.o
@@ -108,7 +109,7 @@ KERN_NOENTRY = $(filter-out $(BUILD)/kernel/arch/x86_64/entry.o, $(KERNOBJS))
 # Third-party software does NOT go here — see ports/.
 # -----------------------------------------------------------------------
 ULIB    = $(addprefix $(BUILD)/lib/, start.o glue.o usys.o)
-CMDS    = schinit schinitd fbinfo shmtest socktest inputtest nettest reflink schattr ping chvt loadkeys sigtest memfdtest pcitest vgpud schdbg schdbgd resolvconf httpd schmode netecho ldlsd
+CMDS    = schinit schinitd fbinfo shmtest socktest inputtest nettest reflink schattr ping chvt loadkeys sigtest memfdtest pcitest vgpud schdbg schdbgd resolvconf httpd schmode netecho ldlsd tone
 CMDBINS = $(addprefix $(BUILD)/cmd/, $(CMDS))
 
 # -----------------------------------------------------------------------
@@ -194,6 +195,18 @@ QEMU_DISPLAY = -vga std -device virtio-gpu-pci
 # claim and exits, and the single window is the thing you wanted to look at.
 QEMU_DISPLAY_1 = -vga std
 
+# Sound, on every QEMU target.
+#
+# `wav` rather than a host audio backend: a build machine may have no
+# soundcard, no PulseAudio and no session bus, and a QEMU that fails to open
+# one of those prints a warning per voice and carries on -- which is noise in
+# every boot log for a feature most runs are not testing. Writing to a file
+# works everywhere and is the only backend that can be *checked*: the audio
+# test plays a tone and measures the zero crossings of what came out.
+#
+# To actually hear it: make qemu QEMU_AUDIO='-audiodev pa,id=snd0 -device AC97,audiodev=snd0'
+QEMU_AUDIO ?= -audiodev wav,id=snd0,path=$(BUILD)/qemu-audio.wav -device AC97,audiodev=snd0
+
 # A network card, on every QEMU target.
 #
 # Spelled out rather than left to QEMU's default NIC. The default exists and is
@@ -643,7 +656,7 @@ ovmf: $(OVMF_CODE) $(OVMF_VARS)
 all: $(OVMF_CODE) $(OVMF_VARS)
 
 qemu-uefi: esp $(BUILD)/schfs.img $(OVMF_CODE) $(OVMF_VARS)
-	$(QEMU) -machine pc-i440fx-9.2 	    -drive if=pflash,format=raw,unit=0,readonly=on,file=$(OVMF_CODE) 	    -drive if=pflash,format=raw,unit=1,file=$(OVMF_VARS) 	    -drive file=fat:rw:$(BUILD)/esp,index=0,media=disk,format=raw 	    -drive file=$(BUILD)/schfs.img,format=raw,index=1,media=disk 	    -m 1G -smp 1 $(QEMU_ACCEL) -serial mon:stdio $(QEMU_DISPLAY) $(QEMU_INPUT) $(QEMU_NET)
+	$(QEMU) -machine pc-i440fx-9.2 	    -drive if=pflash,format=raw,unit=0,readonly=on,file=$(OVMF_CODE) 	    -drive if=pflash,format=raw,unit=1,file=$(OVMF_VARS) 	    -drive file=fat:rw:$(BUILD)/esp,index=0,media=disk,format=raw 	    -drive file=$(BUILD)/schfs.img,format=raw,index=1,media=disk 	    -m 1G -smp 1 $(QEMU_ACCEL) -serial mon:stdio $(QEMU_DISPLAY) $(QEMU_INPUT) $(QEMU_NET) $(QEMU_AUDIO)
 
 # Build the ramdisk-root variant. This is a target rather than just
 # "make RAMROOT=1" because toggling RAMROOT changes CFLAGS (-DRAMDISK_ROOT),
@@ -1356,7 +1369,7 @@ qemu-gdb: esp $(BUILD)/schfs.img $(OVMF_CODE) $(OVMF_VARS)
 	    -S -gdb tcp::$(GDBPORT)
 
 qemu-kvm: esp $(BUILD)/schfs.img $(OVMF_CODE) $(OVMF_VARS)
-	$(QEMU) -enable-kvm -serial mon:stdio $(QEMU_DISPLAY) $(QEMU_INPUT) $(QEMU_NET) -cpu host \
+	$(QEMU) -enable-kvm -serial mon:stdio $(QEMU_DISPLAY) $(QEMU_INPUT) $(QEMU_NET) $(QEMU_AUDIO) -cpu host \
 	    $(OVMF_DRIVES) -m 1G -smp $(SMP) -machine pc-i440fx-9.2
 
 qemu: esp $(BUILD)/schfs.img $(OVMF_CODE) $(OVMF_VARS)