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  * Audio device controls
172  */
173 
174 /*
175  * Control read or write driver function type.
176  *
177  * Returns zero on success, errno on failure.
178  */
179 typedef int (*audio_ctrl_wr_t)(void *, uint64_t);
180 typedef int (*audio_ctrl_rd_t)(void *, uint64_t *);
181 
182 
183 /*
184  * This will allocate and register a control for my audio device.
185  *
186  * On success this will return a control structure else NULL.
187  */
188 audio_ctrl_t *audio_dev_add_control(audio_dev_t *,
189     audio_ctrl_desc_t *, audio_ctrl_rd_t, audio_ctrl_wr_t, void *);
190 
191 /*
192  * Add a synthetic PCM volume control.  This should only be used by
193  * devices which have no physical PCM volume controls.  The control
194  * implements a simple attenuator on the PCM data; unlike AC'97 there
195  * is no "gain", so using this instead of a hardware control may
196  * result in loss range.  The control is implemented using
197  * AUDIO_CTRL_ID_VOLUME.
198  */
199 void audio_dev_add_soft_volume(audio_dev_t *);
200 
201 /*
202  * This will remove a control from an audio device.
203  */
204 void audio_dev_del_control(audio_ctrl_t *);
205 
206 /*
207  * This will tell the framework that controls have changed
208  * and it should update its values.
209  */
210 void audio_dev_update_controls(audio_dev_t *);
211 
212 /*
213  * This is used to read the current value of a control.
214  * Note, this will cause a callback into the driver to get the value.
215  *
216  * On return zero is returned on success else errno is returned.
217  */
218 int audio_control_read(audio_ctrl_t *, uint64_t *);
219 
220 /*
221  * This is used to write a value to a control.
222  * Note, this will cause a callback into the driver to write the value.
223  *
224  * On return zero is returned on success else errno is returned.
225  */
226 int audio_control_write(audio_ctrl_t *, uint64_t);
227 
228 #endif	/* _KERNEL */
229 
230 #ifdef	__cplusplus
231 }
232 #endif
233 
234 #endif	/* _SYS_AUDIO_AUDIO_DRIVER_H */
235