Skip to contentSkip to conversation

ALSA: docs: Add Marian M2 driver documentation

PATCH Superseded Ivan Orlov 5 participants 13 messages Sep 18, 2023 – Nov 5, 2023

Subsystems (2)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Ivan Orlov

author
#0 lore raw

PATCH v2 1/2 ALSA: docs: Add Marian M2 driver documentation

Add documentation for the new MARIAN Seraph M2 sound card. It covers current development status, available controls of the card and information about the integrated loopback.

---
V1 -> V2:
- Remove redundant documentation fix from the next patch in the series

 Documentation/sound/cards/index.rst     |   1 +
 Documentation/sound/cards/marian-m2.rst | 104 ++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 Documentation/sound/cards/marian-m2.rst
Documentation/sound/cards/index.rst +1 -0
index e68bbb13c384..e873592d8d00 100644
@@ -19,3 +19,4 @@ Card-Specific Information
    serial-u16550
    img-spdif-in
    pcmtest
+   marian-m2
Documentation/sound/cards/marian-m2.rst new file +104 -0

104 lines not on this page · raw message

Signature · 1 line
2.34.1
author
#1 lore raw

PATCH v2 2/2 ALSA: Add new driver for Marian M2 sound card

The original driver was written by Florian Faber in 2012. This patch represents the updated version of the original driver.

List of updates since the initial driver version:
- Update deprecated API calls, so it could be sent upstream
- Fix codestyle issues
- Fix memory allocation issues
- Add locking
- Remove support for other models of Marian sound cards, which I was unable to test and which are not documented anywhere.

Despite lacking of special equipment required for recording and playing MIDI/MADI, I was able to test the driver and fix some issues using the integrated and external loopbacks. Now the driver seems to work well.

---
V1 -> V2:
- Remove redundant documentation fix

 MAINTAINERS          |    7 +
 sound/pci/Kconfig    |   10 +
 sound/pci/Makefile   |    2 +
 sound/pci/marianm2.c | 1785 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 1804 insertions(+)
 create mode 100644 sound/pci/marianm2.c
MAINTAINERS +7 -0
index 90f13281d297..1e04a6c25a55 100644
@@ -12621,6 +12621,13 @@ L:	[email protected]
 S:	Maintained
 F:	arch/mips/boot/dts/img/pistachio*
 
+MARIAN SERAPH M2 SOUND CARD DRIVER
+M:	Ivan Orlov <[email protected]>
+L:	[email protected] (moderated for non-subscribers)
+S:	Maintained
+F:	Documentation/sound/cards/marian-m2.rst
+F:	sound/pci/marianm2.c
+
 MARVELL 88E6XXX ETHERNET SWITCH FABRIC DRIVER
 M:	Andrew Lunn <[email protected]>
 L:	[email protected]
sound/pci/Kconfig +10 -0
index 787868c9e91b..e3dad79743e5 100644
@@ -222,6 +222,16 @@ config SND_CMIPCI
 	  To compile this driver as a module, choose M here: the module
 	  will be called snd-cmipci.
 
+config SND_MARIANM2
+	tristate "MARIAN Seraph M2"
+	select SND_PCM
+	help
+	  Say Y to include support for MARIAN Seraph M2 sound card
+	  <file:Documentation/sound/cards/marian-m2.rst>.
+
+	  To compile this driver as a module, choose M here: the module
+	  will be called snd-marianm2
+
 config SND_OXYGEN_LIB
 	tristate
 
sound/pci/Makefile +2 -0
index 04cac7469139..4d2f52c98a74 100644
@@ -22,6 +22,7 @@ snd-fm801-objs := fm801.o
 snd-intel8x0-objs := intel8x0.o
 snd-intel8x0m-objs := intel8x0m.o
 snd-maestro3-objs := maestro3.o
+snd-marianm2-objs := marianm2.o
 snd-rme32-objs := rme32.o
 snd-rme96-objs := rme96.o
 snd-sis7019-objs := sis7019.o
@@ -48,6 +49,7 @@ obj-$(CONFIG_SND_FM801) += snd-fm801.o
 obj-$(CONFIG_SND_INTEL8X0) += snd-intel8x0.o
 obj-$(CONFIG_SND_INTEL8X0M) += snd-intel8x0m.o
 obj-$(CONFIG_SND_MAESTRO3) += snd-maestro3.o
+obj-$(CONFIG_SND_MARIANM2) += snd-marianm2.o
 obj-$(CONFIG_SND_RME32) += snd-rme32.o
 obj-$(CONFIG_SND_RME96) += snd-rme96.o
 obj-$(CONFIG_SND_SIS7019) += snd-sis7019.o
sound/pci/marianm2.c new file +1785 -0

1,785 lines not on this page · raw message

Signature · 1 line
2.34.1
#2 lore raw

Re: [PATCH v2 2/2] ALSA: Add new driver for Marian M2 sound card

kernel test robot noticed the following build warnings:

Hi Ivan,

kernel test robot noticed the following build warnings:

[auto build test WARNING on tiwai-sound/for-next]
[also build test WARNING on tiwai-sound/for-linus linus/master v6.6-rc2 next-20230918] [If your patch is applied to the wrong git tree, kindly drop us a note. And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Ivan-Orlov/ALSA-Add-new-driver-for-Marian-M2-sound-card/20230919-021236
base:   https://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git for-next
patch link:    https://lore.kernel.org/r/20230918181044.7257-2-ivan.orlov0322%40gmail.com
patch subject: [PATCH v2 2/2] ALSA: Add new driver for Marian M2 sound card
config: sparc-allmodconfig (https://download.01.org/0day-ci/archive/20230919/[email protected]/config)
compiler: sparc64-linux-gcc (GCC) 13.2.0
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20230919/[email protected]/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <[email protected]>
| Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/

All warnings (new ones prefixed by >>):

sound/pci/marianm2.c: In function 'snd_marian_hw_params':

>> sound/pci/marianm2.c:466:13: warning: variable 'buffer_frames' set but not used [-Wunused-but-set-variable]
     466 |         int buffer_frames;
         |             ^~~~~~~~~~~~~

vim +/buffer_frames +466 sound/pci/marianm2.c

460
461 static int snd_marian_hw_params(struct snd_pcm_substream *substream,
462 struct snd_pcm_hw_params *params)
463 {
464 struct marian_card *marian = snd_pcm_substream_chip(substream);
465 unsigned int speedmode;

 > 466		int buffer_frames;

467
468 buffer_frames = SUBSTREAM_BUF_SIZE / M2_FRAME_SIZE;
469
470 if (params_rate(params) < RATE_SLOW)
471 speedmode = SPEEDMODE_SLOW;
472 else if (params_rate(params) < RATE_FAST)
473 speedmode = SPEEDMODE_FAST;
474
475 if (speedmode > marian->desc->speedmode_max) {
476 dev_err(marian->card->dev,
477 "Requested rate (%u Hz) higher than card's maximum\n",
478 params_rate(params));
479 _snd_pcm_hw_param_setempty(params, SNDRV_PCM_HW_PARAM_RATE);
480 return -EBUSY;
481 }
482
483 spin_lock(&marian->reglock);
484 if (marian->desc->set_speedmode)
485 marian->desc->set_speedmode(marian, speedmode);
486 else
487 marian_generic_set_speedmode(marian, speedmode);
488
489 marian->detune = 0;
490
491 marian_generic_set_dco(marian, params_rate(params), 0);
492 spin_unlock(&marian->reglock);
493
494 if (substream->stream == SNDRV_PCM_STREAM_PLAYBACK)
495 snd_pcm_set_runtime_buffer(substream, &marian->playback_buf);
496 else
497 snd_pcm_set_runtime_buffer(substream, &marian->capture_buf);
498
499 // apply optional card specific hw constraints
500 if (marian->desc->hw_constraints_func)
501 marian->desc->hw_constraints_func(marian, substream, params);
502
503 return 0;
504 }
505

Signature · 2 lines
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki
#3 lore raw

Re: [PATCH v2 2/2] ALSA: Add new driver for Marian M2 sound card

In reply to Ivan Orlov

sound/pci/marianm2.c line 20

Quoted 13 lines · Ivan Orlov
sound/pci/marianm2.c new file +12 -0
+#include <sound/core.h>
+#include <sound/control.h>
+#include <sound/pcm.h>
+#include <sound/pcm_params.h>
+#include <sound/core.h>
+#include <sound/pcm.h>
+#include <sound/initval.h>
+#include <sound/info.h>
+#include <linux/delay.h>
+#include <linux/module.h>
+#include <linux/pci.h>
+#include <linux/interrupt.h>

We usually include linux/* at first, followed by sound/*.

Quoted 1 line

+#define DEBUG

Any need to define this for the production system?

Quoted 25 lines
sound/pci/marianm2.c new file +25 -0
+struct marian_card_descriptor;
+struct marian_card;
+
+struct marian_card_descriptor {
+	char *name;
+	char *port_names;
+	unsigned int speedmode_max;
+	unsigned int ch_in;
+	unsigned int ch_out;
+	unsigned int midi_in;
+	unsigned int midi_out;
+	unsigned int serial_in;
+	unsigned int serial_out;
+	unsigned int wck_in;
+	unsigned int wck_out;
+
+	unsigned int dma_bufsize;
+
+	void (*hw_constraints_func)(struct marian_card *marian,
+				    struct snd_pcm_substream *substream,
+				    struct snd_pcm_hw_params *params);
+	/* custom function to set up ALSA controls */
+	void (*create_controls)(struct marian_card *marian);
+	/* init is called after probing the card */
+	int (*init_card)(struct marian_card *marian);

sound/pci/marianm2.c line 155

Quoted 10 lines
sound/pci/marianm2.c new file +10 -0
+	void (*free_card)(struct marian_card *marian);
+	/* prepare is called when ALSA is opening the card */
+	void (*prepare)(struct marian_card *marian);
+	void (*set_speedmode)(struct marian_card *marian, unsigned int speedmode);
+	void (*proc_status)(struct marian_card *marian, struct snd_info_buffer *buffer);
+	void (*proc_ports)(struct marian_card *marian, struct snd_info_buffer *buffer,
+			   unsigned int type);
+
+	struct snd_pcm_hardware info_playback;
+	struct snd_pcm_hardware info_capture;

Do we need this kind of abstraction inside the driver?
As far as I see, the driver supports only a single model, hence there is no real merit of abstracted / indirect function calls.

So I stop reading at this point.

thanks,

Takashi

author
#4 lore raw

Re: [PATCH v2 2/2] ALSA: Add new driver for Marian M2 sound card

Quoted 64 lines · Takashi Iwai

sound/pci/marianm2.c line 20

Quoted 13 lines · Ivan Orlov
sound/pci/marianm2.c new file +12 -0
+#include <sound/core.h>
+#include <sound/control.h>
+#include <sound/pcm.h>
+#include <sound/pcm_params.h>
+#include <sound/core.h>
+#include <sound/pcm.h>
+#include <sound/initval.h>
+#include <sound/info.h>
+#include <linux/delay.h>
+#include <linux/module.h>
+#include <linux/pci.h>
+#include <linux/interrupt.h>

We usually include linux/* at first, followed by sound/*.

Quoted 1 line

+#define DEBUG

Any need to define this for the production system?

Quoted 25 lines
sound/pci/marianm2.c new file +25 -0
+struct marian_card_descriptor;
+struct marian_card;
+
+struct marian_card_descriptor {
+	char *name;
+	char *port_names;
+	unsigned int speedmode_max;
+	unsigned int ch_in;
+	unsigned int ch_out;
+	unsigned int midi_in;
+	unsigned int midi_out;
+	unsigned int serial_in;
+	unsigned int serial_out;
+	unsigned int wck_in;
+	unsigned int wck_out;
+
+	unsigned int dma_bufsize;
+
+	void (*hw_constraints_func)(struct marian_card *marian,
+				    struct snd_pcm_substream *substream,
+				    struct snd_pcm_hw_params *params);
+	/* custom function to set up ALSA controls */
+	void (*create_controls)(struct marian_card *marian);
+	/* init is called after probing the card */
+	int (*init_card)(struct marian_card *marian);

sound/pci/marianm2.c line 155

Quoted 10 lines
sound/pci/marianm2.c new file +10 -0
+	void (*free_card)(struct marian_card *marian);
+	/* prepare is called when ALSA is opening the card */
+	void (*prepare)(struct marian_card *marian);
+	void (*set_speedmode)(struct marian_card *marian, unsigned int speedmode);
+	void (*proc_status)(struct marian_card *marian, struct snd_info_buffer *buffer);
+	void (*proc_ports)(struct marian_card *marian, struct snd_info_buffer *buffer,
+			   unsigned int type);
+
+	struct snd_pcm_hardware info_playback;
+	struct snd_pcm_hardware info_capture;

Do we need this kind of abstraction inside the driver?
As far as I see, the driver supports only a single model, hence there is no real merit of abstracted / indirect function calls.

Quoted 6 lines

So I stop reading at this point.

thanks,

Takashi

Hi Takashi,

Thank you for the review! I will send the next version after removing all indirections and cleaning the code again.

--
Kind regards,
Ivan Orlov

#5 lore raw

Re: [PATCH v2 2/2] ALSA: Add new driver for Marian M2 sound card

In reply to Ivan Orlov

Review

Quoted 2 lines · Ivan Orlov
(quoted diff) +2 -0
+
+#define DEBUG

Do you mean to have DEBUG enabled at all times? Shouldn't this be a runtime issue with the normal dynamic debug infrastructure?

thanks,

greg k-h

author
#6 lore raw

Re: [PATCH v2 2/2] ALSA: Add new driver for Marian M2 sound card

Quoted 10 lines · Greg KH

Review

Quoted 2 lines · Ivan Orlov
(quoted diff) +2 -0
+
+#define DEBUG

Do you mean to have DEBUG enabled at all times? Shouldn't this be a runtime issue with the normal dynamic debug infrastructure?

thanks,

greg k-h

Hi Greg,

Yeah, I was experimenting with dynamic debugging and I've just forgotten to remove it... I'll be more attentive next time :(

By the way, is there any way to detect such issues automatically? I've seen that the kernel test robot detects a lot of similar stuff, perhaps there is any tools/linters which can be set up locally?

--
Kind regards,
Ivan Orlov

#7 lore raw

Re: [PATCH v2 2/2] ALSA: Add new driver for Marian M2 sound card

Quoted 3 lines · Ivan Orlov

By the way, is there any way to detect such issues automatically? I've seen that the kernel test robot detects a lot of similar stuff, perhaps there is any tools/linters which can be set up locally?

Not that I know of, sorry, I rely on the kernel test robot for lots of these things :)

But, the robot is running all open tests, so dig into the public repo of it to see what it is using and perhaps run those tests locally? Lots of them are just different build options and running sparse.

thanks,

greg k-h

author
#8 lore raw

Re: [PATCH v2 2/2] ALSA: Add new driver for Marian M2 sound card

Quoted 5 lines · Greg KH
Quoted 3 lines · Ivan Orlov

By the way, is there any way to detect such issues automatically? I've seen that the kernel test robot detects a lot of similar stuff, perhaps there is any tools/linters which can be set up locally?

Quoted 7 lines

Not that I know of, sorry, I rely on the kernel test robot for lots of these things :)

But, the robot is running all open tests, so dig into the public repo of it to see what it is using and perhaps run those tests locally? Lots of them are just different build options and running sparse.

Alright, I will take a look on the sources. Thank you for the advice! :)

#9 lore raw

Re: [PATCH v2 2/2] ALSA: Add new driver for Marian M2 sound card

In reply to Ivan Orlov
kernel test robot noticed the following build warnings:

Hi Ivan,

kernel test robot noticed the following build warnings:

[auto build test WARNING on tiwai-sound/for-next]
[also build test WARNING on tiwai-sound/for-linus linus/master v6.6 next-20231103] [If your patch is applied to the wrong git tree, kindly drop us a note. And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Ivan-Orlov/ALSA-Add-new-driver-for-Marian-M2-sound-card/20230919-021236
base:   https://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git for-next
patch link:    https://lore.kernel.org/r/20230918181044.7257-2-ivan.orlov0322%40gmail.com
patch subject: [PATCH v2 2/2] ALSA: Add new driver for Marian M2 sound card
config: i386-allyesconfig (https://download.01.org/0day-ci/archive/20231106/[email protected]/config)
compiler: clang version 16.0.4 (https://github.com/llvm/llvm-project.git ae42196bc493ffe877a7e3dff8be32035dea4d07)
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20231106/[email protected]/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <[email protected]>
| Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/

All warnings (new ones prefixed by >>):

sound/pci/marianm2.c:466:6: warning: variable 'buffer_frames' set but not used [-Wunused-but-set-variable]

           int buffer_frames;
               ^
>> sound/pci/marianm2.c:472:11: warning: variable 'speedmode' is used uninitialized whenever 'if' condition is false [-Wsometimes-uninitialized]
           else if (params_rate(params) < RATE_FAST)
                    ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   sound/pci/marianm2.c:475:6: note: uninitialized use occurs here
           if (speedmode > marian->desc->speedmode_max) {
               ^~~~~~~~~
   sound/pci/marianm2.c:472:7: note: remove the 'if' if its condition is always true
           else if (params_rate(params) < RATE_FAST)
                ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   sound/pci/marianm2.c:465:24: note: initialize the variable 'speedmode' to silence this warning
           unsigned int speedmode;
                                 ^
                                  = 0

2 warnings generated.

vim +472 sound/pci/marianm2.c

460
461 static int snd_marian_hw_params(struct snd_pcm_substream *substream,
462 struct snd_pcm_hw_params *params)
463 {
464 struct marian_card *marian = snd_pcm_substream_chip(substream);
465 unsigned int speedmode;

 > 466		int buffer_frames;
   467	
   468		buffer_frames = SUBSTREAM_BUF_SIZE / M2_FRAME_SIZE;
   469	
   470		if (params_rate(params) < RATE_SLOW)
   471			speedmode = SPEEDMODE_SLOW;
 > 472		else if (params_rate(params) < RATE_FAST)

473 speedmode = SPEEDMODE_FAST;
474
475 if (speedmode > marian->desc->speedmode_max) {
476 dev_err(marian->card->dev,
477 "Requested rate (%u Hz) higher than card's maximum\n",
478 params_rate(params));
479 _snd_pcm_hw_param_setempty(params, SNDRV_PCM_HW_PARAM_RATE);
480 return -EBUSY;
481 }
482
483 spin_lock(&marian->reglock);
484 if (marian->desc->set_speedmode)
485 marian->desc->set_speedmode(marian, speedmode);
486 else
487 marian_generic_set_speedmode(marian, speedmode);
488
489 marian->detune = 0;
490
491 marian_generic_set_dco(marian, params_rate(params), 0);
492 spin_unlock(&marian->reglock);
493
494 if (substream->stream == SNDRV_PCM_STREAM_PLAYBACK)
495 snd_pcm_set_runtime_buffer(substream, &marian->playback_buf);
496 else
497 snd_pcm_set_runtime_buffer(substream, &marian->capture_buf);
498
499 // apply optional card specific hw constraints
500 if (marian->desc->hw_constraints_func)
501 marian->desc->hw_constraints_func(marian, substream, params);
502
503 return 0;
504 }
505

Signature · 2 lines
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki
maintainer
#10 lore raw
In reply to Ivan Orlov
Quoted 8 lines · Ivan Orlov

Add documentation for the new MARIAN Seraph M2 sound card. It covers current development status, available controls of the card and information about the integrated loopback.

---
V1 -> V2:
- Remove redundant documentation fix from the next patch in the series

One quick comment below...

Quoted 26 lines
 Documentation/sound/cards/index.rst     |   1 +
 Documentation/sound/cards/marian-m2.rst | 104 ++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 Documentation/sound/cards/marian-m2.rst
Documentation/sound/cards/index.rst +1 -0
index e68bbb13c384..e873592d8d00 100644
@@ -19,3 +19,4 @@ Card-Specific Information
    serial-u16550
    img-spdif-in
    pcmtest
+   marian-m2
Documentation/sound/cards/marian-m2.rst new file +6 -0
new file mode 100644
index 000000000000..bf12445e20d7
@@ -0,0 +1,104 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+MARIAN Seraph M2 Driver
+=======================
+

Documentation/sound/cards/marian-m2.rst line 16

Quoted 10 lines
Documentation/sound/cards/marian-m2.rst new file +10 -0
+Sep 18, 2023
+
+Ivan Orlov <[email protected]>
+
+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.

Sticking to the 80-column limit is best for documentation, especially when there is no reason to go over it.

Quoted 7 lines
Documentation/sound/cards/marian-m2.rst new file +7 -0
+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
+- Integrated loopback (with some exceptions, see below)
+

Documentation/sound/cards/marian-m2.rst line 34

Quoted 10 lines
Documentation/sound/cards/marian-m2.rst new file +10 -0
+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:
+
+CAPTURE_CH_0, CAPTURE_CH_1, ..., CAPTURE_CH_127 | PLAY_CH_0, PLAY_CH_1, ..., PLAY_CH_127

You should really use literal blocks for this (and a lot that follows) or it won't render the way you want in HTML. The simplest way to do that is to use a double colon ("...samples::") and to indent the literal text.

(OK, two comments, sorry about the off-by-one...:)

Thanks,

jon

author
#11 lore raw
Quoted 76 lines · Jonathan Corbet
Quoted 8 lines · Ivan Orlov

Add documentation for the new MARIAN Seraph M2 sound card. It covers current development status, available controls of the card and information about the integrated loopback.

---
V1 -> V2:
- Remove redundant documentation fix from the next patch in the series

One quick comment below...

Quoted 26 lines
  Documentation/sound/cards/index.rst     |   1 +
  Documentation/sound/cards/marian-m2.rst | 104 ++++++++++++++++++++++++
  2 files changed, 105 insertions(+)

create mode 100644 Documentation/sound/cards/marian-m2.rst

Documentation/sound/cards/index.rst +1 -0
index e68bbb13c384..e873592d8d00 100644
@@ -19,3 +19,4 @@ Card-Specific Information
     serial-u16550
     img-spdif-in
     pcmtest
+   marian-m2
Documentation/sound/cards/marian-m2.rst new file +6 -0
new file mode 100644
index 000000000000..bf12445e20d7
@@ -0,0 +1,104 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+MARIAN Seraph M2 Driver
+=======================
+

Documentation/sound/cards/marian-m2.rst line 16

Quoted 10 lines
Documentation/sound/cards/marian-m2.rst new file +10 -0
+Sep 18, 2023
+
+Ivan Orlov <[email protected]>
+
+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.

Sticking to the 80-column limit is best for documentation, especially when there is no reason to go over it.

Quoted 7 lines
Documentation/sound/cards/marian-m2.rst new file +7 -0
+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
+- Integrated loopback (with some exceptions, see below)
+

Documentation/sound/cards/marian-m2.rst line 34

Quoted 10 lines
Documentation/sound/cards/marian-m2.rst new file +10 -0
+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:
+
+CAPTURE_CH_0, CAPTURE_CH_1, ..., CAPTURE_CH_127 | PLAY_CH_0, PLAY_CH_1, ..., PLAY_CH_127

You should really use literal blocks for this (and a lot that follows) or it won't render the way you want in HTML. The simplest way to do that is to use a double colon ("...samples::") and to indent the literal text.

Quoted 5 lines

(OK, two comments, sorry about the off-by-one...:)

Thanks,

jon

Hi Jonathan,

Thank you for the review, I'll rewrite the documentation so it will follow the 80-column rule. Also, in the next version I will use the literal blocks.

Thanks again!

--
Kind regards,
Ivan Orlov

#12 lore raw
In reply to Ivan Orlov
Quoted 35 lines · Ivan Orlov

Add documentation for the new MARIAN Seraph M2 sound card. It covers current development status, available controls of the card and information about the integrated loopback.

---
V1 -> V2:
- Remove redundant documentation fix from the next patch in the series

 Documentation/sound/cards/index.rst     |   1 +
 Documentation/sound/cards/marian-m2.rst | 104 ++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 Documentation/sound/cards/marian-m2.rst
Documentation/sound/cards/index.rst +1 -0
index e68bbb13c384..e873592d8d00 100644
@@ -19,3 +19,4 @@ Card-Specific Information
    serial-u16550
    img-spdif-in
    pcmtest
+   marian-m2
Documentation/sound/cards/marian-m2.rst new file +6 -0
new file mode 100644
index 000000000000..bf12445e20d7
@@ -0,0 +1,104 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+MARIAN Seraph M2 Driver
+=======================
+

Documentation/sound/cards/marian-m2.rst line 16

Quoted 10 lines
Documentation/sound/cards/marian-m2.rst new file +10 -0
+Sep 18, 2023
+
+Ivan Orlov <[email protected]>
+
+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.

Minor nit, shouldn't these lines be wrapped a bit shorter as it's a text file? 80 columns? The other files in this directory seem to all do that so maybe do the same here as well?

thanks,

greg k-h