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, 0 insertions, 382 deletions
diff --git a/static/freebsd/man4/sndstat.4 3.html b/static/freebsd/man4/sndstat.4 3.html deleted file mode 100644 index 30f37c7f..00000000 --- a/static/freebsd/man4/sndstat.4 3.html +++ /dev/null @@ -1,382 +0,0 @@ -<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> |