SchOS/docs/architecture/audio.md

Audio

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

tone 440 2          # 440 Hz for two seconds

Three pieces, in the order a sample passes through them:

/dev/dsp	kernel/dev/audio.c. A character device: write() is audio, and a handful of OSS ioctls say what the samples are.
AudioEngine	The same file. 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	kernel/drivers/audio/ac97.c today. Bound by class, exactly as a display driver is — device_find_class(DEVCLASS_AUDIO).

Why OSS and not something new

The ioctls are SNDCTL_DSP_SPEED, SNDCTL_DSP_CHANNELS, SNDCTL_DSP_SETFMT, SNDCTL_DSP_SYNC and SNDCTL_DSP_GETOSPACE, with OSS's own numbering. They are not invented here and they are not copied for nostalgia: every UNIX audio program that has ever been written knows them, 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 everything 9% fast, and that is its bug rather than the driver's. configure in the class works the same way, and for the same reason — a driver that can only do 48 kHz says so there, rather than by quietly failing a write() later.

What the engine is, and what it deliberately is not

It owns format negotiation, the "is there room" question, and blocking. Those are genuinely shared: a second driver should not have to re-implement wait until the speaker has caught up.

It is one stream. Mixing several programs into one device is a real feature with a real design behind it, and building it before anything had played a single sound would be exactly the mistake ../plan/1.0.md keeps a register against: 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.

Waiting on the tick, not on the device

audio_wait() sleeps until the next timer tick rather than on an interrupt from the sound card, which looks like the lazy choice and is not.

A ring that drains is a ring with room in it, so asking again in ten milliseconds always makes progress. Sleeping on the device would make audio depend on the interrupt arriving — and on a machine whose line is misrouted, or a chip that needs a kick, that is not a stutter, it is a writer that never wakes up. The interrupt handler is still there and still accounts for finished buffers; the point is that deleting it would cost efficiency and not correctness.

AC'97 first, and HDA later

AC'97 is the simplest audio device that exists both on real machines and in QEMU. Intel HDA is what a laptop built this century actually has, and it is a much larger driver — codec enumeration, CORB/RIRB, stream descriptors. Writing it first would have meant writing two unproven things at once: a driver, and the interface it is the only user of.

The class is the whole point of the order. HDA arrives as a second struct audio_ops and nothing above it changes.

How it plays

The chip reads a buffer descriptor list: 32 entries, each naming a physical address and a length. It plays the entry at CIV and stops when it reaches LVI, the last valid index. Playing continuously is therefore not "start it and walk away" — it is keeping LVI ahead of CIV, which is what queue() does, one 4 KB descriptor at a time.

Retiring finished descriptors happens in both queue() and the interrupt handler, through the same tail pointer so the two cannot disagree. That is the same "the interrupt is an optimisation" stance as above.

Both register files are I/O ports, not MMIO — which is why nothing in the driver maps anything. bar[n].is_io is what says so, and a driver that ioremaped these would be mapping a port number as though it were an address.

Through ALSA, for programs that expect it

SDL 3 has no OSS backend and SchOS has no ALSA kernel side, so sound from SDL games and anything else that speaks ALSA goes SDL → alsa-lib → alsa-plugins' OSS plugin → /dev/dsp. alsa-lib and alsa-plugins are in the Alpine world, and /etc/asound.conf (from schos-base) makes the default device a plug onto the OSS device at 16-bit stereo 48 kHz, which is what every SchOS audio driver plays.

Running that path found two bugs underneath it:

• AC'97: resetting the PCM-out box also clears the descriptor-list address and nothing set it again, so every stream after the first stop played a "list" at physical address 0 — silence — and ALSA resets before each stream. If the engine halts at the end of the queue, the run bit is set again.
• /dev/dsp was missing the ioctls the plugin's ring-and-pointer model uses: SETFRAGMENT, GETFMTS, GETCAPS, SETTRIGGER, GETOPTR, GETODELAY, and poll(), writable once a whole fragment fits (ALSA spun at 76% CPU otherwise). speaker-test now plays in real time at 0% CPU, verified in a recording of QEMU's AC'97.

How it is tested

QEMU's wav audio backend writes what the guest plays to a file, so the test is not "it did not crash":

make qemu            # QEMU_AUDIO puts an AC97 on every target
tone 440 2

and the file is measured — 1.97 seconds of 44.1 kHz stereo, peak amplitude 14177 against the tone generator's table maximum of 14178, and 880 zero crossings per second, which is 440 Hz exactly.

wav rather than a host backend on purpose: a build machine may have no sound card, no PulseAudio and no session bus, and it is the only backend whose output can be checked. To actually hear it:

make qemu QEMU_AUDIO='-audiodev pa,id=snd0 -device AC97,audiodev=snd0'

What it does not do

• Recording. read() on /dev/dsp returns ENOSYS rather than zero, because zero is end-of-file and a recorder would write an empty file and call it a success.
• Mixing. One stream; see above.
• Mono. The driver reports two channels because AC'97 plays stereo, and a mono stream would have to be doubled somewhere. The write-back tells the caller, which is the whole reason the ioctl has a direction.
• Formats other than signed 16-bit little-endian. It is what every PC audio chip takes natively and what a WAV file already contains. Converting in the kernel to satisfy a caller that could have converted first is not an obvious trade.
• Volume. The mixer is set to full and left there. How loud a machine is is not the kernel's decision, and a device that comes up silent reads as broken to whoever is testing it.