Difference between revisions of "Serial TTY line discipline"

[quality revision] [pending revision]
(Created page with "<noinclude> {{ArticleMainWriter|ErwanLR}} {{ArticleApprovedVersion | Jean-ChristopheT | Nobody | No previous approved version | Automatic approval (article under construction)...")
 
m
 
Under construction.png Coming soon

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

1 Framework purpose[edit]

UART is a common interface for several device types, such as Bluetooth, NFC, FM Radio and GPS devices.
Since kernel version 4.12, the serial device bus (also called Serdev) has been introduced in the TTY framework to improve the interface offered to devices attached to a serial port. Please refer to the Serial TTY overview article for a detailed description of the TTY framework purpose. Nevertheless it's still possible (even if not recommended) to use line disciplines "drivers". This article focuses on the line discipline interface offered to devices attached to a serial port.

2 System overview[edit]

Serial TTY Line Discipline overview.png


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[1] which offers an interface to develop an application using serial drivers.
  • Client subsystem: kernel subsystem client of TTY core (Example: a Bluetooth device)
  • 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.

Info.png A line discipline driver can be used when a serial interface is needed at kernel level.

For example, a kernel driver maybe needed to control an external device through an U(S)ART port.

  • The line discipline will be responsible for:
    • creating this new kernel API
    • routing data flow between serial core and new kernel API


3 References[edit]

  1. 1.0 1.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



'''SUMMARY'''<br>

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


==Framework purpose==
UART is a common interface for several device types, such as Bluetooth, NFC, FM Radio and GPS devices. <br/>

Since kernel version 4.12, the serial device bus (also called Serdev) has been introduced in the TTY framework to improve the interface offered to devices attached to a serial port. Please refer to the [[Serial TTY overview]] article for a detailed description of the TTY framework purpose. Nevertheless it's still possible (even if not recommended) to use line disciplines "drivers".
This article focuses on the line discipline interface offered to devices attached to a serial port.
{{ReviewsComments|FGA W1941: I just reworked that a little. please check.}}
==System overview==
[[File:Serial TTY Line Discipline overview.png|center|link=]]<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'''.
{{ReviewsComments|FGA W1941: I can't find TTY tools in above figure. Is it relevant here?.}}
* Termios: API<ref name="termios API">[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> which offers an interface to develop an application using serial drivers.
*Client subsystem: kernel subsystem client of '''TTY''' core (Example:  a Bluetooth device)
{{ReviewsComments|FGA W1941: I can't find "Client subsystem" in above figure.}}
* 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''']].
{{ReviewsComments|FGA W1941: "TTY framework" -> "TTY Core" in above figure ?}}
* Serial framework: low-level serial driver management, including the {{CodeSource | Linux kernel | drivers/tty/serial/serial_core.c | '''serial core''' functions}}.
{{ReviewsComments|FGA W1941: "Serial framework" -> "Serial Core" in above figure ?}}
* 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
{{ReviewsComments|FGA W1941: Maybe worth adding the external device in the above figure ?}}

===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 name="termios API"/> 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/>


{{Info|A [[Serial TTY line discipline|'''line discipline''']] driver can be used when a serial interface is needed at kernel level.}}
For example, a kernel driver maybe needed to control an external device through an U(S)ART port.
{{ReviewsComments|FGA W1941: I rephrased above note, can you please double-ckeck ?}}
* The '''line discipline''' will be responsible for:
** creating this new kernel API
** routing data flow between serial core and new kernel API <br/>


{{ReviewsComments|FGA W1941: No how to use section, nor examples ? Is it deliberate ?<br/>

FGA W1941: Maybe worth pointing out some existing examples in the kernel ?}}

==References==
<references />

<noinclude>

{{ArticleMainWriter|ErwanLR}}
{{ArticleApprovedVersion | Jean-ChristopheT | Nobody | No previous approved version | Automatic approval (article under construction) | 28Jan’19}}
[[Category:Serial TTY|6]]</noinclude>

{{UnderConstruction}}
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
  +
'''SUMMARY'''<br>
  +
This article gives information about the Linux® TTY framework. It explains how to activate the '''UART''' interface with line disciplines, and how to access it from user and kernel spaces.<br />
  +
  +
==Framework purpose==
  +
UART is a common interface for several device types, such as Bluetooth, NFC, FM Radio and GPS devices. <br/>
  +
Since kernel version 4.12, the serial device bus (also called Serdev) has been introduced in the TTY framework to improve the interface offered to devices attached to a serial port. Please refer to the [[Serial TTY overview]] article for a detailed description of the TTY framework purpose. Nevertheless it's still possible (even if not recommended) to use line disciplines "drivers".
  +
This article focuses on the line discipline interface offered to devices attached to a serial port.
  +
{{ReviewsComments|FGA W1941: I just reworked that a little. please check.}}
  +
==System overview==
  +
[[File:Serial TTY Line Discipline overview.png|center|link=]]
  +
<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'''.
  +
{{ReviewsComments|FGA W1941: I can't find TTY tools in above figure. Is it relevant here?.}}
  +
* Termios: API<ref name="termios API">[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> which offers an interface to develop an application using serial drivers.
  +
*Client subsystem: kernel subsystem client of '''TTY''' core (Example:  a Bluetooth device)
  +
{{ReviewsComments|FGA W1941: I can't find "Client subsystem" in above figure.}}
  +
* 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''']].
  +
{{ReviewsComments|FGA W1941: "TTY framework" -> "TTY Core" in above figure ?}}
  +
* Serial framework: low-level serial driver management, including the {{CodeSource | Linux kernel | drivers/tty/serial/serial_core.c | '''serial core''' functions}}.
  +
{{ReviewsComments|FGA W1941: "Serial framework" -> "Serial Core" in above figure ?}}
  +
* 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
  +
{{ReviewsComments|FGA W1941: Maybe worth adding the external device in the above figure ?}}
  +
  +
===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 name="termios API"/> 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/>
  +
  +
{{Info|A [[Serial TTY line discipline|'''line discipline''']] driver can be used when a serial interface is needed at kernel level.}}
  +
For example, a kernel driver maybe needed to control an external device through an U(S)ART port.
  +
{{ReviewsComments|FGA W1941: I rephrased above note, can you please double-ckeck ?}}
  +
* The '''line discipline''' will be responsible for:
  +
** creating this new kernel API
  +
** routing data flow between serial core and new kernel API <br/>
  +
  +
{{ReviewsComments|FGA W1941: No how to use section, nor examples ? Is it deliberate ?<br/>
  +
FGA W1941: Maybe worth pointing out some existing examples in the kernel ?}}
  +
  +
==References==
  +
  +
<references />
  +
 
<noinclude>
 
<noinclude>
 
{{ArticleMainWriter|ErwanLR}}
 
{{ArticleMainWriter|ErwanLR}}
Line 4: Line 57:
 
[[Category:Serial TTY|6]]
 
[[Category:Serial TTY|6]]
 
</noinclude>
 
</noinclude>
{{UnderConstruction}}
 

Attachments

Discussions