1Software Interface ALSA-DSP MADI Driver 
2
3(translated from German, so no good English ;-), 
42004 - 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
326Calling 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).
363