Open Sound System
The Hitchhiker's Guide to OSS 4.1 Internals

Do you have problems with sound/audio application development? Don't panic! Click here for help!


Audio DMA buffer descriptor structure


Each OSS audio engine (recording or playback) has a dmap_t structure which describes the DMA related features of the device/driver. Each audio engine has one or two dmap_t structures (pointed by the dmap_out and dmap_in fields of the adev_t structure. Full duplex audio engines will have both dmap entries allocated. However in non-duplex devices both dmap fields will point to the same dmap structure.

The dmap structures will be allocated by audio_init_device() in audio/oss_audio_core.c. The actual DMA buffer will be allocated when the device is opened and freed when the device is closed (by audio.c). Low level audio drivers can provide their own alloc_buffer() and free_buffer() methods. However in most cases the default functions provided by audio.c will be used.

The dmap_t structure has the following fields

mutex A mutex/semaphore variable for the dmap_t entry.
osdev OSS device descriptor for this dmap_t entry.
master_osdev The OSS device decsriptor pointer for this dmap_t entry. Usually this field contains the same value as osdev. However for virtual drivers this is a pointer to the osdev variable of the actual physical device.
adev This field is a pointer to the adev_t structure related with the actual audio device.
dmabuf Virtual (kernel) memory address of the DMA buffer for this audio engine.
dmabuf_phys Physical (bus) address of the DMA buffer.
buffsize Size (in bytes) of the DMA buffer allocated for the DMA engine.
buffer_protected By default the OSS audio core will initialize the DMA buffer to silence when the device is opened or closed. Hoever in rare cases (vmix) this may cause audible artifacts to the sund output. By setting this field to 1 the drier can prevent this.
tmpbuf1 Used internally by the audio core for format conversions.
tmpbuf2 Used internally by the audio core for format conversions.
driver_use_ptr This field can be used by the low level drivers for their internal purpses.
driver_use_value This field can be used by the low level drivers for their internal purpses.
audio_callback Virtual drivers can use this field to attach a callback function to be called when the device has received an audio interrupt (playback or recording).
callback_parm An integer parameter to be passed to the above callback routine.
srcstate An internal use field for the audio format conversion handler (audiofmt.c).
dma_mode Internal use variable for the audio core ( DMA direction (PCM_ENABLE_INPUT and/or PCM_EBABLE_OUTPUT.
flags Reserved for internal use by the audio core.
dma_mode PCM_ENABLE_INPUT, PCM_ENABLE_OUTPUT or 0 depending on the direction.
fragment_size Current fragment size in bytes.
nfrags Number of fragments in use.
bytes_in_use Number of bytes of the total buffer size that are actually used (nfrags*fragment_size). The application can request smaller buffer than the available maximum size (SNDCTL_DSP_SETFRAGMENT). The low level drivers should use this value when programming the DMA buffer size to the hardware registers.
data_rate Number of bytes/second to be played/recorded when the device is active. Computed by audio.c.
frame_size Size of a single sample frame as seen by the device in bytes. Computed by audio.c and it depends on the sample format/size and number of channels.
user_frame_size Size of a single sample frame as seen by the application. Usually this field has the same value as frame_size. However automatic sample format conversions may cause that the application uses different sample rate than the device.
fragsize_rq Internal use field for audio.c. This field contains the parameter passed to the SNDCTL_DSP_SETFRAGMENT call by the application. The audio core will (later) use this value when computing the fragment size to be used.
low_water The "low water" limit defines the granularity of select/poll system calls and some ioctl calls such as SNDCTL_DSP_GETOSPACE and SNDCTL_DSP_GETISPACE. These calls will report "no space available" if the buffer has less bytes available than the low water limit. The default low water limit is one fragment (may be different in some OSS versions). However the application can use SNDCTL_DSP_LOW_WATER to change the value.
low_water_rq The low water limit requested using SNDCTL_DSP_LOW_WATER will be temporarily stored here. This value will be copied to the low_water field later when the actual low water limit is computed.
byte_counter This is a 64 bit counter that tells how many bytes of audio data the device has already played or recorded. byte_counter%bytes_in use is the latest known device DMA pointer within the DMA buffer. Note that this information is only updated on interrupts or by some ioctl calls. So the actual pointer is always at least few sample frames beoyond this value.
user_counter A 64 bit counter that tells how many bytes have been written or read to/from the DMA buffer by the application. user_counter%bytes_in_use is the current application pointer within the DMA buffer. Note that this field is not updated when the application is using mmap() to access the device buffer directly.
interrupt_count Number of device play or record interrupts received since the device was started.
fragment_counter Current fragment pointer within the DMA buffer. used by some ioctl calls if the driver/device doesn't support the get_buffer_pointer() method.
expand_factor A coefficient that tells the ratio between the audio format/rate used by the device and the format/rate used by the application. Value of UNIT_EXPAND (currently 1024) means 1 (both the device and the application are using the same rate/format). This field is used to adjust the values returned by many ioctl calls when automatic sample rate/format conversions are in use.
mapping_flags This field is set to DMA_MAP_MAPPED when the application is using the mmap() method and to 0 otherwise.
neutral_byte This fields contains the byte value to be used when the DMA buffer is cleared (to silent values). The value will be 0x80 with the (unsigned) 8 bit format and 0 otherwise.
Other fieldsThere are few other fields in this structure that are not documented yet (TODO).

Referenced by

vmix_core/rec_export_int.incLocal input buffer to application export routine for vmix (int)
vmix_core/vmix.hDefinitions for the vmix driver
vmix_core/vmix_input.cVirtual mixing audio driver recording routines
vmix_core/playmix.incApplication to local playback buffer import routine for vmix (FP)
vmix_core/playmix_src.incApplication to local playback buffer resampling routine for vmix
vmix_core/playmix_int.incApplication to local playback buffer import routine for vmix (int)
vmix_core/rec_export.incLocal input buffer to application export routine for vmix (FP version)
vmix_core/vmix_output.cVirtual mixing audio driver output mixing routines
vmix_core/vmix_core.cSet the master sampling rate of given vmix instance.
audio/audiocnv.incHelper functions used by audiofmt.c
audio/oss_audiofmt.cAudio format conversion routines used by audio.c
audio/oss_audio_core.cAudio core functionality of OSS
include/ossddk.hSource file oss-current/kernel/framework/include/ossddk/ossddk.h
include/audio_core.hInternal definitions for the OS audio core
include/oss_config.hThe top level header file for compiling OSS itself.
include/oss_calls.hPrototypes for various internal routines of OSS.
remux/oss_remux.cMulti channel playback support for devices with multiple stereo engines.
oss_hdaudio/oss_hdaudio.cThe High Definition Audio (HDA/Azalia) driver.
oss_cmpci/oss_cmpci.cDriver for CMEDIA CM8738 PCI audio controller.
oss_userdev/oss_userdev_devicepair.cClient/server audio device pair for oss_userdev
oss_envy24ht/oss_envy24ht.cVIA ENVY24HT chipset driver.
oss_trident/oss_trident.cDriver for Trident 4DWAVE, ALI 5451 and SiS 7918 audio chips
oss_cs4281/oss_cs4281.cDriver for Crystal PCI audio controller.
oss_solo/oss_solo.cDriver for ESS Solo PCI audio controller.
oss_sbpci/oss_sbpci.cCreative/Ensoniq AudioPCI97 driver (ES1371/ES1373)
oss_madi/oss_madi.cDriver for RME MADI and AES32 audio interfaces
oss_ymf7xx/oss_ymf7xx.cDriver for Yamaha YMF7xx PCI audio controller.
oss_imux/oss_imux.cPseudo driver for sharing one input device between multiple apps.
oss_via823x/oss_via823x.cDriver for the VIA8233/8235 AC97 audio controller
oss_digi96/oss_digi96.cDriver for RME Digi96 family
oss_fmedia/oss_fmedia.cDriver for FM801 FM801 PCI audio controller.
oss_ich/oss_ich.cDriver for the Intel ICH AC97 audio controller
oss_sblive/oss_sblive.cDriver for Creative SB Live/Audigy/2/4. Audio, MIDI and mixer services.
oss_audiopci/oss_audiopci.cCreative/Ensoniq AudioPCI driver (ES1370 "CONCERT" ASIC and AKM4531 codec/mixer)
oss_sadasupport/sadasupport_sol9.hSolaris 9 compatible version of sadasupport_open/close
oss_sadasupport/oss_sadasupport.cSupport for the legacy (SADA) /dev/audio interfaces of Solaris
oss_audioloop/oss_audioloop.cOSS audio loopback (virtual) driver
oss_emu10k1x/oss_emu10k1x.cDriver for Creative emu10k1x audio controller
oss_cmi878x/oss_cmi878x.cDriver for C-Media CMI8788 PCI audio controller.
oss_audigyls/oss_audigyls.cDriver for Creative Audigy LS audio controller
oss_cs461x/oss_cs461x.cDriver for Crystal cs461x and cs461x PCI audio controllers
oss_geode/oss_geode.cDriver for the NS/Cyrix/AMD Geode AC97 audio controller
oss_via97/oss_via97.cDriver for the VIA VT82C686A AC97 audio controller
oss_ali5455/oss_ali5455.cDriver for the ALI 5455 (AC97) audio controller
oss_usb/ossusb_audio.cUSB audio streaming interface support
oss_atiaudio/oss_atiaudio.cDriver for the ATI IXP (AC97) audio controller
oss_sbxfi/oss_sbxfi.cDriver for Sound Blaster X-Fi (emu20k)
oss_sbxfi/sbxfi_hwaccess.cSource file oss-current/kernel/drv/oss_sbxfi/sbxfi_hwaccess.c
oss_audiocs/oss_audiocs.cDriver for the UltraSparc workstations using CS4231 codec for audio
oss_envy24/oss_envy24.cDriver for IC Ensemble ENVY24 based audio cards.
oss_envy24/envy24_direct.cDirect 24 bit multich driver for Envy24.
Linux/os_linux.cOperating system abstraction functions for Linux
VxWorks/os_vxworks.cSource file oss-current/kernel/OS/VxWorks/os_vxworks.c
SunOS/os_solaris.cOperating system abstraction functions for Solaris
BeOS/os_beos.cOperating system abstraction functions for BeOS/Haiku
FreeBSD/os_freebsd.cOperating system abstraction functions for FreeBSD
SCO_SV/os_sco.cOperating system abstraction functions for SCO OpenServer/UnixWare
Linux/osscore.cLinux kernel version specific wrapper routines.

Copyright (C) 4Front Technologies, 2007. All rights reserved.
Back to index OSS web site