NetBSD/share/man/man9/wsdisplay.9

385 lines
12 KiB
Groff
Raw Normal View History

.\" $NetBSD: wsdisplay.9,v 1.13 2003/04/16 13:35:36 wiz Exp $
2001-10-22 07:29:58 +04:00
.\"
.\" 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
2001-10-22 07:29:58 +04:00
.\" 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
2001-10-22 07:29:58 +04:00
.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
2001-10-22 07:29:58 +04:00
.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
2002-10-14 17:43:14 +04:00
framework to provide machine-independent display support.
Most of the support is provided by the
2001-10-22 07:29:58 +04:00
.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
2002-10-14 17:43:14 +04:00
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
2001-10-22 07:29:58 +04:00
.Xr rasops 9
interface to provide enough support to allow glass-tty terminal
2002-10-14 17:43:14 +04:00
emulation.
If the display is not the console, terminal emulation does not make
sense and the display operates using the bit-mapped interface.
2001-10-22 07:29:58 +04:00
.Pp
2002-10-14 17:43:14 +04:00
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.
2001-10-22 07:29:58 +04:00
.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
2002-10-14 17:43:14 +04:00
userland program which require direct device access, such as X11.
All displays must provide this structure and pass it to the
2001-10-22 07:29:58 +04:00
.Xr wsdisplay 4
2002-10-14 17:43:14 +04:00
child device.
It has the following members:
2001-10-22 07:29:58 +04:00
.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
2002-10-14 17:43:14 +04:00
ioctl calls.
The
2001-10-22 07:29:58 +04:00
.Fa mmap
member defines the function for mapping a part of the display device
2002-10-14 17:43:14 +04:00
into user address space.
The
2001-10-22 07:29:58 +04:00
.Fa alloc_screen
member defines a function for allocating a new screen which can be
2002-10-14 17:43:14 +04:00
used as a virtual terminal.
The
2001-10-22 07:29:58 +04:00
.Fa free_screen
2002-10-14 17:43:14 +04:00
member defines a function for de-allocating a screen.
The
2001-10-22 07:29:58 +04:00
.Fa show_screen
member defines a function for mapping a screen onto the physical
2002-10-14 17:43:14 +04:00
display.
This function is used for between switching screens.
The
2001-10-22 07:29:58 +04:00
.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
2002-10-14 17:43:14 +04:00
child device for the simple bit-mapped interface.
If the full terminal-emulation interface is to be used, then
2001-10-22 07:29:58 +04:00
.Em struct wsemuldisplaydev_attach_args
2002-10-14 17:43:14 +04:00
should be used instead.
It has the following members:
2001-10-22 07:29:58 +04:00
.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
2002-10-14 17:43:14 +04:00
child device for the full terminal emulation interface.
If the simple bit-mapped interface is to be used, then
2001-10-22 07:29:58 +04:00
.Em struct wsdisplaydev_attach_args
2002-10-14 17:43:14 +04:00
should be used instead.
It has the following members:
2001-10-22 07:29:58 +04:00
.Bd -literal
int console;
const struct wsscreen_list *scrdata;
const struct wsdisplay_accessops *accessops;
void *accesscookie;
.Ed
.It Fa struct wsdisplay_emulops
2002-10-14 17:43:14 +04:00
A structure used to specify the display emulation functions.
All displays intending to provide terminal emulation must provide
2001-10-22 07:29:58 +04:00
this structure and pass it to the
.Xr wsdisplay 4
2002-10-14 17:43:14 +04:00
child device.
It has the following members:
2001-10-22 07:29:58 +04:00
.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,
2001-10-22 07:29:58 +04:00
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
2002-02-12 19:14:13 +03:00
A structure passed to wscons by the display driver to describe a
2002-10-14 17:43:14 +04:00
screen.
All displays which can operate as a console must provide this structure
and pass it to the
2001-10-22 07:29:58 +04:00
.Xr wsdisplay 4
2002-10-14 17:43:14 +04:00
child device.
It contains the following members:
2001-10-22 07:29:58 +04:00
.Bd -literal
char *name;
int ncols, nrows;
const struct wsdisplay_emulops *textops;
int fontwidth, fontheight;
int capabilities;
.Ed
.Pp
The
.Em capabilities
2002-10-14 17:43:14 +04:00
member is a set of flags describing the screen capabilities.
It can contain the following flags:
2001-10-22 07:29:58 +04:00
.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
2002-10-14 17:43:14 +04:00
capabilities.
It contains the following members:
2001-10-22 07:29:58 +04:00
.Bd -literal
int nscreens;
const struct wsscreen_descr **screens;
.Ed
.It Fa struct wscons_syncops
2002-02-12 19:14:13 +03:00
A structure passed to wscons by the display driver describing the
2002-03-10 21:39:42 +03:00
interface for external screen switching/process synchronization.
2001-10-22 07:29:58 +04:00
This structure is optional and only required by displays operating
2002-10-14 17:43:14 +04:00
with terminal emulation and intending to support multiple screens.
It contains the following members:
2001-10-22 07:29:58 +04:00
.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
2002-03-10 21:39:42 +03:00
specifies the default attribute (color) for the console.
2001-10-22 07:29:58 +04:00
.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
2002-10-14 17:43:14 +04:00
specifies the default attribute (color) for the console.
Different terminal emulations can be active at the same time on one display.
2001-10-22 07:29:58 +04:00
.It Fn wsdisplaydevprint "aux" "pnp"
The default wsdisplay printing routine used by
.Fn config_found .
(see
.Xr autoconf 9 ) .
2001-10-22 07:29:58 +04:00
.It Fn wsemuldisplaydevprint "aux" "pnp"
The default wsemul printing routine used by
.Fn config_found .
(see
.Xr autoconf 9 ) .
2001-10-22 07:29:58 +04:00
.El
.Sh AUTOCONFIGURATION
Display drivers which want to use the wsdisplay module must be a
2001-10-22 07:29:58 +04:00
parent to the
.Xr wsdisplay 4
2002-10-14 17:43:14 +04:00
device and provide an attachment interface.
To attach the
2001-10-22 07:29:58 +04:00
.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 ) .
2001-10-22 07:29:58 +04:00
.Pp
Display drivers which want to use the wscons terminal emulation
2001-10-22 07:29:58 +04:00
module must be a parent to the
.Xr wsdisplay 4
device and provide a
.Fa wsemuldisplaydev_attach_args
structure instead of the standard
2002-03-10 20:31:25 +03:00
.Fa wsdisplaydev_attach_args
2001-10-22 07:29:58 +04:00
to
.Fn config_found
2002-10-14 17:43:14 +04:00
to perform the attach.
If the display is not the console the attachment is the same
as wsdisplaydev_attach_args.
2001-10-22 07:29:58 +04:00
.Sh OPERATION
2002-03-10 21:39:42 +03:00
If the display belongs to the system console, it must describe the
2001-10-22 07:29:58 +04:00
default screen by invoking
2002-03-10 20:31:25 +03:00
.Fn wsdisplay_cnattach
2001-10-22 07:29:58 +04:00
at console attach time.
.Pp
All display manipulation is performed by the wscons interface by using
the callbacks defined in the
.Em wsdisplay_accessops
2002-10-14 17:43:14 +04:00
structure.
The
2001-10-22 07:29:58 +04:00
.Fn ioctl
function is called by the wscons interface to perform display-specific
ioctl operations (see
.Xr ioctl 2 ) .
2001-10-22 07:29:58 +04:00
The argument
.Fa cmd
to the
2001-10-22 07:29:58 +04:00
.Fn ioctl
function specifies the specific command to perform using the data
2002-09-19 04:52:54 +04:00
.Fa data .
Valid commands are listed in
.Pa sys/dev/wscons/wsconsio.h
and documented in
.Xr wsdisplay 4 .
2001-10-22 07:29:58 +04:00
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 using the
2002-10-14 17:43:14 +04:00
machine-independent wscons subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
2001-10-22 07:29:58 +04:00
.Pp
The wscons subsystem is implemented within the directory
.Pa sys/dev/wscons .
The
.Nm
2002-03-10 20:31:25 +03:00
module itself is implemented within the file
2001-10-22 07:29:58 +04:00
.Pa sys/dev/wscons/wsdisplay.c .
The terminal emulation support
2002-03-10 20:31:25 +03:00
is implemented within the files
2001-10-22 07:29:58 +04:00
.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 ,
2001-10-22 07:29:58 +04:00
.Xr autoconf 9 ,
.Xr driver 9 ,
.Xr intro 9 ,
.Xr rasops 9 ,
.Xr wsfont 9 ,
.Xr wskbd 9 ,
.Xr wsmouse 9