xref: /netbsd/share/man/man9/wsdisplay.9 (revision bf9ec67e)
1.\"     $NetBSD: wsdisplay.9,v 1.6 2002/03/10 18:39:42 wiz Exp $
2.\"
3.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Gregory McGarry.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"        This product includes software developed by the NetBSD
20.\"        Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\"    contributors may be used to endorse or promote products derived
23.\"    from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
37.Dd October 7, 2001
38.Dt WSDISPLAY 9
39.Os
40.Sh NAME
41.Nm wsdisplay ,
42.Nm wsdisplay_switchtoconsole ,
43.Nm wsdisplay_cnattach ,
44.Nm wsdisplaydevprint ,
45.Nm wsemuldisplaydevprint
46.Nd wscons display support
47.Sh SYNOPSIS
48.Fd #include \*[Lt]dev/wscons/wsconsio.h\*[Gt]
49.Fd #include \*[Lt]dev/wscons/wsdisplayvar.h\*[Gt]
50.Fd #include \*[Lt]dev/wscons/wsemulvar.h\*[Gt]
51.Fd #include \*[Lt]dev/wscons/wsemul_vt100var.h\*[Gt]
52.Ft void
53.Fn wsdisplay_switchtoconsole ""
54.Ft void
55.Fn wsdisplay_cnattach "const struct wsscreen_descr *type" "void *cookie" \
56"int ccol" "int crow" "long defattr"
57.Ft void
58.Fn wsemul_xxx_cnattach "const struct wsscreen_descr *type" "void *cookie" \
59"int ccol" "int crow" "long defattr"
60.Ft int
61.Fn wsdisplaydevprint "void *aux" "const char *pnp"
62.Ft int
63.Fn wsemuldisplaydevprint "void * aux" "const char *pnp"
64.Sh DESCRIPTION
65The
66.Nm
67module is a component of the
68.Xr wscons 9
69framework to provide machine-independent display support.  Most of the
70support is provided by the
71.Xr wsdisplay 4
72device driver, which must be a child of the hardware device driver.
73.Pp
74The wscons display interface is complicated by the fact that there are
75two different interfaces.  The first interface corresponds to the
76simple bit-mapped display which doesn't provide terminal-emulation and
77console facilities.  The second interface provides machine-independent
78terminal emulation for displays that can support glass-tty terminal
79emulations.  These are character-oriented displays, with row and
80column numbers starting at zero in the upper left hand corner of the
81screen.  Display drivers which cannot emulate terminals use the first
82interface.  In most cases, the low-level hardware driver can use the
83.Xr rasops 9
84interface to provide enough support to allow glass-tty terminal
85emulation.  If the display is not the console, terminal emulation does
86not make sense and the display operates using the bit-mapped
87interface.
88.Pp
89The wscons framework allows concurrent displays to be active.  It also
90provides support for multiple screens for each display and therefore
91allows a virtual terminal on each screen.  Multiple terminal
92emulations and fonts can be active at the same time allowing different
93emulations and fonts for each screen.
94.Pp
95Font manipulation facilities for the terminal emulation interface are
96available through the
97.Xr wsfont 9
98module.
99.Sh DATA TYPES
100Display drivers providing support for wscons displays will make use
101of the following data types:
102.Bl -tag -width compact
103.It Fa struct wsdisplay_accessops
104A structure used to specify the display access functions invoked by
105userland program which require direct device access, such as X11.  All
106displays must provide this structure and pass it to the
107.Xr wsdisplay 4
108child device.  It has the following members:
109.Bd -literal
110	int	(*ioctl)(void *v, u_long cmd, caddr_t data,
111			int flag, struct proc *p);
112	paddr_t	(*mmap)(void *v, off_t off, int prot);
113	int	(*alloc_screen)(void *,
114			const struct wsscreen_descr *, void **,
115			int *, int *, long *);
116	void	(*free_screen)(void *, void *);
117	int	(*show_screen)(void *, void *, int,
118			void (*)(), void *);
119	int	(*load_font)(void *, void *,
120			struct wsdisplay_font *);
121	void	(*pollc)(void *, int);
122.Ed
123.Pp
124The
125.Fa ioctl
126member defines the function to be called to perform display-specific
127ioctl calls.  The
128.Fa mmap
129member defines the function for mapping a part of the display device
130into user address space.  The
131.Fa alloc_screen
132member defines a function for allocating a new screen which can be
133used as a virtual terminal.  The
134.Fa free_screen
135member defines a function for de-allocating a screen.  The
136.Fa show_screen
137member defines a function for mapping a screen onto the physical
138display.  This function is used for between switching screens.  The
139.Fa load_font
140member defines a function for loading a new font into the display.
141The
142.Fa pollc
143member defines a function for polling the console.
144.Pp
145There is a
146.Fa void *
147cookie provided by the display driver associated with these
148functions, which is passed to them when they are invoked.
149.It Fa struct wsdisplaydev_attach_args
150A structure used to attach the
151.Xr wsdisplay 4
152child device for the simple bit-mapped interface.  If the full
153terminal-emulation interface is to be used, then
154.Em struct wsemuldisplaydev_attach_args
155should be used instead.  It has the following members:
156.Bd -literal
157	const struct wsdisplay_accessops *accessops;
158	void *accesscookie;
159.Ed
160.It Fa struct wsemuldisplaydev_attach_args
161A structure used to attach the
162.Xr wsdisplay 4
163child device for the full terminal emulation interface.  If the simple
164bit-mapped interface is to be used, then
165.Em struct wsdisplaydev_attach_args
166should be used instead.  It has the following members:
167.Bd -literal
168	int console;
169	const struct wsscreen_list *scrdata;
170	const struct wsdisplay_accessops *accessops;
171	void *accesscookie;
172.Ed
173.It Fa struct wsdisplay_emulops
174A structure used to specify the display emulation functions.  All
175displays intending to provide terminal emulation must must provide
176this structure and pass it to the
177.Xr wsdisplay 4
178child device.  It has the following members:
179.Bd -literal
180	void	(*cursor)(void *c, int on, int row, int col);
181	int	(*mapchar)(void *, int, unsigned int *);
182	void	(*putchar)(void *c, int row, int col,
183			u_int uc, long attr);
184	void	(*copycols)(void *c, int row, int srccol,
185			int dstcol, int ncols);
186	void	(*erasecols)(void *c, int row, int startcol,
187			int ncols, long);
188	void	(*copyrows)(void *c, int srcrow, int dstrow,
189			int nrows);
190	void	(*eraserows)(void *c, int row, int nrows, long);
191	int	(*alloc_attr)(void *c, int fg, int bg, int flags,
192			long *);
193.Ed
194.Pp
195There is a
196.Fa void *
197cookie provided by the display driver associated with these
198functions, which is passed to them when they are invoked.
199.It Fa struct wsscreen_descr
200A structure passed to wscons by the display driver to describe a
201screen.  All displays which can operate as a console must provide this
202structure and pass it to the
203.Xr wsdisplay 4
204child device.  It contains the following members:
205.Bd -literal
206        char *name;
207        int ncols, nrows;
208        const struct wsdisplay_emulops *textops;
209        int fontwidth, fontheight;
210        int capabilities;
211.Ed
212.Pp
213The
214.Em capabilities
215member is a set of flags describing the screen capabilities.  It can
216contain the following flags:
217.Pp
218.Bl -tag -offset indent -width WSSCREEN_UNDERLINE -compact
219.It WSSCREEN_WSCOLORS
220minimal color capability
221.It WSSCREEN_REVERSE
222can display reversed
223.It WSSCREEN_HILIT
224can highlight (however)
225.It WSSCREEN_BLINK
226can blink
227.It WSSCREEN_UNDERLINE
228can underline
229.El
230.It Fa struct wsscreen_list
231A structure passed to wscons by the display driver to tell about its
232capabilities.  It contains the following members:
233.Bd -literal
234	int nscreens;
235	const struct wsscreen_descr **screens;
236.Ed
237.It Fa struct wscons_syncops
238A structure passed to wscons by the display driver describing the
239interface for external screen switching/process synchronization.
240This structure is optional and only required by displays operating
241with terminal emulation and intending to support multiple screens.  It
242contains the following members:
243.Bd -literal
244	int	(*detach)(void *, int, void (*)(), void *);
245	int	(*attach)(void *, int, void (*)(), void *);
246	int	(*check)(void *);
247	void	(*destroy)(void *);
248.Ed
249.El
250.Sh FUNCTIONS
251.Bl -tag -width compact
252.It Fn wsdisplay_switchtoconsole ""
253Switch the console display to its first screen.
254.It Fn wsdisplay_cnattach "type" "cookie" "ccol" "crow" "defattr"
255Attach this display as the console input by specifying the number of
256columns
257.Fa ccol
258and number of rows
259.Fa crows .
260The argument
261.Fa defattr
262specifies the default attribute (color) for the console.
263.It Fn wsemul_xxx_cnattach "type" "cookie" "ccol" "crow" "defattr"
264Attach this display as the console with terminal emulation described
265by the
266.Em xxx
267and specifying the number of columns
268.Fa ccol
269and number of rows
270.Fa crows .
271The argument
272.Fa defattr
273specifies the default attribute (color) for the console.  Different
274terminal emulations can be active at the same time on one display.
275.It Fn wsdisplaydevprint "aux" "pnp"
276The default wsdisplay printing routine used by
277.Fn config_found .
278(see
279.Xr autoconf 9 ) .
280.It Fn wsemuldisplaydevprint "aux" "pnp"
281The default wsemul printing routine used by
282.Fn config_found .
283(see
284.Xr autoconf 9 ) .
285.El
286.Sh AUTOCONFIGURATION
287Display drivers which want to utilize the wsdisplay module must be a
288parent to the
289.Xr wsdisplay 4
290device and provide an attachment interface.  To attach the
291.Xr wsdisplay 4
292device, the display driver must allocate and populate a
293.Fa wsdisplaydev_attach_args
294structure with the supported operations and callbacks and call
295.Fn config_found
296to perform the attach (see
297.Xr autoconf 9 ) .
298.Pp
299Display drivers which want to utilize the wscons terminal emulation
300module must be a parent to the
301.Xr wsdisplay 4
302device and provide a
303.Fa wsemuldisplaydev_attach_args
304structure instead of the standard
305.Fa wsdisplaydev_attach_args
306to
307.Fn config_found
308to perform the attach.  If the display is not the console the
309attachment is the same as wsdisplaydev_attach_args.
310.Sh OPERATION
311If the display belongs to the system console, it must describe the
312default screen by invoking
313.Fn wsdisplay_cnattach
314at console attach time.
315.Pp
316All display manipulation is performed by the wscons interface by using
317the callbacks defined in the
318.Em wsdisplay_accessops
319structure.  The
320.Fn ioctl
321function is called by the wscons interface to perform display-specific
322ioctl operations (see
323.Xr ioctl 2 ) .
324The argument
325.Fa cmd to the
326.Fn ioctl
327function specifies the specific command to perform using the data
328data.  Valid commands are listed in
329.Pa sys/dev/wscons/wsconsio.h .
330Operations for terminal emulation are performed using the callbacks
331defined in the
332.Em wsdisplay_emulops
333structure.
334.Sh CODE REFERENCES
335This section describes places within the
336.Nx
337source tree where actual code implementing or utilizing the
338machine-independent wscons subsystem can be found.  All pathnames are
339relative to
340.Pa /usr/src .
341.Pp
342The wscons subsystem is implemented within the directory
343.Pa sys/dev/wscons .
344The
345.Nm
346module itself is implemented within the file
347.Pa sys/dev/wscons/wsdisplay.c .
348The terminal emulation support
349is implemented within the files
350.Pa sys/dev/wscons/wsemul_* .
351.Xr ioctl 2
352operations are listed in
353.Pa sys/dev/wscons/wsconsio.h .
354.Sh SEE ALSO
355.Xr ioctl 2 ,
356.Xr autoconf 9 ,
357.Xr driver 9 ,
358.Xr intro 9 ,
359.Xr rasops 9 ,
360.Xr wsfont 9 ,
361.Xr wskbd 9 ,
362.Xr wsmouse 9
363