[PATCH v3 1/2] ALSA: docs: Add MARIAN M2 driver documentation

[Ivan Orlov]

Add documentation for the new MARIAN Seraph M2 driver. MARIAN Seraph M2
is a fully digital PCI soundcard with 2 MADI inputs and outputs.

This patch introduces the documentation for the card driver. It covers
current development status, overview of the card, available controls and
information about the integrated loopback.

Signed-off-by: Ivan Orlov <ivan.orlov0322@xxxxxxxxx>
---
V1 -> V2:
- Remove redundant documentation fix
V2 -> V3:
- Make the documentation to follow 80-column rule
- Use literal blocks for markup
- Update the documentation correspondingly with the latest driver
changes: remove mHz and detune controls descriptions, remove
'speedmode' control.
- Extend the documentation to cover the card overview.

 Documentation/sound/cards/index.rst     |   1 +
 Documentation/sound/cards/marian-m2.rst | 140 ++++++++++++++++++++++++
 2 files changed, 141 insertions(+)
 create mode 100644 Documentation/sound/cards/marian-m2.rst

diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index e68bbb13c384..e873592d8d00 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -19,3 +19,4 @@ Card-Specific Information
    serial-u16550
    img-spdif-in
    pcmtest
+   marian-m2
diff --git a/Documentation/sound/cards/marian-m2.rst b/Documentation/sound/cards/marian-m2.rst
new file mode 100644
index 000000000000..3c12fe024e37
--- /dev/null
+++ b/Documentation/sound/cards/marian-m2.rst
@@ -0,0 +1,140 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+MARIAN Seraph M2 Driver
+=======================
+
+Sep 18, 2023
+
+Ivan Orlov <ivan.orlov0322@xxxxxxxxx>
+
+STATE OF DEVELOPMENT
+====================
+
+This driver is based on the driver written by Florian Faber in 2012, which
+seemed to work fine. However, the initial code contained multiple issues, which
+had to be solved before sending the driver upstream.
+
+The vendor lost the full documentation, so what we have here was recovered from
+drafts and found after experiments with the card.
+
+What seems to be working fine:
+
+ * Playback and capture for all supported rates
+ * MADI output frame mode changing
+ * Input frequency/frame mode measurement
+ * Integrated loopback (with some exceptions, see below)
+
+CARD INFORMATION
+================
+
+The card is fully digital and contains two MADI Inputs and two MADI outputs.
+It has internal clocks, but could be synchronized with clocks on any of its
+inputs. Also it could be synchronized with other MARIAN M2 sound card via
+SyncBus cable.
+
+Outputs support two modes: 56 channel mode and 64 channel mode. The number of
+audio channels will be halved automatically to 28 or 32 depending on the
+sample rate.
+
+The driver currently supports 48 and 96 kHz MADI frame formats for output.
+
+MEMORY MODEL
+============
+
+The hardware requires one huge contiguous DMA space to be allocated. After
+allocation, the bus address of this buffer should be written to the hardware
+register.
+
+We can split this space into two parts: the first one contains samples for
+capture, another one contains play samples::
+
+   CAP_CH_0, CAP_CH_1, ..., CAP_CH_127 | PLAY_CH_0, PLAY_CH_1, ..., PLAY_CH_127
+
+The card supports the non-interleaved access mode only, so samples for each
+channel lay together::
+
+   C0, ..., C0, C1, ..., C1, ..., C127 | C0, ..., C0, C1, ..., C1, ..., C127
+
+The count of samples per each channel buffer needs to be set explicitly, so the
+address of the first byte of the playback data depends on this value.
+The playback buffer starts where the capture buffer ends. It makes the arbitrary
+period count/buffer size feature impossible to implement, and the driver
+supports only 2 periods per buffer.
+
+Controls
+========
+
+ * Input 1 Sync
+
+   - 0 - No signal, 1 - valid MADI signal found, 2 - Synced with MADI signal
+
+ * Input 2 Sync
+
+   - 0 - No signal, 1 - valid MADI signal found, 2 - Synced with MADI signal
+
+ * Input 1 Channel Mode
+
+   - 0 - 56 channels, 1 - 64 channels
+
+ * Input 2 Channel Mode
+
+   - 0 - 56 channels, 1 - 64 channels
+
+ * Input 1 Frame Mode
+
+   - 0 - 48 kHz, 1 - 96 kHz
+
+ * Input 2 Frame Mode
+
+   - 0 - 48 kHz, 1 - 96 kHz
+
+ * Input 1 Frequency
+
+   - Measured frequency on Input 1
+
+ * Input 2 Frequency
+
+   - Measured frequency on Input 2
+
+ * Output 1 Channel Mode
+
+   - 0 - 56 channels, 1 - 64 channels
+
+ * Output 2 Channel Mode
+
+   - 0 - 56 channels, 1 - 64 channels
+
+ * Output 1 Frame Mode
+
+   - 0 - 48 kHz, 1 - 96 kHz
+
+ * Output 2 Frame Mode
+
+   - 0 - 48 kHz, 1 - 96 kHz
+
+ * Clock Source
+
+   - Internal/Sync Bus, Input Port 1, Input Port 2
+
+ * DCO Frequency (Hz)
+
+ * Loopback
+
+   - Enable/Disable integrated loopback
+
+
+Loopback
+========
+
+The card contains integrated loopback. When it is enabled, it sets
+the hardware’s DAW-in memory pointer to the hardware’s DAW-out memory. So, what
+you play is what you record.
+
+You will not observe the effect of channel halving when using the integrated
+loopback, as the data bypasses all DSP functionality in such case.
+
+You can enable the integrated loopback using the corresponding control.
+
+The loopback seems to work well on lower rates (like 28000). However, when the
+rate goes higher, the count of mistakes in recorded byte ordering increases.
-- 
2.34.1