ryanbeasley:ioctlref

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
ryanbeasley:ioctlref [2006/08/22 20:05] – Since SNDCTL_MIXERINFO was implemented, move its entry to the stubbed section. RyanBeasleyryanbeasley:ioctlref [2008/06/17 21:37] (current) – converted to 1.6 markup 127.0.0.1
Line 3: Line 3:
 ====== ioctls listed in current OSS v4.0 documentation ====== ====== ioctls listed in current OSS v4.0 documentation ======
  
-  * [#todo Still missing] +  * [[#todo|Still missing]] 
-  * [#hmpf Still missing, and not fully documented] +  * [[#hmpf|Still missing, and not fully documented]] 
-  * [#stub2 Null stub (commented, but just returns EINVAL)] +  * [[#stub2|Null stub (commented, but just returns EINVAL)]] 
-  * [#stub Stubbed (preliminary support)] +  * [[#prelim|Preliminary support added]] 
-  * [#complete Already supported] +  * [[#complete|Already supported]] 
-  * [#obsolete Missing, but obsolete]+  * [[#obsolete|Missing, but obsolete]]
  
-|  [[/Anchor(todo)|Anchor(todo)]] Still missing  ||||||+|   Still missing  ||||||
 | ioctl | compatibility | summary | notes | argument | | ioctl | compatibility | summary | notes | argument |
-| [[/Anchor(SNDCTL_DSP_COOKEDMODE)|Anchor(SNDCTL_DSP_COOKEDMODE)]]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.)[[/BR|BR]][[/BR|BR]]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 |+| 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 |
  
-|  [[/Anchor(hmpf)|Anchor(hmpf)]] Still missing, and not fully documented  ||||||+|   Still missing, and not fully documented  ||||||
 | ioctl | compatibility | summary | notes | argument | | ioctl | compatibility | summary | notes | argument |
 | SNDCTL_MIDIINFO | ossv4 | Returns information about a MIDI device | No sample available.  "Under construction." | oss_midi_info | | SNDCTL_MIDIINFO | ossv4 | Returns information about a MIDI device | No sample available.  "Under construction." | oss_midi_info |
Line 20: Line 20:
 | SNDCTL_MIX_EXTINFO | ossv4 |  | Not fully documented.  See $OSS/sndkit/samples/mixext.readme. | oss_mixext | | SNDCTL_MIX_EXTINFO | ossv4 |  | Not fully documented.  See $OSS/sndkit/samples/mixext.readme. | oss_mixext |
  
-|  [[/Anchor(stub2)|Anchor(stub2)]] Null stub (commented, but just returns EINVAL)  ||||||+|   Null stub (commented, but just returns EINVAL)  ||||||
 | ioctl | compatibility | summary | notes | argument | | 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_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.**[[/BR|BR]]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_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_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.**[[/BR|BR]]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_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_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.**[[/BR|BR]]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_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_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_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 | | SNDCTL_DSP_WRITECTL | ossv4 | Alters the S/PDIF interface setup. | See READCTL | oss_digital_control ctl |
  
-|  [[/Anchor(stub)|Anchor(stub)]] Stubbed  ||||||+|   Preliminary support added  ||||||
 | ioctl | compatibility | summary | notes | argument | | 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_IPTR | ossv4 | Returns current recording position | Same caveat as SNDCTL_DSP_CURRENT_OPTR. | oss_count_t |
Line 57: Line 57:
 | SNDCTL_DSP_SYNCGROUP | ossv4 | Creates a synchronization group. |  | oss_syncgroup group | | 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_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 |
-| [wiki:Self:[[/RyanBeasley|RyanBeasley]]/ioctlref/SNDCTL_AUDIOINFO 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 |+| [[RyanBeasley/ioctlref/SNDCTL_AUDIOINFO|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_MIXERINFO | ossv4 | Returns information about a mixer device | Ioctl call supported by all OSS devices.  (See SNDCTL_AUDIOINFO.) | oss_mixerinfo |
-| [wiki:Self:[[/RyanBeasley|RyanBeasley]]/ioctlref/SNDCTL_SYSINFO 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 |+| [[RyanBeasley/ioctlref/SNDCTL_SYSINFO|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 |
  
-|  [[/Anchor(complete)|Anchor(complete)]] Already supported  ||||||+|   Already supported  ||||||
 | ioctl | compatibility | summary | notes | argument | | ioctl | compatibility | summary | notes | argument |
-| [[/Anchor(SNDCTL_DSP_CHANNELS)|Anchor(SNDCTL_DSP_CHANNELS)]]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_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[[/BR|BR]]SNDCTL_DSP_GETOSPACE[[/BR|BR]]SNDCTL_DSP_GETISPACE[[/BR|BR]] | int fragsize | +| 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 [http://manuals.opensound.com/developer/audio_capabilities.html Audio device capabilties][[/BR|BR]] | int caps |+| SNDCTL_DSP_GETCAPS | ~ossv3.5 | Returns the capabilities of an audio device | See [[http://manuals.opensound.com/developer/audio_capabilities.html|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_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 [[/BR|BR]][#SNDCTL_DSP_CURRENT_IPTR SNDCTL_DSP_CURRENT_IPTR]. | count_info |+| SNDCTL_DSP_GETIPTR | all versions | Returns the current recording pointer | Useful only w/ mmap.  Obsoleted by \\ [[#SNDCTL_DSP_CURRENT_IPTR|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_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_GETODELAY | all versions | Returns the playback buffering delay |  | int delay |
Line 77: Line 77:
 | SNDCTL_DSP_POST | all versions | Forces audio playback to start | According to OSS, useless.  %%FreeBSD%% just calls chn_start. | NULL | | 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_SETDUPLEX | all versions | Turns on the duplex mode |  | NULL |
-| SNDCTL_DSP_SETFMT | all versions | Select the sample format | [http://manuals.opensound.com/developer/formats.html Supported formats][[/BR|BR]]TODO: compare to presently supported formats (expecting no major differences) | int format |+| SNDCTL_DSP_SETFMT | all versions | Select the sample format | [[http://manuals.opensound.com/developer/formats.html|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_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_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 |
Line 84: Line 84:
 | SNDCTL_DSP_SYNC | all versions | Suspend the application until all samples have been played |  | NULL | | SNDCTL_DSP_SYNC | all versions | Suspend the application until all samples have been played |  | NULL |
  
-|  [[/Anchor(obsolete)|Anchor(obsolete)]] Missing, but obsolete  ||||||+|   Missing, but obsolete  ||||||
 | ioctl | compatibility | summary | notes | argument | | ioctl | compatibility | summary | notes | argument |
-| [[/Anchor(SNDCTL_DSP_BIND_CHANNEL)|Anchor(SNDCTL_DSP_BIND_CHANNEL)]]SNDCTL_DSP_BIND_CHANNEL | unofficial, obsolete | Route stereo output to the specified channels | Obsoleted by[[/BR|BR]][#SNDCTL_DSP_SET_PLAYTGT SNDCTL_DSP_SET_PLAYTGT][[/BR|BR]][#SNDCTL_DSP_GET_PLAYTGT SNDCTL_DSP_GET_PLAYTGT][[/BR|BR]][#SNDCTL_DSP_GET_PLAYTGT_NAMES SNDCTL_DSP_GET_PLAYTGT_NAMES] | +| SNDCTL_DSP_BIND_CHANNEL | unofficial, obsolete | Route stereo output to the specified channels | Obsoleted by\\ [[#SNDCTL_DSP_SET_PLAYTGT|SNDCTL_DSP_SET_PLAYTGT]]\\ [[#SNDCTL_DSP_GET_PLAYTGT|SNDCTL_DSP_GET_PLAYTGT]]\\ [[#SNDCTL_DSP_GET_PLAYTGT_NAMES|SNDCTL_DSP_GET_PLAYTGT_NAMES]] | 
-| SNDCTL_DSP_GETCHANNELMASK | unofficial | Returns the bindings supported by the device | Same as [#SNDCTL_DSP_BIND_CHANNEL SNDCTL_DSP_BIND_CHANNEL] |  |+| SNDCTL_DSP_GETCHANNELMASK | unofficial | Returns the bindings supported by the device | Same as [[#SNDCTL_DSP_BIND_CHANNEL|SNDCTL_DSP_BIND_CHANNEL]] |  |
 | SNDCTL_DSP_SAMPLESIZE | ??? | Sets the sample size | "This ioctl call is obsolete. You should use SNDCTL_DSP_SETFMT instead." |  | | SNDCTL_DSP_SAMPLESIZE | ??? | Sets the sample size | "This ioctl call is obsolete. You should use SNDCTL_DSP_SETFMT instead." |  |
  
  • ryanbeasley/ioctlref.1156277144.txt.gz
  • Last modified: 2006/08/22 20:05
  • by RyanBeasley