diff options
Diffstat (limited to 'sys/modules/netgraph/tty/ng_tty.4')
-rw-r--r-- | sys/modules/netgraph/tty/ng_tty.4 | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/sys/modules/netgraph/tty/ng_tty.4 b/sys/modules/netgraph/tty/ng_tty.4 new file mode 100644 index 0000000..660b46c --- /dev/null +++ b/sys/modules/netgraph/tty/ng_tty.4 @@ -0,0 +1,141 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs <archie@whistle.com> +.\" +.\" $FreeBSD$ +.\" $Whistle: ng_tty.8,v 1.5 1999/01/25 23:46:28 archie Exp $ +.\" +.Dd January 19, 1999 +.Dt NG_TTY 8 +.Os FreeBSD 3 +.Sh NAME +.Nm ng_tty +.Nd netgraph node type that is also a line discipline +.Sh SYNOPSIS +.Fd #include <netgraph/ng_message.h> +.Fd #include <netgraph/ng_tty.h> +.Sh DESCRIPTION +The +.Nm tty +node type is both a netgraph node type and a line discipline. +A new node is created when the corresponding line discipline is +registered on a tty device (see +.Xr tty 4 ")." +.Pp +The node has a single hook called +.Dv hook . +Incoming bytes received on the tty device are sent out on this hook, +and frames received on +.Dv hook +are transmitted out on the tty device. +No modification to the data is performed in either direction. +While the line discipline is installed on a tty, the normal +read and write operations are unavailable, returning +.Er EIO . +.Pp +The node supports an optional ``hot character.'' If set to non-zero, incoming +data from the tty device is queued until this character is seen. +This avoids sending lots of mbufs containing a small number of bytes, +but introduces potentially infinite latency. +The default hot character is 0x7e, consistent with +.Dv hook +being connected to a +.Xr ng_async 8 +type node. The hot character has no effect on the transmission of data. +.Pp +The node will attempt to give itself the same netgraph name as the name +of the tty device. +In any case, information about the node is available via the netgraph +.Xr ioctl 2 +command +.Dv NGIOCGINFO . +This command returns a +.Dv "struct nodeinfo" +similar to the +.Dv NGM_NODEINFO +netgraph control message. +.Sh HOOKS +This node type supports the following hooks: +.Pp +.Bl -tag -width foobar +.It Dv hook +.Xr tty 4 +serial data contained in +.Dv mbuf +structures, with arbitrary inter-frame boundaries. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_TTY_SET_HOTCHAR +This command takes an integer argument and sets the hot character +from the lower 8 bits. A hot character of zero disables queueing, +so that all received data is forwarded immediately. +.It Dv NGM_TTY_GET_HOTCHAR +Returns an integer containing the current hot character in the lower +eight bits. +.Sh SHUTDOWN +This node shuts down when the corresponding device is closed +(or the line discipline is uninstalled on the device). +The +.Dv NGM_SHUTDOWN +control message is not valid, and always returns the error +.Er EOPNOTSUPP . +.Sh BUGS +The +.Nm tty +type registers its line discipline when the type is installed, +where it is dynamically assigned an integer index. +Unfortunately, there's no way to know what this integer is +except by reading the output of +.Xr dmesg 8 . +The fix for this is to have line disciplines identified by +unique ASCII strings instead of fixed integer constants, +or else to assign one of those constants to +.Nm ng_tty . +.Pp +The serial driver code also has a notion of a ``hot character.'' +Unfortunately, this value is statically defined in terms of the +line discipline and cannot be changed. +Therefore, if a hot character other than 0x7e (the default) is set for the +.Nm tty +node, the node has no way to convey this information to the +serial driver, and sub-optimal performance may result. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr netgraph 4 , +.Xr tty 4 , +.Xr ng_async 8 , +.Xr ngctl 8 . +.Sh AUTHOR +Archie Cobbs <archie@whistle.com> |