diff options
Diffstat (limited to 'Documentation')
25 files changed, 466 insertions, 179 deletions
diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml index ff364bd0fbac..30eaa62e1aed 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml @@ -23,7 +23,9 @@ properties: - fsl,imx8qxp-lpuart - fsl,imxrt1050-lpuart - items: - - const: fsl,imx8ulp-lpuart + - enum: + - fsl,imx93-lpuart + - fsl,imx8ulp-lpuart - const: fsl,imx7ulp-lpuart - items: - enum: diff --git a/Documentation/devicetree/bindings/serial/qcom,serial-geni-qcom.yaml b/Documentation/devicetree/bindings/serial/qcom,serial-geni-qcom.yaml new file mode 100644 index 000000000000..05a6999808d1 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/qcom,serial-geni-qcom.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/serial/qcom,serial-geni-qcom.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm Geni based QUP UART interface + +maintainers: + - Andy Gross <agross@kernel.org> + - Bjorn Andersson <bjorn.andersson@linaro.org> + +allOf: + - $ref: /schemas/serial/serial.yaml# + +properties: + compatible: + enum: + - qcom,geni-uart + - qcom,geni-debug-uart + + clocks: + maxItems: 1 + + clock-names: + const: se + + interconnects: + maxItems: 2 + + interconnect-names: + items: + - const: qup-core + - const: qup-config + + interrupts: + minItems: 1 + items: + - description: UART core irq + - description: Wakeup irq (RX GPIO) + + operating-points-v2: true + + pinctrl-0: true + pinctrl-1: true + + pinctrl-names: + minItems: 1 + items: + - const: default + - const: sleep + + power-domains: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - clocks + - clock-names + - interrupts + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,gcc-sc7180.h> + #include <dt-bindings/interconnect/qcom,sc7180.h> + + serial@a88000 { + compatible = "qcom,geni-uart"; + reg = <0xa88000 0x7000>; + interrupts = <GIC_SPI 355 IRQ_TYPE_LEVEL_HIGH>; + clock-names = "se"; + clocks = <&gcc GCC_QUPV3_WRAP0_S0_CLK>; + pinctrl-0 = <&qup_uart0_default>; + pinctrl-names = "default"; + interconnects = <&qup_virt MASTER_QUP_CORE_0 0 &qup_virt SLAVE_QUP_CORE_0 0>, + <&gem_noc MASTER_APPSS_PROC 0 &config_noc SLAVE_QUP_0 0>; + interconnect-names = "qup-core", "qup-config"; + }; +... diff --git a/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml b/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml index e98ec48fee46..b25aca733b72 100644 --- a/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml @@ -9,12 +9,16 @@ title: Renesas EMMA Mobile UART Interface maintainers: - Magnus Damm <magnus.damm@gmail.com> -allOf: - - $ref: serial.yaml# - properties: compatible: - const: renesas,em-uart + oneOf: + - items: + - enum: + - renesas,r9a09g011-uart # RZ/V2M + - const: renesas,em-uart # generic EMMA Mobile compatible UART + + - items: + - const: renesas,em-uart # generic EMMA Mobile compatible UART reg: maxItems: 1 @@ -23,10 +27,31 @@ properties: maxItems: 1 clocks: - maxItems: 1 + minItems: 1 + items: + - description: UART functional clock + - description: Internal clock to access the registers clock-names: - const: sclk + minItems: 1 + items: + - const: sclk + - const: pclk + +allOf: + - $ref: serial.yaml# + + - if: + properties: + compatible: + contains: + const: renesas,r9a09g011-uart + then: + properties: + clocks: + minItems: 2 + clock-names: + minItems: 2 required: - compatible diff --git a/Documentation/devicetree/bindings/serial/renesas,hscif.yaml b/Documentation/devicetree/bindings/serial/renesas,hscif.yaml index ee9804cd49bb..87180d95cd4c 100644 --- a/Documentation/devicetree/bindings/serial/renesas,hscif.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,hscif.yaml @@ -51,10 +51,16 @@ properties: - renesas,hscif-r8a77980 # R-Car V3H - renesas,hscif-r8a77990 # R-Car E3 - renesas,hscif-r8a77995 # R-Car D3 - - renesas,hscif-r8a779a0 # R-Car V3U - const: renesas,rcar-gen3-hscif # R-Car Gen3 and RZ/G2 - const: renesas,hscif # generic HSCIF compatible UART + - items: + - enum: + - renesas,hscif-r8a779a0 # R-Car V3U + - renesas,hscif-r8a779g0 # R-Car V4H + - const: renesas,rcar-gen4-hscif # R-Car Gen4 + - const: renesas,hscif # generic HSCIF compatible UART + reg: maxItems: 1 @@ -113,6 +119,7 @@ if: enum: - renesas,rcar-gen2-hscif - renesas,rcar-gen3-hscif + - renesas,rcar-gen4-hscif then: required: - resets diff --git a/Documentation/devicetree/bindings/serial/renesas,scif.yaml b/Documentation/devicetree/bindings/serial/renesas,scif.yaml index 5d37f8f189fb..90fe45265fbc 100644 --- a/Documentation/devicetree/bindings/serial/renesas,scif.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,scif.yaml @@ -60,12 +60,12 @@ properties: - renesas,scif-r8a77980 # R-Car V3H - renesas,scif-r8a77990 # R-Car E3 - renesas,scif-r8a77995 # R-Car D3 - - renesas,scif-r8a779a0 # R-Car V3U - const: renesas,rcar-gen3-scif # R-Car Gen3 and RZ/G2 - const: renesas,scif # generic SCIF compatible UART - items: - enum: + - renesas,scif-r8a779a0 # R-Car V3U - renesas,scif-r8a779f0 # R-Car S4-8 - const: renesas,rcar-gen4-scif # R-Car Gen4 - const: renesas,scif # generic SCIF compatible UART diff --git a/Documentation/devicetree/bindings/serial/rs485.yaml b/Documentation/devicetree/bindings/serial/rs485.yaml index 0c9fa694f85c..f2c9c9fe6aa7 100644 --- a/Documentation/devicetree/bindings/serial/rs485.yaml +++ b/Documentation/devicetree/bindings/serial/rs485.yaml @@ -33,6 +33,11 @@ properties: description: drive RTS low when sending (default is high). $ref: /schemas/types.yaml#/definitions/flag + rs485-rx-active-high: + description: Polarity of receiver enable signal (when separate from RTS). + True indicates active high (default is low). + $ref: /schemas/types.yaml#/definitions/flag + linux,rs485-enabled-at-boot-time: description: enables the rs485 feature at boot time. It can be disabled later with proper ioctl. diff --git a/Documentation/devicetree/bindings/serial/socionext,uniphier-uart.yaml b/Documentation/devicetree/bindings/serial/socionext,uniphier-uart.yaml index d490c7c4b967..3d01cc355778 100644 --- a/Documentation/devicetree/bindings/serial/socionext,uniphier-uart.yaml +++ b/Documentation/devicetree/bindings/serial/socionext,uniphier-uart.yaml @@ -20,7 +20,10 @@ properties: maxItems: 1 clocks: - minItems: 1 + maxItems: 1 + + resets: + maxItems: 1 auto-flow-control: description: enable automatic flow control support. diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index a7b0223e2886..d76a60d95b58 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -101,6 +101,7 @@ available subsections can be seen below. surface_aggregator/index switchtec sync_file + tty/index vfio-mediated-device vfio vfio-pci-device-specific-driver-acceptance diff --git a/Documentation/driver-api/serial/driver.rst b/Documentation/driver-api/serial/driver.rst index 06ec04ba086f..7ef83fd3917b 100644 --- a/Documentation/driver-api/serial/driver.rst +++ b/Documentation/driver-api/serial/driver.rst @@ -311,7 +311,7 @@ hardware. This call must not sleep set_ldisc(port,termios) - Notifier for discipline change. See Documentation/tty/tty_ldisc.rst. + Notifier for discipline change. See ../tty/tty_ldisc.rst. Locking: caller holds tty_port->mutex diff --git a/Documentation/driver-api/serial/index.rst b/Documentation/driver-api/serial/index.rst index 7eb21a695fc3..03a55b987a1d 100644 --- a/Documentation/driver-api/serial/index.rst +++ b/Documentation/driver-api/serial/index.rst @@ -16,8 +16,6 @@ Serial drivers .. toctree:: :maxdepth: 1 - moxa-smartio - n_gsm serial-iso7816 serial-rs485 diff --git a/Documentation/driver-api/serial/n_gsm.rst b/Documentation/driver-api/serial/n_gsm.rst deleted file mode 100644 index 49956509ad73..000000000000 --- a/Documentation/driver-api/serial/n_gsm.rst +++ /dev/null @@ -1,159 +0,0 @@ -============================== -GSM 0710 tty multiplexor HOWTO -============================== - -This line discipline implements the GSM 07.10 multiplexing protocol -detailed in the following 3GPP document: - - https://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip - -This document give some hints on how to use this driver with GPRS and 3G -modems connected to a physical serial port. - -How to use it -------------- -1. config initiator -^^^^^^^^^^^^^^^^^^^^^ - -1.1 initialize the modem in 0710 mux mode (usually AT+CMUX= command) through - its serial port. Depending on the modem used, you can pass more or less - parameters to this command. - -1.2 switch the serial line to using the n_gsm line discipline by using - TIOCSETD ioctl. - -1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl. - -1.4 obtain base gsmtty number for the used serial port. - -Major parts of the initialization program : -(a good starting point is util-linux-ng/sys-utils/ldattach.c):: - - #include <stdio.h> - #include <stdint.h> - #include <linux/gsmmux.h> - #include <linux/tty.h> - #define DEFAULT_SPEED B115200 - #define SERIAL_PORT /dev/ttyS0 - - int ldisc = N_GSM0710; - struct gsm_config c; - struct termios configuration; - uint32_t first; - - /* open the serial port connected to the modem */ - fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY); - - /* configure the serial port : speed, flow control ... */ - - /* send the AT commands to switch the modem to CMUX mode - and check that it's successful (should return OK) */ - write(fd, "AT+CMUX=0\r", 10); - - /* experience showed that some modems need some time before - being able to answer to the first MUX packet so a delay - may be needed here in some case */ - sleep(3); - - /* use n_gsm line discipline */ - ioctl(fd, TIOCSETD, &ldisc); - - /* get n_gsm configuration */ - ioctl(fd, GSMIOC_GETCONF, &c); - /* we are initiator and need encoding 0 (basic) */ - c.initiator = 1; - c.encapsulation = 0; - /* our modem defaults to a maximum size of 127 bytes */ - c.mru = 127; - c.mtu = 127; - /* set the new configuration */ - ioctl(fd, GSMIOC_SETCONF, &c); - /* get first gsmtty device node */ - ioctl(fd, GSMIOC_GETFIRST, &first); - printf("first muxed line: /dev/gsmtty%i\n", first); - - /* and wait for ever to keep the line discipline enabled */ - daemon(0,0); - pause(); - -1.5 use these devices as plain serial ports. - - for example, it's possible: - - - and to use gnokii to send / receive SMS on ttygsm1 - - to use ppp to establish a datalink on ttygsm2 - -1.6 first close all virtual ports before closing the physical port. - - Note that after closing the physical port the modem is still in multiplexing - mode. This may prevent a successful re-opening of the port later. To avoid - this situation either reset the modem if your hardware allows that or send - a disconnect command frame manually before initializing the multiplexing mode - for the second time. The byte sequence for the disconnect command frame is:: - - 0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9. - -2. config requester -^^^^^^^^^^^^^^^^^^^^^ - -2.1 receive string "AT+CMUX= command" through its serial port,initialize - mux mode config - -2.2 switch the serial line to using the n_gsm line discipline by using - TIOCSETD ioctl. - -2.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl. - -2.4 obtain base gsmtty number for the used serial port:: - - #include <stdio.h> - #include <stdint.h> - #include <linux/gsmmux.h> - #include <linux/tty.h> - #define DEFAULT_SPEED B115200 - #define SERIAL_PORT /dev/ttyS0 - - int ldisc = N_GSM0710; - struct gsm_config c; - struct termios configuration; - uint32_t first; - - /* open the serial port */ - fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY); - - /* configure the serial port : speed, flow control ... */ - - /* get serial data and check "AT+CMUX=command" parameter ... */ - - /* use n_gsm line discipline */ - ioctl(fd, TIOCSETD, &ldisc); - - /* get n_gsm configuration */ - ioctl(fd, GSMIOC_GETCONF, &c); - /* we are requester and need encoding 0 (basic) */ - c.initiator = 0; - c.encapsulation = 0; - /* our modem defaults to a maximum size of 127 bytes */ - c.mru = 127; - c.mtu = 127; - /* set the new configuration */ - ioctl(fd, GSMIOC_SETCONF, &c); - /* get first gsmtty device node */ - ioctl(fd, GSMIOC_GETFIRST, &first); - printf("first muxed line: /dev/gsmtty%i\n", first); - - /* and wait for ever to keep the line discipline enabled */ - daemon(0,0); - pause(); - -Additional Documentation ------------------------- -More practical details on the protocol and how it's supported by industrial -modems can be found in the following documents : - -- http://www.telit.com/module/infopool/download.php?id=616 -- http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf -- http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx -- http://wm.sim.com/sim/News/photo/2010721161442.pdf - -11-03-08 - Eric Bénard - <eric@eukrea.com> diff --git a/Documentation/tty/index.rst b/Documentation/driver-api/tty/index.rst index 21ea0cb21e55..2d32606a4278 100644 --- a/Documentation/tty/index.rst +++ b/Documentation/driver-api/tty/index.rst @@ -36,18 +36,16 @@ In-detail description of the named TTY structures is in separate documents: tty_struct tty_ldisc tty_buffer - n_tty tty_internals Writing TTY Driver ================== Before one starts writing a TTY driver, they must consider -:doc:`Serial <../driver-api/serial/driver>` and :doc:`USB Serial -<../usb/usb-serial>` layers -first. Drivers for serial devices can often use one of these specific layers to -implement a serial driver. Only special devices should be handled directly by -the TTY Layer. If you are about to write such a driver, read on. +:doc:`Serial <../serial/driver>` and :doc:`USB Serial <../../usb/usb-serial>` +layers first. Drivers for serial devices can often use one of these specific +layers to implement a serial driver. Only special devices should be handled +directly by the TTY Layer. If you are about to write such a driver, read on. A *typical* sequence a TTY driver performs is as follows: @@ -61,3 +59,15 @@ A *typical* sequence a TTY driver performs is as follows: Steps regarding driver, i.e. 1., 3., and 5. are described in detail in :doc:`tty_driver`. For the other two (devices handling), look into :doc:`tty_port`. + +Other Documentation +=================== + +Miscellaneous documentation can be further found in these documents: + +.. toctree:: + :maxdepth: 2 + + moxa-smartio + n_gsm + n_tty diff --git a/Documentation/driver-api/serial/moxa-smartio.rst b/Documentation/driver-api/tty/moxa-smartio.rst index af25bc5cc3e6..af25bc5cc3e6 100644 --- a/Documentation/driver-api/serial/moxa-smartio.rst +++ b/Documentation/driver-api/tty/moxa-smartio.rst diff --git a/Documentation/driver-api/tty/n_gsm.rst b/Documentation/driver-api/tty/n_gsm.rst new file mode 100644 index 000000000000..35d7381515b0 --- /dev/null +++ b/Documentation/driver-api/tty/n_gsm.rst @@ -0,0 +1,153 @@ +============================== +GSM 0710 tty multiplexor HOWTO +============================== + +.. contents:: :local: + +This line discipline implements the GSM 07.10 multiplexing protocol +detailed in the following 3GPP document: + + https://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip + +This document give some hints on how to use this driver with GPRS and 3G +modems connected to a physical serial port. + +How to use it +============= + +Config Initiator +---------------- + +#. Initialize the modem in 0710 mux mode (usually ``AT+CMUX=`` command) through + its serial port. Depending on the modem used, you can pass more or less + parameters to this command. + +#. Switch the serial line to using the n_gsm line discipline by using + ``TIOCSETD`` ioctl. + +#. Configure the mux using ``GSMIOC_GETCONF``/``GSMIOC_SETCONF`` ioctl. + +#. Obtain base gsmtty number for the used serial port. + + Major parts of the initialization program + (a good starting point is util-linux-ng/sys-utils/ldattach.c):: + + #include <stdio.h> + #include <stdint.h> + #include <linux/gsmmux.h> + #include <linux/tty.h> + + #define DEFAULT_SPEED B115200 + #define SERIAL_PORT /dev/ttyS0 + + int ldisc = N_GSM0710; + struct gsm_config c; + struct termios configuration; + uint32_t first; + + /* open the serial port connected to the modem */ + fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY); + + /* configure the serial port : speed, flow control ... */ + + /* send the AT commands to switch the modem to CMUX mode + and check that it's successful (should return OK) */ + write(fd, "AT+CMUX=0\r", 10); + + /* experience showed that some modems need some time before + being able to answer to the first MUX packet so a delay + may be needed here in some case */ + sleep(3); + + /* use n_gsm line discipline */ + ioctl(fd, TIOCSETD, &ldisc); + + /* get n_gsm configuration */ + ioctl(fd, GSMIOC_GETCONF, &c); + /* we are initiator and need encoding 0 (basic) */ + c.initiator = 1; + c.encapsulation = 0; + /* our modem defaults to a maximum size of 127 bytes */ + c.mru = 127; + c.mtu = 127; + /* set the new configuration */ + ioctl(fd, GSMIOC_SETCONF, &c); + /* get first gsmtty device node */ + ioctl(fd, GSMIOC_GETFIRST, &first); + printf("first muxed line: /dev/gsmtty%i\n", first); + + /* and wait for ever to keep the line discipline enabled */ + daemon(0,0); + pause(); + +#. Use these devices as plain serial ports. + + For example, it's possible: + + - to use *gnokii* to send / receive SMS on ``ttygsm1`` + - to use *ppp* to establish a datalink on ``ttygsm2`` + +#. First close all virtual ports before closing the physical port. + + Note that after closing the physical port the modem is still in multiplexing + mode. This may prevent a successful re-opening of the port later. To avoid + this situation either reset the modem if your hardware allows that or send + a disconnect command frame manually before initializing the multiplexing mode + for the second time. The byte sequence for the disconnect command frame is:: + + 0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9 + +Config Requester +---------------- + +#. Receive ``AT+CMUX=`` command through its serial port, initialize mux mode + config. + +#. Switch the serial line to using the *n_gsm* line discipline by using + ``TIOCSETD`` ioctl. + +#. Configure the mux using ``GSMIOC_GETCONF``/``GSMIOC_SETCONF`` ioctl. + +#. Obtain base gsmtty number for the used serial port:: + + #include <stdio.h> + #include <stdint.h> + #include <linux/gsmmux.h> + #include <linux/tty.h> + #define DEFAULT_SPEED B115200 + #define SERIAL_PORT /dev/ttyS0 + + int ldisc = N_GSM0710; + struct gsm_config c; + struct termios configuration; + uint32_t first; + + /* open the serial port */ + fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY); + + /* configure the serial port : speed, flow control ... */ + + /* get serial data and check "AT+CMUX=command" parameter ... */ + + /* use n_gsm line discipline */ + ioctl(fd, TIOCSETD, &ldisc); + + /* get n_gsm configuration */ + ioctl(fd, GSMIOC_GETCONF, &c); + /* we are requester and need encoding 0 (basic) */ + c.initiator = 0; + c.encapsulation = 0; + /* our modem defaults to a maximum size of 127 bytes */ + c.mru = 127; + c.mtu = 127; + /* set the new configuration */ + ioctl(fd, GSMIOC_SETCONF, &c); + /* get first gsmtty device node */ + ioctl(fd, GSMIOC_GETFIRST, &first); + printf("first muxed line: /dev/gsmtty%i\n", first); + + /* and wait for ever to keep the line discipline enabled */ + daemon(0,0); + pause(); + +11-03-08 - Eric Bénard - <eric@eukrea.com> diff --git a/Documentation/tty/n_tty.rst b/Documentation/driver-api/tty/n_tty.rst index 15b70faee72d..15b70faee72d 100644 --- a/Documentation/tty/n_tty.rst +++ b/Documentation/driver-api/tty/n_tty.rst diff --git a/Documentation/tty/tty_buffer.rst b/Documentation/driver-api/tty/tty_buffer.rst index a39d4781e0d2..a39d4781e0d2 100644 --- a/Documentation/tty/tty_buffer.rst +++ b/Documentation/driver-api/tty/tty_buffer.rst diff --git a/Documentation/tty/tty_driver.rst b/Documentation/driver-api/tty/tty_driver.rst index cc529f863406..cc529f863406 100644 --- a/Documentation/tty/tty_driver.rst +++ b/Documentation/driver-api/tty/tty_driver.rst diff --git a/Documentation/tty/tty_internals.rst b/Documentation/driver-api/tty/tty_internals.rst index d0d415820300..d0d415820300 100644 --- a/Documentation/tty/tty_internals.rst +++ b/Documentation/driver-api/tty/tty_internals.rst diff --git a/Documentation/tty/tty_ldisc.rst b/Documentation/driver-api/tty/tty_ldisc.rst index 5144751be804..5144751be804 100644 --- a/Documentation/tty/tty_ldisc.rst +++ b/Documentation/driver-api/tty/tty_ldisc.rst diff --git a/Documentation/tty/tty_port.rst b/Documentation/driver-api/tty/tty_port.rst index 5cb90e954fcf..5cb90e954fcf 100644 --- a/Documentation/tty/tty_port.rst +++ b/Documentation/driver-api/tty/tty_port.rst diff --git a/Documentation/tty/tty_struct.rst b/Documentation/driver-api/tty/tty_struct.rst index c72f5a4293b2..c72f5a4293b2 100644 --- a/Documentation/tty/tty_struct.rst +++ b/Documentation/driver-api/tty/tty_struct.rst diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 6b62425ef9cd..dbb03022b127 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -389,6 +389,31 @@ descriptors once the device is released. See Documentation/firmware-guide/acpi/gpio-properties.rst for more information about the _DSD binding related to GPIOs. +RS-485 support +============== + +ACPI _DSD (Device Specific Data) can be used to describe RS-485 capability +of UART. + +For example:: + + Device (DEV) + { + ... + + // ACPI 5.1 _DSD used for RS-485 capabilities + Name (_DSD, Package () + { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () + { + Package () {"rs485-rts-active-low", Zero}, + Package () {"rs485-rx-active-high", Zero}, + Package () {"rs485-rx-during-tx", Zero}, + } + }) + ... + MFD devices =========== diff --git a/Documentation/index.rst b/Documentation/index.rst index 062cf88c2216..67036a05b771 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -136,7 +136,6 @@ needed). misc-devices/index scheduler/index mhi/index - tty/index peci/index Architecture-agnostic documentation diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index 30ac58f81901..756be15a49a4 100644 --- a/Documentation/misc-devices/index.rst +++ b/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 diff --git a/Documentation/misc-devices/oxsemi-tornado.rst b/Documentation/misc-devices/oxsemi-tornado.rst new file mode 100644 index 000000000000..b33351bef6cf --- /dev/null +++ b/Documentation/misc-devices/oxsemi-tornado.rst @@ -0,0 +1,131 @@ +.. 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 [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 +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 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. + +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. + +Maciej W. Rozycki <macro@orcam.me.uk> + +.. [OX200] "OXPCIe200 PCI Express Multi-Port Bridge", Oxford Semiconductor, + Inc., DS-0045, 10 Nov 2008, Section "950 Mode", pp. 64-65 + +.. [OX952] "OXPCIe952 PCI Express Bridge to Dual Serial & Parallel Port", + Oxford Semiconductor, Inc., DS-0046, Mar 06 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 + +.. [OX958] "OXPCIe958 PCI Express Bridge to Octal Serial Port", Oxford + Semiconductor, Inc., DS-0048, Feb 08, Section "950 Mode", p. 20 |