FreeBSD Manual Pages
SNDSTAT(4) Kernel Interfaces Manual SNDSTAT(4) NAME sndstat -- nvlist-based PCM audio device enumeration interface SYNOPSIS To compile the driver into the kernel, place the following lines in the kernel configuration file: device sound DESCRIPTION The ioctl interface provided by /dev/sndstat device allows callers to enumerate PCM audio devices available for use. In other words, it pro- vides means to get the list of all audio devices available to the sys- tem. IOCTLS For ioctl calls that take an argument, the following structure is used: struct sndstioc_nv_arg { size_t nbytes; void *buf; }; Here is an example of an nvlist object with explanations of the common fields: dsps (NVLIST ARRAY): 1 from_user (BOOL): FALSE nameunit (STRING): [pcm0] devnode (STRING): [dsp0] desc (STRING): [Generic (0x8086) (Analog Line-out)] pchan (NUMBER): 1 rchan (NUMBER): 0 info_play (NVLIST): min_rate (NUMBER): 48000 max_rate (NUMBER): 48000 formats (NUMBER): 16 min_chn (NUMBER): 2 max_chn (NUMBER): 2 provider_info (NVLIST): unit (NUMBER): 0 status (STRING): on hdaa0 bitperfect (BOOL): FALSE pvchan (NUMBER): 1 pvchanrate (NUMBER): 48000 pvchanformat (NUMBER): 0x00000010 rvchan (NUMBER): 0 rvchanrate (NUMBER): 48000 rvchanformat (NUMBER): 0x00000010 channel_info (NVLIST_ARRAY): 1 name (STRING): pcm0:virtual_play:dsp0.vp0 parentchan (STRING): pcm0:play:dsp0.p0 unit (NUMBER): 1 caps (NUMBER): 0x073200 latency (NUMBER): 2 rate (NUMBER): 48000 format (NUMBER): 0x201000 pid (NUMBER): 1234 comm (STRING): mpv interrupts (NUMBER): 0 feedcount (NUMBER): 0 xruns (NUMBER): 0 left_volume (NUMBER): 45 right_volume (NUMBER): 45 hwbuf_fmt (NUMBER): 0x200010 hwbuf_size (NUMBER): 0 hwbuf_blksz (NUMBER): 0 hwbuf_blkcnt (NUMBER): 0 hwbuf_free (NUMBER): 0 hwbuf_ready (NUMBER): 0 swbuf_fmt (NUMBER): 0x201000 swbuf_size (NUMBER): 16384 swbuf_blksz (NUMBER): 2048 swbuf_blkcnt (NUMBER): 8 swbuf_free (NUMBER): 16384 swbuf_ready (NUMBER): 0 feederchain (STRING): [userland -> feeder_root(0x00201000) -> feeder_format(0x00201000 -> 0x00200010) -> feeder_volume(0x00200010) -> hardware] provider (STRING): [sound(4)] from_user Whether the PCM audio device node is created by in-ker- nel audio subsystem or userspace providers. nameunit The device identification in the form of subsystem plus a unit number. devnode The PCM audio device node relative path in devfs. desc The descripton of the PCM audio device. pchan The number of playback channels supported by hardware. This can be 0 if this PCM audio device does not support playback at all. rchan The number of recording channels supported by hardware. This can be 0 if this PCM audio device does not support recording at all. info_play Supported configurations in playback direction. This exists only if this PCM audio device supports playback. There are a number of name/value pairs inside this field: min_rate Minimum supported sampling rate. max_rate Maximum supported sampling rate. formats Supported sample formats. min_chn Minimum supported number of channels in chan- nel layout max_chn Maximum supported number of channels in chan- nel layout info_rec Supported configurations in recording direction. This exists only if this PCM audio device supports recording. There are a number of name/value pairs inside this field: min_rate Minimum supported sampling rate. max_rate Maximum supported sampling rate. formats Supported sample formats. min_chn Minimum supported number of channels in chan- nel layout max_chn Maximum supported number of channels in chan- nel layout provider_info Provider-specific fields. This field may not exist if the PCM audio device is not provided by in-kernel inter- face. This field will not exist if the provider field is an empty string. For the sound(4) provider, there are a number of name/value pairs inside this field: unit Sound card unit. status Status string. Usually reports the driver the device is attached on. bitperfect Whether the sound card has bit-perfect mode enabled. pvchan Number of playback virtual channels. pvchanrate Playback virtual channel sample rate. pvchanformat Playback virtual channel format. rvchan Number of recording virtual channels. rvchanrate Recording virtual channel sample rate. rvchanformat Recording virtual channel format. channel_info Channel information. There are a number of name/value pairs inside this field: name Channel name. parentchan Parent channel name (e.g., in the case of virtual chan- nels). unit Channel unit. caps OSS capabilities. latency Latency. rate Sampling rate. format Sampling format. pid PID of the process consuming the channel. comm Name of the process consum- ing the channel. interrupts Number of interrupts since the channel has been opened. xruns Number of overruns/under- runs, depending on channel direction. feedcount Number of read/written bytes since the channel has been opened. left_volume Left volume. right_volume Right volume. hwbuf_format Hardware buffer format. hwbuf_size Hardware buffer size. hwbuf_blksz Hardware buffer block size. hwbuf_blkcnt Hardware buffer block count. hwbuf_free Free space in hardware buffer (in bytes). hwbuf_ready Number of bytes ready to be read/written from hardware buffer. swbuf_format Software buffer format. swbuf_size Software buffer size. swbuf_blksz Software buffer block size. swbuf_blkcnt Software buffer block count. swbuf_free Free space in software buffer (in bytes). swbuf_ready Number of bytes ready to be read/written from software buffer. feederchain Channel feeder chain. provider A string specifying the provider of the PCm audio de- vice. The following ioctls are provided for use: SNDSTIOC_REFRESH_DEVS Drop any previously fetched PCM audio devices list snapshots. This ioctl takes no argu- ments. SNDSTIOC_GET_DEVS Generate and/or return PCM audio devices list snapshots to callers. This ioctl takes a pointer to struct sndstioc_nv_arg as the first and the only argument. Callers need to provide a sufficiently large buffer to hold a serialized nvlist. If there is no existing PCM audio device list snapshot available in the internal structure of the opened sndstat. fd, a new PCM audio device list snapshot will be automatically generated. Callers have to set nbytes to either 0 or the size of buffer provided. In case nbytes is 0, the buffer size required to hold a serialized nvlist stream of current snapshot will be returned in nbytes, and buf will be ignored. Other- wise, if the buffer is not sufficiently large, the ioctl returns success, and nbytes will be set to 0. If the buffer provided is sufficiently large, nbytes will be set to the size of the serialized nvlist written to the provided buffer. Once a PCM audio device list snapshot is returned to user-space suc- cessfully, the snapshot stored in the subsys- tem's internal structure of the given fd will be freed. SNDSTIOC_ADD_USER_DEVS Add a list of PCM audio devices provided by callers to /dev/sndstat device. This ioctl takes a pointer to struct sndstioc_nv_arg as the first and the only argument. Callers have to provide a buffer holding a serialized nvlist. nbytes should be set to the length in bytes of the serialized nvlist. buf should be pointed to a buffer storing the se- rialized nvlist. Userspace-backed PCM audio device nodes should be listed inside the se- rialized nvlist. SNDSTIOC_FLUSH_USER_DEVS Flush any PCM audio devices previously added by callers. This ioctl takes no arguments. FILES /dev/sndstat EXAMPLES The following code enumerates all available PCM audio devices: #include <sys/types.h> #include <err.h> #include <fcntl.h> #include <stdio.h> #include <stdlib.h> #include <sys/nv.h> #include <sys/sndstat.h> #include <sysexits.h> #include <unistd.h> int main() { int fd; struct sndstioc_nv_arg arg; const nvlist_t * const *di; size_t i, nitems; nvlist_t *nvl; /* Open sndstat node in read-only first */ fd = open("/dev/sndstat", O_RDONLY); if (ioctl(fd, SNDSTIOC_REFRESH_DEVS, NULL)) err(1, "ioctl(fd, SNDSTIOC_REFRESH_DEVS, NULL)"); /* Get the size of snapshot, when nbytes = 0 */ arg.nbytes = 0; arg.buf = NULL; if (ioctl(fd, SNDSTIOC_GET_DEVS, &arg)) err(1, "ioctl(fd, SNDSTIOC_GET_DEVS, &arg)"); /* Get snapshot data */ arg.buf = malloc(arg.nbytes); if (arg.buf == NULL) err(EX_OSERR, "malloc"); if (ioctl(fd, SNDSTIOC_GET_DEVS, &arg)) err(1, "ioctl(fd, SNDSTIOC_GET_DEVS, &arg)"); /* Deserialize the nvlist stream */ nvl = nvlist_unpack(arg.buf, arg.nbytes, 0); free(arg.buf); /* Get DSPs array */ di = nvlist_get_nvlist_array(nvl, SNDST_DSPS, &nitems); for (i = 0; i < nitems; i++) { const char *nameunit, *devnode, *desc; /* * Examine each device nvlist item */ nameunit = nvlist_get_string(di[i], SNDST_DSPS_NAMEUNIT); devnode = nvlist_get_string(di[i], SNDST_DSPS_DEVNODE); desc = nvlist_get_string(di[i], SNDST_DSPS_DESC); printf("Name unit: `%s`, Device node: `%s`, Description: `%s`0, nameunit, devnode, desc); } nvlist_destroy(nvl); return (0); } SEE ALSO sound(4), nv(9) HISTORY The nvlist-based ioctls support for sndstat device first appeared in FreeBSD 13.0. AUTHORS This manual page was written by Ka Ho Ng <khng@FreeBSD.org>. FreeBSD 14.3 July 26, 2024 SNDSTAT(4)
NAME | SYNOPSIS | DESCRIPTION | IOCTLS | FILES | EXAMPLES | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=sndstat&sektion=4&manpath=FreeBSD+14.3-RELEASE+and+Ports>