xref: /freebsd/share/man/man4/ng_tty.4 (revision 6990ffd8a95caaba6858ad44ff1b3157d1efba8f)
1.\" Copyright (c) 1996-1999 Whistle Communications, Inc.
2.\" All rights reserved.
3.\"
4.\" Subject to the following obligations and disclaimer of warranty, use and
5.\" redistribution of this software, in source or object code forms, with or
6.\" without modifications are expressly permitted by Whistle Communications;
7.\" provided, however, that:
8.\" 1. Any and all reproductions of the source or object code must include the
9.\"    copyright notice above and the following disclaimer of warranties; and
10.\" 2. No rights are granted, in any manner or form, to use Whistle
11.\"    Communications, Inc. trademarks, including the mark "WHISTLE
12.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
13.\"    such appears in the above copyright notice or in the software.
14.\"
15.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
16.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
17.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
18.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
19.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
20.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
21.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
22.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
23.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
24.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
25.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
26.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
27.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
31.\" OF SUCH DAMAGE.
32.\"
33.\" Author: Archie Cobbs <archie@FreeBSD.org>
34.\"
35.\" $FreeBSD$
36.\" $Whistle: ng_tty.8,v 1.5 1999/01/25 23:46:28 archie Exp $
37.\"
38.Dd January 19, 1999
39.Dt NG_TTY 4
40.Os
41.Sh NAME
42.Nm ng_tty
43.Nd netgraph node type that is also a line discipline
44.Sh SYNOPSIS
45.Fd #include <sys/ttycom.h>
46.Fd #include <netgraph/ng_message.h>
47.Fd #include <netgraph/ng_tty.h>
48.Sh DESCRIPTION
49The
50.Nm tty
51node type is both a netgraph node type and a line discipline.
52A new node is created when the corresponding line discipline,
53.Dv NETGRAPHDISC ,
54is registered on a tty device (see
55.Xr tty 4 ) .
56.Pp
57The node has a single hook called
58.Dv hook .
59Incoming bytes received on the tty device are sent out on this hook,
60and frames received on
61.Dv hook
62are transmitted out on the tty device.
63No modification to the data is performed in either direction.
64While the line discipline is installed on a tty, the normal
65read and write operations are unavailable, returning
66.Er EIO .
67.Pp
68The node supports an optional
69.Dq hot character .
70If set to non-zero, incoming
71data from the tty device is queued until this character is seen.
72This avoids sending lots of mbufs containing a small number of bytes,
73but introduces potentially infinite latency.
74The default hot character is 0x7e, consistent with
75.Dv hook
76being connected to a
77.Xr ng_async 4
78type node. The hot character has no effect on the transmission of data.
79.Pp
80The node will attempt to give itself the same netgraph name as the name
81of the tty device.
82In any case, information about the node is available via the netgraph
83.Xr ioctl 2
84command
85.Dv NGIOCGINFO .
86This command returns a
87.Dv "struct nodeinfo"
88similar to the
89.Dv NGM_NODEINFO
90netgraph control message.
91.Sh HOOKS
92This node type supports the following hooks:
93.Pp
94.Bl -tag -width foobar
95.It Dv hook
96.Xr tty 4
97serial data contained in
98.Dv mbuf
99structures, with arbitrary inter-frame boundaries.
100.El
101.Sh CONTROL MESSAGES
102This node type supports the generic control messages, plus the following:
103.Bl -tag -width foo
104.It Dv NGM_TTY_SET_HOTCHAR
105This command takes an integer argument and sets the hot character
106from the lower 8 bits. A hot character of zero disables queueing,
107so that all received data is forwarded immediately.
108.It Dv NGM_TTY_GET_HOTCHAR
109Returns an integer containing the current hot character in the lower
110eight bits.
111.El
112.Sh SHUTDOWN
113This node shuts down when the corresponding device is closed
114(or the line discipline is uninstalled on the device).
115The
116.Dv NGM_SHUTDOWN
117control message is not valid, and always returns the error
118.Er EOPNOTSUPP .
119.Sh BUGS
120The serial driver code also has a notion of a
121.Dq hot character .
122Unfortunately, this value is statically defined in terms of the
123line discipline and cannot be changed.
124Therefore, if a hot character other than 0x7e (the default) is set for the
125.Nm
126node, the node has no way to convey this information to the
127serial driver, and sub-optimal performance may result.
128.Sh SEE ALSO
129.Xr ioctl 2 ,
130.Xr netgraph 4 ,
131.Xr ng_async 4 ,
132.Xr tty 4 ,
133.Xr ngctl 8
134.Sh HISTORY
135The
136.Nm
137node type was implemented in
138.Fx 4.0 .
139.Sh AUTHORS
140.An Archie Cobbs Aq archie@FreeBSD.org
141