include/sys/audio/audio_driver.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or http://www.opensolaris.org/os/licensing.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21 /*
  22  * Copyright (C) 4Front Technologies 1996-2008.
  23  *
  24  * Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
  25  */
  26
  27 #ifndef _SYS_AUDIO_AUDIO_DRIVER_H
  28 #define _SYS_AUDIO_AUDIO_DRIVER_H
  29
  30 #include <sys/types.h>
  31 #include <sys/list.h>
  32 #include <sys/ddi.h>
  33 #include <sys/sunddi.h>
  34 #include <sys/audio/audio_common.h>
  35
  36
  37 #ifdef  __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 #ifdef  _KERNEL
  42
  43 struct audio_engine_ops {
  44         int     audio_engine_version;
  45 #define AUDIO_ENGINE_VERSION    2
  46
  47         /*
  48          * Initialize engine, including buffer allocation.  Arguments
  49          * that are pointers are hints.  On return, they are updated with
  50          * the actual values configured by the driver.
  51          */
  52         int     (*audio_engine_open)(void *, int, uint_t *, caddr_t *);
  53         void    (*audio_engine_close)(void *);
  54
  55         /*
  56          * Start and stop are used to actually get the hardware running
  57          * or stop the hardware.  Until this is kicked off, the engine
  58          * will not actually transfer data.  These are not destructive to
  59          * ring positions, etc.  (Think of it like pause/play).
  60          */
  61         int     (*audio_engine_start)(void *);
  62         void    (*audio_engine_stop)(void *);
  63
  64         /*
  65          * Obtain the engine offset.  Offsets start at zero at engine_open,
  66          * and keep counting upwards.  Count is returned in frames.
  67          */
  68         uint64_t        (*audio_engine_count)(void *);
  69
  70         /*
  71          * The following entry points return the currently configured
  72          * status of the engine.  It is assumed that the engine's
  73          * configuration is relatively fixed, and does not change
  74          * while open, or in response to open.
  75          *
  76          * However, in the future we might like to allow for the
  77          * device to change the settings while it is not open, which
  78          * could allow for mixerctl to change the configured channels,
  79          * for example.  In order to synchronize this properly, we'll
  80          * need the engine to perform a notification/request.  That
  81          * will be added later.
  82          *
  83          * AC3: We will have to figure out how to support dynamically
  84          * selecting different sampling frequencies for AC3, since
  85          * it needs to be able to support 32, 44.1, and 48 kHz.
  86          * Perhaps special flags used during open() would do the trick.
  87          */
  88         int     (*audio_engine_format)(void *);
  89         int     (*audio_engine_channels)(void *);
  90         int     (*audio_engine_rate)(void *);
  91
  92         /*
  93          * DMA cache synchronization.  The framework does this on
  94          * behalf of the driver for both input and output.  The driver
  95          * is responsible for tracking the direction (based on the
  96          * flags passed to ae_open()), and dealing with any partial
  97          * synchronization if any is needed.
  98          */
  99         void    (*audio_engine_sync)(void *, uint_t);
 100
 101         /*
 102          * The framework may like to know how deep the device queues data.
 103          * This can be used to provide a more accurate latency calculation.
 104          */
 105         uint_t  (*audio_engine_qlen)(void *);
 106
 107         /*
 108          * If the driver doesn't use simple interleaving, then we need to
 109          * know more about the offsets of channels within the buffer.
 110          * We obtain both the starting offset within the buffer, and the
 111          * increment for each new sample.  As usual, these are given in
 112          * samples.  If this entry point is NULL, the framework assumes
 113          * that simple interlevaing is used instead.
 114          */
 115         void    (*audio_engine_chinfo)(void *, int chan, uint_t *offset,
 116             uint_t *incr);
 117
 118         /*
 119          * The following entry point is used to determine the play ahead
 120          * desired by the engine.  Engines with less consistent scheduling,
 121          * or with a need for deeper queuing, implement this.  If not
 122          * implemented, the framework assumes 1.5 * fragfr.
 123          */
 124         uint_t  (*audio_engine_playahead)(void *);
 125 };
 126
 127 /*
 128  * Drivers call these.
 129  */
 130 void audio_init_ops(struct dev_ops *, const char *);
 131 void audio_fini_ops(struct dev_ops *);
 132
 133 audio_dev_t *audio_dev_alloc(dev_info_t *, int);
 134 void audio_dev_free(audio_dev_t *);
 135
 136 void audio_dev_set_description(audio_dev_t *, const char *);
 137 void audio_dev_set_version(audio_dev_t *, const char *);
 138 void audio_dev_add_info(audio_dev_t *, const char *);
 139
 140 audio_engine_t *audio_engine_alloc(audio_engine_ops_t *, uint_t);
 141 void audio_engine_set_private(audio_engine_t *, void *);
 142 void *audio_engine_get_private(audio_engine_t *);
 143 void audio_engine_free(audio_engine_t *);
 144
 145 void audio_dev_add_engine(audio_dev_t *, audio_engine_t *);
 146 void audio_dev_remove_engine(audio_dev_t *, audio_engine_t *);
 147 int audio_dev_register(audio_dev_t *);
 148 int audio_dev_unregister(audio_dev_t *);
 149 void audio_dev_suspend(audio_dev_t *);
 150 void audio_dev_resume(audio_dev_t *);
 151 void audio_dev_warn(audio_dev_t *, const char *, ...);
 152
 153 /* DEBUG ONLY */
 154 void audio_dump_bytes(const uint8_t *w, int dcount);
 155 void audio_dump_words(const uint16_t *w, int dcount);
 156 void audio_dump_dwords(const uint32_t *w, int dcount);
 157
 158
 159 /* Engine flags */
 160 #define ENGINE_OUTPUT_CAP       (1U << 2)
 161 #define ENGINE_INPUT_CAP        (1U << 3)
 162 #define ENGINE_CAPS             (ENGINE_OUTPUT_CAP | ENGINE_INPUT_CAP)
 163 #define ENGINE_DRIVER_FLAGS     (0xffff)        /* flags usable by driver */
 164
 165 #define ENGINE_OUTPUT           (1U << 16)      /* fields not for driver use */
 166 #define ENGINE_INPUT            (1U << 17)
 167 #define ENGINE_EXCLUSIVE        (1U << 20)      /* exclusive use, e.g. AC3 */
 168 #define ENGINE_NDELAY           (1U << 21)      /* non-blocking open */
 169
 170 /*
 171  * entry points used by legacy SADA drivers
 172  */
 173 int audio_legacy_open(queue_t *, dev_t *, int, int, cred_t *);
 174 int audio_legacy_close(queue_t *, int, cred_t *);
 175 int audio_legacy_wput(queue_t *, mblk_t *);
 176 int audio_legacy_wsrv(queue_t *);
 177
 178
 179
 180 /*
 181  * Audio device controls
 182  */
 183
 184 /*
 185  * Control read or write driver function type.
 186  *
 187  * Returns zero on success, errno on failure.
 188  */
 189 typedef int (*audio_ctrl_wr_t)(void *, uint64_t);
 190 typedef int (*audio_ctrl_rd_t)(void *, uint64_t *);
 191
 192
 193 /*
 194  * This will allocate and register a control for my audio device.
 195  *
 196  * On success this will return a control structure else NULL.
 197  */
 198 audio_ctrl_t *audio_dev_add_control(audio_dev_t *,
 199     audio_ctrl_desc_t *, audio_ctrl_rd_t, audio_ctrl_wr_t, void *);
 200
 201 /*
 202  * Add a synthetic PCM volume control.  This should only be used by
 203  * devices which have no physical PCM volume controls.  The control
 204  * implements a simple attenuator on the PCM data; unlike AC'97 there
 205  * is no "gain", so using this instead of a hardware control may
 206  * result in loss range.  The control is implemented using
 207  * AUDIO_CTRL_ID_VOLUME.
 208  */
 209 void audio_dev_add_soft_volume(audio_dev_t *);
 210
 211 /*
 212  * This will remove a control from an audio device.
 213  */
 214 void audio_dev_del_control(audio_ctrl_t *);
 215
 216 /*
 217  * This will tell the framework that controls have changed
 218  * and it should update its values.
 219  */
 220 void audio_dev_update_controls(audio_dev_t *);
 221
 222 /*
 223  * This is used to read the current value of a control.
 224  * Note, this will cause a callback into the driver to get the value.
 225  *
 226  * On return zero is returned on success else errno is returned.
 227  */
 228 int audio_control_read(audio_ctrl_t *, uint64_t *);
 229
 230 /*
 231  * This is used to write a value to a control.
 232  * Note, this will cause a callback into the driver to write the value.
 233  *
 234  * On return zero is returned on success else errno is returned.
 235  */
 236 int audio_control_write(audio_ctrl_t *, uint64_t);
 237
 238 #endif  /* _KERNEL */
 239
 240 #ifdef  __cplusplus
 241 }
 242 #endif
 243
 244 #endif  /* _SYS_AUDIO_AUDIO_DRIVER_H */