1 /* $NetBSD: audio_if.h,v 1.70 2014/11/18 01:50:12 jmcneill Exp $ */
2
3 /*
4 * Copyright (c) 1994 Havard Eidnes.
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 * 3. All advertising materials mentioning features or use of this software
16 * must display the following acknowledgement:
17 * This product includes software developed by the Computer Systems
18 * Engineering Group at Lawrence Berkeley Laboratory.
19 * 4. Neither the name of the University nor of the Laboratory may be used
20 * to endorse or promote products derived from this software without
21 * specific prior written permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 * SUCH DAMAGE.
34 *
35 */
36
37 #ifndef _SYS_DEV_AUDIO_IF_H_
38 #define _SYS_DEV_AUDIO_IF_H_
39
40 #include <sys/types.h>
41 #include <sys/audioio.h>
42 #include <sys/mutex.h>
43
44 /* check we have an audio(4) configured into kernel */
45 #if defined(_KERNEL_OPT)
46 #include "audio.h"
47
48 #if (NAUDIO == 0) && (NMIDI == 0) && (NMIDIBUS == 0)
49 #error "No 'audio* at audiobus?' or 'midi* at midibus?' or similar configured"
50 #endif
51
52 #endif /* _KERNEL_OPT */
53
54 /*
55 * Interfaces for hardware drivers and MI audio.
56 */
57
58 struct audio_softc;
59
60 /**
61 * audio stream format
62 */
63 typedef struct audio_params {
64 u_int sample_rate; /* sample rate */
65 u_int encoding; /* e.g. mu-law, linear, etc */
66 u_int precision; /* bits/subframe */
67 u_int validbits; /* valid bits in a subframe */
68 u_int channels; /* mono(1), stereo(2) */
69 } audio_params_t;
70
71 /* The default audio mode: 8 kHz mono mu-law */
72 extern const struct audio_params audio_default;
73
74 /**
75 * audio stream buffer
76 */
77 typedef struct audio_stream {
78 size_t bufsize; /* allocated memory */
79 uint8_t *start; /* start of buffer area */
80 uint8_t *end; /* end of valid buffer area */
81 uint8_t *inp; /* address to be written next */
82 const uint8_t *outp; /* address to be read next */
83 int used; /* valid data size in this stream */
84 audio_params_t param; /* represents this stream */
85 bool loop;
86 } audio_stream_t;
87
88 static __inline int
audio_stream_get_space(const audio_stream_t * s)89 audio_stream_get_space(const audio_stream_t *s)
90 {
91 if (s)
92 return (s->end - s->start) - s->used;
93 return 0;
94 }
95
96 static __inline int
audio_stream_get_used(const audio_stream_t * s)97 audio_stream_get_used(const audio_stream_t *s)
98 {
99 return s ? s->used : 0;
100 }
101
102 static __inline uint8_t *
audio_stream_add_inp(audio_stream_t * s,uint8_t * v,int diff)103 audio_stream_add_inp(audio_stream_t *s, uint8_t *v, int diff)
104 {
105 s->used += diff;
106 v += diff;
107 if (v >= s->end)
108 v -= s->end - s->start;
109 return v;
110 }
111
112 static __inline const uint8_t *
audio_stream_add_outp(audio_stream_t * s,const uint8_t * v,int diff)113 audio_stream_add_outp(audio_stream_t *s, const uint8_t *v, int diff)
114 {
115 s->used -= diff;
116 v += diff;
117 if (v >= s->end)
118 v -= s->end - s->start;
119 return v;
120 }
121
122 /**
123 * an interface to fill a audio stream buffer
124 */
125 typedef struct stream_fetcher {
126 int (*fetch_to)(struct audio_softc *, struct stream_fetcher *,
127 audio_stream_t *, int);
128 } stream_fetcher_t;
129
130 /**
131 * audio stream filter.
132 * This must be an extension of stream_fetcher_t.
133 */
134 typedef struct stream_filter {
135 /* public: */
136 stream_fetcher_t base;
137 void (*dtor)(struct stream_filter *);
138 void (*set_fetcher)(struct stream_filter *, stream_fetcher_t *);
139 void (*set_inputbuffer)(struct stream_filter *, audio_stream_t *);
140 /* private: */
141 stream_fetcher_t *prev;
142 audio_stream_t *src;
143 } stream_filter_t;
144
145 /**
146 * factory method for stream_filter_t
147 */
148 typedef stream_filter_t *stream_filter_factory_t(struct audio_softc *,
149 const audio_params_t *, const audio_params_t *);
150
151 /**
152 * filter pipeline request
153 *
154 * filters[0] is the first filter for playing or the last filter for recording.
155 * The audio_params_t instance for the hardware is filters[0].param.
156 */
157 #ifndef AUDIO_MAX_FILTERS
158 # define AUDIO_MAX_FILTERS 8
159 #endif
160 typedef struct stream_filter_list {
161 void (*append)(struct stream_filter_list *, stream_filter_factory_t,
162 const audio_params_t *);
163 void (*prepend)(struct stream_filter_list *, stream_filter_factory_t,
164 const audio_params_t *);
165 void (*set)(struct stream_filter_list *, int, stream_filter_factory_t,
166 const audio_params_t *);
167 int req_size;
168 struct stream_filter_req {
169 stream_filter_factory_t *factory;
170 audio_params_t param; /* from-param for recording,
171 to-param for playing */
172 } filters[AUDIO_MAX_FILTERS];
173 } stream_filter_list_t;
174
175 struct audio_hw_if {
176 int (*open)(void *, int); /* open hardware */
177 void (*close)(void *); /* close hardware */
178 int (*drain)(void *); /* Optional: drain buffers */
179
180 /* Encoding. */
181 /* XXX should we have separate in/out? */
182 int (*query_encoding)(void *, audio_encoding_t *);
183
184 /* Set the audio encoding parameters (record and play).
185 * Return 0 on success, or an error code if the
186 * requested parameters are impossible.
187 * The values in the params struct may be changed (e.g. rounding
188 * to the nearest sample rate.)
189 */
190 int (*set_params)(void *, int, int, audio_params_t *,
191 audio_params_t *, stream_filter_list_t *,
192 stream_filter_list_t *);
193
194 /* Hardware may have some say in the blocksize to choose */
195 int (*round_blocksize)(void *, int, int, const audio_params_t *);
196
197 /*
198 * Changing settings may require taking device out of "data mode",
199 * which can be quite expensive. Also, audiosetinfo() may
200 * change several settings in quick succession. To avoid
201 * having to take the device in/out of "data mode", we provide
202 * this function which indicates completion of settings
203 * adjustment.
204 */
205 int (*commit_settings)(void *);
206
207 /* Start input/output routines. These usually control DMA. */
208 int (*init_output)(void *, void *, int);
209 int (*init_input)(void *, void *, int);
210 int (*start_output)(void *, void *, int,
211 void (*)(void *), void *);
212 int (*start_input)(void *, void *, int,
213 void (*)(void *), void *);
214 int (*halt_output)(void *);
215 int (*halt_input)(void *);
216
217 int (*speaker_ctl)(void *, int);
218 #define SPKR_ON 1
219 #define SPKR_OFF 0
220
221 int (*getdev)(void *, struct audio_device *);
222 int (*setfd)(void *, int);
223
224 /* Mixer (in/out ports) */
225 int (*set_port)(void *, mixer_ctrl_t *);
226 int (*get_port)(void *, mixer_ctrl_t *);
227
228 int (*query_devinfo)(void *, mixer_devinfo_t *);
229
230 /* Allocate/free memory for the ring buffer. Usually malloc/free. */
231 void *(*allocm)(void *, int, size_t);
232 void (*freem)(void *, void *, size_t);
233 size_t (*round_buffersize)(void *, int, size_t);
234 paddr_t (*mappage)(void *, void *, off_t, int);
235
236 int (*get_props)(void *); /* device properties */
237
238 int (*trigger_output)(void *, void *, void *, int,
239 void (*)(void *), void *, const audio_params_t *);
240 int (*trigger_input)(void *, void *, void *, int,
241 void (*)(void *), void *, const audio_params_t *);
242 int (*dev_ioctl)(void *, u_long, void *, int, struct lwp *);
243 void (*get_locks)(void *, kmutex_t **, kmutex_t **);
244 };
245
246 struct audio_attach_args {
247 int type;
248 const void *hwif; /* either audio_hw_if * or midi_hw_if * */
249 void *hdl;
250 };
251 #define AUDIODEV_TYPE_AUDIO 0
252 #define AUDIODEV_TYPE_MIDI 1
253 #define AUDIODEV_TYPE_OPL 2
254 #define AUDIODEV_TYPE_MPU 3
255 #define AUDIODEV_TYPE_AUX 4
256
257 /* Attach the MI driver(s) to the MD driver. */
258 device_t audio_attach_mi(const struct audio_hw_if *, void *, device_t);
259 int audioprint(void *, const char *);
260
261 /* Get the hw device from an audio softc */
262 device_t audio_get_device(struct audio_softc *);
263
264 /* Device identity flags */
265 #define SOUND_DEVICE 0
266 #define AUDIO_DEVICE 0x80
267 #define AUDIOCTL_DEVICE 0xc0
268 #define MIXER_DEVICE 0x10
269
270 #define AUDIOUNIT(x) (minor(x)&0x0f)
271 #define AUDIODEV(x) (minor(x)&0xf0)
272
273 #define ISDEVSOUND(x) (AUDIODEV((x)) == SOUND_DEVICE)
274 #define ISDEVAUDIO(x) (AUDIODEV((x)) == AUDIO_DEVICE)
275 #define ISDEVAUDIOCTL(x) (AUDIODEV((x)) == AUDIOCTL_DEVICE)
276 #define ISDEVMIXER(x) (AUDIODEV((x)) == MIXER_DEVICE)
277
278 /*
279 * USB Audio specification defines 12 channels:
280 * L R C LFE Ls Rs Lc Rc S Sl Sr T
281 */
282 #define AUDIO_MAX_CHANNELS 12
283
284 #endif /* _SYS_DEV_AUDIO_IF_H_ */
285
286