xref: /titanic_51/usr/src/uts/common/sys/audio/audio_driver.h (revision e557d412e15c7f384b2ea3bf316a739a0f81cd55)
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 2010 Sun Microsystems, Inc.  All rights reserved.
25  * Use is subject to license terms.
26  */
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
39 extern "C" {
40 #endif
41 
42 #ifdef	_KERNEL
43 
44 struct 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 
129 void audio_init_ops(struct dev_ops *, const char *);
130 void audio_fini_ops(struct dev_ops *);
131 
132 audio_dev_t *audio_dev_alloc(dev_info_t *, int);
133 void audio_dev_free(audio_dev_t *);
134 
135 void audio_dev_set_description(audio_dev_t *, const char *);
136 void audio_dev_set_version(audio_dev_t *, const char *);
137 void audio_dev_add_info(audio_dev_t *, const char *);
138 
139 audio_engine_t *audio_engine_alloc(audio_engine_ops_t *, unsigned);
140 void audio_engine_set_private(audio_engine_t *, void *);
141 void *audio_engine_get_private(audio_engine_t *);
142 void audio_engine_free(audio_engine_t *);
143 
144 void audio_dev_add_engine(audio_dev_t *, audio_engine_t *);
145 void audio_dev_remove_engine(audio_dev_t *, audio_engine_t *);
146 int audio_dev_register(audio_dev_t *);
147 int audio_dev_unregister(audio_dev_t *);
148 void audio_dev_warn(audio_dev_t *, const char *, ...);
149 /* DEBUG ONLY */
150 void audio_dump_bytes(const uint8_t *w, int dcount);
151 void audio_dump_words(const uint16_t *w, int dcount);
152 void audio_dump_dwords(const uint32_t *w, int dcount);
153 
154 /*
155  * Drivers call these.
156  */
157 void audio_engine_consume(audio_engine_t *);
158 void audio_engine_produce(audio_engine_t *);
159 void audio_engine_reset(audio_engine_t *);
160 void audio_engine_lock(audio_engine_t *);
161 void audio_engine_unlock(audio_engine_t *);
162 
163 /* Engine flags */
164 #define	ENGINE_OUTPUT_CAP	(1U << 2)
165 #define	ENGINE_INPUT_CAP	(1U << 3)
166 #define	ENGINE_CAPS		(ENGINE_OUTPUT_CAP | ENGINE_INPUT_CAP)
167 #define	ENGINE_DRIVER_FLAGS	(0xffff)	/* flags usable by driver */
168 
169 #define	ENGINE_OUTPUT		(1U << 16)	/* fields not for driver use */
170 #define	ENGINE_INPUT		(1U << 17)
171 #define	ENGINE_OPEN		(1U << 18)
172 #define	ENGINE_RUNNING		(1U << 19)
173 #define	ENGINE_EXCLUSIVE	(1U << 20)	/* exclusive use, e.g. AC3 */
174 #define	ENGINE_NDELAY		(1U << 21)	/* non-blocking open */
175 #define	ENGINE_WAKE		(1U << 22)	/* wakeup tq running */
176 
177 /*
178  * entry points used by legacy SADA drivers
179  */
180 int audio_legacy_open(queue_t *, dev_t *, int, int, cred_t *);
181 int audio_legacy_close(queue_t *, int, cred_t *);
182 int audio_legacy_wput(queue_t *, mblk_t *);
183 int audio_legacy_wsrv(queue_t *);
184 
185 
186 
187 /*
188  * Audio device controls
189  */
190 
191 /*
192  * Control read or write driver function type.
193  *
194  * Returns zero on success, errno on failure.
195  */
196 typedef int (*audio_ctrl_wr_t)(void *, uint64_t);
197 typedef int (*audio_ctrl_rd_t)(void *, uint64_t *);
198 
199 
200 /*
201  * This will allocate and register a control for my audio device.
202  *
203  * On success this will return a control structure else NULL.
204  */
205 audio_ctrl_t *audio_dev_add_control(audio_dev_t *,
206     audio_ctrl_desc_t *, audio_ctrl_rd_t, audio_ctrl_wr_t, void *);
207 
208 /*
209  * Add a synthetic PCM volume control.  This should only be used by
210  * devices which have no physical PCM volume controls.  The control
211  * implements a simple attenuator on the PCM data; unlike AC'97 there
212  * is no "gain", so using this instead of a hardware control may
213  * result in loss range.  The control is implemented using
214  * AUDIO_CTRL_ID_VOLUME.
215  */
216 int audio_dev_add_soft_volume(audio_dev_t *);
217 
218 /*
219  * This will remove a control from an audio device.
220  */
221 void audio_dev_del_control(audio_ctrl_t *);
222 
223 /*
224  * This will tell the framework that controls have changed
225  * and it should update its values.
226  */
227 void audio_dev_update_controls(audio_dev_t *);
228 
229 /*
230  * This is used to read the current value of a control.
231  * Note, this will cause a callback into the driver to get the value.
232  *
233  * On return zero is returned on success else errno is returned.
234  */
235 int audio_control_read(audio_ctrl_t *, uint64_t *);
236 
237 /*
238  * This is used to write a value to a control.
239  * Note, this will cause a callback into the driver to write the value.
240  *
241  * On return zero is returned on success else errno is returned.
242  */
243 int audio_control_write(audio_ctrl_t *, uint64_t);
244 
245 #endif	/* _KERNEL */
246 
247 #ifdef	__cplusplus
248 }
249 #endif
250 
251 #endif	/* _SYS_AUDIO_AUDIO_DRIVER_H */
252