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