1 MIXER(7I)                       Ioctl Requests                       MIXER(7I)
   2 
   3 NAME
   4      mixer - generic mixer device interface
   5 
   6 SYNOPSIS
   7      #include <sys/soundcard.h>
   8 
   9 DESCRIPTION
  10    Mixer Pseudo-Device
  11      The /dev/mixer pseudo-device is provided for two purposes:
  12 
  13            o   The first purpose is for applications that wish to learn about
  14                the list of audio devices on the system, so that they can
  15                select (or provide for users to select) an appropriate audio
  16                device.  The /dev/mixer pseudo-device provides interfaces to
  17                enumerate all of the audio devices on the system.
  18 
  19            o   The second purpose is for mixer panel type applications which
  20                need to control master settings for the audio hardware in the
  21                system, such as gain levels, balance, port functionality, and
  22                other device features.
  23 
  24      Ordinary audio applications should not attempt to adjust their playback
  25      or record volumes or other device settings using this device.  Instead,
  26      they should use the SNDCTL_DSP_SETPLAYVOL and SNDCTL_DSP_SETRECVOL ioctls
  27      that are documented in dsp(7I).
  28 
  29    Sndstat Device
  30      The /dev/sndstat device supports read(2), and can be read to retrieve
  31      human-readable information about the audio devices on the system.
  32      Software should not attempt to interpret the contents of this device.
  33 
  34 IOCTLS
  35    Information IOCTLs
  36      The following ioctls are intended to aid applications in identifying the
  37      audio devices available on the system.  These ioctls can be issued
  38      against either the pseudo-device /dev/mixer, or a against a file
  39      descriptor open to any other audio device in the system.
  40 
  41      Applications should issue SNDCTL_SYSINFO first to learn what audio
  42      devices and mixers are available on the system, and then use
  43      SNDCTL_AUDIOINFO or SNDCTL_MIXERINFO to obtain more information about the
  44      audio devices or mixers, respectively.
  45 
  46      OSS_GETVERSION    The argument is a pointer to an integer, which
  47                        retrieves the version of the OSS API used.  The value
  48                        is encoded with the major version (currently 4) encoded
  49                        in the most significant 16 bits, and a minor version
  50                        encoded in the lower 16 bits.
  51 
  52      SNDCTL_SYSINFO    The argument is a pointer to an oss_sysinfo structure,
  53                        which has the following definition:
  54 
  55                          typedef struct oss_sysinfo {
  56                             char product[32];     /* E.g. SunOS Audio */
  57                             char version[32];     /* E.g. 4.0a */
  58                             int versionnum;       /* See OSS_GETVERSION */
  59                             char options[128];    /* NOT SUPPORTED */
  60 
  61                             int numaudios;        /* # of audio/dsp devices */
  62                             int openedaudio[8];   /* Reserved, always 0 */
  63 
  64                             int numsynths;        /* NOT SUPPORTED, always 0 */
  65                             int nummidis;         /* NOT SUPPORTED, always 0 */
  66                             int numtimers;        /* NOT SUPPORTED, always 0 */
  67                             int nummixers;        /* # of mixer devices */
  68 
  69                             /* Mask of midi devices are busy */
  70                             int openedmidi[8];
  71 
  72                             /* Number of sound cards in the system */
  73                             int numcards;
  74 
  75                             /* Number of audio engines in the system */
  76                             int numaudioengines;
  77                             char license[16];         /* E.g. "GPL" or "CDDL" */
  78                             char revision_info[256];  /* Reserved */
  79                             int filler[172];          /* Reserved */
  80                          } oss_sysinfo;
  81 
  82                        The important fields here are numaudios, which is used
  83                        to determine the number of audio devices that can be
  84                        queried with SNDCTL_AUDIOINFO, nummixers which provides
  85                        a count of mixers on the system, and numcards which
  86                        counts to total number of aggregate devices.  A card
  87                        can consist of one or more audio devices and one or
  88                        more mixers, although more typically there is exactly
  89                        one audio device and one mixer for each card.
  90 
  91      SNDCTL_AUDIOINFO  The argument is a pointer to an oss_audioinfo
  92                        structure, which has the following structure:
  93 
  94                          typedef struct oss_audioinfo {
  95                             int dev;             /* Device to query */
  96                             char name[64];       /* Human readable name */
  97                             int busy;            /* reserved */
  98                             int pid;             /* reserved */
  99 
 100                             /* PCM_CAP_INPUT, PCM_CAP_OUTPUT */
 101                             int caps;
 102                             int iformats;        /* Supported input formats */
 103                             int oformats;        /* Supported output formats */
 104                             int magic;           /* reserved */
 105                             char cmd[64];        /* reserved */
 106                             int card_number;
 107                             int port_number;     /* reserved */
 108                             int mixer_dev;
 109 
 110                             /* Obsolete field.  Replaced by devnode */
 111                             int legacy_device;
 112                             int enabled;         /* reserved */
 113                             int flags;           /* reserved */
 114                             int min_rate;        /* Minimum sample rate */
 115                             int max_rate;        /* Maximum sample rate */
 116                             int min_channels;  /* Minimum number of channels */
 117                             int max_channels;  /* Maximum number of channels */
 118                             int binding;         /* reserved */
 119                             int rate_source;     /* reserved */
 120                             char handle[32];     /* reserved */
 121                             unsigned int nrates;     /* reserved */
 122                             unsigned int rates[20];  /* reserved */
 123                             char song_name[64];  /* reserved */
 124                             char label[16];      /* reserved */
 125                             int latency;         /* reserved */
 126 
 127                             /* Device special file name (absolute path) */
 128                             char devnode[32];
 129                             int next_play_engine;    /* reserved */
 130                             int next_rec_engine;     /* reserved */
 131                             int filler[184];         /* reserved */
 132                          } oss_audioinfo;
 133 
 134                        In the above structure, all of the fields are reserved
 135                        except the following: dev, name, card_number,
 136                        mixer_dev, caps, min_rate, max_rate, min_channels,
 137                        max_channels, and devnode.  The reserved fields are
 138                        provided for compatibility with other OSS
 139                        implementations, and available for legacy applications.
 140                        New applications should not attempt to use these
 141                        fields.
 142 
 143                        The dev field should be initialized by the application
 144                        to the number of the device to query.  This is a number
 145                        between zero (inclusive) and value of numaudios
 146                        (exclusive) returned by SNDCTL_SYSINFO.  Alternatively,
 147                        when issuing the ioctl against a real mixer or dsp
 148                        device, the special value -1 can be used to indicate
 149                        that the query is being made against the device opened.
 150                        If -1 is used, the field is overwritten with the device
 151                        number for the current device on successful return.
 152 
 153                        No other fields are significant upon entry, but a
 154                        successful return contains details of the device.
 155 
 156                        The name field is a human readable name representing
 157                        the device.  Applications should not try to interpret
 158                        it.
 159 
 160                        The card_number field indicates the number assigned to
 161                        the aggregate device.  This can be used with the
 162                        SNDCTL_CARDINFO ioctl.
 163 
 164                        The mixer_dev is the mixer device number for the mixing
 165                        device associated with the audio device.  This can be
 166                        used with the SNDCTL_MIXERINFO ioctl.
 167 
 168                        The caps field contains any of the bits PCM_CAP_INPUT,
 169                        PCM_CAP_OUTPUT, and PCM_CAP_DUPLEX.  Indicating whether
 170                        the device support input, output, and whether input and
 171                        output can be used simultaneously.  All other bits are
 172                        reserved.
 173 
 174                        The min_rate and max_rate fields indicate the minimum
 175                        and maximum sample rates supported by the device.  Most
 176                        applications should try to use the maximum supported
 177                        rate for the best audio quality and lowest system
 178                        resource consumption.
 179 
 180                        The min_channels and max_channels provide an indication
 181                        of the number of channels (1 for mono, 2 for stereo, 6
 182                        for 5.1, etc.) supported by the device.
 183 
 184                        The devnode field contains the actual full path to the
 185                        device node for this device, such as
 186                        /dev/sound/audio810:0dsp.  Applications should open
 187                        this file to access the device.
 188 
 189      SNDCTL_CARDINFO   The argument is a pointer to a struct oss_card_info,
 190                        which has the following definition:
 191 
 192                          typedef struct oss_card_info {
 193                             int card;
 194                             char shortname[16];
 195                             char longname[128];
 196                             int flags;          /* reserved */
 197                             char hw_info[400];
 198                             int intr_count;     /* reserved */
 199                             int ack_count;      /* reserved */
 200                             int filler[154];
 201                          } oss_card_info;
 202 
 203                        This ioctl is used to query for information about the
 204                        aggregate audio device.
 205 
 206                        The card field should be initialized by the application
 207                        to the number of the card to query.  This is a number
 208                        between zero (inclusive) and value of numcards
 209                        (exclusive) returned by SNDCTL_SYSINFO.  Alternatively,
 210                        when issuing the ioctl against a real mixer or dsp
 211                        device, the special value -1 can be used to indicate
 212                        that the query is being made against the device opened.
 213                        If -1 is used, the field is overwritten with the number
 214                        for the current hardware device on successful return.
 215 
 216                        The shortname, longname, and hw_info contain ASCIIZ
 217                        strings describing the device in more detail.  The
 218                        hw_info member can contain multiple lines of detail,
 219                        each line ending in a NEWLINE.
 220 
 221                        The flag, intr_count, and ack_count fields are not used
 222                        by this implementation.
 223 
 224      SNDCTL_MIXERINFO  The argument is a pointer to a struct oss_mixer_info,
 225                        which has the following definition:
 226 
 227                          typedef struct oss_mixerinfo {
 228                              int dev;
 229                              char id[16];        /* Reserved */
 230                              char name[32];
 231                              int modify_counter;
 232                              int card_number;
 233                              int port_number;    /* Reserved */
 234                              char handle[32];    /* Reserved */
 235                              int magic;          /* Reserved */
 236                              int enabled;        /* Reserved */
 237                              int caps;           /* Reserved */
 238                              int flags;          /* Reserved */
 239                              int nrext;
 240                              int priority;
 241 
 242                              /* Deice special file name (absolute path) */
 243                              char devnode[32];
 244                              int legacy_device;  /* Reserved */
 245                              int filler[245];    /* Reserved */
 246                          } oss_mixerinfo;
 247 
 248                        In the above structure, all of the fields are reserved
 249                        except the following: dev, name, modify_counter,
 250                        card_number, nrext, priority, and devnode.  The
 251                        reserved fields are provided for compatibility with
 252                        other OSS implementations, and available for legacy
 253                        applications.  New applications should not attempt to
 254                        use these fields.
 255 
 256                        The dev field should be initialized by the application
 257                        to the number of the device to query.  This is a number
 258                        between zero inclusive and value of nummixers
 259                        (exclusive) returned by SNDCTL_SYSINFO, or by
 260                        SNDCTL_MIX_NRMIX.  Alternatively, when issuing the
 261                        ioctl against a real mixer or dsp device, the special
 262                        value -1 can be used to indicate that the query is
 263                        being made against the device opened.  If -1 is used,
 264                        the field is overwritten with the mixer number for the
 265                        current open file on successful return.
 266 
 267                        No other fields are significant upon entry, but on
 268                        successful return contains details of the device.
 269 
 270                        The name field is a human readable name representing
 271                        the device.  Applications should not try to interpret
 272                        it.
 273 
 274                        The modify_counter is changed by the mixer framework
 275                        each time the settings for the various controls or
 276                        extensions of the device are changed.  Applications can
 277                        poll this value to learn if any other changes need to
 278                        be searched for.
 279 
 280                        The card_number field is the number of the aggregate
 281                        audio device this mixer is located on.  It can be used
 282                        with the SNDCTL_CARDINFO ioctl.
 283 
 284                        The nrext field is the number of mixer extensions
 285                        available on this mixer.  See the SNDCTL_MIX_NREXT
 286                        description.
 287 
 288                        The priority is used by the framework to assign a
 289                        preference that applications can use in choosing a
 290                        device.  Higher values are preferable.  Mixers with
 291                        priorities less than -1 should never be selected by
 292                        default.
 293 
 294                        The devnode field contains the actual full path to the
 295                        device node for the physical mixer, such as
 296                        /dev/sound/audio810:0mixer.  Applications should open
 297                        this file to access the mixer settings.
 298 
 299    Mixer Extension IOCTLs
 300      The pseudo /dev/mixer device supports ioctls that can change the oarious
 301      settings for the audio hardware in the system.
 302 
 303      Those ioctls should only be used by dedicated mixer applications or
 304      desktop olumme controls, and not by typical ordinary audio applications
 305      such as media players.  Ordinary applications that wish to adjust their
 306      own volume settings should use the SNDCTL_DSP_SETPLAYVOL or
 307      SNDCTL_DSP_SETRECVOL ioctls for that purpose.  See dsp(7I) for more
 308      information.  Ordinary applications should never attempt to change master
 309      port selection or hardware settings such as monitor gain settings.
 310 
 311      The ioctls in this section can only be used to access the mixer device
 312      that is associated with the current file descriptor.
 313 
 314      Applications should not assume that a single /dev/mixer node is able to
 315      access any physical settings.  Instead, they should use the ioctl
 316      SNDCTL_MIXERINFO to determine the device path for the real mixer device,
 317      and issue ioctls on a file descriptor opened against the corresponding
 318      devnode field.
 319 
 320      When a dev member is specified in each of the following ioctls, the
 321      application should specify -1, although for compatibility the mixer
 322      allows the application to specify the mixer device number.
 323 
 324      SNDCTL_MIX_NRMIX     The argument is a pointer to an integer, which
 325                           receives the number of mixer devices in the system.
 326                           Each can be queried by using its number with the
 327                           SNDCTL_MIXERINFO ioctl.  The same information is
 328                           available using the SNDCTL_SYSINFO ioctl.
 329 
 330      SNDCTL_MIX_NREXT     The argument is a pointer to an integer.  On entry,
 331                           the integer should contain the special value -1.  On
 332                           return the argument receives the number of mixer
 333                           extensions (or mixer controls) supported by the
 334                           mixer device.  More details about each extension can
 335                           be obtained by SNDCTL_MIX_EXTINFO ioctl.
 336 
 337      SNDCTL_MIX_EXTINFO   The argument is a pointer to an oss_mixext structure
 338                           which is defined as follows:
 339 
 340                             typedef struct oss_mixext {
 341                                int dev;            /* Mixer device number */
 342                                int ctrl;           /* Extension number */
 343                                int type;           /* Entry type */
 344                                int maxvalue;
 345                                int minvalue;
 346                                int flags;
 347                                char id[16];  /* Mnemonic ID (internal use) */
 348                                int parent;   /* Entry# of parent (-1 if root) */
 349                                int dummy;          /* NOT SUPPORTED */
 350                                int timestamp;
 351                                char data[64];      /* Reserved */
 352 
 353                                /* Mask of allowed enum values */
 354                                unsigned char enum_present[32];
 355                                int control_no;     /* Reserved */
 356                                unsigned int desc;  /* NOT SUPPORTED */
 357                                char extname[32];
 358                                int update_counter;
 359                                int filler[7];      /* Reserved */
 360                             } oss_mixext;
 361 
 362                           On entry, the dev field should be initialized to the
 363                           value -1, and the ctrl field should be initialized
 364                           with the number of the extension being accessed.
 365                           Between 0, inclusive, and the value returned by
 366                           SNDCTL_MIX_NREXT, exclusive.
 367 
 368                           Mixer extensions are organized as a logical tree,
 369                           starting with a root node.  The root node always has
 370                           a ctrl value of zero.  The structure of the tree can
 371                           be determined by looking at the parent field, which
 372                           contains the extension number of the parent
 373                           extension, or -1 if the extension is the root
 374                           extension.
 375 
 376                           The type indicates the type of extension used.  This
 377                           implementation supports the following values:
 378 
 379                             MIXT_DEVROOT         Root node for extension tree
 380                             MIXT_GROUP           Logical grouping of controls
 381                             MXIT_ONOFF           Boolean value, 0 = off, 1 = on.
 382                             MIXT_ENUM            Enumerated value, 0 to maxvalue.
 383                             MIXT_MONOSLIDER      Monophonic slider, 0 to 255.
 384                             MIXT_STEREOSLIDER    Stereophonic slider, 0 to 255
 385                                                  (encoded as lower two bytes in
 386                                                  value.)
 387                             MIXT_MARKER          Place holder, can ignore.
 388 
 389                           The flags field is a bit array.  This implementation
 390                           makes use of the following possible bits:
 391 
 392                             MIXF_READABLE     Extension's value is readable.
 393                             MIXF_WRITEABLE    Extension's value is modifiable.
 394                             MIXF_POLL         Extension can self-update.
 395                             MIXF_PCMVOL       Extension is for master PCM
 396                                               playback volume.
 397                             MIXF_MAINVOL      Extension is for a typical analog
 398                                               volume
 399                             MIXF_RECVOL       Extension is for master record
 400                                               gain.
 401                             MIXF_MONVOL       Extension is for a monitor
 402                                               source's gain.
 403 
 404                           The id field contains an ASCIIZ identifier for the
 405                           extension.
 406 
 407                           The timestamp field is set when the extension tree
 408                           is first initialized.  Applications must use the
 409                           same timestamp value when attempting to change the
 410                           values.  A change in the timestamp indicates a
 411                           change a in the structure of the extension tree.
 412 
 413                           The enum_present field is a bit mask of possible
 414                           enumeration values.  If a bit is present in the
 415                           enum_present mask, then the corresponding
 416                           enumeration value is legal.  The mask is in little
 417                           endian order.
 418 
 419                           The desc field provides information about scoping,
 420                           which can be useful as layout hints to applications.
 421                           The following hints are available:
 422 
 423                             MIXEXT_SCOPE_MASK       Mask of possible scope
 424                                                     values.
 425                             MIXEXT_SCOPE_INPUT      Extension is an input
 426                                                     control.
 427                             MIXEXT_SCOPE_OUTPUT     Extension is an output
 428                                                     control.
 429                             MIXEXT_SCOPE_MONITOR    Extension relates to input
 430                                                     monitoring.
 431                             MIXEXT_SCOPE_OTHER      scoping hint provided.
 432 
 433                           The extname is the full name of the extension.
 434 
 435                           The update_counter is incremented each time the
 436                           control's value is changed.
 437 
 438      SNDCTL_MIX_ENUMINFO  The argument is a pointer to an oss_mixer_enuminfo
 439                           structure, which is defined as follows:
 440 
 441                             typedef struct oss_mixer_enuminfo {
 442                                int dev;
 443                                int ctrl;
 444                                int nvalues;
 445                                int version;
 446                                short strindex[255];
 447                                char strings[3000];
 448                             } oss_mixer_enuminfo;
 449 
 450                           On entry, the dev field should be initialized to the
 451                           value -1, and the ctrl field should be initialized
 452                           with the number of the extension being accessed.
 453                           Between 0, inclusive, and the value returned by
 454                           SNDCTL_MIX_NREXT, exclusive.
 455 
 456                           On return the nvalues field contains the number of
 457                           values, and strindex contains an array of indices
 458                           into the strings member, each index pointing to an
 459                           ASCIIZ describing the enumeration value.
 460 
 461      SNDCTL_MIX_READ
 462      SNDCTL_MIX_WRITE     The argument is a pointer to an oss_mixer_value
 463                           structure, defined as follows:
 464 
 465                             typedef struct oss_mixer_value {
 466                                int dev;
 467                                int ctrl;
 468                                int value;
 469 
 470                                /* Reserved for future use.  Initialize to 0 */
 471                                int flags;
 472 
 473                                /* Must be set to oss_mixext.timestamp */
 474                                int timestamp;
 475 
 476                                /* Reserved for future use.  Initialize to 0 */
 477                                int filler[8];
 478                             } oss_mixer_value;
 479 
 480                           On entry, the dev field should be initialized to the
 481                           value -1, and the ctrl field should be initialized
 482                           with the number of the extension being accessed.
 483                           Between 0, inclusive, and the value returned by
 484                           SNDCTL_MIX_NREXT, exclusive.  Additionally, the
 485                           timestamp member must be initialized to the same
 486                           value as was supplied in the oss_mixext structure
 487                           used with SNDCTL_MIX_EXTINFO.
 488 
 489                           For SNDCTL_MIX_WRITE, the application should supply
 490                           the new value for the extension.  For
 491                           SNDCTL_MIX_READ, the mixer returns the extensions
 492                           current value in value.
 493 
 494    Compatibility IOCTLs
 495      The following ioctls are for compatibility use only:
 496 
 497        SOUND_MIXER_READ_VOLUME
 498        SOUND_MIXER_READ_PCM
 499        SOUND_MIXER_READ_OGAIN
 500        SOUND_MIXER_READ_RECGAIN
 501        SOUND_MIXER_READ_RECLEV
 502        SOUND_MIXER_READ_IGAIN
 503        SOUND_MIXER_READ_RECSRC
 504        SOUND_MIXER_READ_RECMASK
 505        SOUND_MIXER_READ_DEVMASK
 506        SOUND_MIXER_READ_STEREODEVS
 507        SOUND_MIXER_WRITE_VOLUME
 508        SOUND_MIXER_WRITE_PCM
 509        SOUND_MIXER_WRITE_OGAIN
 510        SOUND_MIXER_WRITE_RECGAIN
 511        SOUND_MIXER_WRITE_RECLEV
 512        SOUND_MIXER_WRITE_IGAIN
 513        SOUND_MIXER_WRITE_RECSRC
 514        SOUND_MIXER_WRITE_RECMASK
 515        SOUND_MIXER_INFO
 516        SNDCTL_AUDIOINFO_EX
 517        SNDCTL_ENGINEINFO
 518 
 519      These ioctls can affect the software volume levels associated with the
 520      calling process.  They have no effect on the physical hardware levels or
 521      settings.  They should not be used in new applications.
 522 
 523 FILES
 524      /dev/mixer    Symbolic link to the pseudo mixer device for the system
 525 
 526      /dev/sndstat  Sound status device
 527 
 528 ERRORS
 529      An ioctl(2) fails if:
 530 
 531      EINVAL  The parameter changes requested in the ioctl are invalid or are
 532              not supported by the device.
 533 
 534      ENXIO   The device or extension referenced does not exist.
 535 
 536 ARCHITECTURE
 537      SPARC x86
 538 
 539 INTERFACE STABILITY
 540      The information and mixer extension IOCTLs are Uncommitted.  The
 541      Compatibility IOCTLs are Obsolete Uncommitted.  The extension names are
 542      Uncommitted.
 543 
 544 SEE ALSO
 545      close(2), ioctl(2), open(2), read(2), attributes(5), dsp(7I)
 546 
 547 BUGS
 548      The names of mixer extensions are not guaranteed to be predictable.
 549 
 550 illumos                        February 1, 2019                        illumos