'\" te .\" Copyright (c) 2005, 4Front Technologies 2005\&. .TH ossddk_install_audiodev 9ossddk "12 Sep 2005" "SunOS 5.10" "OSS DDK Services" .SH "NAME" ossddk_install_audiodev \- Install an audio device .PP .SH "SYNOPSIS" .nf #include .LP #include .fi .LP \fBint\fR ossddk_install_audiodev(\fBint \fIvers\fP, \fBoss_device_t * \fIosdev\fP, \fBoss_device_t * \fImaster_osdev\fP, \fBchar *\fIname\fP, \fBconst audiodrv_t *\fIdriver\fP, \fBint \fIdriver_size\fP, \fBint \fIflags\fP, \fBunsigned int \fIformat_mask\fP, \fBvoid *\fIdevc\fP, \fBint \fIparent\fP); .PP .SH "INTERFACE LEVEL" .PP Open Sound System specific (OSS 4.0 DDK)\&. .PP .SH "ARGUMENTS" .PP .sp .ne 2 .mk \fB\fIvers\fR .in +16n .rt Audio driver interface version. Must be set to OSS_AUDIO_DRIVER_VERSION. .in -16n .sp .ne 2 .mk \fB\fIosdev\fR .in +16n .rt OSS device handle. Returned by ossddk_register_device. .in -16n .sp .ne 2 .mk \fB\fImaster_osdev\fR .in +16n .rt OSS device handle for the master device. Usually same as \fIosdev\fR but virtual drivers have to give the osdev handle of the master/physical device here. OSS uses this parameter for example to get the right iblock_cookie. .in -16n .sp .ne 2 .mk \fB\fIname\fR .in +16n .rt Name of the device. This name will be reported in /dev/sndstat as well as to the applications using SNDCTL_AUDIOINFO(2oss) ioctl (such as ossinfo). .in -16n .sp .ne 2 .mk \fB\fIdriver\fR .in +16n .rt Pointer to the audio_driver structure that defines the entry points for this low level audio driver. .in -16n .sp .ne 2 .mk \fB\fIdriver_size\fR .in +16n .rt Size of the driver structure. Pass sizeof(audiodrv_t) in this parameter. .in -16n .sp .ne 2 .mk \fB\fIflags\fR .in +16n .rt Audio device flags (see the description below). .in -16n .sp .ne 2 .mk \fB\fIformat_mask\fR .in +16n .rt Bit mask describing the sample formats supported by the device. See the \fISupported Audio Formats\fR section of OSS v4.0 API reference for more info. For example \fBAFMT_S16_LE|AFMT_U8\fR tells that the driver supports the industry standard 8 and 16 bit audio formats. .PP If the device supports different formats for recording and playback the driver should use the \fIossddk_adev_set_formats(9ossddk)\fR routine to set the masks. .in -16n .sp .ne 2 .mk \fB\fIdevc\fR .in +16n .rt Pointer to driver defined device instance data. .in -16n .sp .ne 2 .mk \fB\fIparent\fR .in +16n .rt Reserved for future use. Set to -1. .in -16n .PP .SH "DESCRIPTION" .PP \fIossddk_install_audiodev\fR creates an audio device file (/dev/dsp0 to /dev/dspN) and installs its driver callbacks. By default the device will be input/output capable. Behaviour of the driver can be modified using the \fIflags\fR parameter in the following way: .PP .sp .ne 2 .mk \fBADEV_DUPLEX\fR .in +30n .rt Give this flag if this device supports full duplex (simultaneous recording and playback). .in -30n .sp .ne 2 .mk \fBADEV_NOINPUT\fR .in +30n .rt Set this flag if the device doesn't do recording (ie it's playback only). .in -30n .sp .ne 2 .mk \fBADEV_NOOUTPUT\fR .in +30n .rt Set this flag if the device doesn't do playback (ie it's recording only). .in -30n .sp All new OSS drivers should create separate device files for input and output. Earlier OSS versions created just a single input/output device file with \fBADEV_DUPLEX\fR flag. However this approach doesn't work with all device so it should not be used any more. .sp .ne 2 .mk \fBADEV_VIRTUAL\fR .in +30n .rt This flag tells that this device is virtual which means that it doesn't drive any real hardware device. Instead it performs some software-only processing or works on top of some other device. This flag is used to prevent chaining multiple virtual drivers. Also some applications using SNDCTL_AUDIOINFO(2oss) may use this flag for some purposes. .in -30n .sp .ne 2 .mk \fBADEV_NOCONVERT\fR .in +30n .rt This flag prevents the audio core from doing any automatic sample rate or format conversions with this device. This flag should be set only if there is some strong reason to prevent the conversions. .in -30n .sp .ne 2 .mk \fBADEV_HIDDEN\fR .in +30n .rt This flag means that the device serves some very special purpose and it should be hidden from ordinary audio applications. It will not be visible in device selection lists shown by applications. Instead the user/administrator should know the device file to use. .in -30n .sp .ne 2 .mk \fBADEV_SHADOW\fR .in +30n .rt Some devices have multiple audio playback engines that are functionally identical (in theory this kind of input devices are possible too but). An OSS audio driver is supposed to create one audio device file for each of the available engines. All but the first one should have this flag set. .in -30n .sp .ne 2 .mk \fBADEV_NOSRC\fR .in +30n .rt This flag disables automatic sample rate conversions performed by the audio core of OSS. It's similar than the \fBADEV_NOCONVERT\fR flag but doesn't disable other kind of format conversions. Usually used with rofessional audio devices (digital ones in particular) to prevent lossy sample rate conversions. .in -30n .sp .ne 2 .mk \fBADEV_SPECIAL\fR .in +30n .rt Use this flag with devices that should not be used to play system sounds (warning beeps, etc). For example multi channel only or digital (AES/EBU or S/PDIF) devices should specify this flag. .in -30n .sp .ne 2 .mk \fBADEV_NOMMAP\fR .in +30n .rt Use this flag if the device doesn't support mmap (direct access to the DMA buffer) for some reason. .in -30n .sp .ne 2 .mk \fBADEV_DISABLE_VIRTUAL\fR .in +30n .rt Use this flag if the device is not suitable to be used as a master device of some virtual driver. This flag should be set for example when the interrupt routine of this device uses large amounts of stack (which may cause a stack overflow when the virtual driver gets invoked). .in -30n .sp .ne 2 .mk .PP .SH "RETURN VALUES" .PP Negative value is an error code (-errno). Zero or positive is the audio device number created. .PP .SH "SEE ALSO" .PP \fIWriting Sound Device Drivers with OSS DDK\fR \fIOpen Sound System Programmer's Guide\fR