share/man/man4/sndstat.4

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" This software was developed by Ka Ho Ng
   5 .\" under sponsorship from the FreeBSD Foundation.
   6 .\"
   7 .\" Copyright (c) 2020 The FreeBSD Foundation
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .\" Note: The date here should be updated whenever a non-trivial
  33 .\" change is made to the manual page.
  34 .Dd April 15, 2021
  35 .Dt SNDSTAT 4
  36 .Os
  37 .Sh NAME
  38 .Nm sndstat
  39 .Nd "nvlist-based PCM audio device enumeration interface"
  40 .Sh SYNOPSIS
  41 To compile the driver into the kernel,
  42 place the following lines in the
  43 kernel configuration file:
  44 .Bd -ragged -offset indent
  45 .Cd "device sound"
  46 .Ed
  47 .Sh DESCRIPTION
  48 The ioctl interface provided by
  49 .Pa /dev/sndstat
  50 device allows callers to enumerate PCM audio devices available for use.
  51 In other words, it provides means to get the list of all audio devices
  52 available to the system.
  53 .Sh IOCTLS
  54 For ioctl calls that take an argument, the following structure is used:
  55 .Bd -literal -offset indent
  56 struct sndstioc_nv_arg {
  57         size_t nbytes;
  58         void *buf;
  59 };
  60 .Ed
  61 .Pp
  62 Here is an example of an nvlist object with explanations of the common fields:
  63 .Bd -literal -offset indent
  64 dsps (NVLIST ARRAY): 1
  65     from_user (BOOL): FALSE
  66     nameunit (STRING): [pcm0]
  67     devnode (STRING): [dsp0]
  68     desc (STRING): [Generic (0x8086) (Analog Line-out)]
  69     pchan (NUMBER): 1 (1) (0x1)
  70     rchan (NUMBER): 0 (0) (0x0)
  71     info_play (NVLIST):
  72         min_rate (NUMBER): 48000 (48000) (0xbb80)
  73         max_rate (NUMBER): 48000 (48000) (0xbb80)
  74         formats (NUMBER): 16 (16) (0x10)
  75         min_chn (NUMBER): 2 (2) (0x2)
  76         max_chn (NUMBER): 2 (2) (0x2)
  77     provider_info (NVLIST):
  78         unit (NUMBER): 0 (0) (0x0)
  79         bitperfect (BOOL): FALSE
  80         pvchan (NUMBER): 1 (1) (0x1)
  81         rvchan (NUMBER): 0 (0) (0x0)
  82     provider (STRING): [sound(4)]
  83     ,
  84 .Ed
  85 .Bl -tag -width ".Dv provider_info"
  86 .It Dv from_user
  87 Whether the PCM audio device node is created by in-kernel audio subsystem or
  88 userspace providers.
  89 .It Dv nameunit
  90 The device identification in the form of subsystem plus a unit number.
  91 .It Dv devnode
  92 The PCM audio device node relative path in devfs.
  93 .It Dv desc
  94 The descripton of the PCM audio device.
  95 .It Dv pchan
  96 The number of playback channels supported by hardware.
  97 This can be 0 if this PCM audio device does not support playback at all.
  98 .It Dv rchan
  99 The number of recording channels supported by hardware.
 100 This can be 0 if this PCM audio device does not support recording at all.
 101 .It Dv info_play
 102 Supported configurations in playback direction.
 103 This exists only if this PCM audio device supports playback.
 104 There are a number of name/value pairs inside this field:
 105 .Bl -tag -width ".Dv min_rate"
 106 .It Dv min_rate
 107 Minimum supported sampling rate.
 108 .It Dv max_rate
 109 Maximum supported sampling rate.
 110 .It Dv formats
 111 Supported sample formats.
 112 .It Dv min_chn
 113 Minimum supported number of channels in channel layout
 114 .It Dv max_chn
 115 Maximum supported number of channels in channel layout
 116 .El
 117 .It Dv info_rec
 118 Supported configurations in recording direction.
 119 This exists only if this PCM audio device supports recording.
 120 There are a number of name/value pairs inside this field:
 121 .Bl -tag -width ".Dv min_rate"
 122 .It Dv min_rate
 123 Minimum supported sampling rate.
 124 .It Dv max_rate
 125 Maximum supported sampling rate.
 126 .It Dv formats
 127 Supported sample formats.
 128 .It Dv min_chn
 129 Minimum supported number of channels in channel layout
 130 .It Dv max_chn
 131 Maximum supported number of channels in channel layout
 132 .El
 133 .It Dv provider_info
 134 Provider-specific fields.
 135 This field may not exist if the PCM audio device is not provided by in-kernel
 136 interface.
 137 This field will not exist if the provider field is an empty string.
 138 .It Dv provider
 139 A string specifying the provider of the PCm audio device.
 140 .El
 141 .Pp
 142 The following ioctls are provided for use:
 143 .Bl -tag -width ".Dv SNDSTIOC_FLUSH_USER_DEVS"
 144 .It Dv SNDSTIOC_REFRESH_DEVS
 145 Drop any previously fetched PCM audio devices list snapshots.
 146 This ioctl takes no arguments.
 147 .It Dv SNDSTIOC_GET_DEVS
 148 Generate and/or return PCM audio devices list snapshots to callers.
 149 This ioctl takes a pointer to
 150 .Fa struct sndstioc_nv_arg
 151 as the first and the only argument.
 152 Callers need to provide a sufficiently large buffer to hold a serialized
 153 nvlist.
 154 If there is no existing PCM audio device list snapshot available in the
 155 internal structure of the opened sndstat.
 156 .Fa fd ,
 157 a new PCM audio device list snapshot will be automatically generated.
 158 Callers have to set
 159 .Fa nbytes
 160 to either 0 or the size of buffer provided.
 161 In case
 162 .Fa nbytes
 163 is 0, the buffer size required to hold a serialized nvlist
 164 stream of current snapshot will be returned in
 165 .Fa nbytes ,
 166 and
 167 .Fa buf
 168 will be ignored.
 169 Otherwise, if the buffer is not sufficiently large,
 170 the ioctl returns success, and
 171 .Fa nbytes
 172 will be set to 0.
 173 If the buffer provided is sufficiently large,
 174 .Fa nbytes
 175 will be set to the size of the serialized nvlist written to the provided buffer.
 176 Once a PCM audio device list snapshot is returned to user-space successfully,
 177 the snapshot stored in the subsystem's internal structure of the given
 178 .Fa fd
 179 will be freed.
 180 .It Dv SNDSTIOC_ADD_USER_DEVS
 181 Add a list of PCM audio devices provided by callers to
 182 .Pa /dev/sndstat
 183 device.
 184 This ioctl takes a pointer to
 185 .Fa struct sndstioc_nv_arg
 186 as the first and the only argument.
 187 Callers have to provide a buffer holding a serialized nvlist.
 188 .Fa nbytes
 189 should be set to the length in bytes of the serialized nvlist.
 190 .Fa buf
 191 should be pointed to a buffer storing the serialized nvlist.
 192 Userspace-backed PCM audio device nodes should be listed inside the serialized
 193 nvlist.
 194 .It Dv SNDSTIOC_FLUSH_USER_DEVS
 195 Flush any PCM audio devices previously added by callers.
 196 This ioctl takes no arguments.
 197 .El
 198 .Sh FILES
 199 .Bl -tag -width ".Pa /dev/sndstat" -compact
 200 .It Pa /dev/sndstat
 201 .El
 202 .Sh EXAMPLES
 203 The following code enumerates all available PCM audio devices:
 204 .Bd -literal -offset indent
 205 #include <sys/types.h>
 206 #include <err.h>
 207 #include <fcntl.h>
 208 #include <stdio.h>
 209 #include <stdlib.h>
 210 #include <sys/nv.h>
 211 #include <sys/sndstat.h>
 212 #include <sysexits.h>
 213 #include <unistd.h>
 214
 215 int
 216 main()
 217 {
 218         int fd;
 219         struct sndstioc_nv_arg arg;
 220         const nvlist_t * const *di;
 221         size_t i, nitems;
 222         nvlist_t *nvl;
 223
 224         /* Open sndstat node in read-only first */
 225         fd = open("/dev/sndstat", O_RDONLY);
 226
 227         if (ioctl(fd, SNDSTIOC_REFRESH_DEVS, NULL))
 228                 err(1, "ioctl(fd, SNDSTIOC_REFRESH_DEVS, NULL)");
 229
 230         /* Get the size of snapshot, when nbytes = 0 */
 231         arg.nbytes = 0;
 232         arg.buf = NULL;
 233         if (ioctl(fd, SNDSTIOC_GET_DEVS, &arg))
 234                 err(1, "ioctl(fd, SNDSTIOC_GET_DEVS, &arg)");
 235
 236         /* Get snapshot data */
 237         arg.buf = malloc(arg.nbytes);
 238         if (arg.buf == NULL)
 239                 err(EX_OSERR, "malloc");
 240         if (ioctl(fd, SNDSTIOC_GET_DEVS, &arg))
 241                 err(1, "ioctl(fd, SNDSTIOC_GET_DEVS, &arg)");
 242
 243         /* Deserialize the nvlist stream */
 244         nvl = nvlist_unpack(arg.buf, arg.nbytes, 0);
 245         free(arg.buf);
 246
 247         /* Get DSPs array */
 248         di = nvlist_get_nvlist_array(nvl, SNDST_DSPS, &nitems);
 249         for (i = 0; i < nitems; i++) {
 250                 const char *nameunit, *devnode, *desc;
 251
 252                 /*
 253                  * Examine each device nvlist item
 254                  */
 255
 256                 nameunit = nvlist_get_string(di[i], SNDST_DSPS_NAMEUNIT);
 257                 devnode = nvlist_get_string(di[i], SNDST_DSPS_DEVNODE);
 258                 desc = nvlist_get_string(di[i], SNDST_DSPS_DESC);
 259                 printf("Name unit: `%s`, Device node: `%s`, Description: `%s`\n",
 260                     nameunit, devnode, desc);
 261         }
 262
 263         nvlist_destroy(nvl);
 264         return (0);
 265 }
 266 .Ed
 267 .Sh SEE ALSO
 268 .Xr sound 4 ,
 269 .Xr nv 9
 270 .Sh HISTORY
 271 The nvlist-based ioctls support for
 272 .Nm
 273 device first appeared in
 274 .Fx 13.0 .
 275 .Sh AUTHORS
 276 This manual page was written by
 277 .An Ka Ho Ng Aq Mt khng@FreeBSD.org .