[PATCH v2] docs: sound: hdspm: clean up driver doc.

[PATCH v2] docs: sound: hdspm: clean up driver doc.

[Randy Dunlap]

Do some overall document cleanups:

- add driver name for clarification
- fix some punctuation issues
- correct some capitalization
- correct some grammar
- convert a few words from German to English
- eliminate double use of "note:"
- unindent Precise Pointer bullets so that they are not part of the Hint
- drop precise_ptr documentation since it has been modified to be
  "always on"

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Shuah Khan <skhan@linuxfoundation.org>
Cc: linux-doc@vger.kernel.org
Cc: Jaroslav Kysela <perex@perex.cz>
Cc: Takashi Iwai <tiwai@suse.com>
Cc: linux-sound@vger.kernel.org

 Documentation/sound/cards/hdspm.rst |  109 +++++++++-----------------
 1 file changed, 40 insertions(+), 69 deletions(-)

--- linux-next-20260911.orig/Documentation/sound/cards/hdspm.rst
+++ linux-next-20260911/Documentation/sound/cards/hdspm.rst
@@ -6,9 +6,11 @@ Software Interface ALSA-DSP MADI Driver
 
 2004 - winfried ritsch
 
+driver name - snd-hdspm
+
 
 Full functionality has been added to the driver. Since some of
-the Controls and startup-options  are ALSA-Standard and only the
+the Controls and startup options are ALSA-Standard, only the
 special Controls are described and discussed below.
 
 
@@ -18,7 +20,7 @@ Hardware functionality
 Audio transmission
 ------------------
 
-* number of channels --  depends on transmission mode
+* 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,
@@ -29,29 +31,29 @@ Audio transmission
 * Single Speed -- 1..64 channels 
 
 .. note::
-		 (Note: Choosing the 56channel mode for transmission or as
+		 Choosing the 56-channel 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)
+		 for the driver.
 
 * Double Speed -- 1..32 channels
 
 .. note::
-		 Note: Choosing the 56-channel mode for
-		 transmission/receive-mode , only 28 are transmitted/received
+		 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
+		 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
+		 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
+		 so channel count for the driver.
 
-* Format -- signed 32 Bit Little Endian (SNDRV_PCM_FMTBIT_S32_LE)
+* Format -- signed 32-bit Little Endian (SNDRV_PCM_FMTBIT_S32_LE)
 
 * Sample Rates --
 
@@ -67,30 +69,6 @@ Audio transmission
 
 * 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::
-		 (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
 ----------
@@ -104,7 +82,7 @@ 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
+one, I decided to export the hardware structure, so that if
 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.
@@ -112,9 +90,9 @@ conversion. A test-application shows the
 * Latency Controls --- not implemented !!!
 
 .. note::
-	   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
+	   Within the Windows driver the latency is accessible via
+	   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.
 
 
@@ -127,12 +105,12 @@ conversion. A test-application shows the
   * Values -- "Master" "Slave"
 
 .. note::
-		  !!!! This is a hardware-function but is in conflict with the
-		  Clock-source controller, which is a kind of ALSA-standard. I
+		  !!!! This is a hardware function but is in conflict with the
+		  Clock-source controller, which is a kind of ALSA-standard. It
 		  makes sense to set the card to a special mode (master at some
-		  frequency or slave), since even not using an Audio-application
+		  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 controller instead !!!!
 
 * Clock Source  
 
@@ -145,11 +123,11 @@ conversion. A test-application shows the
     "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"
+		 Speed-mode or Slave (Autosync). Also see "Preferred Sync Ref".
 
 .. warning::
-       !!!! This is no pure hardware function but was implemented by
-       ALSA by some ALSA-drivers before, so I use it also. !!!
+       !!!! This is not a pure hardware function but was implemented by
+       ALSA by some ALSA drivers before, so I use it also. !!!
 
 
 * Preferred Sync Ref
@@ -165,7 +143,7 @@ conversion. A test-application shows the
 		 chosen. If it is not available another is used if possible.
 
 .. note::
-		 Note: Since MADI has a much higher bit-rate than word-clock, the
+		 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.
@@ -179,12 +157,12 @@ conversion. A test-application shows the
 
   * Values -- 0 1
 
-		 Using 64-channel-modus (1) or 56-channel-modus for
+		 Using 64-channel mode (1) or 56-channel mode for
 		 MADI-transmission (0).
 
 
 .. note::
-		 Note: This control is for output only. Input-mode is detected
+		 This control is for output only. Input mode is detected
 		 automatically from hardware sending MADI.
 
 
@@ -200,7 +178,7 @@ conversion. A test-application shows the
 		 Don't use to lower 5 Audio-bits on AES as additional Bits.
         
 
-* Safe Mode oder Auto Input
+* Safe Mode or Auto Input
 
   * Name -- "Safe Mode"
 
@@ -222,7 +200,7 @@ conversion. A test-application shows the
   * Values -- optical coaxial
 
 
-		 Choosing the Input, optical or coaxial. If Safe-mode is active,
+		 Choosing the Input, optical or coaxial. If Safe mode is active,
 		 this is the preferred Input.
 
 Mixer
@@ -240,7 +218,7 @@ Mixer
 		 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.
+		 is channel muted 0 and 32768 an amplification of 1.
 
 * Chn 1-64
 
@@ -250,14 +228,14 @@ Mixer
 
 * Line Out
 
-  * Name  -- "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.
+		 with mixing or routing. The analog outs reflects channel 63,64.
 
 
 Information (only read access)
@@ -280,7 +258,7 @@ Information (only read access)
 
 
 		 Should be "Autosync Rate", but Name used is
-		 ALSA-Scheme. External Sample frequency liked used on Autosync is
+		 ALSA-Scheme. External Sample frequency like used on Autosync is
 		 reported.
 
 
@@ -315,19 +293,19 @@ Information (only read access)
 
 		 Sync-Reference is either "WordClock", "MADI" or none.
 
-* RX 64ch --- noch nicht implementiert
+* RX 64ch --- not yet implemented
 
-       MADI-Receiver is in 64 channel mode oder 56 channel mode.
+       MADI-Receiver is in 64-channel mode or 56-channel mode.
 
 
-* AB_inp   --- not tested 
+* 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 !!!
+	   !!! This is an ALSA internal function, so no control is used !!!
 
 
 
@@ -352,22 +330,15 @@ Calling Parameter
 
      note: ALSA-standard
 
-* precise_ptr int array (min = 1, max = 8)
-
-     Enable precise pointer, or disable.
-
-.. note::
-     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::
-	  note: each playback channel is mixed to the same numbered output
+	  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)
+	  used before on other cards, so I historically use it again.
 
 
 
@@ -375,5 +346,5 @@ Calling Parameter
 
      Enable Analog Out on Channel 63/64 by default.
 
-.. note ::
-      note: here the analog output is enabled (but not routed).
+.. note::
+      Here the analog output is enabled (but not routed).

Re: [PATCH v2] docs: sound: hdspm: clean up driver doc.

[Takashi Iwai]

On Mon, 14 Sep 2026 21:58:06 +0200,
Randy Dunlap wrote:
> 
> Do some overall document cleanups:
> 
> - add driver name for clarification
> - fix some punctuation issues
> - correct some capitalization
> - correct some grammar
> - convert a few words from German to English
> - eliminate double use of "note:"
> - unindent Precise Pointer bullets so that they are not part of the Hint
> - drop precise_ptr documentation since it has been modified to be
>   "always on"
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>

Applied to for-next branch now.  Thanks.


Takashi