TTY Driver and TTY Operations¶
Allocation¶
The first thing a driver needs to do is to allocate a struct tty_driver
. This
is done by tty_alloc_driver() (or __tty_alloc_driver()
). Next, the newly
allocated structure is filled with information. See TTY Driver Reference at
the end of this document on what actually shall be filled in.
The allocation routines expect a number of devices the driver can handle at
most and flags. Flags are those starting TTY_DRIVER_
listed and described
in TTY Driver Flags below.
When the driver is about to be freed, tty_driver_kref_put()
is called on that.
It will decrements the reference count and if it reaches zero, the driver is
freed.
For reference, both allocation and deallocation functions are explained here in detail:
-
struct tty_driver *
__tty_alloc_driver
(unsigned int lines, struct module *owner, unsigned long flags)¶ - allocate tty driver
Parameters
unsigned int lines
- count of lines this driver can handle at most
struct module *owner
- module which is responsible for this driver
unsigned long flags
- some of
TTY_DRIVER_
flags, will be set in driver->flags
Description
This should not be called directly, some of the provided macros should be used instead. Use IS_ERR() and friends on retval.
-
void
tty_driver_kref_put
(struct tty_driver *driver)¶ - drop a reference to a tty driver
Parameters
struct tty_driver *driver
- driver of which to drop the reference
Description
The final put will destroy and free up the driver.
TTY Driver Flags¶
Here comes the documentation of flags accepted by tty_alloc_driver() (or
__tty_alloc_driver()
):
- TTY_DRIVER_RESET_TERMIOS
- Requests the tty layer to reset the termios setting when the last process has closed the device. Used for PTYs, in particular.
- TTY_DRIVER_REAL_RAW
Indicates that the driver will guarantee not to set any special character handling flags if this is set for the tty:
(IGNBRK || (!BRKINT && !PARMRK)) && (IGNPAR || !INPCK)
That is, if there is no reason for the driver to send notifications of parity and break characters up to the line driver, it won’t do so. This allows the line driver to optimize for this case if this flag is set. (Note that there is also a promise, if the above case is true, not to signal overruns, either.)
- TTY_DRIVER_DYNAMIC_DEV
- The individual tty devices need to be registered with a call to
tty_register_device()
when the device is found in the system and unregistered with a call totty_unregister_device()
so the devices will be show up properly in sysfs. If not set, alltty_driver.num
entries will be created by the tty core in sysfs whentty_register_driver()
is called. This is to be used by drivers that have tty devices that can appear and disappear while the main tty driver is registered with the tty core. - TTY_DRIVER_DEVPTS_MEM
- Don’t use the standard arrays (
tty_driver.ttys
andtty_driver.termios
), instead use dynamic memory keyed through the devpts filesystem. This is only applicable to the PTY driver. - TTY_DRIVER_HARDWARE_BREAK
- Hardware handles break signals. Pass the requested timeout to the
tty_operations.break_ctl
instead of using a simple on/off interface. - TTY_DRIVER_DYNAMIC_ALLOC
- Do not allocate structures which are needed per line for this driver
(
tty_driver.ports
) as it would waste memory. The driver will take care. This is only applicable to the PTY driver. - TTY_DRIVER_UNNUMBERED_NODE
- Do not create numbered
/dev
nodes. For example, create/dev/ttyprintk
and not/dev/ttyprintk0
. Applicable only when a driver for a single tty device is being allocated.
Registration¶
When a struct tty_driver
is allocated and filled in, it can be registered using
tty_register_driver()
. It is recommended to pass TTY_DRIVER_DYNAMIC_DEV
in
flags of tty_alloc_driver(). If it is not passed, all devices are also
registered during tty_register_driver()
and the following paragraph of
registering devices can be skipped for such drivers. However, the struct
tty_port
part in Registering Devices is still relevant there.
-
int
tty_register_driver
(struct tty_driver *driver)¶ - register a tty driver
Parameters
struct tty_driver *driver
- driver to register
Description
Called by a tty driver to register itself.
-
void
tty_unregister_driver
(struct tty_driver *driver)¶ - unregister a tty driver
Parameters
struct tty_driver *driver
- driver to unregister
Description
Called by a tty driver to unregister itself.
Registering Devices¶
Every TTY device shall be backed by a struct tty_port
. Usually, TTY drivers
embed tty_port into device’s private structures. Further details about handling
tty_port can be found in TTY Port. The driver is also recommended to use
tty_port’s reference counting by tty_port_get() and tty_port_put()
. The final
put is supposed to free the tty_port including the device’s private struct.
Unless TTY_DRIVER_DYNAMIC_DEV
was passed as flags to tty_alloc_driver(),
TTY driver is supposed to register every device discovered in the system
(the latter is preferred). This is performed by tty_register_device()
. Or by
tty_register_device_attr()
if the driver wants to expose some information
through struct attribute_group. Both of them register index
’th device and
upon return, the device can be opened. There are also preferred tty_port
variants described in Linking Devices to Ports later. It is up to driver to
manage free indices and choosing the right one. The TTY layer only refuses to
register more devices than passed to tty_alloc_driver().
When the device is opened, the TTY layer allocates struct tty_struct
and starts
calling operations from tty_driver.ops
, see TTY Operations
Reference.
The registration routines are documented as follows:
-
struct device *
tty_register_device
(struct tty_driver *driver, unsigned index, struct device *device)¶ register a tty device
Parameters
struct tty_driver *driver
- the tty driver that describes the tty device
unsigned index
- the index in the tty driver for this tty device
struct device *device
- a
struct device
that is associated with this tty device. This field is optional, if there is no knownstruct device
for this tty device it can be set to NULL safely.
Description
This call is required to be made to register an individual tty device
if the tty driver’s flags have the TTY_DRIVER_DYNAMIC_DEV
bit set. If
that bit is not set, this function should not be called by a tty
driver.
Locking: ??
Return
A pointer to the struct device
for this tty device (or
ERR_PTR(-EFOO) on error).
-
struct device *
tty_register_device_attr
(struct tty_driver *driver, unsigned index, struct device *device, void *drvdata, const struct attribute_group **attr_grp)¶ register a tty device
Parameters
struct tty_driver *driver
- the tty driver that describes the tty device
unsigned index
- the index in the tty driver for this tty device
struct device *device
- a
struct device
that is associated with this tty device. This field is optional, if there is no knownstruct device
for this tty device it can be set toNULL
safely. void *drvdata
- Driver data to be set to device.
const struct attribute_group **attr_grp
- Attribute group to be set on device.
Description
This call is required to be made to register an individual tty device if the
tty driver’s flags have the TTY_DRIVER_DYNAMIC_DEV
bit set. If that bit is
not set, this function should not be called by a tty driver.
Locking: ??
Return
A pointer to the struct device
for this tty device (or
ERR_PTR(-EFOO) on error).
-
void
tty_unregister_device
(struct tty_driver *driver, unsigned index)¶ unregister a tty device
Parameters
struct tty_driver *driver
- the tty driver that describes the tty device
unsigned index
- the index in the tty driver for this tty device
Description
If a tty device is registered with a call to tty_register_device()
then
this function must be called when the tty device is gone.
Locking: ??
Linking Devices to Ports¶
As stated earlier, every TTY device shall have a struct tty_port
assigned to
it. It must be known to the TTY layer at tty_driver.ops.install()
at latest. There are few helpers to link the two. Ideally, the driver uses
tty_port_register_device()
or tty_port_register_device_attr()
instead of
tty_register_device()
and tty_register_device_attr()
at the registration time.
This way, the driver needs not care about linking later on.
If that is not possible, the driver still can link the tty_port to a specific
index before the actual registration by tty_port_link_device()
. If it still
does not fit, tty_port_install()
can be used from the
tty_driver.ops.install
hook as a last resort. The last one is
dedicated mostly for in-memory devices like PTY where tty_ports are allocated
on demand.
The linking routines are documented here:
-
void
tty_port_link_device
(struct tty_port *port, struct tty_driver *driver, unsigned index)¶ link tty and tty_port
Parameters
struct tty_port *port
- tty_port of the device
struct tty_driver *driver
- tty_driver for this device
unsigned index
- index of the tty
Description
Provide the tty layer with a link from a tty (specified by index) to a
tty_port (port). Use this only if neither tty_port_register_device()
nor
tty_port_install()
is used in the driver. If used, this has to be called
before tty_register_driver()
.
-
struct device *
tty_port_register_device
(struct tty_port *port, struct tty_driver *driver, unsigned index, struct device *device)¶ register tty device
Parameters
struct tty_port *port
- tty_port of the device
struct tty_driver *driver
- tty_driver for this device
unsigned index
- index of the tty
struct device *device
- parent if exists, otherwise NULL
Description
It is the same as tty_register_device()
except the provided port is linked
to a concrete tty specified by index. Use this or tty_port_install()
(or
both). Call tty_port_link_device()
as a last resort.
-
struct device *
tty_port_register_device_attr
(struct tty_port *port, struct tty_driver *driver, unsigned index, struct device *device, void *drvdata, const struct attribute_group **attr_grp)¶ register tty device
Parameters
struct tty_port *port
- tty_port of the device
struct tty_driver *driver
- tty_driver for this device
unsigned index
- index of the tty
struct device *device
- parent if exists, otherwise NULL
void *drvdata
- Driver data to be set to device.
const struct attribute_group **attr_grp
- Attribute group to be set on device.
Description
It is the same as tty_register_device_attr()
except the provided port is
linked to a concrete tty specified by index. Use this or tty_port_install()
(or both). Call tty_port_link_device()
as a last resort.
TTY Driver Reference¶
All members of struct tty_driver
are documented here. The required members are
noted at the end. struct tty_operations
are documented next.
-
struct
tty_driver
¶ - driver for TTY devices
Definition
struct tty_driver {
int magic;
struct kref kref;
struct cdev **cdevs;
struct module *owner;
const char *driver_name;
const char *name;
int name_base;
int major;
int minor_start;
unsigned int num;
short type;
short subtype;
struct ktermios init_termios;
unsigned long flags;
struct proc_dir_entry *proc_entry;
struct tty_driver *other;
struct tty_struct **ttys;
struct tty_port **ports;
struct ktermios **termios;
void *driver_state;
const struct tty_operations *ops;
struct list_head tty_drivers;
};
Members
magic
- set to
TTY_DRIVER_MAGIC
in__tty_alloc_driver()
kref
- reference counting. Reaching zero frees all the internals and the driver.
cdevs
- allocated/registered character /dev devices
owner
- modules owning this driver. Used drivers cannot be rmmod’ed. Automatically set by tty_alloc_driver().
driver_name
- name of the driver used in /proc/tty
name
- used for constructing /dev node name
name_base
- used as a number base for constructing /dev node name
major
- major /dev device number (zero for autoassignment)
minor_start
- the first minor /dev device number
num
- number of devices allocated
type
- type of tty driver (
TTY_DRIVER_TYPE_
) subtype
- subtype of tty driver (
SYSTEM_TYPE_
,PTY_TYPE_
,SERIAL_TYPE_
) init_termios
- termios to set to each tty initially (e.g.
tty_std_termios
) flags
- tty driver flags (
TTY_DRIVER_
) proc_entry
- proc fs entry, used internally
other
- driver of the linked tty; only used for the PTY driver
ttys
- array of active
struct tty_struct
, set bytty_standard_install()
ports
- array of
struct tty_port
; can be set during initialization bytty_port_link_device()
and similar termios
- storage for termios at each TTY close for the next open
driver_state
- pointer to driver’s arbitrary data
ops
- driver hooks for TTYs. Set them using tty_set_operations(). Use
struct tty_port
helpers in them as much as possible. tty_drivers
- used internally to link tty_drivers together
Description
The usual handling of struct tty_driver
is to allocate it by
tty_alloc_driver(), set up all the necessary members, and register it by
tty_register_driver()
. At last, the driver is torn down by calling
tty_unregister_driver()
followed by tty_driver_kref_put()
.
The fields required to be set before calling tty_register_driver()
include
driver_name, name, type, subtype, init_termios, and ops.
TTY Operations Reference¶
When a TTY is registered, these driver hooks can be invoked by the TTY layer:
-
struct
tty_operations
¶ - interface between driver and tty
Definition
struct tty_operations {
struct tty_struct * (*lookup)(struct tty_driver *driver, struct file *filp, int idx);
int (*install)(struct tty_driver *driver, struct tty_struct *tty);
void (*remove)(struct tty_driver *driver, struct tty_struct *tty);
int (*open)(struct tty_struct * tty, struct file * filp);
void (*close)(struct tty_struct * tty, struct file * filp);
void (*shutdown)(struct tty_struct *tty);
void (*cleanup)(struct tty_struct *tty);
int (*write)(struct tty_struct * tty, const unsigned char *buf, int count);
int (*put_char)(struct tty_struct *tty, unsigned char ch);
void (*flush_chars)(struct tty_struct *tty);
unsigned int (*write_room)(struct tty_struct *tty);
unsigned int (*chars_in_buffer)(struct tty_struct *tty);
int (*ioctl)(struct tty_struct *tty, unsigned int cmd, unsigned long arg);
long (*compat_ioctl)(struct tty_struct *tty, unsigned int cmd, unsigned long arg);
void (*set_termios)(struct tty_struct *tty, struct ktermios * old);
void (*throttle)(struct tty_struct * tty);
void (*unthrottle)(struct tty_struct * tty);
void (*stop)(struct tty_struct *tty);
void (*start)(struct tty_struct *tty);
void (*hangup)(struct tty_struct *tty);
int (*break_ctl)(struct tty_struct *tty, int state);
void (*flush_buffer)(struct tty_struct *tty);
void (*set_ldisc)(struct tty_struct *tty);
void (*wait_until_sent)(struct tty_struct *tty, int timeout);
void (*send_xchar)(struct tty_struct *tty, char ch);
int (*tiocmget)(struct tty_struct *tty);
int (*tiocmset)(struct tty_struct *tty, unsigned int set, unsigned int clear);
int (*resize)(struct tty_struct *tty, struct winsize *ws);
int (*get_icount)(struct tty_struct *tty, struct serial_icounter_struct *icount);
int (*get_serial)(struct tty_struct *tty, struct serial_struct *p);
int (*set_serial)(struct tty_struct *tty, struct serial_struct *p);
void (*show_fdinfo)(struct tty_struct *tty, struct seq_file *m);
#ifdef CONFIG_CONSOLE_POLL;
int (*poll_init)(struct tty_driver *driver, int line, char *options);
int (*poll_get_char)(struct tty_driver *driver, int line);
void (*poll_put_char)(struct tty_driver *driver, int line, char ch);
#endif;
int (*proc_show)(struct seq_file *m, void *driver);
};
Members
lookup
struct tty_struct *()(struct tty_driver *self, struct file *, int idx)
Return the tty device corresponding to idx,
NULL
if there is not one currently in use and anERR_PTR
value on error. Called undertty_mutex
(for now!)Optional method. Default behaviour is to use the self->ttys array.
install
int ()(struct tty_driver *self, struct tty_struct *tty)
Install a new tty into the self’s internal tables. Used in conjunction with lookup and remove methods.
Optional method. Default behaviour is to use the self->ttys array.
remove
void ()(struct tty_driver *self, struct tty_struct *tty)
Remove a closed tty from the self’s internal tables. Used in conjunction with lookup and remove methods.
Optional method. Default behaviour is to use the self->ttys array.
open
int ()(struct tty_struct *tty, struct file *)
This routine is called when a particular tty device is opened. This routine is mandatory; if this routine is not filled in, the attempted open will fail with
ENODEV
.Required method. Called with tty lock held. May sleep.
close
void ()(struct tty_struct *tty, struct file *)
This routine is called when a particular tty device is closed. At the point of return from this call the driver must make no further ldisc calls of any kind.
Remark: called even if the corresponding open() failed.
Required method. Called with tty lock held. May sleep.
shutdown
void ()(struct tty_struct *tty)
This routine is called under the tty lock when a particular tty device is closed for the last time. It executes before the tty resources are freed so may execute while another function holds a tty kref.
cleanup
void ()(struct tty_struct *tty)
This routine is called asynchronously when a particular tty device is closed for the last time freeing up the resources. This is actually the second part of shutdown for routines that might sleep.
write
int ()(struct tty_struct *tty, const unsigned char *buf, int count)
This routine is called by the kernel to write a series (count) of characters (buf) to the tty device. The characters may come from user space or kernel space. This routine will return the number of characters actually accepted for writing.
May occur in parallel in special cases. Because this includes panic paths drivers generally shouldn’t try and do clever locking here.
Optional: Required for writable devices. May not sleep.
put_char
int ()(struct tty_struct *tty, unsigned char ch)
This routine is called by the kernel to write a single character ch to the tty device. If the kernel uses this routine, it must call the flush_chars() routine (if defined) when it is done stuffing characters into the driver. If there is no room in the queue, the character is ignored.
Optional: Kernel will use the write method if not provided. Do not call this function directly, call
tty_put_char()
.flush_chars
void ()(struct tty_struct *tty)
This routine is called by the kernel after it has written a series of characters to the tty device using put_char().
Optional. Do not call this function directly, call tty_driver_flush_chars().
write_room
unsigned int ()(struct tty_struct *tty)
This routine returns the numbers of characters the tty driver will accept for queuing to be written. This number is subject to change as output buffers get emptied, or if the output flow control is acted.
The ldisc is responsible for being intelligent about multi-threading of write_room/write calls
Required if write method is provided else not needed. Do not call this function directly, call tty_write_room()
chars_in_buffer
unsigned int ()(struct tty_struct *tty)
This routine returns the number of characters in the device private output queue. Used in tty_wait_until_sent() and for poll() implementation.
Optional: if not provided, it is assumed there is no queue on the device. Do not call this function directly, call tty_chars_in_buffer().
ioctl
int ()(struct tty_struct *tty, unsigned int cmd, unsigned long arg)
This routine allows the tty driver to implement device-specific ioctls. If the ioctl number passed in cmd is not recognized by the driver, it should return
ENOIOCTLCMD
.Optional.
compat_ioctl
long ()(struct tty_struct *tty, unsigned int cmd, unsigned long arg)
Implement ioctl processing for 32 bit process on 64 bit system.
Optional.
set_termios
void ()(struct tty_struct *tty, struct ktermios *old)
This routine allows the tty driver to be notified when device’s termios settings have changed. New settings are in tty->termios. Previous settings are passed in the old argument.
The API is defined such that the driver should return the actual modes selected. This means that the driver is responsible for modifying any bits in tty->termios it cannot fulfill to indicate the actual modes being used.
Optional. Called under the tty->termios_rwsem. May sleep.
throttle
void ()(struct tty_struct *tty)
This routine notifies the tty driver that input buffers for the line discipline are close to full, and it should somehow signal that no more characters should be sent to the tty.
Serialization including with unthrottle() is the job of the ldisc layer.
Optional: Always invoke via tty_throttle_safe(). Called under the tty->termios_rwsem.
unthrottle
void ()(struct tty_struct *tty)
This routine notifies the tty driver that it should signal that characters can now be sent to the tty without fear of overrunning the input buffers of the line disciplines.
Optional. Always invoke via tty_unthrottle(). Called under the tty->termios_rwsem.
stop
void ()(struct tty_struct *tty)
This routine notifies the tty driver that it should stop outputting characters to the tty device.
Called with tty->flow.lock held. Serialized with
start()
method.Optional. Always invoke via
stop_tty()
.start
void ()(struct tty_struct *tty)
This routine notifies the tty driver that it resumed sending characters to the tty device.
Called with tty->flow.lock held. Serialized with
stop()
method.Optional. Always invoke via
start_tty()
.hangup
void ()(struct tty_struct *tty)
This routine notifies the tty driver that it should hang up the tty device.
Optional. Called with tty lock held.
break_ctl
int ()(struct tty_struct *tty, int state)
This optional routine requests the tty driver to turn on or off BREAK status on the RS-232 port. If state is -1, then the BREAK status should be turned on; if state is 0, then BREAK should be turned off.
If this routine is implemented, the high-level tty driver will handle the following ioctls:
TCSBRK
,TCSBRKP
,TIOCSBRK
,TIOCCBRK
.If the driver sets
TTY_DRIVER_HARDWARE_BREAK
in tty_alloc_driver(), then the interface will also be called with actual times and the hardware is expected to do the delay work itself. 0 and -1 are still used for on/off.Optional: Required for
TCSBRK
/BRKP
/etc. handling. May sleep.flush_buffer
void ()(struct tty_struct *tty)
This routine discards device private output buffer. Invoked on close, hangup, to implement
TCOFLUSH
ioctl and similar.Optional: if not provided, it is assumed there is no queue on the device. Do not call this function directly, call tty_driver_flush_buffer().
set_ldisc
void ()(struct tty_struct *tty)
This routine allows the tty driver to be notified when the device’s line discipline is being changed. At the point this is done the discipline is not yet usable.
Optional. Called under the tty->ldisc_sem and tty->termios_rwsem.
wait_until_sent
void ()(struct tty_struct *tty, int timeout)
This routine waits until the device has written out all of the characters in its transmitter FIFO. Or until timeout (in jiffies) is reached.
Optional: If not provided, the device is assumed to have no FIFO. Usually correct to invoke via tty_wait_until_sent(). May sleep.
send_xchar
void ()(struct tty_struct *tty, char ch)
This routine is used to send a high-priority XON/XOFF character (ch) to the tty device.
Optional: If not provided, then the write method is called under the tty->atomic_write_lock to keep it serialized with the ldisc.
tiocmget
int ()(struct tty_struct *tty)
This routine is used to obtain the modem status bits from the tty driver.
Optional: If not provided, then
ENOTTY
is returned from theTIOCMGET
ioctl. Do not call this function directly, calltty_tiocmget()
.tiocmset
int ()(struct tty_struct *tty, unsigned int set, unsigned int clear)
This routine is used to set the modem status bits to the tty driver. First, clear bits should be cleared, then set bits set.
Optional: If not provided, then
ENOTTY
is returned from theTIOCMSET
ioctl. Do not call this function directly, calltty_tiocmset()
.resize
int ()(struct tty_struct *tty, struct winsize *ws)
Called when a termios request is issued which changes the requested terminal geometry to ws.
Optional: the default action is to update the termios structure without error. This is usually the correct behaviour. Drivers should not force errors here if they are not resizable objects (e.g. a serial line). See
tty_do_resize()
if you need to wrap the standard method in your own logic – the usual case.get_icount
int ()(struct tty_struct *tty, struct serial_icounter *icount)
Called when the tty device receives a
TIOCGICOUNT
ioctl. Passed a kernel structure icount to complete.Optional: called only if provided, otherwise
ENOTTY
will be returned.get_serial
int ()(struct tty_struct *tty, struct serial_struct *p)
Called when the tty device receives a
TIOCGSERIAL
ioctl. Passed a kernel structure p (struct serial_struct
) to complete.Optional: called only if provided, otherwise
ENOTTY
will be returned. Do not call this function directly, call tty_tiocgserial().set_serial
int ()(struct tty_struct *tty, struct serial_struct *p)
Called when the tty device receives a
TIOCSSERIAL
ioctl. Passed a kernel structure p (struct serial_struct
) to set the values from.Optional: called only if provided, otherwise
ENOTTY
will be returned. Do not call this function directly, call tty_tiocsserial().show_fdinfo
void ()(struct tty_struct *tty, struct seq_file *m)
Called when the tty device file descriptor receives a fdinfo request from VFS (to show in /proc/<pid>/fdinfo/). m should be filled with information.
Optional: called only if provided, otherwise nothing is written to m. Do not call this function directly, call tty_show_fdinfo().
poll_init
int ()(struct tty_driver *driver, int line, char *options)
kgdboc support (Using kgdb, kdb and the kernel debugger internals). This routine is called to initialize the HW for later use by calling poll_get_char or poll_put_char.
Optional: called only if provided, otherwise skipped as a non-polling driver.
poll_get_char
int ()(struct tty_driver *driver, int line)
kgdboc support (see poll_init). driver should read a character from a tty identified by line and return it.
Optional: called only if poll_init provided.
poll_put_char
void ()(struct tty_driver *driver, int line, char ch)
kgdboc support (see poll_init). driver should write character ch to a tty identified by line.
Optional: called only if poll_init provided.
proc_show
int ()(struct seq_file *m, void *driver)
Driver driver (cast to
struct tty_driver
) can show additional info in /proc/tty/driver/<driver_name>. It is enough to fill in the information into m.Optional: called only if provided, otherwise no /proc entry created.
Description
This structure defines the interface between the low-level tty driver and
the tty routines. These routines can be defined. Unless noted otherwise,
they are optional, and can be filled in with a NULL
pointer.