[PATCH 0/3] Documentation: Fix issues with Oxford Semiconductor PCIe (Tornado) 950

[PATCH 0/3] Documentation: Fix issues with Oxford Semiconductor PCIe (Tornado) 950

[Maciej W. Rozycki]

Hi,

 Here are fixes for the Sphinx processing warnings reported with `make 
htmldocs' for the description of the Oxford Semiconductor PCIe (Tornado) 
950 driver recently added.  I have split them into two parts so that they 
can be considered separately.

 First, Documentation/tty/ has been moved to driver-api, which I find not 
suitable for user documentation, so I have now moved the description to 
Documentation/misc-devices/.  I found no better place, but I can update 
the change again if you have a better suggestion.

 Second, actual warnings have been removed.  I have corrected quoting for 
symbol/parameter references, quoted tables and rewritten bibligraphy in
Sphinx's style.

 Third, the document has now been wired into the misc-devices document, so 
that it is not an orphan page in the HTML format anymore and it is also 
included in PDF documentation.

 I have verified the result and considered it visually sound with output 
produced by `make htmldocs' and `make pdfdocs'.

 For the latter command however I need to note that several other 
documents in our Documentation/ tree suffer from a problem that causes 
`make pdfdocs' to fail (and the failure cannot be worked around with 
make's `-k -i' options, i.e. no output is ever produced), e.g.:

Markup is unsupported in LaTeX:
filesystems/9p:: nested tables are not yet implemented.

and similarly for: filesystems/erofs, filesystems/f2fs, filesystems/ntfs, 
networking/device_drivers/ethernet/dlink/dl2k, scsi/arcmsr_spec, 
scsi/g_NCR5380, scsi/ncr53c8xx, and scsi/sym53c8xx_2.  I don't know if it 
is a known problem, possibly addressed in a newer version of tools, so 
I've thought it might be worth reporting.

 I have worked around the problem by removing the offending files, which 
let `make pdfdocs' proceed to completion.  I have spotted another problem 
there then in that the table of contents is only generated in the output 
file produced upon the second or subsequent invocations of `make pdfdocs'.  
Similarly bibligraphy links (but not the list itself).  Upon the first run 
of `make pdfdocs' on a clean Documentation/ tree the Contents section only 
has its heading and bibligraphy links are dead with `[?]' showing (the 
section is correctly populated however).  It's not clear to me if this is 
a bug in the tools used or something wrong with our Makefile system, so 
again I've thought it might be worth reporting.

 NB XeTeX, Version 3.14159265-2.6-0.99999 (TeX Live 2019/dev/Debian) and 
Sphinx 1.8.4 here.

 The issues are not directly related to the changes proposed here though,
so please apply them.

  Maciej

[PATCH 1/3] Documentation: Move Oxford Semiconductor PCIe (Tornado) 950 to misc-devices

[Maciej W. Rozycki]

Documentation/tty has been moved to driver-api, which is not suitable 
for user documentation, so move the Oxford Semiconductor PCIe (Tornado) 
950 description to misc-devices instead.

Signed-off-by: Maciej W. Rozycki <macro@orcam.me.uk>
---
 Documentation/misc-devices/oxsemi-tornado.rst       |  129 ++++++++++++++++++++
 Documentation/tty/device_drivers/oxsemi-tornado.rst |  129 --------------------
 2 files changed, 129 insertions(+), 129 deletions(-)

linux-doc-oxsemi-tornado-move.diff
Index: linux-macro/Documentation/misc-devices/oxsemi-tornado.rst
===================================================================
--- /dev/null
+++ linux-macro/Documentation/misc-devices/oxsemi-tornado.rst
@@ -0,0 +1,129 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================================================
+Notes on Oxford Semiconductor PCIe (Tornado) 950 serial port devices
+====================================================================
+
+Oxford Semiconductor PCIe (Tornado) 950 serial port devices are driven
+by a fixed 62.5MHz clock input derived from the 100MHz PCI Express clock.
+
+The baud rate produced by the baud generator is obtained from this input
+frequency by dividing it by the clock prescaler, which can be set to any
+value from 1 to 63.875 in increments of 0.125, and then the usual 16-bit
+divisor is used as with the original 8250, to divide the frequency by a
+value from 1 to 65535.  Finally a programmable oversampling rate is used
+that can take any value from 4 to 16 to divide the frequency further and
+determine the actual baud rate used.  Baud rates from 15625000bps down
+to 0.933bps can be obtained this way.
+
+By default the oversampling rate is set to 16 and the clock prescaler is
+set to 33.875, meaning that the frequency to be used as the reference
+for the usual 16-bit divisor is 115313.653, which is close enough to the
+frequency of 115200 used by the original 8250 for the same values to be
+used for the divisor to obtain the requested baud rates by software that
+is unaware of the extra clock controls available.
+
+The oversampling rate is programmed with the TCR register and the clock
+prescaler is programmed with the CPR/CPR2 register pair[1][2][3][4].
+To switch away from the default value of 33.875 for the prescaler the
+the enhanced mode has to be explicitly enabled though, by setting bit 4
+of the EFR.  In that mode setting bit 7 in the MCR enables the prescaler
+or otherwise it is bypassed as if the value of 1 was used.  Additionally
+writing any value to CPR clears CPR2 for compatibility with old software
+written for older conventional PCI Oxford Semiconductor devices that do
+not have the extra prescaler's 9th bit in CPR2, so the CPR/CPR2 register
+pair has to be programmed in the right order.
+
+By using these parameters rates from 15625000bps down to 1bps can be
+obtained, with either exact or highly-accurate actual bit rates for
+standard and many non-standard rates.
+
+Here are the figures for the standard and some non-standard baud rates
+(including those quoted in Oxford Semiconductor documentation), giving
+the requested rate (r), the actual rate yielded (a) and its deviation
+from the requested rate (d), and the values of the oversampling rate
+(tcr), the clock prescaler (cpr) and the divisor (div) produced by the
+new `get_divisor' handler:
+
+r: 15625000, a: 15625000.00, d:  0.0000%, tcr:  4, cpr:  1.000, div:     1
+r: 12500000, a: 12500000.00, d:  0.0000%, tcr:  5, cpr:  1.000, div:     1
+r: 10416666, a: 10416666.67, d:  0.0000%, tcr:  6, cpr:  1.000, div:     1
+r:  8928571, a:  8928571.43, d:  0.0000%, tcr:  7, cpr:  1.000, div:     1
+r:  7812500, a:  7812500.00, d:  0.0000%, tcr:  8, cpr:  1.000, div:     1
+r:  4000000, a:  4000000.00, d:  0.0000%, tcr:  5, cpr:  3.125, div:     1
+r:  3686400, a:  3676470.59, d: -0.2694%, tcr:  8, cpr:  2.125, div:     1
+r:  3500000, a:  3496503.50, d: -0.0999%, tcr: 13, cpr:  1.375, div:     1
+r:  3000000, a:  2976190.48, d: -0.7937%, tcr: 14, cpr:  1.500, div:     1
+r:  2500000, a:  2500000.00, d:  0.0000%, tcr: 10, cpr:  2.500, div:     1
+r:  2000000, a:  2000000.00, d:  0.0000%, tcr: 10, cpr:  3.125, div:     1
+r:  1843200, a:  1838235.29, d: -0.2694%, tcr: 16, cpr:  2.125, div:     1
+r:  1500000, a:  1492537.31, d: -0.4975%, tcr:  5, cpr:  8.375, div:     1
+r:  1152000, a:  1152073.73, d:  0.0064%, tcr: 14, cpr:  3.875, div:     1
+r:   921600, a:   919117.65, d: -0.2694%, tcr: 16, cpr:  2.125, div:     2
+r:   576000, a:   576036.87, d:  0.0064%, tcr: 14, cpr:  3.875, div:     2
+r:   460800, a:   460829.49, d:  0.0064%, tcr:  7, cpr:  3.875, div:     5
+r:   230400, a:   230414.75, d:  0.0064%, tcr: 14, cpr:  3.875, div:     5
+r:   115200, a:   115207.37, d:  0.0064%, tcr: 14, cpr:  1.250, div:    31
+r:    57600, a:    57603.69, d:  0.0064%, tcr:  8, cpr:  3.875, div:    35
+r:    38400, a:    38402.46, d:  0.0064%, tcr: 14, cpr:  3.875, div:    30
+r:    19200, a:    19201.23, d:  0.0064%, tcr:  8, cpr:  3.875, div:   105
+r:     9600, a:     9600.06, d:  0.0006%, tcr:  9, cpr:  1.125, div:   643
+r:     4800, a:     4799.98, d: -0.0004%, tcr:  7, cpr:  2.875, div:   647
+r:     2400, a:     2400.02, d:  0.0008%, tcr:  9, cpr:  2.250, div:  1286
+r:     1200, a:     1200.00, d:  0.0000%, tcr: 14, cpr:  2.875, div:  1294
+r:      300, a:      300.00, d:  0.0000%, tcr: 11, cpr:  2.625, div:  7215
+r:      200, a:      200.00, d:  0.0000%, tcr: 16, cpr:  1.250, div: 15625
+r:      150, a:      150.00, d:  0.0000%, tcr: 13, cpr:  2.250, div: 14245
+r:      134, a:      134.00, d:  0.0000%, tcr: 11, cpr:  2.625, div: 16153
+r:      110, a:      110.00, d:  0.0000%, tcr: 12, cpr:  1.000, div: 47348
+r:       75, a:       75.00, d:  0.0000%, tcr:  4, cpr:  5.875, div: 35461
+r:       50, a:       50.00, d:  0.0000%, tcr: 16, cpr:  1.250, div: 62500
+r:       25, a:       25.00, d:  0.0000%, tcr: 16, cpr:  2.500, div: 62500
+r:        4, a:        4.00, d:  0.0000%, tcr: 16, cpr: 20.000, div: 48828
+r:        2, a:        2.00, d:  0.0000%, tcr: 16, cpr: 40.000, div: 48828
+r:        1, a:        1.00, d:  0.0000%, tcr: 16, cpr: 63.875, div: 61154
+
+With the baud base set to 15625000 and the unsigned 16-bit UART_DIV_MAX
+limitation imposed by `serial8250_get_baud_rate' standard baud rates
+below 300bps become unavailable in the regular way, e.g. the rate of
+200bps requires the baud base to be divided by 78125 and that is beyond
+the unsigned 16-bit range.  The historic spd_cust feature can still be
+used by encoding the values for, the prescaler, the oversampling rate
+and the clock divisor (DLM/DLL) as follows to obtain such rates if so
+required:
+
+ 31 29 28             20 19   16 15                            0
++-----+-----------------+-------+-------------------------------+
+|0 0 0|    CPR2:CPR     |  TCR  |            DLM:DLL            |
++-----+-----------------+-------+-------------------------------+
+
+Use a value such encoded for the `custom_divisor' field along with the
+ASYNC_SPD_CUST flag set in the `flags' field in `struct serial_struct'
+passed with the TIOCSSERIAL ioctl(2), such as with the setserial(8)
+utility and its `divisor' and `spd_cust' parameters, and the select
+the baud rate of 38400bps.  Note that the value of 0 in TCR sets the
+oversampling rate to 16 and prescaler values below 1 in CPR2/CPR are
+clamped by the driver to 1.
+
+For example the value of 0x1f4004e2 will set CPR2/CPR, TCR and DLM/DLL
+respectively to 0x1f4, 0x0 and 0x04e2, choosing the prescaler value,
+the oversampling rate and the clock divisor of 62.500, 16 and 1250
+respectively.  These parameters will set the baud rate for the serial
+port to 62500000 / 62.500 / 1250 / 16 = 50bps.
+
+References:
+
+[1] "OXPCIe200 PCI Express Multi-Port Bridge", Oxford Semiconductor,
+    Inc., DS-0045, 10 Nov 2008, Section "950 Mode", pp. 64-65
+
+[2] "OXPCIe952 PCI Express Bridge to Dual Serial & Parallel Port",
+    Oxford Semiconductor, Inc., DS-0046, Mar 06 08, Section "950 Mode",
+    p. 20
+
+[3] "OXPCIe954 PCI Express Bridge to Quad Serial Port", Oxford
+    Semiconductor, Inc., DS-0047, Feb 08, Section "950 Mode", p. 20
+
+[4] "OXPCIe958 PCI Express Bridge to Octal Serial Port", Oxford
+    Semiconductor, Inc., DS-0048, Feb 08, Section "950 Mode", p. 20
+
+Maciej W. Rozycki  <macro@orcam.me.uk>
Index: linux-macro/Documentation/tty/device_drivers/oxsemi-tornado.rst
===================================================================
--- linux-macro.orig/Documentation/tty/device_drivers/oxsemi-tornado.rst
+++ /dev/null
@@ -1,129 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-====================================================================
-Notes on Oxford Semiconductor PCIe (Tornado) 950 serial port devices
-====================================================================
-
-Oxford Semiconductor PCIe (Tornado) 950 serial port devices are driven
-by a fixed 62.5MHz clock input derived from the 100MHz PCI Express clock.
-
-The baud rate produced by the baud generator is obtained from this input
-frequency by dividing it by the clock prescaler, which can be set to any
-value from 1 to 63.875 in increments of 0.125, and then the usual 16-bit
-divisor is used as with the original 8250, to divide the frequency by a
-value from 1 to 65535.  Finally a programmable oversampling rate is used
-that can take any value from 4 to 16 to divide the frequency further and
-determine the actual baud rate used.  Baud rates from 15625000bps down
-to 0.933bps can be obtained this way.
-
-By default the oversampling rate is set to 16 and the clock prescaler is
-set to 33.875, meaning that the frequency to be used as the reference
-for the usual 16-bit divisor is 115313.653, which is close enough to the
-frequency of 115200 used by the original 8250 for the same values to be
-used for the divisor to obtain the requested baud rates by software that
-is unaware of the extra clock controls available.
-
-The oversampling rate is programmed with the TCR register and the clock
-prescaler is programmed with the CPR/CPR2 register pair[1][2][3][4].
-To switch away from the default value of 33.875 for the prescaler the
-the enhanced mode has to be explicitly enabled though, by setting bit 4
-of the EFR.  In that mode setting bit 7 in the MCR enables the prescaler
-or otherwise it is bypassed as if the value of 1 was used.  Additionally
-writing any value to CPR clears CPR2 for compatibility with old software
-written for older conventional PCI Oxford Semiconductor devices that do
-not have the extra prescaler's 9th bit in CPR2, so the CPR/CPR2 register
-pair has to be programmed in the right order.
-
-By using these parameters rates from 15625000bps down to 1bps can be
-obtained, with either exact or highly-accurate actual bit rates for
-standard and many non-standard rates.
-
-Here are the figures for the standard and some non-standard baud rates
-(including those quoted in Oxford Semiconductor documentation), giving
-the requested rate (r), the actual rate yielded (a) and its deviation
-from the requested rate (d), and the values of the oversampling rate
-(tcr), the clock prescaler (cpr) and the divisor (div) produced by the
-new `get_divisor' handler:
-
-r: 15625000, a: 15625000.00, d:  0.0000%, tcr:  4, cpr:  1.000, div:     1
-r: 12500000, a: 12500000.00, d:  0.0000%, tcr:  5, cpr:  1.000, div:     1
-r: 10416666, a: 10416666.67, d:  0.0000%, tcr:  6, cpr:  1.000, div:     1
-r:  8928571, a:  8928571.43, d:  0.0000%, tcr:  7, cpr:  1.000, div:     1
-r:  7812500, a:  7812500.00, d:  0.0000%, tcr:  8, cpr:  1.000, div:     1
-r:  4000000, a:  4000000.00, d:  0.0000%, tcr:  5, cpr:  3.125, div:     1
-r:  3686400, a:  3676470.59, d: -0.2694%, tcr:  8, cpr:  2.125, div:     1
-r:  3500000, a:  3496503.50, d: -0.0999%, tcr: 13, cpr:  1.375, div:     1
-r:  3000000, a:  2976190.48, d: -0.7937%, tcr: 14, cpr:  1.500, div:     1
-r:  2500000, a:  2500000.00, d:  0.0000%, tcr: 10, cpr:  2.500, div:     1
-r:  2000000, a:  2000000.00, d:  0.0000%, tcr: 10, cpr:  3.125, div:     1
-r:  1843200, a:  1838235.29, d: -0.2694%, tcr: 16, cpr:  2.125, div:     1
-r:  1500000, a:  1492537.31, d: -0.4975%, tcr:  5, cpr:  8.375, div:     1
-r:  1152000, a:  1152073.73, d:  0.0064%, tcr: 14, cpr:  3.875, div:     1
-r:   921600, a:   919117.65, d: -0.2694%, tcr: 16, cpr:  2.125, div:     2
-r:   576000, a:   576036.87, d:  0.0064%, tcr: 14, cpr:  3.875, div:     2
-r:   460800, a:   460829.49, d:  0.0064%, tcr:  7, cpr:  3.875, div:     5
-r:   230400, a:   230414.75, d:  0.0064%, tcr: 14, cpr:  3.875, div:     5
-r:   115200, a:   115207.37, d:  0.0064%, tcr: 14, cpr:  1.250, div:    31
-r:    57600, a:    57603.69, d:  0.0064%, tcr:  8, cpr:  3.875, div:    35
-r:    38400, a:    38402.46, d:  0.0064%, tcr: 14, cpr:  3.875, div:    30
-r:    19200, a:    19201.23, d:  0.0064%, tcr:  8, cpr:  3.875, div:   105
-r:     9600, a:     9600.06, d:  0.0006%, tcr:  9, cpr:  1.125, div:   643
-r:     4800, a:     4799.98, d: -0.0004%, tcr:  7, cpr:  2.875, div:   647
-r:     2400, a:     2400.02, d:  0.0008%, tcr:  9, cpr:  2.250, div:  1286
-r:     1200, a:     1200.00, d:  0.0000%, tcr: 14, cpr:  2.875, div:  1294
-r:      300, a:      300.00, d:  0.0000%, tcr: 11, cpr:  2.625, div:  7215
-r:      200, a:      200.00, d:  0.0000%, tcr: 16, cpr:  1.250, div: 15625
-r:      150, a:      150.00, d:  0.0000%, tcr: 13, cpr:  2.250, div: 14245
-r:      134, a:      134.00, d:  0.0000%, tcr: 11, cpr:  2.625, div: 16153
-r:      110, a:      110.00, d:  0.0000%, tcr: 12, cpr:  1.000, div: 47348
-r:       75, a:       75.00, d:  0.0000%, tcr:  4, cpr:  5.875, div: 35461
-r:       50, a:       50.00, d:  0.0000%, tcr: 16, cpr:  1.250, div: 62500
-r:       25, a:       25.00, d:  0.0000%, tcr: 16, cpr:  2.500, div: 62500
-r:        4, a:        4.00, d:  0.0000%, tcr: 16, cpr: 20.000, div: 48828
-r:        2, a:        2.00, d:  0.0000%, tcr: 16, cpr: 40.000, div: 48828
-r:        1, a:        1.00, d:  0.0000%, tcr: 16, cpr: 63.875, div: 61154
-
-With the baud base set to 15625000 and the unsigned 16-bit UART_DIV_MAX
-limitation imposed by `serial8250_get_baud_rate' standard baud rates
-below 300bps become unavailable in the regular way, e.g. the rate of
-200bps requires the baud base to be divided by 78125 and that is beyond
-the unsigned 16-bit range.  The historic spd_cust feature can still be
-used by encoding the values for, the prescaler, the oversampling rate
-and the clock divisor (DLM/DLL) as follows to obtain such rates if so
-required:
-
- 31 29 28             20 19   16 15                            0
-+-----+-----------------+-------+-------------------------------+
-|0 0 0|    CPR2:CPR     |  TCR  |            DLM:DLL            |
-+-----+-----------------+-------+-------------------------------+
-
-Use a value such encoded for the `custom_divisor' field along with the
-ASYNC_SPD_CUST flag set in the `flags' field in `struct serial_struct'
-passed with the TIOCSSERIAL ioctl(2), such as with the setserial(8)
-utility and its `divisor' and `spd_cust' parameters, and the select
-the baud rate of 38400bps.  Note that the value of 0 in TCR sets the
-oversampling rate to 16 and prescaler values below 1 in CPR2/CPR are
-clamped by the driver to 1.
-
-For example the value of 0x1f4004e2 will set CPR2/CPR, TCR and DLM/DLL
-respectively to 0x1f4, 0x0 and 0x04e2, choosing the prescaler value,
-the oversampling rate and the clock divisor of 62.500, 16 and 1250
-respectively.  These parameters will set the baud rate for the serial
-port to 62500000 / 62.500 / 1250 / 16 = 50bps.
-
-References:
-
-[1] "OXPCIe200 PCI Express Multi-Port Bridge", Oxford Semiconductor,
-    Inc., DS-0045, 10 Nov 2008, Section "950 Mode", pp. 64-65
-
-[2] "OXPCIe952 PCI Express Bridge to Dual Serial & Parallel Port",
-    Oxford Semiconductor, Inc., DS-0046, Mar 06 08, Section "950 Mode",
-    p. 20
-
-[3] "OXPCIe954 PCI Express Bridge to Quad Serial Port", Oxford
-    Semiconductor, Inc., DS-0047, Feb 08, Section "950 Mode", p. 20
-
-[4] "OXPCIe958 PCI Express Bridge to Octal Serial Port", Oxford
-    Semiconductor, Inc., DS-0048, Feb 08, Section "950 Mode", p. 20
-
-Maciej W. Rozycki  <macro@orcam.me.uk>

[PATCH 2/3] Documentation: Reformat Oxford Semiconductor PCIe (Tornado) 950

[Maciej W. Rozycki]

Reformat Oxford Semiconductor PCIe (Tornado) 950 description in terms of 
reStructuredText markup, fixing warnings with `make htmldocs'.  While at 
it remove typos: s/the the/the/ and s/the/then/ in lines changed anyway.

Signed-off-by: Maciej W. Rozycki <macro@orcam.me.uk>
---
 Documentation/misc-devices/oxsemi-tornado.rst |  136 +++++++++++++-------------
 1 file changed, 69 insertions(+), 67 deletions(-)

linux-doc-oxsemi-tornado-fix.diff
Index: linux-macro/Documentation/misc-devices/oxsemi-tornado.rst
===================================================================
--- linux-macro.orig/Documentation/misc-devices/oxsemi-tornado.rst
+++ linux-macro/Documentation/misc-devices/oxsemi-tornado.rst
@@ -24,15 +24,15 @@ used for the divisor to obtain the reque
 is unaware of the extra clock controls available.
 
 The oversampling rate is programmed with the TCR register and the clock
-prescaler is programmed with the CPR/CPR2 register pair[1][2][3][4].
-To switch away from the default value of 33.875 for the prescaler the
-the enhanced mode has to be explicitly enabled though, by setting bit 4
-of the EFR.  In that mode setting bit 7 in the MCR enables the prescaler
-or otherwise it is bypassed as if the value of 1 was used.  Additionally
-writing any value to CPR clears CPR2 for compatibility with old software
-written for older conventional PCI Oxford Semiconductor devices that do
-not have the extra prescaler's 9th bit in CPR2, so the CPR/CPR2 register
-pair has to be programmed in the right order.
+prescaler is programmed with the CPR/CPR2 register pair [OX200]_ [OX952]_
+[OX954]_ [OX958]_.  To switch away from the default value of 33.875 for
+the prescaler the enhanced mode has to be explicitly enabled though, by
+setting bit 4 of the EFR.  In that mode setting bit 7 in the MCR enables
+the prescaler or otherwise it is bypassed as if the value of 1 was used.
+Additionally writing any value to CPR clears CPR2 for compatibility with
+old software written for older conventional PCI Oxford Semiconductor
+devices that do not have the extra prescaler's 9th bit in CPR2, so the
+CPR/CPR2 register pair has to be programmed in the right order.
 
 By using these parameters rates from 15625000bps down to 1bps can be
 obtained, with either exact or highly-accurate actual bit rates for
@@ -43,48 +43,50 @@ Here are the figures for the standard an
 the requested rate (r), the actual rate yielded (a) and its deviation
 from the requested rate (d), and the values of the oversampling rate
 (tcr), the clock prescaler (cpr) and the divisor (div) produced by the
-new `get_divisor' handler:
+new ``get_divisor`` handler:
 
-r: 15625000, a: 15625000.00, d:  0.0000%, tcr:  4, cpr:  1.000, div:     1
-r: 12500000, a: 12500000.00, d:  0.0000%, tcr:  5, cpr:  1.000, div:     1
-r: 10416666, a: 10416666.67, d:  0.0000%, tcr:  6, cpr:  1.000, div:     1
-r:  8928571, a:  8928571.43, d:  0.0000%, tcr:  7, cpr:  1.000, div:     1
-r:  7812500, a:  7812500.00, d:  0.0000%, tcr:  8, cpr:  1.000, div:     1
-r:  4000000, a:  4000000.00, d:  0.0000%, tcr:  5, cpr:  3.125, div:     1
-r:  3686400, a:  3676470.59, d: -0.2694%, tcr:  8, cpr:  2.125, div:     1
-r:  3500000, a:  3496503.50, d: -0.0999%, tcr: 13, cpr:  1.375, div:     1
-r:  3000000, a:  2976190.48, d: -0.7937%, tcr: 14, cpr:  1.500, div:     1
-r:  2500000, a:  2500000.00, d:  0.0000%, tcr: 10, cpr:  2.500, div:     1
-r:  2000000, a:  2000000.00, d:  0.0000%, tcr: 10, cpr:  3.125, div:     1
-r:  1843200, a:  1838235.29, d: -0.2694%, tcr: 16, cpr:  2.125, div:     1
-r:  1500000, a:  1492537.31, d: -0.4975%, tcr:  5, cpr:  8.375, div:     1
-r:  1152000, a:  1152073.73, d:  0.0064%, tcr: 14, cpr:  3.875, div:     1
-r:   921600, a:   919117.65, d: -0.2694%, tcr: 16, cpr:  2.125, div:     2
-r:   576000, a:   576036.87, d:  0.0064%, tcr: 14, cpr:  3.875, div:     2
-r:   460800, a:   460829.49, d:  0.0064%, tcr:  7, cpr:  3.875, div:     5
-r:   230400, a:   230414.75, d:  0.0064%, tcr: 14, cpr:  3.875, div:     5
-r:   115200, a:   115207.37, d:  0.0064%, tcr: 14, cpr:  1.250, div:    31
-r:    57600, a:    57603.69, d:  0.0064%, tcr:  8, cpr:  3.875, div:    35
-r:    38400, a:    38402.46, d:  0.0064%, tcr: 14, cpr:  3.875, div:    30
-r:    19200, a:    19201.23, d:  0.0064%, tcr:  8, cpr:  3.875, div:   105
-r:     9600, a:     9600.06, d:  0.0006%, tcr:  9, cpr:  1.125, div:   643
-r:     4800, a:     4799.98, d: -0.0004%, tcr:  7, cpr:  2.875, div:   647
-r:     2400, a:     2400.02, d:  0.0008%, tcr:  9, cpr:  2.250, div:  1286
-r:     1200, a:     1200.00, d:  0.0000%, tcr: 14, cpr:  2.875, div:  1294
-r:      300, a:      300.00, d:  0.0000%, tcr: 11, cpr:  2.625, div:  7215
-r:      200, a:      200.00, d:  0.0000%, tcr: 16, cpr:  1.250, div: 15625
-r:      150, a:      150.00, d:  0.0000%, tcr: 13, cpr:  2.250, div: 14245
-r:      134, a:      134.00, d:  0.0000%, tcr: 11, cpr:  2.625, div: 16153
-r:      110, a:      110.00, d:  0.0000%, tcr: 12, cpr:  1.000, div: 47348
-r:       75, a:       75.00, d:  0.0000%, tcr:  4, cpr:  5.875, div: 35461
-r:       50, a:       50.00, d:  0.0000%, tcr: 16, cpr:  1.250, div: 62500
-r:       25, a:       25.00, d:  0.0000%, tcr: 16, cpr:  2.500, div: 62500
-r:        4, a:        4.00, d:  0.0000%, tcr: 16, cpr: 20.000, div: 48828
-r:        2, a:        2.00, d:  0.0000%, tcr: 16, cpr: 40.000, div: 48828
-r:        1, a:        1.00, d:  0.0000%, tcr: 16, cpr: 63.875, div: 61154
+::
+
+ r: 15625000, a: 15625000.00, d:  0.0000%, tcr:  4, cpr:  1.000, div:     1
+ r: 12500000, a: 12500000.00, d:  0.0000%, tcr:  5, cpr:  1.000, div:     1
+ r: 10416666, a: 10416666.67, d:  0.0000%, tcr:  6, cpr:  1.000, div:     1
+ r:  8928571, a:  8928571.43, d:  0.0000%, tcr:  7, cpr:  1.000, div:     1
+ r:  7812500, a:  7812500.00, d:  0.0000%, tcr:  8, cpr:  1.000, div:     1
+ r:  4000000, a:  4000000.00, d:  0.0000%, tcr:  5, cpr:  3.125, div:     1
+ r:  3686400, a:  3676470.59, d: -0.2694%, tcr:  8, cpr:  2.125, div:     1
+ r:  3500000, a:  3496503.50, d: -0.0999%, tcr: 13, cpr:  1.375, div:     1
+ r:  3000000, a:  2976190.48, d: -0.7937%, tcr: 14, cpr:  1.500, div:     1
+ r:  2500000, a:  2500000.00, d:  0.0000%, tcr: 10, cpr:  2.500, div:     1
+ r:  2000000, a:  2000000.00, d:  0.0000%, tcr: 10, cpr:  3.125, div:     1
+ r:  1843200, a:  1838235.29, d: -0.2694%, tcr: 16, cpr:  2.125, div:     1
+ r:  1500000, a:  1492537.31, d: -0.4975%, tcr:  5, cpr:  8.375, div:     1
+ r:  1152000, a:  1152073.73, d:  0.0064%, tcr: 14, cpr:  3.875, div:     1
+ r:   921600, a:   919117.65, d: -0.2694%, tcr: 16, cpr:  2.125, div:     2
+ r:   576000, a:   576036.87, d:  0.0064%, tcr: 14, cpr:  3.875, div:     2
+ r:   460800, a:   460829.49, d:  0.0064%, tcr:  7, cpr:  3.875, div:     5
+ r:   230400, a:   230414.75, d:  0.0064%, tcr: 14, cpr:  3.875, div:     5
+ r:   115200, a:   115207.37, d:  0.0064%, tcr: 14, cpr:  1.250, div:    31
+ r:    57600, a:    57603.69, d:  0.0064%, tcr:  8, cpr:  3.875, div:    35
+ r:    38400, a:    38402.46, d:  0.0064%, tcr: 14, cpr:  3.875, div:    30
+ r:    19200, a:    19201.23, d:  0.0064%, tcr:  8, cpr:  3.875, div:   105
+ r:     9600, a:     9600.06, d:  0.0006%, tcr:  9, cpr:  1.125, div:   643
+ r:     4800, a:     4799.98, d: -0.0004%, tcr:  7, cpr:  2.875, div:   647
+ r:     2400, a:     2400.02, d:  0.0008%, tcr:  9, cpr:  2.250, div:  1286
+ r:     1200, a:     1200.00, d:  0.0000%, tcr: 14, cpr:  2.875, div:  1294
+ r:      300, a:      300.00, d:  0.0000%, tcr: 11, cpr:  2.625, div:  7215
+ r:      200, a:      200.00, d:  0.0000%, tcr: 16, cpr:  1.250, div: 15625
+ r:      150, a:      150.00, d:  0.0000%, tcr: 13, cpr:  2.250, div: 14245
+ r:      134, a:      134.00, d:  0.0000%, tcr: 11, cpr:  2.625, div: 16153
+ r:      110, a:      110.00, d:  0.0000%, tcr: 12, cpr:  1.000, div: 47348
+ r:       75, a:       75.00, d:  0.0000%, tcr:  4, cpr:  5.875, div: 35461
+ r:       50, a:       50.00, d:  0.0000%, tcr: 16, cpr:  1.250, div: 62500
+ r:       25, a:       25.00, d:  0.0000%, tcr: 16, cpr:  2.500, div: 62500
+ r:        4, a:        4.00, d:  0.0000%, tcr: 16, cpr: 20.000, div: 48828
+ r:        2, a:        2.00, d:  0.0000%, tcr: 16, cpr: 40.000, div: 48828
+ r:        1, a:        1.00, d:  0.0000%, tcr: 16, cpr: 63.875, div: 61154
 
 With the baud base set to 15625000 and the unsigned 16-bit UART_DIV_MAX
-limitation imposed by `serial8250_get_baud_rate' standard baud rates
+limitation imposed by ``serial8250_get_baud_rate`` standard baud rates
 below 300bps become unavailable in the regular way, e.g. the rate of
 200bps requires the baud base to be divided by 78125 and that is beyond
 the unsigned 16-bit range.  The historic spd_cust feature can still be
@@ -92,15 +94,17 @@ used by encoding the values for, the pre
 and the clock divisor (DLM/DLL) as follows to obtain such rates if so
 required:
 
- 31 29 28             20 19   16 15                            0
-+-----+-----------------+-------+-------------------------------+
-|0 0 0|    CPR2:CPR     |  TCR  |            DLM:DLL            |
-+-----+-----------------+-------+-------------------------------+
+::
 
-Use a value such encoded for the `custom_divisor' field along with the
-ASYNC_SPD_CUST flag set in the `flags' field in `struct serial_struct'
+  31 29 28             20 19   16 15                            0
+ +-----+-----------------+-------+-------------------------------+
+ |0 0 0|    CPR2:CPR     |  TCR  |            DLM:DLL            |
+ +-----+-----------------+-------+-------------------------------+
+
+Use a value such encoded for the ``custom_divisor`` field along with the
+ASYNC_SPD_CUST flag set in the ``flags`` field in ``struct serial_struct``
 passed with the TIOCSSERIAL ioctl(2), such as with the setserial(8)
-utility and its `divisor' and `spd_cust' parameters, and the select
+utility and its ``divisor`` and ``spd_cust`` parameters, and then select
 the baud rate of 38400bps.  Note that the value of 0 in TCR sets the
 oversampling rate to 16 and prescaler values below 1 in CPR2/CPR are
 clamped by the driver to 1.
@@ -111,19 +115,17 @@ the oversampling rate and the clock divi
 respectively.  These parameters will set the baud rate for the serial
 port to 62500000 / 62.500 / 1250 / 16 = 50bps.
 
-References:
-
-[1] "OXPCIe200 PCI Express Multi-Port Bridge", Oxford Semiconductor,
-    Inc., DS-0045, 10 Nov 2008, Section "950 Mode", pp. 64-65
+Maciej W. Rozycki  <macro@orcam.me.uk>
 
-[2] "OXPCIe952 PCI Express Bridge to Dual Serial & Parallel Port",
-    Oxford Semiconductor, Inc., DS-0046, Mar 06 08, Section "950 Mode",
-    p. 20
+.. [OX200] "OXPCIe200 PCI Express Multi-Port Bridge", Oxford Semiconductor,
+   Inc., DS-0045, 10 Nov 2008, Section "950 Mode", pp. 64-65
 
-[3] "OXPCIe954 PCI Express Bridge to Quad Serial Port", Oxford
-    Semiconductor, Inc., DS-0047, Feb 08, Section "950 Mode", p. 20
+.. [OX952] "OXPCIe952 PCI Express Bridge to Dual Serial & Parallel Port",
+   Oxford Semiconductor, Inc., DS-0046, Mar 06 08, Section "950 Mode",
+   p. 20
 
-[4] "OXPCIe958 PCI Express Bridge to Octal Serial Port", Oxford
-    Semiconductor, Inc., DS-0048, Feb 08, Section "950 Mode", p. 20
+.. [OX954] "OXPCIe954 PCI Express Bridge to Quad Serial Port", Oxford
+   Semiconductor, Inc., DS-0047, Feb 08, Section "950 Mode", p. 20
 
-Maciej W. Rozycki  <macro@orcam.me.uk>
+.. [OX958] "OXPCIe958 PCI Express Bridge to Octal Serial Port", Oxford
+   Semiconductor, Inc., DS-0048, Feb 08, Section "950 Mode", p. 20

[PATCH 3/3] Documentation: Wire Oxford Semiconductor PCIe (Tornado) 950

[Maciej W. Rozycki]

Wire Oxford Semiconductor PCIe (Tornado) 950 description as a chapter 
into the misc-devices document.

Signed-off-by: Maciej W. Rozycki <macro@orcam.me.uk>
---
 Documentation/misc-devices/index.rst |    1 +
 1 file changed, 1 insertion(+)

linux-doc-oxsemi-tornado-wire.diff
Index: linux-macro/Documentation/misc-devices/index.rst
===================================================================
--- linux-macro.orig/Documentation/misc-devices/index.rst
+++ linux-macro/Documentation/misc-devices/index.rst
@@ -25,6 +25,7 @@ fit into other categories.
    isl29003
    lis3lv02d
    max6875
+   oxsemi-tornado
    pci-endpoint-test
    spear-pcie-gadget
    uacce

Re: [PATCH 3/3] Documentation: Wire Oxford Semiconductor PCIe (Tornado) 950

[Bagas Sanjaya]

On 5/14/22 05:42, Maciej W. Rozycki wrote:
> Wire Oxford Semiconductor PCIe (Tornado) 950 description as a chapter 
> into the misc-devices document.
> 
> Signed-off-by: Maciej W. Rozycki <macro@orcam.me.uk>
> ---
>  Documentation/misc-devices/index.rst |    1 +
>  1 file changed, 1 insertion(+)
> 
> linux-doc-oxsemi-tornado-wire.diff
> Index: linux-macro/Documentation/misc-devices/index.rst
> ===================================================================
> --- linux-macro.orig/Documentation/misc-devices/index.rst
> +++ linux-macro/Documentation/misc-devices/index.rst
> @@ -25,6 +25,7 @@ fit into other categories.
>     isl29003
>     lis3lv02d
>     max6875
> +   oxsemi-tornado
>     pci-endpoint-test
>     spear-pcie-gadget
>     uacce

Shouldn't this patch be squashed into [1/2]?

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 3/3] Documentation: Wire Oxford Semiconductor PCIe (Tornado) 950

[Bagas Sanjaya]

On 5/14/22 12:50, Bagas Sanjaya wrote:
> 
> Shouldn't this patch be squashed into [1/2]?
> 

Oops, I mean patch [1/3].

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 3/3] Documentation: Wire Oxford Semiconductor PCIe (Tornado) 950

[Maciej W. Rozycki]

On Sat, 14 May 2022, Bagas Sanjaya wrote:

> > Shouldn't this patch be squashed into [1/2]?
> > 
> 
> Oops, I mean patch [1/3].

 Possibly, but I chose to keep one self-contained change per patch as per 
the cover letter and also concluded it makes no sense to wire the document 
while it's still broken.  I'm leaving it up to the maintainers to decide 
and I will repost an updated change if required.

  Maciej

Re: [PATCH 0/3] Documentation: Fix issues with Oxford Semiconductor PCIe (Tornado) 950

[Akira Yokosawa]

Hi Maciej,

On Fri, 13 May 2022 23:41:57 +0100 (BST),
Maciej W. Rozycki wrote:
> Hi,
> 
[...]
> 
>  For the latter command however I need to note that several other 
> documents in our Documentation/ tree suffer from a problem that causes 
> `make pdfdocs' to fail (and the failure cannot be worked around with 
> make's `-k -i' options, i.e. no output is ever produced), e.g.:
> 
> Markup is unsupported in LaTeX:
> filesystems/9p:: nested tables are not yet implemented.
> 
> and similarly for: filesystems/erofs, filesystems/f2fs, filesystems/ntfs, 
> networking/device_drivers/ethernet/dlink/dl2k, scsi/arcmsr_spec, 
> scsi/g_NCR5380, scsi/ncr53c8xx, and scsi/sym53c8xx_2.  I don't know if it 
> is a known problem, possibly addressed in a newer version of tools, so 
> I've thought it might be worth reporting.
> 
[...]
> 
>  NB XeTeX, Version 3.14159265-2.6-0.99999 (TeX Live 2019/dev/Debian) and 
> Sphinx 1.8.4 here.

As mentioned in the section titled "PDF and LaTeX builds" in
Documentation/doc-guide/sphinx.rst, "make pdfdocs" requires Sphinx 2.4 or
later.

Another hint for you.

You can say "make SPHINXDIRS=<sub dir> htmldocs pdfdocs" to
test-build docs under Documentation/<sub dir>/.
You might see false warnings of "WARNING: undefined label: ..."
which you wouldn't see in full builds, though.

Hope this helps.

I see there is no mention of the SPHINXDIRS make variable in the
doc-guide.  I'll see it can be explained somewhere in sphinx.rst.

        Thanks, Akira
> 
>  The issues are not directly related to the changes proposed here though,
> so please apply them.
> 
>   Maciej

Re: [PATCH 0/3] Documentation: Fix issues with Oxford Semiconductor PCIe (Tornado) 950

[Maciej W. Rozycki]

On Sun, 15 May 2022, Akira Yokosawa wrote:

> >  NB XeTeX, Version 3.14159265-2.6-0.99999 (TeX Live 2019/dev/Debian) and 
> > Sphinx 1.8.4 here.
> 
> As mentioned in the section titled "PDF and LaTeX builds" in
> Documentation/doc-guide/sphinx.rst, "make pdfdocs" requires Sphinx 2.4 or
> later.

 Ack, noted.  Note however that Documentation/Changes says:

Sphinx\ [#f1]_         1.7              sphinx-build --version
====================== ===============  ========================================
.. [#f1] Sphinx is needed only to build the Kernel documentation

Perhaps the additional requirement could be mentioned in the footnote?

[Also this is a production system and 1.8.4 is the only version available 
in the distribution it has installed, so I may not be able to upgrade for 
the foreseeable future anyway.]

> You can say "make SPHINXDIRS=<sub dir> htmldocs pdfdocs" to
> test-build docs under Documentation/<sub dir>/.
> You might see false warnings of "WARNING: undefined label: ..."
> which you wouldn't see in full builds, though.
> 
> Hope this helps.

 Sure, thanks a lot!

  Maciej