NetBSD/share/man/man9/wsdisplay.9

.\"     $NetBSD: wsdisplay.9,v 1.7 2002/06/22 19:09:38 bjh21 Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON 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 ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd June 22, 2002
.Dt WSDISPLAY 9
.Os
.Sh NAME
.Nm wsdisplay ,
.Nm wsdisplay_switchtoconsole ,
.Nm wsdisplay_cnattach ,
.Nm wsdisplaydevprint ,
.Nm wsemuldisplaydevprint
.Nd wscons display support
.Sh SYNOPSIS
.Fd #include \*[Lt]dev/wscons/wsconsio.h\*[Gt]
.Fd #include \*[Lt]dev/wscons/wsdisplayvar.h\*[Gt]
.Fd #include \*[Lt]dev/wscons/wsemulvar.h\*[Gt]
.Fd #include \*[Lt]dev/wscons/wsemul_vt100var.h\*[Gt]
.Ft void
.Fn wsdisplay_switchtoconsole ""
.Ft void
.Fn wsdisplay_cnattach "const struct wsscreen_descr *type" "void *cookie" \
"int ccol" "int crow" "long defattr"
.Ft void
.Fn wsemul_xxx_cnattach "const struct wsscreen_descr *type" "void *cookie" \
"int ccol" "int crow" "long defattr"
.Ft int
.Fn wsdisplaydevprint "void *aux" "const char *pnp"
.Ft int
.Fn wsemuldisplaydevprint "void * aux" "const char *pnp"
.Sh DESCRIPTION
The
.Nm
module is a component of the
.Xr wscons 9
framework to provide machine-independent display support.  Most of the
support is provided by the
.Xr wsdisplay 4
device driver, which must be a child of the hardware device driver.
.Pp
The wscons display interface is complicated by the fact that there are
two different interfaces.  The first interface corresponds to the
simple bit-mapped display which doesn't provide terminal-emulation and
console facilities.  The second interface provides machine-independent
terminal emulation for displays that can support glass-tty terminal
emulations.  These are character-oriented displays, with row and
column numbers starting at zero in the upper left hand corner of the
screen.  Display drivers which cannot emulate terminals use the first
interface.  In most cases, the low-level hardware driver can use the
.Xr rasops 9
interface to provide enough support to allow glass-tty terminal
emulation.  If the display is not the console, terminal emulation does
not make sense and the display operates using the bit-mapped
interface.
.Pp
The wscons framework allows concurrent displays to be active.  It also
provides support for multiple screens for each display and therefore
allows a virtual terminal on each screen.  Multiple terminal
emulations and fonts can be active at the same time allowing different
emulations and fonts for each screen.
.Pp
Font manipulation facilities for the terminal emulation interface are
available through the
.Xr wsfont 9
module.
.Sh DATA TYPES
Display drivers providing support for wscons displays will make use
of the following data types:
.Bl -tag -width compact
.It Fa struct wsdisplay_accessops
A structure used to specify the display access functions invoked by
userland program which require direct device access, such as X11.  All
displays must provide this structure and pass it to the
.Xr wsdisplay 4
child device.  It has the following members:
.Bd -literal
	int	(*ioctl)(void *v, u_long cmd, caddr_t data,
			int flag, struct proc *p);
	paddr_t	(*mmap)(void *v, off_t off, int prot);
	int	(*alloc_screen)(void *,
			const struct wsscreen_descr *, void **,
			int *, int *, long *);
	void	(*free_screen)(void *, void *);
	int	(*show_screen)(void *, void *, int,
			void (*)(), void *);
	int	(*load_font)(void *, void *,
			struct wsdisplay_font *);
	void	(*pollc)(void *, int);
.Ed
.Pp
The
.Fa ioctl
member defines the function to be called to perform display-specific
ioctl calls.  The
.Fa mmap
member defines the function for mapping a part of the display device
into user address space.  The
.Fa alloc_screen
member defines a function for allocating a new screen which can be
used as a virtual terminal.  The
.Fa free_screen
member defines a function for de-allocating a screen.  The
.Fa show_screen
member defines a function for mapping a screen onto the physical
display.  This function is used for between switching screens.  The
.Fa load_font
member defines a function for loading a new font into the display.
The
.Fa pollc
member defines a function for polling the console.
.Pp
There is a
.Fa void *
cookie provided by the display driver associated with these
functions, which is passed to them when they are invoked.
.It Fa struct wsdisplaydev_attach_args
A structure used to attach the
.Xr wsdisplay 4
child device for the simple bit-mapped interface.  If the full
terminal-emulation interface is to be used, then
.Em struct wsemuldisplaydev_attach_args
should be used instead.  It has the following members:
.Bd -literal
	const struct wsdisplay_accessops *accessops;
	void *accesscookie;
.Ed
.It Fa struct wsemuldisplaydev_attach_args
A structure used to attach the
.Xr wsdisplay 4
child device for the full terminal emulation interface.  If the simple
bit-mapped interface is to be used, then
.Em struct wsdisplaydev_attach_args
should be used instead.  It has the following members:
.Bd -literal
	int console;
	const struct wsscreen_list *scrdata;
	const struct wsdisplay_accessops *accessops;
	void *accesscookie;
.Ed
.It Fa struct wsdisplay_emulops
A structure used to specify the display emulation functions.  All
displays intending to provide terminal emulation must must provide
this structure and pass it to the
.Xr wsdisplay 4
child device.  It has the following members:
.Bd -literal
	void	(*cursor)(void *c, int on, int row, int col);
	int	(*mapchar)(void *, int, unsigned int *);
	void	(*putchar)(void *c, int row, int col,
			u_int uc, long attr);
	void	(*copycols)(void *c, int row, int srccol,
			int dstcol, int ncols);
	void	(*erasecols)(void *c, int row, int startcol,
			int ncols, long);
	void	(*copyrows)(void *c, int srcrow, int dstrow,
			int nrows);
	void	(*eraserows)(void *c, int row, int nrows, long);
	int	(*alloc_attr)(void *c, int fg, int bg, int flags,
			long *);
.Ed
.Pp
There is a
.Fa void *
cookie provided by the display driver associated with these
functions, which is passed to them when they are invoked.
.It Fa struct wsscreen_descr
A structure passed to wscons by the display driver to describe a
screen.  All displays which can operate as a console must provide this
structure and pass it to the
.Xr wsdisplay 4
child device.  It contains the following members:
.Bd -literal
        char *name;
        int ncols, nrows;
        const struct wsdisplay_emulops *textops;
        int fontwidth, fontheight;
        int capabilities;
.Ed
.Pp
The
.Em capabilities
member is a set of flags describing the screen capabilities.  It can
contain the following flags:
.Pp
.Bl -tag -offset indent -width WSSCREEN_UNDERLINE -compact
.It WSSCREEN_WSCOLORS
minimal color capability
.It WSSCREEN_REVERSE
can display reversed
.It WSSCREEN_HILIT
can highlight (however)
.It WSSCREEN_BLINK
can blink
.It WSSCREEN_UNDERLINE
can underline
.El
.It Fa struct wsscreen_list
A structure passed to wscons by the display driver to tell about its
capabilities.  It contains the following members:
.Bd -literal
	int nscreens;
	const struct wsscreen_descr **screens;
.Ed
.It Fa struct wscons_syncops
A structure passed to wscons by the display driver describing the
interface for external screen switching/process synchronization.
This structure is optional and only required by displays operating
with terminal emulation and intending to support multiple screens.  It
contains the following members:
.Bd -literal
	int	(*detach)(void *, int, void (*)(), void *);
	int	(*attach)(void *, int, void (*)(), void *);
	int	(*check)(void *);
	void	(*destroy)(void *);
.Ed
.El
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn wsdisplay_switchtoconsole ""
Switch the console display to its first screen.
.It Fn wsdisplay_cnattach "type" "cookie" "ccol" "crow" "defattr"
Attach this display as the console input by specifying the number of
columns
.Fa ccol
and number of rows
.Fa crows .
The argument
.Fa defattr
specifies the default attribute (color) for the console.
.It Fn wsemul_xxx_cnattach "type" "cookie" "ccol" "crow" "defattr"
Attach this display as the console with terminal emulation described
by the
.Em xxx
and specifying the number of columns
.Fa ccol
and number of rows
.Fa crows .
The argument
.Fa defattr
specifies the default attribute (color) for the console.  Different
terminal emulations can be active at the same time on one display.
.It Fn wsdisplaydevprint "aux" "pnp"
The default wsdisplay printing routine used by
.Fn config_found .
(see
.Xr autoconf 9 ) .
.It Fn wsemuldisplaydevprint "aux" "pnp"
The default wsemul printing routine used by
.Fn config_found .
(see
.Xr autoconf 9 ) .
.El
.Sh AUTOCONFIGURATION
Display drivers which want to utilize the wsdisplay module must be a
parent to the
.Xr wsdisplay 4
device and provide an attachment interface.  To attach the
.Xr wsdisplay 4
device, the display driver must allocate and populate a
.Fa wsdisplaydev_attach_args
structure with the supported operations and callbacks and call
.Fn config_found
to perform the attach (see
.Xr autoconf 9 ) .
.Pp
Display drivers which want to utilize the wscons terminal emulation
module must be a parent to the
.Xr wsdisplay 4
device and provide a
.Fa wsemuldisplaydev_attach_args
structure instead of the standard
.Fa wsdisplaydev_attach_args
to
.Fn config_found
to perform the attach.  If the display is not the console the
attachment is the same as wsdisplaydev_attach_args.
.Sh OPERATION
If the display belongs to the system console, it must describe the
default screen by invoking
.Fn wsdisplay_cnattach
at console attach time.
.Pp
All display manipulation is performed by the wscons interface by using
the callbacks defined in the
.Em wsdisplay_accessops
structure.  The
.Fn ioctl
function is called by the wscons interface to perform display-specific
ioctl operations (see
.Xr ioctl 2 ) .
The argument
.Fa cmd
to the
.Fn ioctl
function specifies the specific command to perform using the data
data.  Valid commands are listed in
.Pa sys/dev/wscons/wsconsio.h
and documented in
.Xr wsdisplay 4 .
Operations for terminal emulation are performed using the callbacks
defined in the
.Em wsdisplay_emulops
structure.
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or utilizing the
machine-independent wscons subsystem can be found.  All pathnames are
relative to
.Pa /usr/src .
.Pp
The wscons subsystem is implemented within the directory
.Pa sys/dev/wscons .
The
.Nm
module itself is implemented within the file
.Pa sys/dev/wscons/wsdisplay.c .
The terminal emulation support
is implemented within the files
.Pa sys/dev/wscons/wsemul_* .
.Xr ioctl 2
operations are listed in
.Pa sys/dev/wscons/wsconsio.h .
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr wsdisplay 4 ,
.Xr autoconf 9 ,
.Xr driver 9 ,
.Xr intro 9 ,
.Xr rasops 9 ,
.Xr wsfont 9 ,
.Xr wskbd 9 ,
.Xr wsmouse 9