The audio subsystem page listed the source files and the configuration
options, but nothing about the interface the upper half presents to
applications. PR #18348 added a device state machine, a second buffer
allocation mode, poll and mmap support and several new ioctls, none of
which were described anywhere, so the only way to learn the expected
call sequence was to read audio/audio.c.
Document what the upper half now guarantees:
- the device state machine, and the fact that AUDIOIOC_START is
rejected until AUDIOIOC_CONFIGURE has moved the device out of
AUDIO_STATE_OPEN;
- the normal open/configure/allocate/enqueue/start sequence;
- the two AUDIOIOC_ALLOCBUFFER modes selected by u.pbuffer, who owns
the buffers in each, and that a shared ring request may return zero
when the ring is already populated;
- that AUDIOIOC_GETBUFFERINFO also establishes the shared ring depth,
so a lower half which does not implement it disables that mode;
- the poll event semantics and how mmap() selects between a ring
buffer and the device status by requested length;
- all ioctls handled by the upper half, grouped by purpose;
- how per-open state is aggregated into the device state when several
applications share one device.
No functional change.
Signed-off-by: fangyibo <fangyibo@xiaomi.com>
This commit adds some documentation about the audio tone driver, how to
use it and links to it from the main audio component page. I also added
some back links to other audio docs there for convenience.
Signed-off-by: Matteo Golin <matteo.golin@gmail.com>
