diff options
Diffstat (limited to 'static/freebsd/man4/sndstat.4 3.html')
| -rw-r--r-- | static/freebsd/man4/sndstat.4 3.html | 382 |
1 files changed, 382 insertions, 0 deletions
diff --git a/static/freebsd/man4/sndstat.4 3.html b/static/freebsd/man4/sndstat.4 3.html new file mode 100644 index 00000000..30f37c7f --- /dev/null +++ b/static/freebsd/man4/sndstat.4 3.html @@ -0,0 +1,382 @@ +<table class="head"> + <tr> + <td class="head-ltitle">SNDSTAT(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">SNDSTAT(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">sndstat</code> — + <span class="Nd">nvlist-based PCM audio device enumeration + interface</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp">To compile the driver into the kernel, place the following lines + in the kernel configuration file:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">device sound</code></div> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The ioctl interface provided by + <span class="Pa">/dev/sndstat</span> device allows callers to enumerate PCM + audio devices available for use. In other words, it provides means to get + the list of all audio devices available to the system.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="IOCTLS"><a class="permalink" href="#IOCTLS">IOCTLS</a></h1> +<p class="Pp">For ioctl calls that take an argument, the following structure is + used:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>struct sndstioc_nv_arg { + size_t nbytes; + void *buf; +};</pre> +</div> +<p class="Pp">Here is an example of an nvlist object with explanations of the + common fields:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>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 (BOOL): TRUE + pvchanrate (NUMBER): 48000 + pvchanformat (NUMBER): 0x00000010 + rvchan (BOOL): TRUE + rvchanrate (NUMBER): 48000 + rvchanformat (NUMBER): 0x00000010 + channel_info (NVLIST_ARRAY): 1 + name (STRING): dsp0.virtual_play.0 + parentchan (STRING): dsp0.play.0 + 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_rate (NUMBER): 48000 + 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_rate (NUMBER): 48000 + 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)]</pre> +</div> +<dl class="Bl-tag"> + <dt id="from_user"><a class="permalink" href="#from_user"><code class="Dv">from_user</code></a></dt> + <dd>Whether the PCM audio device node is created by in-kernel audio subsystem + or userspace providers.</dd> + <dt id="nameunit"><a class="permalink" href="#nameunit"><code class="Dv">nameunit</code></a></dt> + <dd>The device identification in the form of subsystem plus a unit + number.</dd> + <dt id="devnode"><a class="permalink" href="#devnode"><code class="Dv">devnode</code></a></dt> + <dd>The PCM audio device node relative path in devfs.</dd> + <dt id="desc"><a class="permalink" href="#desc"><code class="Dv">desc</code></a></dt> + <dd>The description of the PCM audio device.</dd> + <dt id="pchan"><a class="permalink" href="#pchan"><code class="Dv">pchan</code></a></dt> + <dd>The number of playback channels supported by hardware. This can be 0 if + this PCM audio device does not support playback at all.</dd> + <dt id="rchan"><a class="permalink" href="#rchan"><code class="Dv">rchan</code></a></dt> + <dd>The number of recording channels supported by hardware. This can be 0 if + this PCM audio device does not support recording at all.</dd> + <dt id="info_play"><a class="permalink" href="#info_play"><code class="Dv">info_play</code></a></dt> + <dd>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: + <dl class="Bl-tag"> + <dt id="min_rate"><a class="permalink" href="#min_rate"><code class="Dv">min_rate</code></a></dt> + <dd>Minimum supported sampling rate.</dd> + <dt id="max_rate"><a class="permalink" href="#max_rate"><code class="Dv">max_rate</code></a></dt> + <dd>Maximum supported sampling rate.</dd> + <dt id="formats"><a class="permalink" href="#formats"><code class="Dv">formats</code></a></dt> + <dd>Supported sample formats.</dd> + <dt id="min_chn"><a class="permalink" href="#min_chn"><code class="Dv">min_chn</code></a></dt> + <dd>Minimum supported number of channels in channel layout</dd> + <dt id="max_chn"><a class="permalink" href="#max_chn"><code class="Dv">max_chn</code></a></dt> + <dd>Maximum supported number of channels in channel layout</dd> + </dl> + </dd> + <dt id="info_rec"><a class="permalink" href="#info_rec"><code class="Dv">info_rec</code></a></dt> + <dd>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: + <dl class="Bl-tag"> + <dt id="min_rate~2"><a class="permalink" href="#min_rate~2"><code class="Dv">min_rate</code></a></dt> + <dd>Minimum supported sampling rate.</dd> + <dt id="max_rate~2"><a class="permalink" href="#max_rate~2"><code class="Dv">max_rate</code></a></dt> + <dd>Maximum supported sampling rate.</dd> + <dt id="formats~2"><a class="permalink" href="#formats~2"><code class="Dv">formats</code></a></dt> + <dd>Supported sample formats.</dd> + <dt id="min_chn~2"><a class="permalink" href="#min_chn~2"><code class="Dv">min_chn</code></a></dt> + <dd>Minimum supported number of channels in channel layout</dd> + <dt id="max_chn~2"><a class="permalink" href="#max_chn~2"><code class="Dv">max_chn</code></a></dt> + <dd>Maximum supported number of channels in channel layout</dd> + </dl> + </dd> + <dt id="provider_info"><a class="permalink" href="#provider_info"><code class="Dv">provider_info</code></a></dt> + <dd>Provider-specific fields. This field may not exist if the PCM audio device + is not provided by in-kernel interface. This field will not exist if the + provider field is an empty string. For the <a class="Xr">sound(4)</a> + provider, there are a number of name/value pairs inside this field: + <dl class="Bl-tag"> + <dt id="unit"><a class="permalink" href="#unit"><code class="Dv">unit</code></a></dt> + <dd>Sound card unit.</dd> + <dt id="status"><a class="permalink" href="#status"><code class="Dv">status</code></a></dt> + <dd>Status string. Usually reports the driver the device is attached + on.</dd> + <dt id="bitperfect"><a class="permalink" href="#bitperfect"><code class="Dv">bitperfect</code></a></dt> + <dd>Whether the sound card has bit-perfect mode enabled.</dd> + <dt id="pvchan"><a class="permalink" href="#pvchan"><code class="Dv">pvchan</code></a></dt> + <dd>Playback virtual channels enabled.</dd> + <dt id="pvchanrate"><a class="permalink" href="#pvchanrate"><code class="Dv">pvchanrate</code></a></dt> + <dd>Playback virtual channel sample rate.</dd> + <dt id="pvchanformat"><a class="permalink" href="#pvchanformat"><code class="Dv">pvchanformat</code></a></dt> + <dd>Playback virtual channel format.</dd> + <dt id="rvchan"><a class="permalink" href="#rvchan"><code class="Dv">rvchan</code></a></dt> + <dd>Recording virtual channels enabled.</dd> + <dt id="rvchanrate"><a class="permalink" href="#rvchanrate"><code class="Dv">rvchanrate</code></a></dt> + <dd>Recording virtual channel sample rate.</dd> + <dt id="rvchanformat"><a class="permalink" href="#rvchanformat"><code class="Dv">rvchanformat</code></a></dt> + <dd>Recording virtual channel format.</dd> + <dt id="channel_info"><a class="permalink" href="#channel_info"><code class="Dv">channel_info</code></a></dt> + <dd>Channel information. There are a number of name/value pairs inside + this field: + <dl class="Bl-tag"> + <dt id="name"><a class="permalink" href="#name"><code class="Dv">name</code></a></dt> + <dd>Channel name.</dd> + <dt id="parentchan"><a class="permalink" href="#parentchan"><code class="Dv">parentchan</code></a></dt> + <dd>Parent channel name (e.g., in the case of virtual channels).</dd> + <dt id="unit~2"><a class="permalink" href="#unit~2"><code class="Dv">unit</code></a></dt> + <dd>Channel unit.</dd> + <dt id="caps"><a class="permalink" href="#caps"><code class="Dv">caps</code></a></dt> + <dd>OSS capabilities.</dd> + <dt id="latency"><a class="permalink" href="#latency"><code class="Dv">latency</code></a></dt> + <dd>Latency.</dd> + <dt id="rate"><a class="permalink" href="#rate"><code class="Dv">rate</code></a></dt> + <dd>Sampling rate.</dd> + <dt id="format"><a class="permalink" href="#format"><code class="Dv">format</code></a></dt> + <dd>Sampling format.</dd> + <dt id="pid"><a class="permalink" href="#pid"><code class="Dv">pid</code></a></dt> + <dd>PID of the process consuming the channel.</dd> + <dt id="comm"><a class="permalink" href="#comm"><code class="Dv">comm</code></a></dt> + <dd>Name of the process consuming the channel.</dd> + <dt id="interrupts"><a class="permalink" href="#interrupts"><code class="Dv">interrupts</code></a></dt> + <dd>Number of interrupts since the channel has been opened.</dd> + <dt id="xruns"><a class="permalink" href="#xruns"><code class="Dv">xruns</code></a></dt> + <dd>Number of overruns/underruns, depending on channel direction.</dd> + <dt id="feedcount"><a class="permalink" href="#feedcount"><code class="Dv">feedcount</code></a></dt> + <dd>Number of read/written bytes since the channel has been + opened.</dd> + <dt id="left_volume"><a class="permalink" href="#left_volume"><code class="Dv">left_volume</code></a></dt> + <dd>Left volume.</dd> + <dt id="right_volume"><a class="permalink" href="#right_volume"><code class="Dv">right_volume</code></a></dt> + <dd>Right volume.</dd> + <dt id="hwbuf_format"><a class="permalink" href="#hwbuf_format"><code class="Dv">hwbuf_format</code></a></dt> + <dd>Hardware buffer format.</dd> + <dt id="hwbuf_rate"><a class="permalink" href="#hwbuf_rate"><code class="Dv">hwbuf_rate</code></a></dt> + <dd>Hardware buffer sample rate;</dd> + <dt id="hwbuf_size"><a class="permalink" href="#hwbuf_size"><code class="Dv">hwbuf_size</code></a></dt> + <dd>Hardware buffer size.</dd> + <dt id="hwbuf_blksz"><a class="permalink" href="#hwbuf_blksz"><code class="Dv">hwbuf_blksz</code></a></dt> + <dd>Hardware buffer block size.</dd> + <dt id="hwbuf_blkcnt"><a class="permalink" href="#hwbuf_blkcnt"><code class="Dv">hwbuf_blkcnt</code></a></dt> + <dd>Hardware buffer block count.</dd> + <dt id="hwbuf_free"><a class="permalink" href="#hwbuf_free"><code class="Dv">hwbuf_free</code></a></dt> + <dd>Free space in hardware buffer (in bytes).</dd> + <dt id="hwbuf_ready"><a class="permalink" href="#hwbuf_ready"><code class="Dv">hwbuf_ready</code></a></dt> + <dd>Number of bytes ready to be read/written from hardware + buffer.</dd> + <dt id="swbuf_format"><a class="permalink" href="#swbuf_format"><code class="Dv">swbuf_format</code></a></dt> + <dd>Software buffer format.</dd> + <dt id="swbuf_rate"><a class="permalink" href="#swbuf_rate"><code class="Dv">swbuf_rate</code></a></dt> + <dd>Software buffer sample rate;</dd> + <dt id="swbuf_size"><a class="permalink" href="#swbuf_size"><code class="Dv">swbuf_size</code></a></dt> + <dd>Software buffer size.</dd> + <dt id="swbuf_blksz"><a class="permalink" href="#swbuf_blksz"><code class="Dv">swbuf_blksz</code></a></dt> + <dd>Software buffer block size.</dd> + <dt id="swbuf_blkcnt"><a class="permalink" href="#swbuf_blkcnt"><code class="Dv">swbuf_blkcnt</code></a></dt> + <dd>Software buffer block count.</dd> + <dt id="swbuf_free"><a class="permalink" href="#swbuf_free"><code class="Dv">swbuf_free</code></a></dt> + <dd>Free space in software buffer (in bytes).</dd> + <dt id="swbuf_ready"><a class="permalink" href="#swbuf_ready"><code class="Dv">swbuf_ready</code></a></dt> + <dd>Number of bytes ready to be read/written from software + buffer.</dd> + <dt id="feederchain"><a class="permalink" href="#feederchain"><code class="Dv">feederchain</code></a></dt> + <dd>Channel feeder chain.</dd> + </dl> + </dd> + </dl> + </dd> + <dt id="provider"><a class="permalink" href="#provider"><code class="Dv">provider</code></a></dt> + <dd>A string specifying the provider of the PCm audio device.</dd> +</dl> +<p class="Pp">The following ioctls are provided for use:</p> +<dl class="Bl-tag"> + <dt id="SNDSTIOC_REFRESH_DEVS"><a class="permalink" href="#SNDSTIOC_REFRESH_DEVS"><code class="Dv">SNDSTIOC_REFRESH_DEVS</code></a></dt> + <dd>Drop any previously fetched PCM audio devices list snapshots. This ioctl + takes no arguments.</dd> + <dt id="SNDSTIOC_GET_DEVS"><a class="permalink" href="#SNDSTIOC_GET_DEVS"><code class="Dv">SNDSTIOC_GET_DEVS</code></a></dt> + <dd>Generate and/or return PCM audio devices list snapshots to callers. This + ioctl takes a pointer to <var class="Fa">struct sndstioc_nv_arg</var> 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. <var class="Fa">fd</var>, a new PCM audio device list + snapshot will be automatically generated. Callers have to set + <var class="Fa">nbytes</var> to either 0 or the size of buffer provided. + In case <var class="Fa">nbytes</var> is 0, the buffer size required to + hold a serialized nvlist stream of current snapshot will be returned in + <var class="Fa">nbytes</var>, and <var class="Fa">buf</var> will be + ignored. Otherwise, if the buffer is not sufficiently large, the ioctl + returns success, and <var class="Fa">nbytes</var> will be set to 0. If the + buffer provided is sufficiently large, <var class="Fa">nbytes</var> 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 + successfully, the snapshot stored in the subsystem's internal structure of + the given <var class="Fa">fd</var> will be freed.</dd> + <dt id="SNDSTIOC_ADD_USER_DEVS"><a class="permalink" href="#SNDSTIOC_ADD_USER_DEVS"><code class="Dv">SNDSTIOC_ADD_USER_DEVS</code></a></dt> + <dd>Add a list of PCM audio devices provided by callers to + <span class="Pa">/dev/sndstat</span> device. This ioctl takes a pointer to + <var class="Fa">struct sndstioc_nv_arg</var> as the first and the only + argument. Callers have to provide a buffer holding a serialized nvlist. + <var class="Fa">nbytes</var> should be set to the length in bytes of the + serialized nvlist. <var class="Fa">buf</var> should be pointed to a buffer + storing the serialized nvlist. Userspace-backed PCM audio device nodes + should be listed inside the serialized nvlist.</dd> + <dt id="SNDSTIOC_FLUSH_USER_DEVS"><a class="permalink" href="#SNDSTIOC_FLUSH_USER_DEVS"><code class="Dv">SNDSTIOC_FLUSH_USER_DEVS</code></a></dt> + <dd>Flush any PCM audio devices previously added by callers. This ioctl takes + no arguments.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<dl class="Bl-tag Bl-compact"> + <dt><span class="Pa">/dev/sndstat</span></dt> + <dd style="width: auto;"> </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The following code enumerates all available PCM audio devices:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>#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); +}</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">sound(4)</a>, <a class="Xr">nv(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The nvlist-based ioctls support for + <code class="Nm">sndstat</code> device first appeared in + <span class="Ux">FreeBSD 13.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This manual page was written by <span class="An">Ka Ho Ng</span> + <<a class="Mt" href="mailto:khng@FreeBSD.org">khng@FreeBSD.org</a>>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 26, 2024</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |