NAME
wsdisplay,
wsdisplay_switchtoconsole,
wsdisplay_cnattach,
wsdisplaydevprint,
wsemuldisplaydevprint —
wscons
display support
SYNOPSIS
#include <dev/wscons/wsconsio.h>
#include <dev/wscons/wsdisplayvar.h>
#include <dev/wscons/wsemulvar.h>
#include
<dev/wscons/wsemul_vt100var.h>
void
wsdisplay_switchtoconsole(
);
void
wsdisplay_cnattach(
const
struct wsscreen_descr *type,
void *cookie,
int ccol,
int crow,
long defattr);
void
wsemul_xxx_cnattach(
const
struct wsscreen_descr *type,
void *cookie,
int ccol,
int crow,
long defattr);
int
wsdisplaydevprint(
void
*aux,
const char
*pnp);
int
wsemuldisplaydevprint(
void
* aux,
const char
*pnp);
DESCRIPTION
The
wsdisplay module is a component of the
wscons(9) framework to provide
machine-independent display support. Most of the support is provided by the
wsdisplay(4) device driver,
which must be a child of the hardware device driver.
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
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.
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.
Font manipulation facilities for the terminal emulation interface are available
through the
wsfont(9) module.
DATA TYPES
Display drivers providing support for wscons displays will make use of the
following data types:
-
-
- 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
wsdisplay(4) child
device. It has the following members:
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);
The ioctl member defines the function to be called to
perform display-specific ioctl calls. The mmap
member defines the function for mapping a part of the display device into
user address space. The alloc_screen member defines
a function for allocating a new screen which can be used as a virtual
terminal. The free_screen member defines a function
for de-allocating a screen. The show_screen member
defines a function for mapping a screen onto the physical display. This
function is used for switching between screens. The
load_font member defines a function for loading a
new font into the display. The pollc member defines
a function for polling the console. The scroll
member defines a function for scrolling the contents of the display.
There is a void * cookie provided by the display
driver associated with these functions, which is passed to them when they
are invoked.
The void *vs cookie, passed to
ioctl() and mmap(), points to the
virtual screen on which these operations were executed.
-
-
- struct
wsdisplaydev_attach_args
- A structure used to attach the
wsdisplay(4) child device
for the simple bit-mapped interface. It has the following members:
const struct wsdisplay_accessops *accessops;
void *accesscookie;
If the full terminal-emulation interface is to be used, then
struct wsemuldisplaydev_attach_args should be used
instead.
-
-
- struct
wsemuldisplaydev_attach_args
- A structure used to attach the
wsdisplay(4) child device
for the full terminal emulation interface. It has the following members:
int console;
const struct wsscreen_list *scrdata;
const struct wsdisplay_accessops *accessops;
void *accesscookie;
If the simple bit-mapped interface is to be used, then struct
wsdisplaydev_attach_args should be used instead.
-
-
- 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
wsdisplay(4) child
device. It has the following members:
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);
The cursor member defines a function for painting (or
unpainting, depending on the on parameter) the
cursor at the specified position. The mapchar member
defines a function for changing the character mapped at a given position
in the character table. The putchar member defines a
function for writing a character on the screen, given its position and
attribute. The copycols member defines a function
for copying a set of columns within the same line. The
erasecols member defines a function for clearing a
set of columns in a line, filling the space with the given attribute. The
copyrows member defines a function for copying a set
of complete rows. The eraserows member defines a
function for clearing a set of complete rows, filling the space with the
given attribute. The 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 replaceattr
member defines a function for replacing an attribute by another one across
the whole visible part of the screen; this function is optional.
There is a void * cookie provided by the display
driver associated with these functions, which is passed to them when they
are invoked.
-
-
- 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
wsdisplay(4) child
device. It contains the following members:
char *name;
int ncols, nrows;
const struct wsdisplay_emulops *textops;
int fontwidth, fontheight;
int capabilities;
The capabilities member is a set of flags describing the
screen capabilities. It can contain the following flags:
- WSSCREEN_WSCOLORS
- minimal color capability
- WSSCREEN_REVERSE
- can display reversed
- WSSCREEN_HILIT
- can highlight (however)
- WSSCREEN_BLINK
- can blink
- WSSCREEN_UNDERLINE
- can underline
-
-
- struct
wsscreen_list
- A structure passed to wscons by the display driver to tell
about its capabilities. It contains the following members:
int nscreens;
const struct wsscreen_descr **screens;
-
-
- 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:
int (*detach)(void *, int, void (*)(), void *);
int (*attach)(void *, int, void (*)(), void *);
int (*check)(void *);
void (*destroy)(void *);
FUNCTIONS
-
-
- wsdisplay_switchtoconsole()
- Switch the console display to its first screen.
-
-
- wsdisplay_cnattach(type,
cookie, ccol,
crow, defattr)
- Attach this display as the console input by specifying the
number of columns ccol and number of rows
crows. The argument defattr
specifies the default attribute (color) for the console.
-
-
- wsemul_xxx_cnattach(type,
cookie, ccol,
crow, defattr)
- Attach this display as the console with terminal emulation
described by the xxx and specifying the number of
columns ccol and number of rows
crows. The argument defattr
specifies the default attribute (color) for the console. Different
terminal emulations can be active at the same time on one display.
-
-
- wsdisplaydevprint(aux,
pnp)
- The default wsdisplay printing routine used by
config_found(). (see
autoconf(9)).
-
-
- wsemuldisplaydevprint(aux,
pnp)
- The default wsemul printing routine used by
config_found(). (see
autoconf(9)).
AUTOCONFIGURATION
Display drivers which want to use the wsdisplay module must be a parent to the
wsdisplay(4) device and
provide an attachment interface. To attach the
wsdisplay(4) device, the
display driver must allocate and populate a
wsdisplaydev_attach_args structure with the supported
operations and callbacks and call
config_found() to perform
the attach (see
autoconf(9)).
Display drivers which want to use the wscons terminal emulation module must be a
parent to the
wsdisplay(4)
device and provide a
wsemuldisplaydev_attach_args
structure instead of the standard
wsdisplaydev_attach_args to
config_found() to perform the attach. If the display is not
the console the attachment is the same as wsdisplaydev_attach_args.
OPERATION
If the display belongs to the system console, it must describe the default
screen by invoking
wsdisplay_cnattach() at console attach
time.
All display manipulation is performed by the wscons interface by using the
callbacks defined in the
wsdisplay_accessops structure. The
ioctl() function is called by the wscons interface to
perform display-specific ioctl operations (see
ioctl(2)). The argument
cmd to the
ioctl() function specifies
the specific command to perform using the data
data.
Valid commands are listed in
sys/dev/wscons/wsconsio.h and
documented in
wsdisplay(4).
Operations for terminal emulation are performed using the callbacks defined in
the
wsdisplay_emulops structure.
CODE REFERENCES
The wscons subsystem is implemented within the directory
sys/dev/wscons. The
wsdisplay module
itself is implemented within the file
sys/dev/wscons/wsdisplay.c. The terminal emulation support
is implemented within the files
sys/dev/wscons/wsemul_*.
ioctl(2) operations are listed in
sys/dev/wscons/wsconsio.h.
SEE ALSO
ioctl(2),
wsdisplay(4),
autoconf(9),
driver(9),
intro(9),
rasops(9),
wsfont(9),
wskbd(9),
wsmouse(9)