ioctls listed in current OSS v4.0 documentation

Still missing

ioctl

compatibility

summary

notes

argument

SNDCTL_DSP_COOKEDMODE

ossv4

{Dis,en}able "on fly" format conversions

2006-08-15 This one is a toughy. The FreeBSD sound system uses a 2-stage buffer scheme where the primary is closest to the user, and the secondary is a chunk (typically) DMA'd from the soundcard. (This approach supports virtual channels and in-kernel format conversion allowing mixdown of multiple processes' output to a single hardware channel. Cool stuff, really.)

However, this ioctl is meant to give processes direct access to the hardware buffer, giving the application the most control possible (ex: minimizing latency by avoiding in-kernel processing). To faithfully support this will require some massaging, which I still intend to do. But since this ioctl doesn't appear to be very popular yet (no source code hits after a cursory Googling), I believe it's lower in the priority list than remaining mixer-releated work.

int enabled

Still missing, and not fully documented

ioctl

compatibility

summary

notes

argument

SNDCTL_MIDIINFO

ossv4

Returns information about a MIDI device

No sample available. "Under construction."

oss_midi_info

SNDCTL_MIX_ENUMINFO

ossv4

Not fully documented. See $OSS/sndkit/samples/mixext.readme. oss_mixer_enuminfo is provided in soundcard.h, and can inspect ossmix.c (example program) for hints.

oss_mixer_enuminfo

SNDCTL_MIX_EXTINFO

ossv4

Not fully documented. See $OSS/sndkit/samples/mixext.readme.

oss_mixext

Null stub (commented, but just returns EINVAL)

ioctl

compatibility

summary

notes

argument

SNDCTL_CARDINFO

ossv4?

Returns information about a sound card or pseudo device

"The usability of this call is very limited. It's provided only for completeness of the API. OSS API doesn't have any concept of card. Any information returned by this ioctl calld is reserved exclusively for the utility programs included in the OSS package. Applications should not try to use for this information in any ways."

oss_card_info

SNDCTL_GETLABEL

ossv4

Returns label assigned to this device

Under construction.
From Hannu@4Front: For example ossxmix (just like some HW mixer consoles) can show variable "labels" for certain controls. By default the application name (say quake) is shown as the label but applications may change the labels themselves.

oss_label_t

SNDCTL_SETLABEL

ossv4

Sets the label for this device

See SNDCTL_GETLABEL.

oss_label_t

SNDCTL_GETSONG

ossv4

Returns the current song name (if given) related with this device

Under construction.
From Hannu@4Front: Audio players like xmms and ossplay can tell the song or file name they are playing. This is shown in /dev/sndstat. More importantly the song name may be obtained by the application located at the downstream side of a loopback device.

oss_longname_t

SNDCTL_SETSONG

ossv4

Sets the song name related with this device.

See SNDCTL_GETSONG.

oss_longname_t

SNDCTL_SETNAME

ossv4

Sets the name of this device (if changeable)

Under construction.
From Hannu@4Front: This call is used to change the device name reported in /dev/sndstat and ossinfo. So instead of using some generic "OSS loopback audio (MIDI) driver" the device may be given a meaningfull name depending on the current context (for example "OSS virtual wave table synth" or "VoIP link to London").

oss_longname_t

SNDCTL_DSP_GET_CHNORDER

ossv4-draft

Get the channel ordering of a multi channel device

Under construction; "returns the interleaving order of a multichannel stream"

unsigned long long map

SNDCTL_DSP_READCTL

ossv4

Reads the S/PDIF interface status.

4Front advises avoiding this and WRITECTL.

oss_digital_control

SNDCTL_DSP_WRITECTL

ossv4

Alters the S/PDIF interface setup.

See READCTL

oss_digital_control ctl

Preliminary support added

ioctl

compatibility

summary

notes

argument

SNDCTL_DSP_CURRENT_IPTR

ossv4

Returns current recording position

Same caveat as SNDCTL_DSP_CURRENT_OPTR.

oss_count_t

SNDCTL_DSP_CURRENT_OPTR

ossv4

Returns current playback position

This operation queries the pre-feeder software buffer, not the actual hardware buffer. As such, the current pointer location isn't exactly accurate. This could be fixed by: (a) translating from hardware pointer location to this buffer; (b) fixing the COOKEDMODE ioctl command and using the hardware buffer pointer locations. (Just using the hardware locations is feasible, but not very useful to a userland application.)

oss_count_t

SNDCTL_DSP_GETERROR

~ossv3.8

Returns audio device error information

FreeBSD impl. should work as advertised.

audio_errinfo

SNDCTL_DSP_GETIPEAKS

ossv4

Returns peak levels for all recording channels

Currently does next to nothing. Appears to be intended for devices with their own peak meters, so drivers must be twiddled. I'm considering doing analysis in-kernel as an off-by-default option, but I imagine any applications needing this functionality would also perform analysis themselves if the hardware wasn't available.

oss_peaks_t

SNDCTL_DSP_GETOPEAKS

ossv4

The peak levels for all playback channels

Same restrictions as SNDCTL_DSP_GETIPEAKS.

oss_peaks_t

SNDCTL_DSP_GET_PLAYTGT_NAMES

ossv4

Returns labels for the currently available output routings

Works, but is missing corresponding *SET* ioctl cmds.

oss_mixer_enuminfo

SNDCTL_DSP_GET_PLAYTGT

ossv4

Returns the current output routing

For now, each device node only corresponds to a single channel, so this will always return 0. (Same for SNDCTL_DSP_SET_PLAYTGT, too.)

int route

SNDCTL_DSP_GETPLAYVOL

ossv4

Returns the current audio playback volume

int level

SNDCTL_DSP_GET_RECSRC_NAMES

ossv4

Returns labels for the currently available recording sources

See GET_PLAYTGT_NAMES.

oss_mixer_enuminfo

SNDCTL_DSP_GET_RECSRC

ossv4

Returns the current recording source

See SNDCTL_DSP_GET_PLAYTGT.

int route

SNDCTL_DSP_GETRECVOL

ossv4

Returns the current audio recording level

int level

SNDCTL_DSP_HALT_INPUT

ossv4

Aborts audio recording operation

Quoth OSS, "In the earlier OSS versions this ioctl call was called as SNDCTL_DSP_RESET_INPUT. This name is still valid but for clarity reasons it is not recommended in new programs." Usually used when changing audio format while recording is in progress.

NULL

SNDCTL_DSP_HALT_OUTPUT

ossv4

Aborts audio playback operation

Similar notes as HALT_INPUT.

NULL

SNDCTL_DSP_LOW_WATER

ossv4

Sets the trigger threshold for select()

This is initially set to the device fragment size, but what happens when that is changed *after* calling this? Does a change in fragment size overwrite this?

int nbytes

SNDCTL_DSP_POLICY

ossv4

Sets the timing policy of an audio device

User picks integer 0..10 where 0 uses minimum buffer sizes & 10 uses maximum sizes. Tradeoffs are latency vs. CPU usage. Quoth OSS, "easier to use version of SNDCTL_DSP_SETFRAGMENT."

int policy

SNDCTL_DSP_SET_PLAYTGT

ossv4

Sets the current output routing

See GET_PLAYTGT_NAMES.

int route

SNDCTL_DSP_SETPLAYVOL

ossv4

Changes the current audio playback volume

int level

SNDCTL_DSP_SET_RECSRC

ossv4

Sets the current recording source

See GET_RECSRC_NAMES.

int route

SNDCTL_DSP_SETRECVOL

ossv4

Changes the current audio recording level

"This ioctl call replaces the SOUND_MIXER_IGAIN/RECLEV method used with earlier OSS versions."

int level

SNDCTL_DSP_SILENCE

ossv4

Clears the playback buffer with silence

"Can be used to implement playback pause." Resume w/ SNDCTL_DSP_SKIP. (So sound samples are just lost?)

NULL

SNDCTL_DSP_SKIP

ossv4

Discards all samples in the playback buffer

"This ioctl call discards all unplayed samples in the playback buffer by moving the current write position immediately before the point where the device is currently reading the samples. This feature can be used to emulate resume function after playback pause."

NULL

SNDCTL_DSP_SYNCGROUP

ossv4

Creates a synchronization group.

oss_syncgroup group

SNDCTL_DSP_SYNCSTART

ossv4

Starts all devices added to a synchronization group.

BUG: Playback starts on all channels, but gets interrupted (audio pops once like when resetting a channel), though all channels still stay in sync. Still can't track down the cause of this, but will come back to it later.

int id

SNDCTL_AUDIOINFO

ossv4

Return information about an audio device

There are two problems: 1. Channel assignment/allocation is non-deterministic, so opening an audio device node may not result in getting the corresponding hardware or virtual channel. 2. Is meant to query drivers directly to get rates, capabilities, etc., while _getcaps includes software-emulated formats.

oss_audioinfo

SNDCTL_MIXERINFO

ossv4

Returns information about a mixer device

Ioctl call supported by all OSS devices. (See SNDCTL_AUDIOINFO.)

oss_mixerinfo

SNDCTL_SYSINFO

ossv4

Return information about OSS and the devices

For now, only gathers information about audio devices. (Is supposed to compile information about MIDI and mixer devices, too.)

oss_sysinfo

Already supported

ioctl

compatibility

summary

notes

argument

SNDCTL_DSP_CHANNELS

all versions

Set the number of audio channels

API doesn't limit number of channels; depends on device. (ex 1=mono, 2=stereo)

SNDCTL_DSP_GETBLKSIZE

all versions

Get the current fragment size

Obsoleted by
SNDCTL_DSP_GETOSPACE
SNDCTL_DSP_GETISPACE

int fragsize

SNDCTL_DSP_GETCAPS

~ossv3.5

Returns the capabilities of an audio device

See Audio device capabilties

int caps

SNDCTL_DSP_GETFMTS

all versions

Returns a list of natively supported sample formats

Supposed to report only native formats, but FreeBSD also reports emulated formats by default (toggled via sysctl).

SNDCTL_DSP_GETIPTR

all versions

Returns the current recording pointer

Useful only w/ mmap. Obsoleted by
SNDCTL_DSP_CURRENT_IPTR.

count_info

SNDCTL_DSP_GETISPACE

all versions

Returns the number of currently recorded bytes

Can be used to determine # of bytes that can be recorded w/o blocking. OSS docs state it's "out of fashion."

audio_buf_info

SNDCTL_DSP_GETODELAY

all versions

Returns the playback buffering delay

int delay

SNDCTL_DSP_GETOPTR

all versions

Returns the current playback pointer

Similar comments to GETIPTR.

count_info

SNDCTL_DSP_GETOSPACE

all versions

Returns the number of currently recorded bytes

Can be used to determine # of bytes that can play w/o blocking. Quoth OSS docs, "This ioctl is out of fashion."

audio_buf_info

SNDCTL_DSP_GETTRIGGER

???

Returns the current trigger bits

Obsolete. "Will be removed from the API in distant future."

SNDCTL_DSP_HALT

all versions

Aborts audio recording and/or playback operation

Quoth OSS, though I think there may be a copy/paste mistake somewhere, "There is no need to use this call after opening the device. In the earlier OSS versions this ioctl call was called as SNDCTL_DSP_RESET_OUTPUT."

NULL

SNDCTL_DSP_SETFRAGMENT

all versions

Sets the buffer size hint

User can hint at max # of fragments, size of fragments

int frag = (max_fragments << 16) | (size_selector)

SNDCTL_DSP_POST

all versions

Forces audio playback to start

According to OSS, useless. FreeBSD just calls chn_start.

NULL

SNDCTL_DSP_SETDUPLEX

all versions

Turns on the duplex mode

NULL

SNDCTL_DSP_SETFMT

all versions

Select the sample format

Supported formats
TODO: compare to presently supported formats (expecting no major differences)

int format

SNDCTL_DSP_SETSYNCRO

???

Slaves the audio device to the /dev/sequencer driver

OSS: "obsolete".

NULL

SNDCTL_DSP_SETTRIGGER

all versions

Starts audio recording and/or playback in sync

OSS: "However in some cases it's necessary to start it manually. There are exactly three cases when it's necessary. 1) When using mmap() this is the only way to start the device. 2) When recording and playback needs to be started exactly at the same moment. 3) When doing normal recording but when even the first read cannot block."

int mask

SNDCTL_DSP_SPEED

all versions

Set the sampling rate

int rate

SNDCTL_DSP_SUBDIVIDE

pre-ossv4

Requests the device to use smaller fragments

"Obsolete call. Not implemented in OSS 4.0 and later. Use SNDCTL_DSP_SETFRAGMENT instead."

SNDCTL_DSP_SYNC

all versions

Suspend the application until all samples have been played

NULL

Missing, but obsolete

ioctl

compatibility

summary

notes

argument

SNDCTL_DSP_BIND_CHANNEL

unofficial, obsolete

Route stereo output to the specified channels

Obsoleted by
SNDCTL_DSP_SET_PLAYTGT
SNDCTL_DSP_GET_PLAYTGT
SNDCTL_DSP_GET_PLAYTGT_NAMES

SNDCTL_DSP_GETCHANNELMASK

unofficial

Returns the bindings supported by the device

Same as SNDCTL_DSP_BIND_CHANNEL

SNDCTL_DSP_SAMPLESIZE

???

Sets the sample size

"This ioctl call is obsolete. You should use SNDCTL_DSP_SETFMT instead."