Enter your search terms Submit search form   Web www.opensound.com manuals.opensound.com developer.opensound.com

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

dmap_t

Description

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 fields	There are few other fields in this structure that are not documented yet (TODO).

Referenced by