1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
|
.\" $OpenBSD: audio.9,v 1.34 2022/11/02 10:41:34 kn Exp $
.\" $NetBSD: audio.9,v 1.14 2000/02/11 22:56:15 kleink Exp $
.\"
.\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Lennart Augustsson.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: November 2 2022 $
.Dt AUDIO 9
.Os
.Sh NAME
.Nm audio
.Nd interface between low and high level audio drivers
.Sh DESCRIPTION
The audio device driver is divided into a high level,
hardware independent layer, and a low level, hardware
dependent layer.
The interface between these is the
.Va audio_hw_if
structure.
.Bd -literal
struct audio_hw_if {
int (*open)(void *, int);
void (*close)(void *);
int (*set_params)(void *, int, int,
struct audio_params *, struct audio_params *);
int (*round_blocksize)(void *, int);
int (*commit_settings)(void *);
int (*init_output)(void *, void *, int);
int (*init_input)(void *, void *, int);
int (*start_output)(void *, void *, int,
void (*)(void *), void *);
int (*start_input)(void *, void *, int,
void (*)(void *), void *);
int (*halt_output)(void *);
int (*halt_input)(void *);
int (*set_port)(void *, struct mixer_ctrl *);
int (*get_port)(void *, struct mixer_ctrl *);
int (*query_devinfo)(void *, struct mixer_devinfo *);
void *(*allocm)(void *, int, size_t, int, int);
void (*freem)(void *, void *, int);
size_t (*round_buffersize)(void *, int, size_t);
int (*trigger_output)(void *, void *, void *, int,
void (*)(void *), void *, struct audio_params *);
int (*trigger_input)(void *, void *, void *, int,
void (*)(void *), void *, struct audio_params *);
void (*copy_output)(void *hdl, size_t bytes);
void (*underrun)(void *hdl);
int (*set_blksz)(void *, int,
struct audio_params *, struct audio_params *, int);
int (*set_nblks)(void *, int, int,
struct audio_params *, int);
};
struct audio_params {
u_long sample_rate; /* sample rate */
u_int encoding; /* mu-law, linear, etc */
u_int precision; /* bits/sample */
u_int bps; /* bytes/sample */
u_int msb; /* data alignment */
u_int channels; /* mono(1), stereo(2) */
};
.Ed
.Pp
The high level audio driver attaches to the low level driver
when the latter calls
.Fn audio_attach_mi .
This call is:
.Bd -literal -offset indent
struct device *
audio_attach_mi(const struct audio_hw_if *ahwp, void *hdl,
struct device *dev);
.Ed
.Pp
The
.Va audio_hw_if
struct is as shown above.
The
.Fa hdl
argument is a handle to some low level data structure.
It is sent as the first argument to all the functions in
.Fa ahwp
when the high level driver calls them.
.Fa dev
is the device struct for the hardware device.
.Pp
The upper layer of the audio driver allocates one buffer for playing
and one for recording.
It handles the buffering of data from the user processes in these.
The data is presented to the lower level in smaller chunks, called blocks.
During playback, if there is no data available from the user process
when the hardware requests another block, a block of silence will be
used instead.
Similarly, if the user process does not read data quickly enough during
recording, data will be thrown away.
.Pp
The fields of
.Va audio_hw_if
are described in some more detail below.
Some fields are optional and can be set to
.Dv NULL
if not needed.
.Bl -tag -width indent
.It Ft int Fn (*open) "void *hdl" "int flags"
This function is called when the audio device is opened, with
.Fa flags
the kernel representation of flags passed to the
.Xr open 2
system call
.Po
see
.Dv OFLAGS
and
.Dv FFLAGS
in
.In sys/fcntl.h
.Pc .
It initializes the hardware for I/O.
Every successful call to
.Fn open
is matched by a call to
.Fn close .
This function returns 0 on success, otherwise an error code.
.It Ft void Fn (*close) "void *hdl"
This function is called when the audio device is closed.
.It Ft int Fn (*set_params) "void *hdl" "int setmode" "int usemode" \
"struct audio_params *play" "struct audio_params *rec"
This function is called to set the audio encoding mode.
.Fa setmode
is a combination of the
.Dv AUMODE_RECORD
and
.Dv AUMODE_PLAY
flags to indicate which mode(s) are to be set.
.Fa usemode
is also a combination of these flags, but indicates the current
mode of the device (i.e., the value corresponding to the
.Va flags
argument to the
.Fn open
function).
The
.Fa play
and
.Fa rec
structures contain the encoding parameters that will be set.
The values of the structures must also be modified if the hardware
cannot be set to exactly the requested mode (e.g., if the requested
sampling rate is not supported, but one close enough is).
Except the channel count, the same value is passed in both
.Fa play
and
.Fa rec .
.Pp
The machine independent audio driver does some preliminary parameter checking;
it verifies that the precision is compatible with the encoding,
and it translates
.Dv AUDIO_ENCODING_[US]LINEAR
to
.Dv AUDIO_ENCODING_[US]LINEAR_{LE,BE} .
.Pp
This function returns 0 on success, otherwise an error code.
.It Ft int Fn (*round_blocksize) "void *hdl" "int bs"
This function is optional.
If supplied, it is called with the block size,
.Fa bs ,
which has been computed by the upper layer.
It returns a block size, possibly changed according to the needs of the
hardware driver.
.It Ft int Fn (*commit_settings) "void *hdl"
This function is optional.
If supplied, it is called after all calls to
.Fn set_params
and
.Fn set_port
are done.
A hardware driver that needs to get the hardware in
and out of command mode for each change can save all the changes
during previous calls and do them all here.
This function returns 0 on success, otherwise an error code.
.It Ft int Fn (*init_output) "void *hdl" "void *buffer" "int size"
This function is optional.
If supplied, it is called before any output starts, but only after the total
.Fa size
of the output
.Fa buffer
has been determined.
It can be used to initialize looping DMA for hardware that needs it.
This function returns 0 on success, otherwise an error code.
.It Ft int Fn (*init_input) "void *hdl" "void *buffer" "int size"
This function is optional.
If supplied, it is called before any input starts, but only after the total
.Fa size
of the input
.Fa buffer
has been determined.
It can be used to initialize looping DMA for hardware that needs it.
This function returns 0 on success, otherwise an error code.
.It Ft int Fn (*start_output) "void *hdl" "void *block" "int bsize" \
"void (*intr)(void *)" "void *intrarg"
This function is called to start the transfer of
.Fa bsize
bytes from
.Fa block
to the audio hardware.
The call returns when the data transfer
has been initiated (normally with DMA).
When the hardware is ready to accept more samples, the function
.Fa intr
will be called with the argument
.Fa intrarg .
Calling
.Fa intr
will normally initiate another call to
.Fn start_output .
This function returns 0 on success, otherwise an error code.
.It Ft int Fn (*start_input) "void *hdl" "void *block" "int bsize" \
"void (*intr)(void *)" "void *intrarg"
This function is called to start the transfer of
.Fa bsize
bytes to
.Fa block
from the audio hardware.
The call returns when the data transfer
has been initiated (normally with DMA).
When the hardware is ready to deliver more samples, the function
.Fa intr
will be called with the argument
.Fa intrarg .
Calling
.Fa intr
will normally initiate another call to
.Fn start_input .
This function returns 0 on success, otherwise an error code.
.It Ft int Fn (*halt_output) "void *hdl"
This function is called to abort the output transfer (started by
.Fn start_output )
in progress.
This function returns 0 on success, otherwise an error code.
.It Ft int Fn (*halt_input) "void *hdl"
This function is called to abort the input transfer (started by
.Fn start_input )
in progress.
This function returns 0 on success, otherwise an error code.
.It Ft int Fn (*set_port) "void *hdl" "struct mixer_ctrl *mc"
This function is called when the
.Dv AUDIO_MIXER_WRITE
.Xr ioctl 2
is used.
It takes data from
.Fa mc
and sets the corresponding mixer values.
This function returns 0 on success, otherwise an error code.
.It Ft int Fn (*get_port) "void *hdl" "struct mixer_ctrl *mc"
This function is called when the
.Dv AUDIO_MIXER_READ
.Xr ioctl 2
is used.
It fills
.Fa mc
and returns 0 on success, or it returns an error code on failure.
.It Ft int Fn (*query_devinfo) "void *hdl" "struct mixer_devinfo *di"
This function is called when the
.Dv AUDIO_MIXER_DEVINFO
.Xr ioctl 2
is used.
It fills
.Fa di
and returns 0 on success, or it returns an error code on failure.
.It Ft void * Fn (*allocm) "void *hdl" "int direction" "size_t size" "int type" \
"int flags"
This function is optional.
If supplied, it is called to allocate the device buffers.
If not supplied,
.Xr malloc 9
is used instead (with the same arguments but the first two).
The reason for using a device dependent routine instead of
.Xr malloc 9
is that some buses need special allocation to do DMA.
.Fa direction
is
.Dv AUMODE_PLAY
or
.Dv AUMODE_RECORD .
This function returns the address of the buffer on success, or 0 on failure.
.It Ft void Fn (*freem) "void *hdl" "void *addr" "int type"
This function is optional.
If supplied, it is called to free memory allocated by
.Fn allocm .
If not supplied,
.Xr free 9
is used instead.
.\" XXX: code passes int instead of size_t, but decl is size_t
.It Ft size_t Fn (*round_buffersize) "void *hdl" "int direction" \
"size_t bufsize"
This function is optional.
If supplied, it is called at startup to determine the audio buffer size.
The upper layer supplies the suggested size in
.Fa bufsize ,
which the hardware driver can then change if needed.
E.g., DMA on the ISA bus cannot exceed 65536 bytes.
Note that the buffer size is always a multiple of the block size, so
.Fn round_blocksize
and
.Fn round_buffersize
must be consistent.
.It Ft int Fn (*trigger_output) "void *hdl" "void *start" "void *end" "int blksize" \
"void (*intr)(void *)" "void *intrarg" "struct audio_params *param"
This function is optional.
If supplied, it is called to start the transfer of data from the circular
buffer delimited by
.Fa start
and
.Fa end
to the audio hardware, parameterized as in
.Fa param .
The call returns when the data transfer
has been initiated (normally with DMA).
When the hardware is finished transferring each
.Fa blksize
sized block, the function
.Fa intr
will be called with the argument
.Fa intrarg
(typically from the audio hardware interrupt service routine).
Once started, the transfer may be stopped using
.Fn halt_output .
This function returns 0 on success, otherwise an error code.
.It Ft int Fn (*trigger_input) "void *hdl" "void *start" "void *end" "int blksize" \
"void (*intr)(void *)" "void *intrarg" "struct audio_params *param"
This function is optional.
If supplied, it is called to start the transfer of data from the audio
hardware, parameterized as in
.Fa param ,
to the circular buffer delimited by
.Fa start
and
.Fa end .
The call returns when the data transfer
has been initiated (normally with DMA).
When the hardware is finished transferring each
.Fa blksize
sized block, the function
.Fa intr
will be called with the argument
.Fa intrarg
(typically from the audio hardware interrupt service routine).
Once started, the transfer may be stopped using
.Fn halt_input .
This function returns 0 on success, otherwise an error code.
.It Ft void Fn (*copy_output) "void *hdl" "size_t bytes"
This function is called whenever the given amount of bytes was
appended to the play ring buffer, typically during a
.Xr write 2
system call.
Drivers using bounce buffers for transfers between the audio
ring buffer and the device could implement this function
to copy the given amount of bytes into their bounce buffers.
There's no analogue function for recording as data is
produced by the device and could simply be copied upon
transfer completion.
.It Ft void Fn (*underrun) "void *hdl"
This function is called at interrupt context whenever a
play block was skipped by the
.Xr audio 4
driver.
Drivers using bounce buffers for transfers between the audio
ring buffer and the device must implement this method to skip
one block from the audio ring buffer and transfer the
corresponding amount of silence to the device.
.It Ft int Fn (*set_blksz) "void *hdl" "int mode" \
"struct audio_params *play" "struct audio_params *rec" "int blksz"
This function is called to set the audio block size.
.Fa mode
is a combination of the
.Dv AUMODE_RECORD
and
.Dv AUMODE_PLAY
flags indicating the current mode set with the
.Fn open
function.
The
.Fa play
and
.Fa rec
structures contain the current encoding set with the
.Fn set_params
function.
.Fa blksz
is the desired block size in frames.
It may be adjusted to match hardware constraints.
This function returns the adjusted block size.
.It Ft int Fn (*set_nblks) "void *hdl" "int dir" "int blksz" \
"struct audio_params *params" "int nblks"
This function is called to set the number of audio blocks in
the ring buffer.
.Fa dir
is either the
.Dv AUMODE_RECORD
or the
.Dv AUMODE_PLAY
flag, indicating which ring buffer size is set.
The
.Fa params
structure contains the encoding parameters set by the
.Fn set_params
method.
.Fa blksz
is the current block size in frames set with the
.Fa set_params
function.
The
.Fa params
structure is the current encoding parameters, set with the
.Fn set_params
function.
.Fa nblks
is the desired number of blocks in the ring buffer.
It may be lowered to at least two, to match hardware constraints.
This function returns the adjusted number of blocks.
.El
.Pp
If the audio hardware is capable of input from more
than one source, it should define
.Dv AudioNsource
in class
.Dv AudioCrecord .
This mixer control should be of type
.Dv AUDIO_MIXER_ENUM
or
.Dv AUDIO_MIXER_SET
and enumerate the possible input sources.
For each of the named sources there should be
a control in the
.Dv AudioCinputs
class of type
.Dv AUDIO_MIXER_VALUE
if recording level of the source can be set.
If the overall recording level can be changed (i.e., regardless
of the input source) then this control should be named
.Dv AudioNrecord
and be of class
.Dv AudioCinputs .
.Pp
If the audio hardware is capable of output to more than
one destination, it should define
.Dv AudioNoutput
in class
.Dv AudioCmonitor .
This mixer control should be of type
.Dv AUDIO_MIXER_ENUM
or
.Dv AUDIO_MIXER_SET
and enumerate the possible destinations.
For each of the named destinations there should be
a control in the
.Dv AudioCoutputs
class of type
.Dv AUDIO_MIXER_VALUE
if output level of the destination can be set.
If the overall output level can be changed (i.e., regardless
of the destination) then this control should be named
.Dv AudioNmaster
and be of class
.Dv AudioCoutputs .
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr open 2 ,
.Xr sio_open 3 ,
.Xr audio 4 ,
.Xr free 9 ,
.Xr malloc 9
.Sh HISTORY
This
.Nm
interface first appeared in
.Ox 1.2 .
|