Merge git://git.kernel.org/pub/scm/linux/kernel/git/davem/sparc-2.6
[linux-2.6] / Documentation / sound / alsa / hdspm.txt
1 Software Interface ALSA-DSP MADI Driver 
2
3 (translated from German, so no good English ;-), 
4 2004 - winfried ritsch
5
6
7
8  Full functionality has been added to the driver. Since some of
9  the Controls and startup-options  are ALSA-Standard and only the
10  special Controls are described and discussed below.
11
12
13  hardware functionality:
14
15    
16    Audio transmission:
17
18      number of channels --  depends on transmission mode
19
20                 The number of channels chosen is from 1..Nmax. The reason to
21                 use for a lower number of channels is only resource allocation,
22                 since unused DMA channels are disabled and less memory is
23                 allocated. So also the throughput of the PCI system can be
24                 scaled. (Only important for low performance boards).
25
26        Single Speed -- 1..64 channels 
27
28                  (Note: Choosing the 56channel mode for transmission or as
29                  receiver, only 56 are transmitted/received over the MADI, but
30                  all 64 channels are available for the mixer, so channel count
31                  for the driver)
32
33        Double Speed -- 1..32 channels
34
35                  Note: Choosing the 56-channel mode for
36                  transmission/receive-mode , only 28 are transmitted/received
37                  over the MADI, but all 32 channels are available for the mixer,
38                  so channel count for the driver
39
40
41        Quad Speed -- 1..16 channels 
42
43                  Note: Choosing the 56-channel mode for
44                  transmission/receive-mode , only 14 are transmitted/received
45                  over the MADI, but all 16 channels are available for the mixer,
46                  so channel count for the driver
47
48      Format -- signed 32 Bit Little Endian (SNDRV_PCM_FMTBIT_S32_LE)
49
50      Sample Rates --
51
52        Single Speed -- 32000, 44100, 48000
53
54        Double Speed -- 64000, 88200, 96000 (untested)
55
56        Quad Speed -- 128000, 176400, 192000 (untested)
57
58      access-mode -- MMAP (memory mapped), Not interleaved
59      (PCM_NON-INTERLEAVED)
60
61      buffer-sizes -- 64,128,256,512,1024,2048,8192 Samples
62
63      fragments -- 2
64
65      Hardware-pointer -- 2 Modi
66
67
68                  The Card supports the readout of the actual Buffer-pointer,
69                  where DMA reads/writes. Since of the bulk mode of PCI it is only
70                  64 Byte accurate. SO it is not really usable for the
71                  ALSA-mid-level functions (here the buffer-ID gives a better
72                  result), but if MMAP is used by the application. Therefore it
73                  can be configured at load-time with the parameter
74                  precise-pointer.
75
76
77                  (Hint: Experimenting I found that the pointer is maximum 64 to
78                  large never to small. So if you subtract 64 you always have a
79                  safe pointer for writing, which is used on this mode inside
80                  ALSA. In theory now you can get now a latency as low as 16
81                  Samples, which is a quarter of the interrupt possibilities.)
82
83        Precise Pointer -- off
84                                         interrupt used for pointer-calculation
85
86        Precise Pointer -- on
87                                         hardware pointer used.
88
89    Controller:
90
91
92           Since DSP-MADI-Mixer has 8152 Fader, it does not make sense to
93           use the standard mixer-controls, since this would break most of
94           (especially graphic) ALSA-Mixer GUIs. So Mixer control has be
95           provided by a 2-dimensional controller using the
96           hwdep-interface. 
97
98      Also all 128+256 Peak and RMS-Meter can be accessed via the
99      hwdep-interface. Since it could be a performance problem always
100      copying and converting Peak and RMS-Levels even if you just need
101      one, I decided to export the hardware structure, so that of
102      needed some driver-guru can implement a memory-mapping of mixer
103      or peak-meters over ioctl, or also to do only copying and no
104      conversion. A test-application shows the usage of the controller.
105
106     Latency Controls --- not implemented !!!
107
108
109            Note: Within the windows-driver the latency is accessible of a
110            control-panel, but buffer-sizes are controlled with ALSA from
111            hwparams-calls and should not be changed in run-state, I did not
112            implement it here.
113
114
115     System Clock -- suspended !!!!
116
117         Name -- "System Clock Mode"
118
119         Access -- Read Write
120
121         Values -- "Master" "Slave"
122
123
124                   !!!! This is a hardware-function but is in conflict with the
125                   Clock-source controller, which is a kind of ALSA-standard. I
126                   makes sense to set the card to a special mode (master at some
127                   frequency or slave), since even not using an Audio-application
128                   a studio should have working synchronisations setup. So use
129                   Clock-source-controller instead !!!!
130
131     Clock Source  
132
133        Name -- "Sample Clock Source"
134
135        Access -- Read Write
136
137        Values -- "AutoSync", "Internal 32.0 kHz", "Internal 44.1 kHz",
138        "Internal 48.0 kHz", "Internal 64.0 kHz", "Internal 88.2 kHz",
139        "Internal 96.0 kHz"
140
141                  Choose between Master at a specific Frequency and so also the
142                  Speed-mode or Slave (Autosync). Also see  "Preferred Sync Ref"
143
144
145        !!!! This is no pure hardware function but was implemented by
146        ALSA by some ALSA-drivers before, so I use it also. !!!
147
148
149     Preferred Sync Ref
150
151        Name -- "Preferred Sync Reference"
152
153        Access -- Read Write
154
155        Values -- "Word" "MADI"
156
157
158                  Within the Auto-sync-Mode the preferred Sync Source can be
159                  chosen. If it is not available another is used if possible.
160
161                  Note: Since MADI has a much higher bit-rate than word-clock, the
162                  card should synchronise better in MADI Mode. But since the
163                  RME-PLL is very good, there are almost no problems with
164                  word-clock too. I never found a difference.
165
166
167     TX 64 channel --- 
168
169        Name -- "TX 64 channels mode"
170
171        Access -- Read Write
172
173        Values -- 0 1
174
175                  Using 64-channel-modus (1) or 56-channel-modus for
176                  MADI-transmission (0).
177
178
179                  Note: This control is for output only. Input-mode is detected
180                  automatically from hardware sending MADI.
181
182
183     Clear TMS ---
184
185        Name -- "Clear Track Marker"
186
187        Access -- Read Write
188
189        Values -- 0 1
190
191
192                  Don't use to lower 5 Audio-bits on AES as additional Bits.
193         
194
195     Safe Mode oder Auto Input --- 
196
197        Name -- "Safe Mode"
198
199        Access -- Read Write
200
201        Values -- 0 1
202
203        (default on)
204
205                  If on (1), then if either the optical or coaxial connection
206                  has a failure, there is a takeover to the working one, with no
207                  sample failure. Its only useful if you use the second as a
208                  backup connection.
209
210     Input --- 
211
212        Name -- "Input Select"
213
214        Access -- Read Write
215
216        Values -- optical coaxial
217
218
219                  Choosing the Input, optical or coaxial. If Safe-mode is active,
220                  this is the preferred Input.
221
222 -------------- Mixer ----------------------
223
224     Mixer
225
226        Name -- "Mixer"
227
228        Access -- Read Write
229
230        Values - <channel-number 0-127> <Value 0-65535>
231
232
233                  Here as a first value the channel-index is taken to get/set the
234                  corresponding mixer channel, where 0-63 are the input to output
235                  fader and 64-127 the playback to outputs fader. Value 0
236                  is channel muted 0 and 32768 an amplification of  1.
237
238     Chn 1-64
239
240        fast mixer for the ALSA-mixer utils. The diagonal of the
241        mixer-matrix is implemented from playback to output.
242        
243
244     Line Out
245
246        Name  -- "Line Out"
247
248        Access -- Read Write
249
250        Values -- 0 1
251
252                  Switching on and off the analog out, which has nothing to do
253                  with mixing or routing. the analog outs reflects channel 63,64.
254
255
256 --- information (only read access):
257  
258     Sample Rate
259
260        Name -- "System Sample Rate"
261
262        Access -- Read-only
263
264                  getting the sample rate.
265
266
267     External Rate measured
268
269        Name -- "External Rate"
270
271        Access -- Read only
272
273
274                  Should be "Autosync Rate", but Name used is
275                  ALSA-Scheme. External Sample frequency liked used on Autosync is
276                  reported.
277
278
279     MADI Sync Status
280
281        Name -- "MADI Sync Lock Status"
282
283        Access -- Read
284
285        Values -- 0,1,2
286
287        MADI-Input is 0=Unlocked, 1=Locked, or 2=Synced.
288
289
290     Word Clock Sync Status
291
292        Name -- "Word Clock Lock Status"
293
294        Access -- Read
295
296        Values -- 0,1,2
297
298        Word Clock Input is 0=Unlocked, 1=Locked, or 2=Synced.
299
300     AutoSync
301
302        Name -- "AutoSync Reference"
303
304        Access -- Read
305
306        Values -- "WordClock", "MADI", "None"
307
308                  Sync-Reference is either "WordClock", "MADI" or none.
309
310    RX 64ch --- noch nicht implementiert
311
312        MADI-Receiver is in 64 channel mode oder 56 channel mode.
313
314
315    AB_inp   --- not tested 
316
317                  Used input for Auto-Input.
318
319
320    actual Buffer Position --- not implemented
321
322            !!! this is a ALSA internal function, so no control is used !!!
323
324
325
326 Calling Parameter:
327
328    index int array (min = 1, max = 8), 
329      "Index value for RME HDSPM interface." card-index within ALSA
330
331      note: ALSA-standard
332
333    id string array (min = 1, max = 8), 
334      "ID string for RME HDSPM interface."
335
336      note: ALSA-standard
337
338    enable int array (min = 1, max = 8), 
339      "Enable/disable specific HDSPM sound-cards."
340
341      note: ALSA-standard
342
343    precise_ptr int array (min = 1, max = 8), 
344      "Enable precise pointer, or disable."
345
346      note: Use only when the application supports this (which is a special case).
347
348    line_outs_monitor int array (min = 1, max = 8), 
349      "Send playback streams to analog outs by default."
350
351
352           note: each playback channel is mixed to the same numbered output
353           channel (routed). This is against the ALSA-convention, where all
354           channels have to be muted on after loading the driver, but was
355           used before on other cards, so i historically use it again)
356
357
358
359    enable_monitor int array (min = 1, max = 8), 
360      "Enable Analog Out on Channel 63/64 by default."
361
362       note: here the analog output is enabled (but not routed).