1 vwsnd - Sound driver for the Silicon Graphics 320 and 540 Visual
2 Workstations' onboard audio.
3
4 Copyright 1999 Silicon Graphics, Inc. All rights reserved.
5
6
7 At the time of this writing, March 1999, there are two models of
8 Visual Workstation, the 320 and the 540. This document only describes
9 those models. Future Visual Workstation models may have different
10 sound capabilities, and this driver will probably not work on those
11 boxes.
12
13 The Visual Workstation has an Analog Devices AD1843 "SoundComm" audio
14 codec chip. The AD1843 is accessed through the Cobalt I/O ASIC, also
15 known as Lithium. This driver programs both both chips.
16
17 ==============================================================================
18 QUICK CONFIGURATION
19
20 # insmod soundcore
21 # insmod vwsnd
22
23 ==============================================================================
24 I/O CONNECTIONS
25
26 On the Visual Workstation, only three of the AD1843 inputs are hooked
27 up. The analog line in jacks are connected to the AD1843's AUX1
28 input. The CD audio lines are connected to the AD1843's AUX2 input.
29 The microphone jack is connected to the AD1843's MIC input. The mic
30 jack is mono, but the signal is delivered to both the left and right
31 MIC inputs. You can record in stereo from the mic input, but you will
32 get the same signal on both channels (within the limits of A/D
33 accuracy). Full scale on the Line input is +/- 2.0 V. Full scale on
34 the MIC input is 20 dB less, or +/- 0.2 V.
35
36 The AD1843's LOUT1 outputs are connected to the Line Out jacks. The
37 AD1843's HPOUT outputs are connected to the speaker/headphone jack.
38 LOUT2 is not connected. Line out's maximum level is +/- 2.0 V peak to
39 peak. The speaker/headphone out's maximum is +/- 4.0 V peak to peak.
40
41 The AD1843's PCM input channel and one of its output channels (DAC1)
42 are connected to Lithium. The other output channel (DAC2) is not
43 connected.
44
45 ==============================================================================
46 CAPABILITIES
47
48 The AD1843 has PCM input and output (Pulse Code Modulation, also known
49 as wavetable). PCM input and output can be mono or stereo in any of
50 four formats. The formats are 16 bit signed and 8 bit unsigned,
51 u-Law, and A-Law format. Any sample rate from 4 KHz to 49 KHz is
52 available, in 1 Hz increments.
53
54 The AD1843 includes an analog mixer that can mix all three input
55 signals (line, mic and CD) into the analog outputs. The mixer has a
56 separate gain control and mute switch for each input.
57
58 There are two outputs, line out and speaker/headphone out. They
59 always produce the same signal, and the speaker always has 3 dB more
60 gain than the line out. The speaker/headphone output can be muted,
61 but this driver does not export that function.
62
63 The hardware can sync audio to the video clock, but this driver does
64 not have a way to specify syncing to video.
65
66 ==============================================================================
67 PROGRAMMING
68
69 This section explains the API supported by the driver. Also see the
70 Open Sound Programming Guide at http://www.opensound.com/pguide/ .
71 This section assumes familiarity with that document.
72
73 The driver has two interfaces, an I/O interface and a mixer interface.
74 There is no MIDI or sequencer capability.
75
76 ==============================================================================
77 PROGRAMMING PCM I/O
78
79 The I/O interface is usually accessed as /dev/audio or /dev/dsp.
80 Using the standard Open Sound System (OSS) ioctl calls, the sample
81 rate, number of channels, and sample format may be set within the
82 limitations described above. The driver supports triggering. It also
83 supports getting the input and output pointers with one-sample
84 accuracy.
85
86 The SNDCTL_DSP_GETCAP ioctl returns these capabilities.
87
88 DSP_CAP_DUPLEX - driver supports full duplex.
89
90 DSP_CAP_TRIGGER - driver supports triggering.
91
92 DSP_CAP_REALTIME - values returned by SNDCTL_DSP_GETIPTR
93 and SNDCTL_DSP_GETOPTR are accurate to a few samples.
94
95 Memory mapping (mmap) is not implemented.
96
97 The driver permits subdivided fragment sizes from 64 to 4096 bytes.
98 The number of fragments can be anything from 3 fragments to however
99 many fragments fit into 124 kilobytes. It is up to the user to
100 determine how few/small fragments can be used without introducing
101 glitches with a given workload. Linux is not realtime, so we can't
102 promise anything. (sigh...)
103
104 When this driver is switched into or out of mu-Law or A-Law mode on
105 output, it may produce an audible click. This is unavoidable. To
106 prevent clicking, use signed 16-bit mode instead, and convert from
107 mu-Law or A-Law format in software.
108
109 ==============================================================================
110 PROGRAMMING THE MIXER INTERFACE
111
112 The mixer interface is usually accessed as /dev/mixer. It is accessed
113 through ioctls. The mixer allows the application to control gain or
114 mute several audio signal paths, and also allows selection of the
115 recording source.
116
117 Each of the constants described here can be read using the
118 MIXER_READ(SOUND_MIXER_xxx) ioctl. Those that are not read-only can
119 also be written using the MIXER_WRITE(SOUND_MIXER_xxx) ioctl. In most
120 cases, <sys/soundcard.h> defines constants SOUND_MIXER_READ_xxx and
121 SOUND_MIXER_WRITE_xxx which work just as well.
122
123 SOUND_MIXER_CAPS Read-only
124
125 This is a mask of optional driver capabilities that are implemented.
126 This driver's only capability is SOUND_CAP_EXCL_INPUT, which means
127 that only one recording source can be active at a time.
128
129 SOUND_MIXER_DEVMASK Read-only
130
131 This is a mask of the sound channels. This driver's channels are PCM,
132 LINE, MIC, CD, and RECLEV.
133
134 SOUND_MIXER_STEREODEVS Read-only
135
136 This is a mask of which sound channels are capable of stereo. All
137 channels are capable of stereo. (But see caveat on MIC input in I/O
138 CONNECTIONS section above).
139
140 SOUND_MIXER_OUTMASK Read-only
141
142 This is a mask of channels that route inputs through to outputs.
143 Those are LINE, MIC, and CD.
144
145 SOUND_MIXER_RECMASK Read-only
146
147 This is a mask of channels that can be recording sources. Those are
148 PCM, LINE, MIC, CD.
149
150 SOUND_MIXER_PCM Default: 0x5757 (0 dB)
151
152 This is the gain control for PCM output. The left and right channel
153 gain are controlled independently. This gain control has 64 levels,
154 which range from -82.5 dB to +12.0 dB in 1.5 dB steps. Those 64
155 levels are mapped onto 100 levels at the ioctl, see below.
156
157 SOUND_MIXER_LINE Default: 0x4a4a (0 dB)
158
159 This is the gain control for mixing the Line In source into the
160 outputs. The left and right channel gain are controlled
161 independently. This gain control has 32 levels, which range from
162 -34.5 dB to +12.0 dB in 1.5 dB steps. Those 32 levels are mapped onto
163 100 levels at the ioctl, see below.
164
165 SOUND_MIXER_MIC Default: 0x4a4a (0 dB)
166
167 This is the gain control for mixing the MIC source into the outputs.
168 The left and right channel gain are controlled independently. This
169 gain control has 32 levels, which range from -34.5 dB to +12.0 dB in
170 1.5 dB steps. Those 32 levels are mapped onto 100 levels at the
171 ioctl, see below.
172
173 SOUND_MIXER_CD Default: 0x4a4a (0 dB)
174
175 This is the gain control for mixing the CD audio source into the
176 outputs. The left and right channel gain are controlled
177 independently. This gain control has 32 levels, which range from
178 -34.5 dB to +12.0 dB in 1.5 dB steps. Those 32 levels are mapped onto
179 100 levels at the ioctl, see below.
180
181 SOUND_MIXER_RECLEV Default: 0 (0 dB)
182
183 This is the gain control for PCM input (RECording LEVel). The left
184 and right channel gain are controlled independently. This gain
185 control has 16 levels, which range from 0 dB to +22.5 dB in 1.5 dB
186 steps. Those 16 levels are mapped onto 100 levels at the ioctl, see
187 below.
188
189 SOUND_MIXER_RECSRC Default: SOUND_MASK_LINE
190
191 This is a mask of currently selected PCM input sources (RECording
192 SouRCes). Because the AD1843 can only have a single recording source
193 at a time, only one bit at a time can be set in this mask. The
194 allowable values are SOUND_MASK_PCM, SOUND_MASK_LINE, SOUND_MASK_MIC,
195 or SOUND_MASK_CD. Selecting SOUND_MASK_PCM sets up internal
196 resampling which is useful for loopback testing and for hardware
197 sample rate conversion. But software sample rate conversion is
198 probably faster, so I don't know how useful that is.
199
200 SOUND_MIXER_OUTSRC DEFAULT: SOUND_MASK_LINE|SOUND_MASK_MIC|SOUND_MASK_CD
201
202 This is a mask of sources that are currently passed through to the
203 outputs. Those sources whose bits are not set are muted.
204
205 ==============================================================================
206 GAIN CONTROL
207
208 There are five gain controls listed above. Each has 16, 32, or 64
209 steps. Each control has 1.5 dB of gain per step. Each control is
210 stereo.
211
212 The OSS defines the argument to a channel gain ioctl as having two
213 components, left and right, each of which ranges from 0 to 100. The
214 two components are packed into the same word, with the left side gain
215 in the least significant byte, and the right side gain in the second
216 least significant byte. In C, we would say this.
217
218 #include <assert.h>
219
220 ...
221
222 assert(leftgain >= 0 && leftgain <= 100);
223 assert(rightgain >= 0 && rightgain <= 100);
224 arg = leftgain | rightgain << 8;
225
226 So each OSS gain control has 101 steps. But the hardware has 16, 32,
227 or 64 steps. The hardware steps are spread across the 101 OSS steps
228 nearly evenly. The conversion formulas are like this, given N equals
229 16, 32, or 64.
230
231 int round = N/2 - 1;
232 OSS_gain_steps = (hw_gain_steps * 100 + round) / (N - 1);
233 hw_gain_steps = (OSS_gain_steps * (N - 1) + round) / 100;
234
235 Here is a snippet of C code that will return the left and right gain
236 of any channel in dB. Pass it one of the predefined gain_desc_t
237 structures to access any of the five channels' gains.
238
239 typedef struct gain_desc {
240 float min_gain;
241 float gain_step;
242 int nbits;
243 int chan;
244 } gain_desc_t;
245
246 const gain_desc_t gain_pcm = { -82.5, 1.5, 6, SOUND_MIXER_PCM };
247 const gain_desc_t gain_line = { -34.5, 1.5, 5, SOUND_MIXER_LINE };
248 const gain_desc_t gain_mic = { -34.5, 1.5, 5, SOUND_MIXER_MIC };
249 const gain_desc_t gain_cd = { -34.5, 1.5, 5, SOUND_MIXER_CD };
250 const gain_desc_t gain_reclev = { 0.0, 1.5, 4, SOUND_MIXER_RECLEV };
251
252 int get_gain_dB(int fd, const gain_desc_t *gp,
253 float *left, float *right)
254 {
255 int word;
256 int lg, rg;
257 int mask = (1 << gp->nbits) - 1;
258
259 if (ioctl(fd, MIXER_READ(gp->chan), &word) != 0)
260 return -1; /* fail */
261 lg = word & 0xFF;
262 rg = word >> 8 & 0xFF;
263 lg = (lg * mask + mask / 2) / 100;
264 rg = (rg * mask + mask / 2) / 100;
265 *left = gp->min_gain + gp->gain_step * lg;
266 *right = gp->min_gain + gp->gain_step * rg;
267 return 0;
268 }
269
270 And here is the corresponding routine to set a channel's gain in dB.
271
272 int set_gain_dB(int fd, const gain_desc_t *gp, float left, float right)
273 {
274 float max_gain =
275 gp->min_gain + (1 << gp->nbits) * gp->gain_step;
276 float round = gp->gain_step / 2;
277 int mask = (1 << gp->nbits) - 1;
278 int word;
279 int lg, rg;
280
281 if (left < gp->min_gain || right < gp->min_gain)
282 return EINVAL;
283 lg = (left - gp->min_gain + round) / gp->gain_step;
284 rg = (right - gp->min_gain + round) / gp->gain_step;
285 if (lg >= (1 << gp->nbits) || rg >= (1 << gp->nbits))
286 return EINVAL;
287 lg = (100 * lg + mask / 2) / mask;
288 rg = (100 * rg + mask / 2) / mask;
289 word = lg | rg << 8;
290
291 return ioctl(fd, MIXER_WRITE(gp->chan), &word);
292 }
293
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.