Difference between revisions of "Serial TTY overview"

[quality revision] [checked revision]
m
m
 

SUMMARY
This article gives information about the Linux® TTY framework. It explains how to activate the UART interface, and how to access it from user and kernel spaces.

1 Framework Purposepurpose[edit]

The TTY subsytem controls the communication between UART devices and the programs using these devices.
The TTY subsystem is responsible for:

  • controlling the physical flow of data on asynchronous lines (including the transmission speed, character size, and line availability)
  • interpreting the data by recognizing special characters and adapting to national languages
  • controlling jobs and terminal access by using the concept of controlling terminal


The synchronous mode of STM32 USART peripheral is not supported by the TTY subsystem.
A controlling terminal manages the input and output operations of a group of processes. The TTY special file (ttyX filesystem entry) supports the controlling terminal interface.
To perform its tasks, the TTY subsystem is composed of modules, also called disciplines. A module is a set of processing rules that govern the interface for communication between the computer and an asynchronous device. Modules can be added and removed dynamically for each TTY.

The TTY subsystem supports three main types of modules:

  • TTY drivers: TTY drivers, or hardware disciplines, directly control the hardware (TTY devices) or pseudo-hardware (PTY devices). They perform the actual input and output to the adapter by providing services to the modules above it. The services are flow control and special semantics when a port is being opened.
  • Line disciplines: Line disciplines provide editing, job control, and special character interpretation. They perform all transformations that occur on the inbound and outbound data streams. Line disciplines also perform most of the error handling and status monitoring for the TTY drivers.
  • Converter modules: Converter modules, or mapping disciplines, translate, or map, input and output characters.


Since kernel 4.12 version, the serial device bus (also called Serdev) has been introduced in TTY framework to improve the interface offered to devices attached to a serial port (ex: Bluetooth, NFC, FM Radio and GPS devices), as the line disciplines "drivers" have some known limitations:

  • devices are encoded in user space rather than in firmware (Device Tree of ACPI)
  • "driver" are not kernel drivers but user space daemons
  • Associated ressources (GPIOs and interrupts, regulators, clocks, audio interface) are not described in kernel space, wich impacts power management
  • "drivers" are registered when a port is opened

Serdev allows to attach a device on UART without known line disciplines limitations:

  • New bus type: serial
  • Serdev controllers
  • Serdev devices (clients or slaves)
  • Serdev TTY-port controller
    • Only in-kernel controller implementation
    • Registered by TTY driver when client is defined
    • clients are described by firmware (Device Tree or ACPI)


The USART low-level driver provided by STMicroelectronics, (drivers/tty/serial/stm32-usart.c) supports RS-232 standard (for serial communication transmission of data), and RS-485 standard (for modbus protocol applications as example).
The Synchronous mode of USART is not supported by Linux® low-level driver .

TTY framework is used to access the serial device in following use cases:

  • tty virtual console during Linux boot sequence
  • pts pseudo-terminal to access over a terminal
  • user space application

2 System overview[edit]

How to use TTY from an application How to use TTY from a user terminal Example: Bluetooth_overview termios tty char driver Line discipline serdev framework tty framework serial_core framework stm32-usart driver USART internal peripheral
Serial TTY architecture overview Template:WarningImageMapOverlay


Note: during boot, while a serial device is probed, serial framework instantiates an associated tty terminal as a virtual device. Then the system sees this tty virtual device as a child of the associated serial device.

2.1 Components description[edit]

From client application to hardware

  • Application: customer application to read/write data from the peripheral connected on the serial port.
  • TTY tools: tools provided by Linux community, such as stty, ldattach, inputattach, tty, ttys, agetty, mingetty, kermit and minicom.
  • Termios: API which offers an interface to develop an application using serial drivers.
  • USART driver: stm32-usart low-level serial driver for all stm32 family devices.
  • STM32 USART: STM32 frontend IP connected to the external devices through a serial port

2.2 APIs description[edit]

The TTY provides only character device interface (named /dev/ttyX) to user space. The main API for user space TTY client applications is provided by the portable POSIX terminal interface termios, which relies on /dev/ttyX interface for TTY link configuration.

The termios API [1] is a user land API, and its functions describe a general terminal interface that is provided to control asynchronous communications ports.

The POSIX termios API abstracts the low-level details of the hardware, and provides a simple yet complete programming interface that can be used for advanced projects. It is a wrapper on character device API [2] ioctl operations.

Note: If a serial interface is needed at kernel level (to control an external device through U(S)ART by a kernel driver for example), customer can use a line discipline or a Serdev client.

  • The line discipline will be responsible for:
    • creating this new kernel API
    • routing data flow between serial core and new kernel API
  • The Serdev provides an interface to kernel drivers.
    • This interface resembles line-discipline operations: open and close, terminal settings, write, modem control, read (callback), and write wakeup (callback)

3 Configuration[edit]

This section describes how to configure a device on a serial port.

3.1 Kernel Configuration[edit]

Serial driver, serial framework, and TTY framework are activated by default in ST deliveries. Nevertheless, if a specific configuration is needed, this section indicates how IIO can be activated/deactivated in the kernel.

Activate the device TTY in kernel configuration with Linux Menuconfig tool.

For TTY, select:

Device Drivers  --->
   Character devices  --->
     [*]   Enable TTY                           

Allows to remove TTY support which can save space, and blocks features that require TTY from inclusion in the kernel.
TTY is required for any text terminals or serial port communication. Most users should leave this enabled.

For STM32 serial driver, select:

Device Drivers  --->
   Character devices  --->
      Serial drivers  --->
     <*> STMicroelectronics STM32 serial port support
     [*]   Support for console on STM32

This driver is for the on-chip serial controller on STMicroelectronics STM32 MCUs. 
USART supports Rx & Tx functionality. It supports all industry standard baud rates.

3.2 Device tree configuration[edit]

UART configuration thanks to device tree is described in the dedicated article serial/Serial TTY device tree configuration.

4 How to use TTY[edit]

This section describes how to use TTY from user land (from a terminal and a or an application) and from kernel space, based on the two following use cases:

  • How to configure the serial port by using the termios structure
  • How to send/receive data

The termios structure allows to configure communication ports with many settings, such as :

  • Baud rate
  • Character size mask
  • Parity bit enabling
  • Parity and framing errors detection settings
  • Start/stop input and output control
  • RTS/CTS (hardware) flow control
  • ...

As the USART internal peripheral supports 7, 8 and 9 word length data, the following termios character size and parity bit configurations are supported:

  • CS6 with parity bit
  • CS7 with or without parity bit
  • CS8 with or without parity bit

Tips to use TTY:

5 How to trace and debug the framework[edit]

5.1 How to monitor[edit]

As Debugfs doesn't propose any information about serial or TTY frameworks, the way to monitor Serial and TTY frameworks is to use the linux kernel log method (based on printk) described in Dmesg_and_Linux_kernel_log article.

5.2 How to trace[edit]

5.2.1 Kernel boot log[edit]

The following extract of kernel boot log shows a serial driver properly probed:

[    0.793340] STM32 USART driver initialized
[    0.798779] 4000f000.serial: ttySTM1 at MMIO 0x4000f000 (irq = 25, base_baud = 4000000) is a stm32-usart
[    0.808875] stm32-usart 4000f000.serial: interrupt mode used for rx (no dma)
[    0.816106] stm32-usart 4000f000.serial: interrupt mode used for tx (no dma)
[    0.824253] 40010000.serial: ttySTM0 at MMIO 0x40010000 (irq = 27, base_baud = 4000000) is a stm32-usart
[    0.833796] console [ttySTM0] enabled
[    0.833796] console [ttySTM0] enabled
[    0.840862] bootconsole [earlycon0] disabled
[    0.840862] bootconsole [earlycon0] disabled
[    0.850132] stm32-usart 40010000.serial: interrupt mode used for rx (no dma)
[    0.855755] stm32-usart 40010000.serial: interrupt mode used for tx (no dma)

5.2.2 dmesg output information[edit]

The system log shows that the UART devices and associated TTY terminals registered during the probe.

Board $> dmesg | grep ttySTM*
[    0.000000] Kernel command line: root=/dev/mmcblk0p5 rootwait rw earlyprintk console=ttySTM1,115200
# ttySTM1 terminal is associated with usart3 (4000f000.serial) # 
[    0.798779] 4000f000.serial: ttySTM1 at MMIO 0x4000f000 (irq = 25, base_baud = 4000000) is a stm32-usart
# ttySTM0 terminal is associated with uart4 (40010000.serial) for console#
[    0.824253] 40010000.serial: ttySTM0 at MMIO 0x40010000 (irq = 27, base_baud = 4000000) is a stm32-usart      
# ttySTM0 terminal is activated by default for console #
[    0.833796] console [ttySTM0] enabled

5.2.3 Dynamic trace[edit]

A detailed dynamic trace is available in How to use the kernel dynamic debug

 Board $> echo  "file drivers/tty/* +p" > /sys/kernel/debug/dynamic_debug/control

This command enables all the traces related to the TTY core and drivers at runtime.
A finer selection can be made by choosing only the files to trace.

Info.png Reminder: loglevel needs to be increased to 8 by using either boot arguments or the dmesg -n 8 command through the console

5.3 How to debug[edit]

While a TTY serial port is instantiated, TTY core exports different files through devfs, sysfs and procfs.

5.3.1 devfs[edit]

  • The repository /dev contains all the probed TTY serial devices.
Board $> ls /dev/ttySTM*
# ttySTM1 and ttySTM0 terminals are probed #
/dev/ttySTM1  /dev/ttySTM0

5.3.2 sysfs[edit]

  • /sys/class/tty/ lists all TTY devices which ttySx correspond to serial port devices.
Board $> ls /sys/class/tty/*/device/driver
/sys/class/tty/ttySTM1/device/driver -> ../../../../bus/platform/drivers/stm32-usart
/sys/class/tty/ttySTM0/device/driver -> ../../../../bus/platform/drivers/stm32-usart

  • /sys/devices/platform/soc/ lists all the usart devices probed
Board $> ls -d /sys/devices/platform/soc/*.serial
# Serial devices 4000f000.serial (usart3) and 40010000.serial (uart4) are probed #
/sys/devices/platform/soc/4000f000.serial  /sys/devices/platform/soc/40010000.serial

  • /sys/devices/platform/soc/device.serial/tty lists the TTY terminal associated to a serial device
Board $> ls /sys/devices/platform/soc/4000f000.serial/tty/      
# ttySTM1 is associated to serial device 4000f000.serial (usart3)  #
ttySTM1

5.3.3 procfs[edit]

  • The repository /proc/device-tree lists all the usart devices declared in the device-tree, including the disabled ones.
Board $> ls -d /proc/device-tree/soc/serial@*
/proc/device-tree/soc/serial@4000e000  /proc/device-tree/soc/serial@40010000  /proc/device-
tree/soc/serial@40018000  /proc/device-tree/soc/serial@44003000
/proc/device-tree/soc/serial@4000f000  /proc/device-tree/soc/serial@40011000  /proc/device-
tree/soc/serial@40019000  /proc/device-tree/soc/serial@5c000000

Then for each device listed, device-tree properties are available.

Board $> ls /proc/device-tree/soc/serial@40010000/
clock-names  compatible       interrupts-extended  name     pinctrl-0  pinctrl-names  reg     wakeup-source
clocks       interrupt-names  linux,phandle        phandle  pinctrl-1  power-domains  status
As an example, the status entry provide the status of the device in the device tree node.
Board $> cat /proc/device-tree/soc/serial@40010000/status
# status of device serial@40010000 (uart4) is set to "okay" in the device tree #
okay


  • The file /proc/interrupts lists all active interrups. To be listed, the serial interrupts need to be activated by opening a port on the UART instancesthe interrupts for active serial ports.
Board $> cat /proc/interrupts | grep serial
26:          0          0     GIC-0  71 Level     4000f000.serial
27:          0          0  stm32-exti-h  28 Edge      4000f000.serial
28:      13509          0     GIC-0  84 Level     40010000.serial
29:          0          0  stm32-exti-h  30 Edge      40010000.serial


  • The file /proc/tty/driver/stm32-usart lists serial core counters and modem information for each serial instance.
Driver information:
  • serial driver name
  • serial device start address
  • irq number
Counters:
  • tx: Number of bytes sent
  • rx: Number of bytes received
  • fe: Number of framing errors received
  • pe: Number of parity errors received
  • brk: Number of break signals received
  • oe: Number of overrun errors received
  • bo: Number of framework buffer overrun errors received
Modem information:
  • RTS: Request To Send
  • CTS: Clear To Send
  • DTR: Data Terminal Ready
  • DSR: Data Set Ready
  • CD: Carrier Detect
  • RI: Ring Indicator
Board $> cat /proc/tty/driver/stm32-usart 
serinfo:1.0 driver revision:
0: uart:stm32-usart mmio:0x40010000 irq:29 tx:22722 rx:2276 RTS|CTS|DTR|DSR|CD
1: uart:stm32-usart mmio:0x4000F000 irq:27 tx:0 rx:1149 fe:121 oe:2 pe:296 brk:3 RTS|CTS|DTR|DSR|CD
3: uart:stm32-usart mmio:0x4000E000 irq:25 tx:0 rx:0 CTS|DSR|CD

6 How to go further[edit]

The Linux community provides many detailed documentation about Linux serial/TTY. Please find below a selection of the most relevant ones:

  • Linux Serial-HOWTO [3] describes how to set up serial ports from both hardware and software perspectives.
  • Serial Programming Guide for POSIX Compliant Operating Systems [4] , by Michael Sweet.


More information can be found in the following web articles in order to get a good understanding of Linux TTY framework:

  • TTY Subsystem [5], by IBM
  • The TTY demystified [6], by Linus Akesson
  • Serial drivers training [7], by Bootlin
  • Linux Serial drivers [8], by Alessandro Rubini
  • Serial Device Bus [9], by Johan Hovold

7 References[edit]

  1. termios API, Linux Programmer's Manual termios API Documentation (user land API with serial devices)
  2. Character device API overview, Accessing hardware from userspace training, Bootlin documentation
  3. Linux Serial-HOWTO, tdlp.org training document, describes how to set up serial ports from both hardware and software perspectives
  4. Serial Programming Guide for POSIX Compliant Operating Systems, by Michael Sweet, training document
  5. TTY Subsystem, by IBM
  6. The TTY demystified TTY subsystem presentation article, by Linus Akesson
  7. Linux serial drivers training Linux Serial Drivers training, by Bootlin
  8. Linux Serial Drivers Serial drivers article describing data flows, by Alessandro Rubini
  9. The Serial Device Bus Serdev framework presentation, by Johan Hovold




<noinclude>

{{ArticleBasedOnModel|[[Framework overview article model]]}}
{{ArticleMainWriter|ErwanLR}}
{{ArticleApprovedVersion| ErwanLR | Reviewers : FabriceG, AlexandreT, NathalieS | No previous approved version |  Last TW review done by BrunoB- 31Aug'18 - 8368 | 03Sep'18}}

[[Category:Serial TTY|1]]
</noinclude>

'''SUMMARY'''<br>
This article gives information about the Linux® TTY framework. It explains how to activate the '''UART''' interface, and how to access it from user and kernel spaces.<br />


==Framework Purposepurpose==

The '''TTY''' subsytem controls the communication between UART devices and the programs using these devices. <br/>

The TTY subsystem is responsible for:
* controlling the physical flow of data on asynchronous lines (including the transmission speed, character size, and line availability)
* interpreting the data by recognizing special characters and adapting to national languages
* controlling jobs and terminal access by using the concept of controlling terminal<br/>

'''The synchronous mode of STM32 USART peripheral is not supported by the TTY subsystem'''.<br/>

A controlling terminal manages the input and output operations of a group of processes. The TTY special file (ttyX filesystem entry) supports the controlling terminal interface. <br/>

To perform its tasks, the TTY subsystem is composed of modules, also called disciplines. A module is a set of processing rules that govern the interface for communication between the computer and an asynchronous device. Modules can be added and removed dynamically for each TTY.

The TTY subsystem supports three main types of modules:
* TTY drivers: TTY drivers, or hardware disciplines, directly control the hardware (TTY devices) or pseudo-hardware (PTY devices). They perform the actual input and output to the adapter by providing services to the modules above it. The services are flow control and special semantics when a port is being opened.
* Line disciplines: Line disciplines provide editing, job control, and special character interpretation. They perform all transformations that occur on the inbound and outbound data streams. Line disciplines also perform most of the error handling and status monitoring for the TTY drivers.
* Converter modules: Converter modules, or mapping disciplines, translate, or map, input and output characters.<br/>


Since kernel 4.12 version, the serial device bus (also called Serdev) has been introduced in TTY framework to improve the interface offered to devices attached to a serial port (ex: Bluetooth, NFC, FM Radio and GPS devices), as the line disciplines "drivers" have some known limitations:
* devices are encoded in user space rather than in firmware (Device Tree of ACPI)
* "driver" are not kernel drivers but user space daemons
* Associated ressources (GPIOs and interrupts, regulators, clocks, audio interface) are not described in kernel space, wich impacts power management
* "drivers" are registered when a port is opened

Serdev allows to attach a device on UART without known line disciplines limitations:
* New bus type: serial
* Serdev controllers
* Serdev devices (clients or slaves)
* Serdev TTY-port controller
** Only in-kernel controller implementation
** Registered by TTY driver when client is defined
** clients are described by firmware (Device Tree or ACPI)<br/>


The USART low-level driver provided by STMicroelectronics,  ('''drivers/tty/serial/stm32-usart.c''') supports [https://en.wikipedia.org/wiki/RS-232 RS-232] standard (for serial communication transmission of data), and [https://en.wikipedia.org/wiki/RS-485 RS-485] standard (for [https://en.wikipedia.org/wiki/Modbus modbus] protocol applications as example).<br/>

The Synchronous mode of USART is not supported by Linux<sup>&reg;</sup> low-level driver .<br/>
<br/>

TTY framework is used to access the serial device in following use cases:
* '''tty virtual console''' during Linux boot sequence
* '''pts pseudo-terminal''' to access over a terminal
* '''user space application'''

==System overview==
{{
ImageMap|Image:Serial TTY overview.png{{!}} frame {{!}} center{{!}} Serial TTY architecture overview<br/> {{WarningImageMapOverlay}}rect 261 75 412 116 [[How to use TTY from an application | How to use TTY from an application ]]
rect 452 75 603 116 [[How to use TTY with User Terminal | How to use TTY from a user terminal]]
rect 676 75 828 116 [[Bluetooth_overview#System_overview | Example: Bluetooth_overview ]]
rect 346 123268 130 453 169220 [http://man7.org/linux/man-pages/man3/termios.3.html termios]
rect 350 314 502 355 {{CodeSource | Linux kernel | drivers/tty/tty_io.c | tty char driver}}
rect 350 381 502 423 [[Serial TTY line discipline| Line discipline]]
rect 677 382439 827 423479 {{CodeSource | Linux kernel | drivers/tty/serdev | serdev framework}}
rect 350 439 502 480 {{CodeSource | Linux kernel | drivers/tty | tty framework}}
rect 463 514 615 554 {{CodeSource | Linux kernel | drivers/tty/serial/serial_core.c | serial_core framework}}
rect 463 578 615 620 {{CodeSource | Linux kernel | drivers/tty/serial/stm32-usart.c | stm32-usart driver}}
rect 463 653 615 694 [[USART internal peripheral| USART internal peripheral]]
}}<br/>


Note: during boot, while a serial device is probed, serial framework instantiates an associated tty terminal as a virtual device. Then the system sees this tty virtual device as a child of the associated serial device. <br/>


===Components description===
''From client application to hardware''
* Application: customer application to read/write data from the peripheral connected on the serial port.

* [[TTY tools]]: tools provided by Linux community, such as '''stty''', '''ldattach''', '''inputattach''', '''tty''', '''ttys''', '''agetty''', '''mingetty''', '''kermit''' and '''minicom'''.
* Termios: API which offers an interface to develop an application using serial drivers.

*Client subsystem: kernel subsystem client of '''serdev''' core (Example: [[Bluetooth_overview#System_overview | Bluetooth_overview ]])

* TTY framework: high-level TTY structures management, including {{CodeSource | Linux kernel | drivers/tty/tty_io.c | '''tty character device driver'''}}, {{CodeSource | Linux kernel | drivers/tty | '''TTY core functions'''}}, [[Serial TTY line discipline| '''line discipline''']] and {{CodeSource | Linux kernel | drivers/tty/serdev | '''Serdev core functions'''}} management.

* Serial framework: low-level serial driver management, including the {{CodeSource | Linux kernel | drivers/tty/serial/serial_core.c | '''serial core''' functions}}.

* USART driver: {{CodeSource | Linux kernel | drivers/tty/serial/stm32-usart.c | stm32-usart}} '''low-level serial driver''' for all stm32 family devices.

* [[USART internal peripheral| STM32 USART]]: '''STM32 frontend IP''' connected to the external devices through a serial port

===APIs description===

The TTY provides only '''character device interface''' (named /dev/ttyX) to user space.
The main API for user space TTY client applications is provided by the portable POSIX terminal interface termios, which relies on /dev/ttyX interface for TTY link configuration.<br/>


The '''termios API''' <ref>[http://man7.org/linux/man-pages/man3/termios.3.html termios API], Linux Programmer's Manual termios API Documentation (user land API with serial devices)</ref> is a user land API, and its functions describe a general terminal interface that is provided to control asynchronous communications ports. <br/>


The POSIX termios API abstracts the low-level details of the hardware, and provides a simple yet complete programming interface that can be used for advanced projects. It is a wrapper on '''character device API''' <ref> [httphttps://bootlin.com/doc/legacy/accessing-hardware/accessing-hardware.pdf Character device API overview], ''Accessing hardware from userspace'' training, Bootlin documentation</ref> ioctl operations.<br/>


Note:
If a serial interface is needed at kernel level (to control an external device through U(S)ART by a kernel driver for example), customer can use a [[Serial TTY line discipline|'''line discipline''']] or a '''Serdev''' client. <br/>

* The '''line discipline''' will be responsible for:
** creating this new kernel API
** routing data flow between serial core and new kernel API <br/>

*The '''Serdev''' provides an interface to kernel drivers.
**This interface resembles line-discipline operations: open and close, terminal settings, write, modem control, read (callback), and write wakeup (callback)

==Configuration==

This section describes how to configure a device on a serial port.

===Kernel Configuration===
Serial driver, serial framework, and TTY framework are activated by default in ST deliveries. Nevertheless, if a specific configuration is needed, this section indicates how IIO can be activated/deactivated in the kernel.

Activate the device TTY in kernel configuration with Linux [[Menuconfig or how to configure kernel | Menuconfig ]] tool.

For TTY, select:<pre>

Device Drivers  --->
   Character devices  --->
     [*]   Enable TTY                           

Allows to remove TTY support which can save space, and blocks features that require TTY from inclusion in the kernel.
TTY is required for any text terminals or serial port communication. Most users should leave this enabled.</pre>


For STM32 serial driver, select:<pre>

Device Drivers  --->
   Character devices  --->
      Serial drivers  ---><*> STMicroelectronics STM32 serial port support
     [*]   Support for console on STM32

This driver is for the on-chip serial controller on STMicroelectronics STM32 MCUs. 
USART supports Rx & Tx functionality. It supports all industry standard baud rates.</pre>


===Device tree configuration ===
UART configuration thanks to device tree is described in the dedicated article [[Serial TTY device tree configuration|serial/Serial TTY device tree configuration]].

==How to use TTY==
This section describes how to use TTY from user land (from a terminal and a or an application) and from kernel space, based on the two following use cases:
* How to configure the serial port by using the termios structure* How to send/receive data<br/>



The termios structure allows to configure communication ports with many settings, such as :
* Baud rate
* Character size mask
* Parity bit enabling
* Parity and framing errors detection settings
* Start/stop input and output control
* RTS/CTS (hardware) flow control
* ...

As the [[USART internal peripheral]] supports 7, 8 and 9 word length data, the following termios character size and parity bit configurations are supported:<span id{{=}}"CSIZE_configurations"></span>

* CS6 with parity bit
* CS7 with or without parity bit
* CS8 with or without parity bit
Tips to use TTY:
* '''How to use TTY from user terminal''': TTY usage from a user terminal is described in a dedicated article, [[How to use TTY with User Terminal|How to use TTY from a user terminal]]
* '''How to use TTY from an application''': TTY usage from an application is described in a dedicated article, [[How_to_use_TTY_from_an_application|How to use TTY from an application]]
* '''TTY line discipline''': TTY line discipline is described in a dedicated article,  [[Serial TTY line discipline|Serial/ TTY line discipline]]

==How to trace and debug the framework==

=== How to monitor ===
As Debugfs doesn't propose any information about serial or TTY frameworks, the way to monitor Serial and TTY  frameworks is to use the linux kernel log method (based on printk) described in [[Dmesg_and_Linux_kernel_log]] article.

=== How to trace ===* ==== Kernel boot log ====The following extract of '''kernel boot log''' shows a serial driver properly probed:
<pre>

[    0.793340] STM32 USART driver initialized
[    0.798779] 4000f000.serial: ttySTM1 at MMIO 0x4000f000 (irq = 25, base_baud = 4000000) is a stm32-usart
[    0.808875] stm32-usart 4000f000.serial: interrupt mode used for rx (no dma)
[    0.816106] stm32-usart 4000f000.serial: interrupt mode used for tx (no dma)
[    0.824253] 40010000.serial: ttySTM0 at MMIO 0x40010000 (irq = 27, base_baud = 4000000) is a stm32-usart
[    0.833796] console [ttySTM0] enabled
[    0.833796] console [ttySTM0] enabled
[    0.840862] bootconsole [earlycon0] disabled
[    0.840862] bootconsole [earlycon0] disabled
[    0.850132] stm32-usart 40010000.serial: interrupt mode used for rx (no dma)
[    0.855755] stm32-usart 40010000.serial: interrupt mode used for tx (no dma)</pre>

*==== dmesg output information ====The system log shows that the UART devices and associated TTY terminals registered during the probe.
 {{Board$}} dmesg | grep ttySTM*
 [    0.000000] Kernel command line: root=/dev/mmcblk0p5 rootwait rw earlyprintk console=ttySTM1,115200
 {{highlight|# ttySTM1 terminal is associated with usart3 (4000f000.serial) #}} 
 [    0.798779] 4000f000.serial: {{Green|'''ttySTM1'''}} at MMIO 0x4000f000 (irq = 25, base_baud = 4000000) is a stm32-usart
 {{highlight|# ttySTM0 terminal is associated with uart4 (40010000.serial) for console#}}
 [    0.824253] 40010000.serial: {{Green|'''ttySTM0'''}} at MMIO 0x40010000 (irq = 27, base_baud = 4000000) is a stm32-usart      
 {{highlight|# ttySTM0 terminal is activated by default for console #}}
 [    0.833796] console [{{Green|'''ttySTM0'''}}] enabled

=== How to debug ==== Dynamic trace ====
A detailed dynamic trace is available in [[How to use the kernel dynamic debug]]<br/>

  {{Board$}} echo  "file drivers/tty/* +p" > /sys/kernel/debug/dynamic_debug/control
This command enables all the traces related to the TTY core and drivers at runtime.<br/>

A finer selection can be made by choosing only the files to trace.<br/>


{{Info|Reminder: ''loglevel'' needs to be increased to 8 by using either boot arguments or the ''dmesg -n 8'' command through the console}}

=== How to debug ===While a TTY serial port is instantiated, TTY core exports different files through devfs, sysfs and procfs. 

====devfs====
* The repository '''/dev''' contains all the probed TTY serial devices.

 {{Board$}} ls /dev/ttySTM*
 {{highlight|# ttySTM1 and ttySTM0 terminals are probed #}}
 /dev/{{Green|'''ttySTM1'''}}  /dev/{{Green|'''ttySTM0'''}}

====sysfs====
* '''/sys/class/tty/''' lists all TTY devices which ttySx correspond to serial port devices.
 {{Board$}} ls /sys/class/tty/*/device/driver
 /sys/class/tty/{{Green|'''ttySTM1'''}}/device/driver -> ../../../../bus/platform/drivers/{{Green|'''stm32-usart'''}}
 /sys/class/tty/{{Green|'''ttySTM0'''}}/device/driver -> ../../../../bus/platform/drivers/{{Green|'''stm32-usart'''}}

* '''/sys/devices/platform/soc/''' lists all the usart devices probed

 {{Board$}} ls -d /sys/devices/platform/soc/*.serial
 {{highlight|# Serial devices 4000f000.serial (usart3) and 40010000.serial (uart4) are probed #}}
 /sys/devices/platform/soc/{{Green|'''4000f000.serial'''}}  /sys/devices/platform/soc/{{Green|'''40010000.serial'''}}

* '''/sys/devices/platform/soc/''device''.serial/tty''' lists the TTY terminal associated to a serial device

 {{Board$}} ls /sys/devices/platform/soc/{{Green|'''4000f000.serial'''}}/tty/      
 {{highlight|# ttySTM1 is associated to serial device 4000f000.serial (usart3)  #}}
 {{Green|'''ttySTM1'''}}

====procfs====
* The repository '''/proc/device-tree''' lists all the usart devices declared in the device-tree, including the disabled ones.
 {{Board$}} ls -d /proc/device-tree/soc/serial@*
 /proc/device-tree/soc/serial@4000e000  /proc/device-tree/soc/serial@40010000  /proc/device-
 tree/soc/serial@40018000  /proc/device-tree/soc/serial@44003000
 /proc/device-tree/soc/serial@4000f000  /proc/device-tree/soc/serial@40011000  /proc/device-
 tree/soc/serial@40019000  /proc/device-tree/soc/serial@5c000000
* Then for each device listed, device-tree properties are available.
 {{Board$}} ls /proc/device-tree/soc/serial@40010000/
 clock-names  compatible       interrupts-extended  name     pinctrl-0  pinctrl-names  reg     wakeup-source
 clocks       interrupt-names  linux,phandle        phandle  pinctrl-1  power-domains  status
:As an example, the status entry provide the status of the device in the device tree node.

 {{Board$}} cat /proc/device-tree/soc/{{Green|'''serial@40010000'''}}/status
 {{highlight|# status of device serial@40010000 (uart4) is set to "okay" in the device tree #}}
 {{Green|'''okay'''}}
* 

* The file '''/proc/interrupts''' lists all active interrups. To be listed, the serial interrupts need to be activated by opening a port on the UART instancesthe interrupts for active serial ports.
 {{Board$}} cat /proc/interrupts | grep serial
 26:          0          0     GIC-0  71 Level     4000f000.serial
 27:          0          0  stm32-exti-h  28 Edge      4000f000.serial
 28:      13509          0     GIC-0  84 Level     40010000.serial
 29:          0          0  stm32-exti-h  30 Edge      40010000.serial

<span id{{=}}"procfs_serialcounters"></span>

* The file '''/proc/tty/driver/stm32-usart''' lists serial core counters and modem information for each serial instance.

:Driver information:
:* serial driver name
:* serial device start address
:* irq number

:Counters:
:* tx: Number of bytes sent
:* rx: Number of bytes received
:* fe: Number of framing errors received
:* pe: Number of parity errors received
:* brk: Number of break signals received
:* oe: Number of overrun errors received
:* bo: Number of framework buffer overrun errors received

:Modem information:
:* RTS: Request To Send
:* CTS: Clear To Send
:* DTR: Data Terminal Ready
:* DSR: Data Set Ready
:* CD: Carrier Detect
:* RI: Ring Indicator

 {{Board$}} cat /proc/tty/driver/stm32-usart 
 serinfo:1.0 driver revision:
 0: uart:stm32-usart mmio:0x40010000 irq:29 tx:22722 rx:2276 RTS|CTS|DTR|DSR|CD
 1: uart:stm32-usart mmio:0x4000F000 irq:27 tx:0 rx:1149 fe:121 oe:2 pe:296 brk:3 RTS|CTS|DTR|DSR|CD
 3: uart:stm32-usart mmio:0x4000E000 irq:25 tx:0 rx:0 CTS|DSR|CD
==How to go further==
The Linux community provides many detailed documentation about Linux serial/TTY. Please find below a selection of the most relevant ones:
* Linux Serial-HOWTO <ref>[http://tldp.org/HOWTO/Serial-HOWTO.html Linux Serial-HOWTO], tdlp.org training document, describes how to set up serial ports from both hardware and software perspectives</ref> describes how to set up serial ports from both hardware and software perspectives.
* Serial Programming Guide for POSIX Compliant Operating Systems <ref>[https://www.cmrr.umn.edu/~strupp/serial.html Serial Programming Guide for POSIX Compliant Operating Systems], by Michael Sweet, training document</ref> , by Michael Sweet.

More information can be found in the following web articles in order to get a good understanding of Linux TTY framework:
* TTY Subsystem <ref> [https://www.ibm.com/support/knowledgecenter/en/ssw_aix_71/com.ibm.aix.genprogc/ttysys.htm TTY Subsystem], by IBM </ref>, by IBM
* The TTY demystified <ref>[http://www.linusakesson.net/programming/tty/ The TTY demystified] TTY subsystem presentation article, by Linus Akesson </ref>, by Linus Akesson
* Serial drivers training <ref>[http://bootlin.com/doc/legacy/serial-drivers/linux-serial-drivers.pdf Linux serial drivers training] Linux Serial Drivers training, by Bootlin </ref>, by Bootlin
* Linux Serial drivers <ref>[http://www.linux.it/~rubini/docs/serial/serial.html Linux Serial Drivers] Serial drivers article describing data flows, by Alessandro Rubini</ref>, by Alessandro Rubini
* Serial Device Bus <ref>[https://elinux.org/images/0/0e/Serdev-elce-2017-2.pdf The Serial Device Bus] Serdev framework presentation, by Johan Hovold</ref>, by Johan Hovold

==References==
<references />

<noinclude>

{{ArticleBasedOnModel | Framework overview article model}}
{{PublicationRequestId | 8368 | 2018-08-31 | BrunoB}}

[[Category:Serial TTY|1]]</noinclude>
(25 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<noinclude>
 
{{ArticleBasedOnModel|[[Framework overview article model]]}}
 
{{ArticleMainWriter|ErwanLR}}
 
{{ArticleApprovedVersion| ErwanLR | Reviewers : FabriceG, AlexandreT, NathalieS | No previous approved version |  Last TW review done by BrunoB- 31Aug'18 - 8368 | 03Sep'18}}
 
 
[[Category:Serial TTY|1]]
 
 
</noinclude>
 
'''SUMMARY'''<br>
 
 
This article gives information about the Linux® TTY framework. It explains how to activate the '''UART''' interface, and how to access it from user and kernel spaces.<br />
 
This article gives information about the Linux® TTY framework. It explains how to activate the '''UART''' interface, and how to access it from user and kernel spaces.<br />
   
==Framework Purpose==
+
==Framework purpose==
   
 
The '''TTY''' subsytem controls the communication between UART devices and the programs using these devices.  
 
The '''TTY''' subsytem controls the communication between UART devices and the programs using these devices.  
Line 57: Line 48:
 
==System overview==
 
==System overview==
 
{{
 
{{
ImageMap|Image:Serial TTY overview.png{{!}} frame {{!}} center{{!}} Serial TTY architecture overview <br/> {{WarningImageMapOverlay}}
+
ImageMap|Image:Serial TTY overview.png{{!}} frame {{!}} center{{!}} Serial TTY architecture overview
 
rect 261 75 412 116 [[How to use TTY from an application | How to use TTY from an application ]]
 
rect 261 75 412 116 [[How to use TTY from an application | How to use TTY from an application ]]
 
rect 452 75 603 116 [[How to use TTY with User Terminal | How to use TTY from a user terminal]]
 
rect 452 75 603 116 [[How to use TTY with User Terminal | How to use TTY from a user terminal]]
 
rect 676 75 828 116 [[Bluetooth_overview#System_overview | Example: Bluetooth_overview ]]
 
rect 676 75 828 116 [[Bluetooth_overview#System_overview | Example: Bluetooth_overview ]]
rect 346 123 453 169 [http://man7.org/linux/man-pages/man3/termios.3.html termios]
+
rect 268 130 453 220 [http://man7.org/linux/man-pages/man3/termios.3.html termios]
 
rect 350 314 502 355 {{CodeSource | Linux kernel | drivers/tty/tty_io.c | tty char driver}}
 
rect 350 314 502 355 {{CodeSource | Linux kernel | drivers/tty/tty_io.c | tty char driver}}
 
rect 350 381 502 423 [[Serial TTY line discipline| Line discipline]]
 
rect 350 381 502 423 [[Serial TTY line discipline| Line discipline]]
rect 677 382 827 423 {{CodeSource | Linux kernel | drivers/tty/serdev | serdev framework}}
+
rect 677 439 827 479 {{CodeSource | Linux kernel | drivers/tty/serdev | serdev framework}}
 
rect 350 439 502 480 {{CodeSource | Linux kernel | drivers/tty | tty framework}}
 
rect 350 439 502 480 {{CodeSource | Linux kernel | drivers/tty | tty framework}}
 
rect 463 514 615 554 {{CodeSource | Linux kernel | drivers/tty/serial/serial_core.c | serial_core framework}}
 
rect 463 514 615 554 {{CodeSource | Linux kernel | drivers/tty/serial/serial_core.c | serial_core framework}}
Line 99: Line 90:
 
The '''termios API''' <ref>[http://man7.org/linux/man-pages/man3/termios.3.html termios API], Linux Programmer's Manual termios API Documentation (user land API with serial devices)</ref> is a user land API, and its functions describe a general terminal interface that is provided to control asynchronous communications ports. <br/>
 
The '''termios API''' <ref>[http://man7.org/linux/man-pages/man3/termios.3.html termios API], Linux Programmer's Manual termios API Documentation (user land API with serial devices)</ref> is a user land API, and its functions describe a general terminal interface that is provided to control asynchronous communications ports. <br/>
   
The POSIX termios API abstracts the low-level details of the hardware, and provides a simple yet complete programming interface that can be used for advanced projects. It is a wrapper on '''character device API''' <ref> [http://bootlin.com/doc/accessing-hardware.pdf Character device API overview], ''Accessing hardware from userspace'' training, Bootlin documentation</ref> ioctl operations.<br/>
+
The POSIX termios API abstracts the low-level details of the hardware, and provides a simple yet complete programming interface that can be used for advanced projects. It is a wrapper on '''character device API''' <ref> [https://bootlin.com/doc/legacy/accessing-hardware/accessing-hardware.pdf Character device API overview], ''Accessing hardware from userspace'' training, Bootlin documentation</ref> ioctl operations.<br/>
   
 
Note:
 
Note:
Line 140: Line 131:
   
 
===Device tree configuration ===
 
===Device tree configuration ===
UART configuration thanks to device tree is described in the dedicated article [[Serial TTY device tree configuration|serial/TTY device tree configuration]].
+
UART configuration thanks to device tree is described in the dedicated article [[Serial TTY device tree configuration|Serial TTY device tree configuration]].
   
 
==How to use TTY==
 
==How to use TTY==
This section describes how to use TTY from user land (from a terminal and a an application) and from kernel space, based on the two following use cases:
+
This section describes how to use TTY from user land (from a terminal or an application) and from kernel space, based on the two following use cases:
* How to configure the serial port
+
* How to configure the serial port by using the termios structure
 
* How to send/receive data
 
* How to send/receive data
<br/>
+
 
  +
The termios structure allows to configure communication ports with many settings, such as :
  +
* Baud rate
  +
* Character size mask
  +
* Parity bit enabling
  +
* Parity and framing errors detection settings
  +
* Start/stop input and output control
  +
* RTS/CTS (hardware) flow control
  +
* ...
  +
 
  +
As the [[USART internal peripheral]] supports 7, 8 and 9 word length data, the following termios character size and parity bit configurations are supported:
  +
<span id{{=}}"CSIZE_configurations"></span>
  +
* CS6 with parity bit
  +
* CS7 with or without parity bit
  +
* CS8 with or without parity bit
   
 
Tips to use TTY:
 
Tips to use TTY:
 
* '''How to use TTY from user terminal''': TTY usage from a user terminal is described in a dedicated article, [[How to use TTY with User Terminal|How to use TTY from a user terminal]]
 
* '''How to use TTY from user terminal''': TTY usage from a user terminal is described in a dedicated article, [[How to use TTY with User Terminal|How to use TTY from a user terminal]]
 
* '''How to use TTY from an application''': TTY usage from an application is described in a dedicated article, [[How_to_use_TTY_from_an_application|How to use TTY from an application]]
 
* '''How to use TTY from an application''': TTY usage from an application is described in a dedicated article, [[How_to_use_TTY_from_an_application|How to use TTY from an application]]
* '''TTY line discipline''': TTY line discipline is described in a dedicated article,  [[Serial TTY line discipline|Serial/TTY line discipline]]
+
* '''TTY line discipline''': TTY line discipline is described in a dedicated article,  [[Serial TTY line discipline|Serial TTY line discipline]]
   
 
==How to trace and debug the framework==
 
==How to trace and debug the framework==
Line 159: Line 164:
   
 
=== How to trace ===
 
=== How to trace ===
* The following extract of '''kernel boot log''' shows a serial driver properly probed:
+
==== Kernel boot log ====
  +
The following extract of '''kernel boot log''' shows a serial driver properly probed:
   
 
<pre>
 
<pre>
Line 175: Line 181:
 
</pre>
 
</pre>
   
* dmesg output information
+
==== dmesg output information ====
 
The system log shows that the UART devices and associated TTY terminals registered during the probe.
 
The system log shows that the UART devices and associated TTY terminals registered during the probe.
 
  {{Board$}} dmesg | grep ttySTM*
 
  {{Board$}} dmesg | grep ttySTM*
Line 185: Line 191:
 
  {{highlight|# ttySTM0 terminal is activated by default for console #}}
 
  {{highlight|# ttySTM0 terminal is activated by default for console #}}
 
  [    0.833796] console [{{Green|'''ttySTM0'''}}] enabled
 
  [    0.833796] console [{{Green|'''ttySTM0'''}}] enabled
  +
  +
==== Dynamic trace ====
  +
A detailed dynamic trace is available in [[How to use the kernel dynamic debug]]<br/>
  +
  {{Board$}} echo  "file drivers/tty/* +p" > /sys/kernel/debug/dynamic_debug/control
  +
This command enables all the traces related to the TTY core and drivers at runtime.<br/>
  +
A finer selection can be made by choosing only the files to trace.<br/>
  +
  +
{{Info|Reminder: ''loglevel'' needs to be increased to 8 by using either boot arguments or the ''dmesg -n 8'' command through the console}}
   
 
=== How to debug ===
 
=== How to debug ===
Line 222: Line 236:
 
  tree/soc/serial@40019000  /proc/device-tree/soc/serial@5c000000
 
  tree/soc/serial@40019000  /proc/device-tree/soc/serial@5c000000
   
* Then for each device listed, device-tree properties are available.
+
Then for each device listed, device-tree properties are available.
 
  {{Board$}} ls /proc/device-tree/soc/serial@40010000/
 
  {{Board$}} ls /proc/device-tree/soc/serial@40010000/
 
  clock-names  compatible      interrupts-extended  name    pinctrl-0  pinctrl-names  reg    wakeup-source
 
  clock-names  compatible      interrupts-extended  name    pinctrl-0  pinctrl-names  reg    wakeup-source
 
  clocks      interrupt-names  linux,phandle        phandle  pinctrl-1  power-domains  status
 
  clocks      interrupt-names  linux,phandle        phandle  pinctrl-1  power-domains  status
   
As an example, the status entry provide the status of the device in the device tree node.
+
:As an example, the status entry provide the status of the device in the device tree node.
 
   
 
   
 
  {{Board$}} cat /proc/device-tree/soc/{{Green|'''serial@40010000'''}}/status
 
  {{Board$}} cat /proc/device-tree/soc/{{Green|'''serial@40010000'''}}/status
Line 233: Line 247:
 
  {{Green|'''okay'''}}
 
  {{Green|'''okay'''}}
   
* '''/proc/interrupts''' lists all active interrups. To be listed, the serial interrupts need to be activated by opening a port on the UART instances.
+
 
  +
* The file '''/proc/interrupts''' lists the interrupts for active serial ports.
 
  {{Board$}} cat /proc/interrupts | grep serial
 
  {{Board$}} cat /proc/interrupts | grep serial
 
  26:          0          0    GIC-0  71 Level    4000f000.serial
 
  26:          0          0    GIC-0  71 Level    4000f000.serial
Line 239: Line 254:
 
  28:      13509          0    GIC-0  84 Level    40010000.serial
 
  28:      13509          0    GIC-0  84 Level    40010000.serial
 
  29:          0          0  stm32-exti-h  30 Edge      40010000.serial
 
  29:          0          0  stm32-exti-h  30 Edge      40010000.serial
  +
  +
  +
<span id{{=}}"procfs_serialcounters"></span>
  +
* The file '''/proc/tty/driver/stm32-usart''' lists serial core counters and modem information for each serial instance.
  +
  +
:Driver information:
  +
:* serial driver name
  +
:* serial device start address
  +
:* irq number
  +
  +
:Counters:
  +
:* tx: Number of bytes sent
  +
:* rx: Number of bytes received
  +
:* fe: Number of framing errors received
  +
:* pe: Number of parity errors received
  +
:* brk: Number of break signals received
  +
:* oe: Number of overrun errors received
  +
:* bo: Number of framework buffer overrun errors received
  +
  +
:Modem information:
  +
:* RTS: Request To Send
  +
:* CTS: Clear To Send
  +
:* DTR: Data Terminal Ready
  +
:* DSR: Data Set Ready
  +
:* CD: Carrier Detect
  +
:* RI: Ring Indicator
  +
  +
{{Board$}} cat /proc/tty/driver/stm32-usart
  +
serinfo:1.0 driver revision:
  +
0: uart:stm32-usart mmio:0x40010000 irq:29 tx:22722 rx:2276 RTS|CTS|DTR|DSR|CD
  +
1: uart:stm32-usart mmio:0x4000F000 irq:27 tx:0 rx:1149 fe:121 oe:2 pe:296 brk:3 RTS|CTS|DTR|DSR|CD
  +
3: uart:stm32-usart mmio:0x4000E000 irq:25 tx:0 rx:0 CTS|DSR|CD
   
 
==How to go further==
 
==How to go further==
Line 256: Line 303:
   
 
<references />
 
<references />
  +
  +
<noinclude>
  +
{{ArticleBasedOnModel | Framework overview article model}}
  +
{{PublicationRequestId | 8368 | 2018-08-31 | BrunoB}}
  +
  +
[[Category:Serial TTY|1]]
  +
</noinclude>

Attachments

Discussions