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. If there exists a snapshot of device
list, the snapshot will be freed.
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.
Once a snapshot is returned to user-space successfully, the snapshot will be freed.
The schema of the packed nvlist stream is as follows:
dsps (NVLIST ARRAY): 3
from_user (BOOL): FALSE
nameunit (STRING): [pcm0]
devnode (STRING): [dsp0]
desc (STRING): [Generic (0x8086) (Analog Line-out)]
pchan (NUMBER): 1 (1) (0x1)
rchan (NUMBER): 0 (0) (0x0)
pminrate (NUMBER): 48000 (48000) (0xbb80)
pmaxrate (NUMBER): 48000 (48000) (0xbb80)
pfmts (NUMBER): 2097168 (2097168) (0x200010)
provider_info (NVLIST):
unit (NUMBER): 0 (0) (0x0)
bitperfect (BOOL): FALSE
pvchan (NUMBER): 1 (1) (0x1)
rvchan (NUMBER): 0 (0) (0x0)
provider (STRING): [sound(4)]
,
from_user (BOOL): TRUE
pchan (NUMBER): 8 (8) (0x8)
rchan (NUMBER): 8 (8) (0x8)
nameunit (STRING): [vdsp0]
devnode (STRING): [vdsp0]
desc (STRING): [Virtual OSS]
pminrate (NUMBER): 48000 (48000) (0xbb80)
pmaxrate (NUMBER): 48000 (48000) (0xbb80)
pfmts (NUMBER): 16 (16) (0x10)
rminrate (NUMBER): 48000 (48000) (0xbb80)
rmaxrate (NUMBER): 48000 (48000) (0xbb80)
rfmts (NUMBER): 16 (16) (0x10)
provider (STRING): []
,
from_user (BOOL): TRUE
pchan (NUMBER): 8 (8) (0x8)
rchan (NUMBER): 8 (8) (0x8)
nameunit (STRING): [lvdsp0]
devnode (STRING): [lvdsp0]
desc (STRING): [Virtual OSS]
pminrate (NUMBER): 48000 (48000) (0xbb80)
pmaxrate (NUMBER): 48000 (48000) (0xbb80)
pfmts (NUMBER): 16 (16) (0x10)
rminrate (NUMBER): 48000 (48000) (0xbb80)
rmaxrate (NUMBER): 48000 (48000) (0xbb80)
rfmts (NUMBER): 16 (16) (0x10)
provider (STRING): []
,SNDSTAT_ADD_USER_DEVS
This IOCTL command takes struct sndstat_nvlbuf_arg. Callers need to provide a
buffer holding a packed nvlist stream. Userspace-provided DSP nodes should be
listed inside the packed nvlist stream. An example of minimally-defined packed
nvlist stream is as follows:
dsps (NVLIST ARRAY): 2
devnode (STRING): [vdsp0]
desc (STRING): [Virtual device from userspace]
pchan (NUMBER): 1 (1) (0x1)
rchan (NUMBER): 0 (0) (0x0)
,
devnode (STRING): [vdsp1]
desc (STRING): [Virtual device from userspace 2]
pchan (NUMBER): 1 (1) (0x1)
rchan (NUMBER): 1 (1) (0x1)
,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