.\"     $NetBSD: wsdisplay.9,v 1.23 2010/12/02 12:54:13 wiz Exp $
.\"
.\" Copyright (c) 2001, 2004 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.
.\"
.\" 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 April 15, 2006
.Dt WSDISPLAY 9
.Os
.Sh NAME
.Nm wsdisplay ,
.Nm wsdisplay_switchtoconsole ,
.Nm wsdisplay_cnattach ,
.Nm wsdisplaydevprint ,
.Nm wsemuldisplaydevprint
.Nd wscons display support
.Sh SYNOPSIS
.In dev/wscons/wsconsio.h
.In dev/wscons/wsdisplayvar.h
.In dev/wscons/wsemulvar.h
.In dev/wscons/wsemul_vt100var.h
.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, void *vs, u_long cmd,
			void *data, int flag, struct lwp *l);
	paddr_t	(*mmap)(void *v, void *vs, 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);
	void	(*scroll)(void *, 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 switching between 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.
The
.Fa scroll
member defines a function for scrolling the contents of the display.
.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.
.Pp
The
.Fa void *vs
cookie, passed to
.Fn ioctl
and
.Fn mmap ,
points to the virtual screen on which these operations were executed.
.It Fa struct wsdisplaydev_attach_args
A structure used to attach the
.Xr wsdisplay 4
child device for the simple bit-mapped interface.
It has the following members:
.Bd -literal
	const struct wsdisplay_accessops *accessops;
	void *accesscookie;
.Ed
If the full terminal-emulation interface is to be used, then
.Em struct wsemuldisplaydev_attach_args
should be used instead.
.It Fa struct wsemuldisplaydev_attach_args
A structure used to attach the
.Xr wsdisplay 4
child device for the full terminal emulation interface.
It has the following members:
.Bd -literal
	int console;
	const struct wsscreen_list *scrdata;
	const struct wsdisplay_accessops *accessops;
	void *accesscookie;
.Ed
If the simple bit-mapped interface is to be used, then
.Em struct wsdisplaydev_attach_args
should be used instead.
.It Fa struct wsdisplay_emulops
A structure used to specify the display emulation functions.
All displays intending to provide terminal emulation 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	(*allocattr)(void *c, int fg, int bg, int flags,
			long *);
	void	(*replaceattr)(void *c, long oldattr,
			long newattr);
.Ed
.Pp
The
.Fa cursor
member defines a function for painting (or unpainting, depending on the
.Va on
parameter) the cursor at the specified position.
The
.Fa mapchar
member defines a function for changing the character mapped at a given
position in the character table.
The
.Fa putchar
member defines a function for writing a character on the screen, given
its position and attribute.
The
.Fa copycols
member defines a function for copying a set of columns within the same
line.
The
.Fa erasecols
member defines a function for clearing a set of columns in a line,
filling the space with the given attribute.
The
.Fa copyrows
member defines a function for copying a set of complete rows.
The
.Fa eraserows
member defines a function for clearing a set of complete rows,
filling the space with the given attribute.
The
.Fa allocattr
member defines a function for converting an attribute specification
given by its foreground color, background color and flags, to the
internal representation used by the underlying graphics driver.
The
.Fa replaceattr
member defines a function for replacing an attribute by another one
across the whole visible part of the screen; this function is optional.
.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 use 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 use 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
.Fa 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
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