Change Details

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): 3 from_user (BOOL): FALSE unit (NUMBER): 0 (0) (0x0) pchan (NUMBER): 1 (1) (0x1) rchan (NUMBER): 0 (0) (0x0) pvchan (NUMBER): 1 (1) (0x1) rvchan (NUMBER): 0 (0) (0x0) devnode (STRING): [dsp0] desc (STRING): [Generic (0x8086) (Analog Line-out)] , from_user (BOOL): FALSE unit (NUMBER): 1 (1) (0x1) pchan (NUMBER): 1 (1) (0x1) rchan (NUMBER): 0 (0) (0x0) pvchan (NUMBER): 1 (1) (0x1) rvchan (NUMBER): 0 (0) (0x0) devnode (STRING): [dsp1] desc (STRING): [Generic (0x8086) (Analog Line-out)] , from_user (BOOL): TRUE pchan (NUMBER): 1 (1) (0x1) rchan (NUMBER): 0 (0) (0x0) devnode (STRING): [vdsp0] desc (STRING): [Virtual device from userspace] , ``` ###### 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. The schema of the 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.

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): 5 from_user (BOOL): FALSE unit (NUMBER): 0 (0) (0x0) pchan (NUMBER): 1 (1) (0x1) rchan (NUMBER): 0 (0) (0x0) pvchan (NUMBER): 1 (1) (0x1) rvchan (NUMBER): 0 (0) (0x0) nameunit (STRING): [pcm0] devnode (STRING): [/dev/dsp0] desc (STRING): [Generic (0x8086) (Analog Line-out)] , from_user (BOOL): FALSE unit (NUMBER): 1 (1) (0x1) pchan (NUMBER): 1 (1) (0x1) rchan (NUMBER): 0 (0) (0x0) pvchan (NUMBER): 1 (1) (0x1) rvchan (NUMBER): 0 (0) (0x0) nameunit (STRING): [pcm1] devnode (STRING): [/dev/dsp1] desc (STRING): [Generic (0x8086) (Analog Line-out)] , from_user (BOOL): TRUE pchan (NUMBER): 8 (8) (0x8) rchan (NUMBER): 8 (8) (0x8) nameunit (STRING): [pcm10] devnode (STRING): [/dev/pcm10] desc (STRING): [Virtual OSS] , 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] , 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] , ``` ###### 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.

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): 35 from_user (BOOL): FALSE unit (NUMBER): 0 (0) (0x0) pchan (NUMBER): 1 (1) (0x1) rchan (NUMBER): 0 (0) (0x0) pvchan (NUMBER): 1 (1) (0x1) rvchan (NUMBER): 0 (0) (0x0) devnodenameunit (STRING): [dsp0pcm0] devnode (STRING): [/dev/dsp0] desc (STRING): [Generic (0x8086) (Analog Line-out)] , from_user (BOOL): FALSE unit (NUMBER): 1 (1) (0x1) pchan (NUMBER): 1 (1) (0x1) rchan (NUMBER): 0 (0) (0x0) pvchan (NUMBER): 1 (1) (0x1) rvchan (NUMBER): 0 (0) (0x0) devnodenameunit (STRING): [dsp1pcm1] devnode (STRING): [/dev/dsp1] desc (STRING): [Generic (0x8086) (Analog Line-out)] , from_user (BOOL): TRUE pchan (NUMBER): 1 (18 (8) (0x18) rchan (NUMBER): 0 (08 (8) (0x08) devnodenameunit (STRING): [vdsp0pcm10] descdevnode (STRING): [Virtual device from userspace/dev/pcm10] desc (STRING): [Virtual OSS] , ``` ###### SNDSTAT_ADD_USER_DEVS from_user (BOOL): TRUE This IOCTL command takes `struct sndstat_nvlbuf_arg`. Callers need to provide a pchan (NUMBER): 8 (8) (0x8) buffer holding a packed nvlist stream. Userspace-provided DSP nodes should be rchan (NUMBER): 8 (8) (0x8) listed inside the packed nvlist stream. The schema of the packed nvlist stream nameunit (STRING): [dsp10] is as follows: ``` dsps (NVLIST ARRAY): 2 devnode (STRING): [vdsp0/dev/dsp10] desc (STRING): [Virtual device from userspaceOSS] pchan (NUMBER): 1 (1) (0x1), rchan (NUMBER): 0 (0) (0x0)from_user (BOOL): TRUE ,pchan (NUMBER): 8 (8) (0x8) devnode (STRING): [vdsp1]rchan (NUMBER): 8 (8) (0x8) descnameunit (STRING): [Virtual device from userspace 2lvdsp0] pchan (NUMBER): 1 (1) (0x1)devnode (STRING): [/dev/lvdsp0] rchan (NUMBER): 1 (1) (0x1)desc (STRING): [Virtual OSS] , ``` ###### 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.