This is an API draft of the sndstat IOCTLs addition. These IOCTL commands are
drafted to provide an easier way for user space applications to enumerate
existing audio devices and the node they can potentially use.
The exchange of arguments between user space and kernel is based on nvlist.
A few IOCTLs are added to dev sndstat node:
* SNDSTAT_REFRESH_DEVS
* SNDSTAT_GET_DEVS
* SNDSTAT_ADD_USER_DEVS
* SNDSTAT_FLUSH_USER_DEVS
---
###### SNDSTAT_REFRESH_DEVS
This IOCTL command takes NO arguments. It fetches a snapshot of the current
device list if there is no existing device list stored in the corresponding
sndstat_file of the opened sndstat FD. If there exists a snapshot of device
list, a new snapshot will be fetched and will replace the existing snapshot.
###### SNDSTAT_GET_DEVS
This IOCTL command takes `struct sndstat_nvlbuf_arg`. Callers need to provide a
sufficiently large buffer to hold a packed nvlist stream. If there is no
existing device list snapshot available in the corresponding sndstat_file of the
opened sndstat FD, a new snapshot will be automatically fetched. Callers could
call this IOCTL command with arg.nbytes = 0. If it is the case, the buffer size
required to hold a packed nvlist stream of current snapshot will be returned.
Otherwise, callers are required to point arg.nbytes to the size of buffer
provided. If the buffer is not sufficiently large, the command returns with
arg.nbytes set to 0. If the buffer provided is sufficiently large, arg.nbytes will be
the size of packed nvlist stream written to the provided buffer.
The schema of the packed nvlist stream is as follows:
```
dsps (NVLIST ARRAY): 54
from_user (BOOL): FALSE
unit (NUMBER): 0 (0) (0x0)
pchan (NUMBER): 1 (1) (0x1)nameunit (STRING): [pcm0]
rchan (NUMBER): 0 (0) (0x0)devnode (STRING): [/dev/dsp0]
pvchan (NUMBER): 1 (1) (0x1)desc (STRING): [Generic (0x8086) (Analog Line-out)]
rvpchan (NUMBER): 0 (01 (1) (0x01)
nameunit (STRING): [pcm0]rchan (NUMBER): 0 (0) (0x0)
devnode (STRING): [/dev/dsp0]pvchan (NUMBER): 0 (0) (0x0)
desc (STRING): [Generic (0x8086) (Analog Line-out)]rvchan (NUMBER): 0 (0) (0x0)
,pminrate (NUMBER): 16000 (16000) (0x3e80)
from_user (BOOL): FALSEpmaxrate (NUMBER): 192000 (192000) (0x2ee00)
unitpfmts (NUMBER): 1 (1044987 (1044987) (0x1ff1fb)
pchan (NUMBER): 1 (1) (0x1)bitperfect (BOOL): FALSE
rchan (NUMBER): 0 (0) (0x0),
pvchan (NUMBER): 1 (1) (0x1)from_user (BOOL): TRUE
rvpchan (NUMBER): 0 (08 (8) (0x08)
nameunit (STRING): [pcm1]rchan (NUMBER): 8 (8) (0x8)
devnodenameunit (STRING): [/dev/dsp1pcm10]
descdevnode (STRING): [Generic (0x8086) (Analog Line-out)/dev/pcm10]
,desc (STRING): [Virtual OSS]
from_user (BOOL): TRUEpminrate (NUMBER): 48000 (48000) (0xbb80)
pchanpmaxrate (NUMBER): 8 (848000 (48000) (0x8bb80)
rchanpfmts (NUMBER): 8 (80 (0) (0x80)
nameunit (STRING): [pcm10]rminrate (NUMBER): 48000 (48000) (0xbb80)
devnode (STRING): [/dev/pcm10]rmaxrate (NUMBER): 48000 (48000) (0xbb80)
desc (STRING): [Virtual OSS]rfmts (NUMBER): 0 (0) (0x0)
,
from_user (BOOL): TRUE
pchan (NUMBER): 8 (8) (0x8)
rchan (NUMBER): 8 (8) (0x8)
nameunit (STRING): [dsp10]
devnode (STRING): [/dev/dsp10]
desc (STRING): [Virtual OSS]
pminrate (NUMBER): 48000 (48000) (0xbb80)
pmaxrate (NUMBER): 48000 (48000) (0xbb80)
pfmts (NUMBER): 0 (0) (0x0)
rminrate (NUMBER): 48000 (48000) (0xbb80)
rmaxrate (NUMBER): 48000 (48000) (0xbb80)
rfmts (NUMBER): 0 (0) (0x0)
,
from_user (BOOL): TRUE
pchan (NUMBER): 8 (8) (0x8)
rchan (NUMBER): 8 (8) (0x8)
nameunit (STRING): [lvdsp0]
devnode (STRING): [/dev/lvdsp0]
desc (STRING): [Virtual OSS]
pminrate (NUMBER): 48000 (48000) (0xbb80)
pmaxrate (NUMBER): 48000 (48000) (0xbb80)
pfmts (NUMBER): 0 (0) (0x0)
rminrate (NUMBER): 48000 (48000) (0xbb80)
rmaxrate (NUMBER): 48000 (48000) (0xbb80)
rfmts (NUMBER): 0 (0) (0x0)
,
```
###### SNDSTAT_FLUSH_USER_DEVS
This IOCTL command takes NO arguments. It flushes all the user space devices
added to the sndstat_file of the FD so far.
---
sound(4)-devices-specific labels in `dsps`:
* unit
* pvchan
* rvchan
* bitperfect
These labels will not be available if `pchan` is 0:
* pminrate
* pmaxrate
* pfmts
These labels will not be available if `rchan` is 0:
* rminrate
* rmaxrate
* rfmts