1.\"	$OpenBSD: tb.4,v 1.9 2004/03/21 19:47:59 miod Exp $
2.\"	$NetBSD: tb.4,v 1.3.6.1 1996/05/31 00:37:45 cgd Exp $
3.\"
4.\" Copyright (c) 1986, 1991 Regents of the University of California.
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\"    may be used to endorse or promote products derived from this software
17.\"    without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\"     @(#)tb.4	6.4 (Berkeley) 3/27/91
32.\"
33.Dd March 27, 1991
34.Dt TB 4
35.Os
36.Sh NAME
37.Nm tb
38.Nd line discipline for digitizing devices
39.Sh SYNOPSIS
40.Cd "pseudo-device tb" Op Ar count
41.Sh DESCRIPTION
42This line discipline provides a polled interface to many common
43digitizing devices which are connected to a host through a serial line.
44When these devices stream data at high speed, the use of the
45line discipline is critical in minimizing the number of samples
46that would otherwise be lost due to buffer exhaustion in the
47.Xr tty 4
48handler.
49.Pp
50The line discipline is enabled by a sequence:
51.Bd -literal -offset indent
52#include <sys/tablet.h>
53int ldisc = TABLDISC, fildes; ...
54ioctl(fildes, TIOCSETD, &ldisc);
55.Ed
56.Pp
57A typical application program then polls the digitizing device by
58reading a binary data structure which contains: the current X and
59Y positions (in the device coordinate space),
60up-down status of the buttons or pen stylus,
61proximity information (when available), and a count
62of the number of samples received from the input device
63since it was opened.
64In addition, devices such as the
65.Tn GTCO
66append tilt and pressure information to the end of
67the aforementioned structure.
68For the Polhemus 3-D digitizer the structure read is completely different.
69Refer to the include file for a complete description.
70.Pp
71While in tablet mode, normal teletype input and output functions take place.
72Thus, if an 8 bit output data path is desired, it is necessary
73to prepare the output line by putting it into
74.Tn RAW
75mode using
76.Xr ioctl 2 .
77This must be done
78.Em before
79changing the discipline with
80.Dv TIOCSETD ,
81as most
82.Xr ioctl 2
83calls are disabled while in tablet line-discipline mode.
84.Pp
85The line discipline supports
86.Xr ioctl 2
87requests to get/set the operating mode, and to get/set the tablet type
88and operating mode by
89.Em or Ns -ing
90the two values together.
91.Pp
92Calling
93.Xr read 2
94on the device always succeeds, returning the last sample,
95although the
96.Xr select 2
97and
98.Xr poll 2
99system calls will correctly report the read state for new samples.
100.Pp
101The line discipline supports digitizing devices which are
102compatible with Hitachi,
103.Tn GTCO ,
104or Polhemus protocol formats.
105For Hitachi there are several formats with that used in the
106newer model
107.Tn HDG-1111B
108the most common.
109.Sh DIAGNOSTICS
110None.
111.Sh SEE ALSO
112.Xr tty 4
113.Sh HISTORY
114The
115.Nm
116interface appeared in
117.Bx 4.3 .
118