[ALSA] Add documentation for HDSP MADI
authorTakashi Iwai <tiwai@suse.de>
Fri, 3 Jun 2005 09:27:00 +0000 (11:27 +0200)
committerJaroslav Kysela <perex@suse.cz>
Wed, 22 Jun 2005 10:28:15 +0000 (12:28 +0200)
Documentation
Added documentation for HDSP MADI driver by Winfried Ritsch.

Signed-off-by: Takashi Iwai <tiwai@suse.de>
Documentation/sound/alsa/ALSA-Configuration.txt
Documentation/sound/alsa/hdspm.txt [new file with mode: 0644]

index 812ed2b80b8dbedc0d17da6632bc4b0e2e5d2504..ced9a6eac5624d4aa66adb8699751281f3bd3b55 100644 (file)
@@ -674,6 +674,17 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
           stage of boot sequence.  See "Early Buffer Allocation"
          section.
 
+  Module snd-hdspm
+  ----------------
+
+    Module for RME HDSP MADI board.
+
+    precise_ptr                - Enable precise pointer, or disable.
+    line_outs_monitor  - Send playback streams to analog outs by default.
+    enable_monitor     - Enable Analog Out on Channel 63/64 by default.
+
+    See hdspm.txt for details.
+
   Module snd-ice1712
   ------------------
 
diff --git a/Documentation/sound/alsa/hdspm.txt b/Documentation/sound/alsa/hdspm.txt
new file mode 100644 (file)
index 0000000..7a67ff7
--- /dev/null
@@ -0,0 +1,362 @@
+Software Interface ALSA-DSP MADI Driver 
+
+(translated from German, so no good English ;-), 
+2004 - winfried ritsch
+
+
+
+ Full functionality has been added to the driver. Since some of
+ the Controls and startup-options  are ALSA-Standard and only the
+ special Controls are described and discussed below.
+
+
+ hardware functionality:
+
+   
+   Audio transmission:
+
+     number of channels --  depends on transmission mode
+
+               The number of channels chosen is from 1..Nmax. The reason to
+               use for a lower number of channels is only resource allocation,
+               since unused DMA channels are disabled and less memory is
+               allocated. So also the throughput of the PCI system can be
+               scaled. (Only important for low performance boards).
+
+       Single Speed -- 1..64 channels 
+
+                (Note: Choosing the 56channel mode for transmission or as
+                receiver, only 56 are transmitted/received over the MADI, but
+                all 64 channels are available for the mixer, so channel count
+                for the driver)
+
+       Double Speed -- 1..32 channels
+
+                Note: Choosing the 56-channel mode for
+                transmission/receive-mode , only 28 are transmitted/received
+                over the MADI, but all 32 channels are available for the mixer,
+                so channel count for the driver
+
+
+       Quad Speed -- 1..16 channels 
+
+                Note: Choosing the 56-channel mode for
+                transmission/receive-mode , only 14 are transmitted/received
+                over the MADI, but all 16 channels are available for the mixer,
+                so channel count for the driver
+
+     Format -- signed 32 Bit Little Endian (SNDRV_PCM_FMTBIT_S32_LE)
+
+     Sample Rates --
+
+       Single Speed -- 32000, 44100, 48000
+
+       Double Speed -- 64000, 88200, 96000 (untested)
+
+       Quad Speed -- 128000, 176400, 192000 (untested)
+
+     access-mode -- MMAP (memory mapped), Not interleaved
+     (PCM_NON-INTERLEAVED)
+
+     buffer-sizes -- 64,128,256,512,1024,2048,8192 Samples
+
+     fragments -- 2
+
+     Hardware-pointer -- 2 Modi
+
+
+                The Card supports the readout of the actual Buffer-pointer,
+                where DMA reads/writes. Since of the bulk mode of PCI it is only
+                64 Byte accurate. SO it is not really usable for the
+                ALSA-mid-level functions (here the buffer-ID gives a better
+                result), but if MMAP is used by the application. Therefore it
+                can be configured at load-time with the parameter
+                precise-pointer.
+
+
+                (Hint: Experimenting I found that the pointer is maximum 64 to
+                large never to small. So if you subtract 64 you always have a
+                safe pointer for writing, which is used on this mode inside
+                ALSA. In theory now you can get now a latency as low as 16
+                Samples, which is a quarter of the interrupt possibilities.)
+
+       Precise Pointer -- off
+                                       interrupt used for pointer-calculation
+
+       Precise Pointer -- on
+                                       hardware pointer used.
+
+   Controller:
+
+
+         Since DSP-MADI-Mixer has 8152 Fader, it does not make sense to
+         use the standard mixer-controls, since this would break most of
+         (especially graphic) ALSA-Mixer GUIs. So Mixer control has be
+         provided by a 2-dimensional controller using the
+         hwdep-interface. 
+
+     Also all 128+256 Peak and RMS-Meter can be accessed via the
+     hwdep-interface. Since it could be a performance problem always
+     copying and converting Peak and RMS-Levels even if you just need
+     one, I decided to export the hardware structure, so that of
+     needed some driver-guru can implement a memory-mapping of mixer
+     or peak-meters over ioctl, or also to do only copying and no
+     conversion. A test-application shows the usage of the controller.
+
+    Latency Controls --- not implemented !!!
+
+
+          Note: Within the windows-driver the latency is accessible of a
+          control-panel, but buffer-sizes are controlled with ALSA from
+          hwparams-calls and should not be changed in run-state, I did not
+          implement it here.
+
+
+    System Clock -- suspended !!!!
+
+        Name -- "System Clock Mode"
+
+        Access -- Read Write
+
+        Values -- "Master" "Slave"
+
+
+                 !!!! This is a hardware-function but is in conflict with the
+                 Clock-source controller, which is a kind of ALSA-standard. I
+                 makes sense to set the card to a special mode (master at some
+                 frequency or slave), since even not using an Audio-application
+                 a studio should have working synchronisations setup. So use
+                 Clock-source-controller instead !!!!
+
+    Clock Source  
+
+       Name -- "Sample Clock Source"
+
+       Access -- Read Write
+
+       Values -- "AutoSync", "Internal 32.0 kHz", "Internal 44.1 kHz",
+       "Internal 48.0 kHz", "Internal 64.0 kHz", "Internal 88.2 kHz",
+       "Internal 96.0 kHz"
+
+                Choose between Master at a specific Frequency and so also the
+                Speed-mode or Slave (Autosync). Also see  "Preferred Sync Ref"
+
+
+       !!!! This is no pure hardware function but was implemented by
+       ALSA by some ALSA-drivers before, so I use it also. !!!
+
+
+    Preferred Sync Ref
+
+       Name -- "Preferred Sync Reference"
+
+       Access -- Read Write
+
+       Values -- "Word" "MADI"
+
+
+                Within the Auto-sync-Mode the preferred Sync Source can be
+                chosen. If it is not available another is used if possible.
+
+                Note: Since MADI has a much higher bit-rate than word-clock, the
+                card should synchronise better in MADI Mode. But since the
+                RME-PLL is very good, there are almost no problems with
+                word-clock too. I never found a difference.
+
+
+    TX 64 channel --- 
+
+       Name -- "TX 64 channels mode"
+
+       Access -- Read Write
+
+       Values -- 0 1
+
+                Using 64-channel-modus (1) or 56-channel-modus for
+                MADI-transmission (0).
+
+
+                Note: This control is for output only. Input-mode is detected
+                automatically from hardware sending MADI.
+
+
+    Clear TMS ---
+
+       Name -- "Clear Track Marker"
+
+       Access -- Read Write
+
+       Values -- 0 1
+
+
+                Don't use to lower 5 Audio-bits on AES as additional Bits.
+        
+
+    Safe Mode oder Auto Input --- 
+
+       Name -- "Safe Mode"
+
+       Access -- Read Write
+
+       Values -- 0 1
+
+       (default on)
+
+                If on (1), then if either the optical or coaxial connection
+                has a failure, there is a takeover to the working one, with no
+                sample failure. Its only useful if you use the second as a
+                backup connection.
+
+    Input --- 
+
+       Name -- "Input Select"
+
+       Access -- Read Write
+
+       Values -- optical coaxial
+
+
+                Choosing the Input, optical or coaxial. If Safe-mode is active,
+                this is the preferred Input.
+
+-------------- Mixer ----------------------
+
+    Mixer
+
+       Name -- "Mixer"
+
+       Access -- Read Write
+
+       Values - <channel-number 0-127> <Value 0-65535>
+
+
+                Here as a first value the channel-index is taken to get/set the
+                corresponding mixer channel, where 0-63 are the input to output
+                fader and 64-127 the playback to outputs fader. Value 0
+                is channel muted 0 and 32768 an amplification of  1.
+
+    Chn 1-64
+
+       fast mixer for the ALSA-mixer utils. The diagonal of the
+       mixer-matrix is implemented from playback to output.
+       
+
+    Line Out
+
+       Name  -- "Line Out"
+
+       Access -- Read Write
+
+       Values -- 0 1
+
+                Switching on and off the analog out, which has nothing to do
+                with mixing or routing. the analog outs reflects channel 63,64.
+
+
+--- information (only read access):
+    Sample Rate
+
+       Name -- "System Sample Rate"
+
+       Access -- Read-only
+
+                getting the sample rate.
+
+
+    External Rate measured
+
+       Name -- "External Rate"
+
+       Access -- Read only
+
+
+                Should be "Autosync Rate", but Name used is
+                ALSA-Scheme. External Sample frequency liked used on Autosync is
+                reported.
+
+
+    MADI Sync Status
+
+       Name -- "MADI Sync Lock Status"
+
+       Access -- Read
+
+       Values -- 0,1,2
+
+       MADI-Input is 0=Unlocked, 1=Locked, or 2=Synced.
+
+
+    Word Clock Sync Status
+
+       Name -- "Word Clock Lock Status"
+
+       Access -- Read
+
+       Values -- 0,1,2
+
+       Word Clock Input is 0=Unlocked, 1=Locked, or 2=Synced.
+
+    AutoSync
+
+       Name -- "AutoSync Reference"
+
+       Access -- Read
+
+       Values -- "WordClock", "MADI", "None"
+
+                Sync-Reference is either "WordClock", "MADI" or none.
+
+   RX 64ch --- noch nicht implementiert
+
+       MADI-Receiver is in 64 channel mode oder 56 channel mode.
+
+
+   AB_inp   --- not tested 
+
+                Used input for Auto-Input.
+
+
+   actual Buffer Position --- not implemented
+
+          !!! this is a ALSA internal function, so no control is used !!!
+
+
+
+Calling Parameter:
+
+   index int array (min = 1, max = 8), 
+     "Index value for RME HDSPM interface." card-index within ALSA
+
+     note: ALSA-standard
+
+   id string array (min = 1, max = 8), 
+     "ID string for RME HDSPM interface."
+
+     note: ALSA-standard
+
+   enable int array (min = 1, max = 8), 
+     "Enable/disable specific HDSPM sound-cards."
+
+     note: ALSA-standard
+
+   precise_ptr int array (min = 1, max = 8), 
+     "Enable precise pointer, or disable."
+
+     note: Use only when the application supports this (which is a special case).
+
+   line_outs_monitor int array (min = 1, max = 8), 
+     "Send playback streams to analog outs by default."
+
+
+         note: each playback channel is mixed to the same numbered output
+         channel (routed). This is against the ALSA-convention, where all
+         channels have to be muted on after loading the driver, but was
+         used before on other cards, so i historically use it again)
+
+
+
+   enable_monitor int array (min = 1, max = 8), 
+     "Enable Analog Out on Channel 63/64 by default."
+
+      note: here the analog output is enabled (but not routed).
\ No newline at end of file