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