adda7c4307
WSDISPLAY_CUSTOM_BORDER, WSDISPLAY_CUSTOM_OUTPUT and WSDISPLAY_DEFAULTSCREENS
kernel options.
Also document the WSDISPLAYIO_{GET,PUT}WSCHAR ioctls.
569 lines
16 KiB
Groff
569 lines
16 KiB
Groff
.\" $NetBSD: wsdisplay.4,v 1.25 2004/07/30 14:00:18 jmmv Exp $
|
|
.\"
|
|
.\" Copyright (c) 1999 Matthias Drochner.
|
|
.\" Copyright (c) 2002 Ben Harris.
|
|
.\" Copyright (c) 2004 Julio M. Merino Vidal.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" 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 AUTHOR 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 AUTHOR 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 July 30, 2004
|
|
.Os
|
|
.Dt WSDISPLAY 4
|
|
.Sh NAME
|
|
.Nm wsdisplay
|
|
.Nd generic display device support in wscons
|
|
.Sh SYNOPSIS
|
|
.Cd "wsdisplay* at ega? console ?"
|
|
(EGA display on ISA)
|
|
.Cd "wsdisplay* at vga? console ?"
|
|
(VGA display on ISA or PCI)
|
|
.Cd "wsdisplay* at pcdisplay? console ?"
|
|
(generic PC (ISA) display)
|
|
.Cd "wsdisplay* at tga? console ?"
|
|
(DEC TGA display, alpha only)
|
|
.Cd "wsdisplay* at pfb? console ?"
|
|
(PCI framebuffer, bebox only)
|
|
.Cd "wsdisplay0 at ofb? console ?"
|
|
(Open Firmware framebuffer, macppc only)
|
|
.Cd "wsdisplay* at nextdisplay? console ?"
|
|
(NeXT display)
|
|
.Cd "wsdisplay0 at smg0"
|
|
(VAXstation small monochrome display)
|
|
.Cd "wsdisplay* at ... kbdmux N"
|
|
.Cd options WSDISPLAY_BORDER_COLOR=WSCOL_XXX
|
|
.Cd options WSDISPLAY_CHARFUNCS
|
|
.Cd options WSDISPLAY_CUSTOM_BORDER
|
|
.Cd options WSDISPLAY_CUSTOM_OUTPUT
|
|
.Cd options WSDISPLAY_DEFAULTSCREENS=N
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver is an abstraction layer for display devices within the
|
|
.Xr wscons 4
|
|
framework.
|
|
It attaches to the hardware specific display device driver and makes it
|
|
available as a text terminal or graphics interface.
|
|
.Pp
|
|
A display device can have the ability to display characters on it
|
|
(without the help of an X server), either directly by hardware or through
|
|
software putting pixel data into the display memory.
|
|
Such displays are called
|
|
.Dq emulating ,
|
|
the
|
|
.Nm
|
|
driver will connect a terminal emulation module and provide a tty-like
|
|
software interface.
|
|
In contrary, non-emulating displays can only be used by special programs
|
|
like X servers.
|
|
.Pp
|
|
The
|
|
.Em console
|
|
locator in the configuration line refers to the device's use as the output
|
|
part of the operating system console.
|
|
A device specification containing a positive value here will only match if
|
|
the device is in use as the system console.
|
|
(The console device selection in early system startup is not influenced.)
|
|
This way, the console device can be connected to a known wsdisplay device
|
|
instance.
|
|
(Naturally, only
|
|
.Dq emulating
|
|
display devices are usable as console.)
|
|
.Pp
|
|
The
|
|
.Em kbdmux
|
|
locator in the configuration line refers to the
|
|
.Xr wsmux 4
|
|
that will be used to get keyboard events.
|
|
If this locator is -1 no mux will be used.
|
|
.Pp
|
|
The logical unit of an independent contents displayed on a display
|
|
(sometimes referred to as
|
|
.Dq virtual terminal
|
|
) is called a
|
|
.Dq screen
|
|
here. If the underlying device driver supports it, multiple screens can
|
|
be used on one display.
|
|
(As of this writing, only the
|
|
.Xr vga 4
|
|
and the
|
|
.Tn VAX
|
|
.Dq smg
|
|
display drivers provide this ability.)
|
|
Screens have different minor device numbers and separate tty instances.
|
|
One screen possesses the
|
|
.Dq focus ,
|
|
this means it is visible and its tty device will get
|
|
the keyboard input. (In some cases \- if no screen is set up or if a screen
|
|
was just deleted \- it is possible that no focus is present at all.)
|
|
The focus can be switched by either special keyboard input (typically
|
|
.Tn CTRL-ALT-F Ns Ar n )
|
|
or an ioctl command issued by a user program.
|
|
Screens are created and deleted through the
|
|
.Pa /dev/ttyEcfg
|
|
control device (preferably using the
|
|
.Xr wsconscfg 8
|
|
utility). Alternatively, the compile-time option
|
|
.Dv WSDISPLAY_DEFAULTSCREENS Ns = Ns Ar n
|
|
will also create (at autoconfiguration time)
|
|
.Ar n
|
|
initial screens of the display driver's default type with
|
|
the system's default terminal emulator.
|
|
.Ss Kernel options
|
|
The following kernel options are available to configure the behavior of the
|
|
.Nm
|
|
driver:
|
|
.Bl -tag -width xxxxxxxx
|
|
.It Cd options WSDISPLAY_BORDER_COLOR=WSCOL_XXX
|
|
Sets the border color at boot time.
|
|
Possible values are defined in
|
|
.Pa src/sys/dev/wscons/wsdisplayvar.h .
|
|
Defaults to
|
|
.Sq WSCOL_BLACK .
|
|
.It Cd options WSDISPLAY_CHARFUNCS
|
|
Enables the
|
|
.Dv WSDISPLAYIO_GETWSCHAR
|
|
and
|
|
.Dv WSDISPLAYIO_PUTWSCHAR
|
|
ioctls.
|
|
These are mainly used by the
|
|
.Sq selection
|
|
mode of
|
|
.Xr wsmoused 8 .
|
|
.It Cd options WSDISPLAY_CUSTOM_BORDER
|
|
Enables the
|
|
.Dv WSDISPLAYIO_GBORDER
|
|
and
|
|
.Dv WSDISPLAYIO_SBORDER
|
|
ioctls, which allow the customization of the border color from userland
|
|
(after boot).
|
|
See
|
|
.Xr wsconsctl 8 .
|
|
.It Cd options WSDISPLAY_CUSTOM_OUTPUT
|
|
Enables the
|
|
.Dv WSDISPLAYIO_GMSGATTRS
|
|
and
|
|
.Dv WSDISPLAYIO_SMSGATTRS
|
|
ioctls, which allow the customization of the console output and kernel
|
|
messages from userland (after boot).
|
|
See
|
|
.Xr wsconsctl 8 .
|
|
.It Cd options WSDISPLAY_DEFAULTSCREENS=N
|
|
Sets the number of virtual screens to allocate at boot time.
|
|
Useful for small root filesystems where the
|
|
.Xr wsconscfg 8
|
|
utility is not wanted.
|
|
.El
|
|
.Ss Ioctls
|
|
The following
|
|
.Xr ioctl 2
|
|
calls are provided by the
|
|
.Nm
|
|
driver or by devices which use it.
|
|
Their definitions are found in
|
|
.Aq Pa dev/wscons/wsconsio.h .
|
|
.Bl -tag -width Dv
|
|
.It Dv WSDISPLAYIO_GTYPE Pq Li int
|
|
Retrieve the type of the display.
|
|
The list of types is in
|
|
.Aq Pa dev/wscons/wsconsio.h .
|
|
.It Dv WSDISPLAYIO_GINFO Pq Li "struct wsdisplay_fbinfo"
|
|
Retrieve basic information about a framebuffer display.
|
|
The returned structure is as follows:
|
|
.Bd -literal -offset indent
|
|
struct wsdisplay_fbinfo {
|
|
u_int height;
|
|
u_int width;
|
|
u_int depth;
|
|
u_int cmsize;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va height
|
|
and
|
|
.Va width
|
|
members are counted in pixels.
|
|
The
|
|
.Va depth
|
|
member indicates the number of bits per pixel, and
|
|
.Va cmsize
|
|
indicates the number of color map entries accessible through
|
|
.Dv WSDISPLAYIO_GETCMAP
|
|
and
|
|
.Dv WSDISPLAYIO_PUTCMAP .
|
|
This call is likely to be unavailable on text-only displays.
|
|
.It Dv WSDISPLAYIO_GETCMAP Pq Li "struct wsdisplay_cmap"
|
|
Retrieve the current color map from the display.
|
|
This call needs the
|
|
following structure set up beforehand:
|
|
.Bd -literal -offset indent
|
|
struct wsdisplay_cmap {
|
|
u_int index;
|
|
u_int count;
|
|
u_char *red;
|
|
u_char *green;
|
|
u_char *blue;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va index
|
|
and
|
|
.Va count
|
|
members specify the range of color map entries to retrieve.
|
|
The
|
|
.Va red ,
|
|
.Va green ,
|
|
and
|
|
.Va blue
|
|
members should each point to an array of
|
|
.Va count
|
|
.Li u_char Ns s .
|
|
On return, these will be filled in with the appropriate entries from the
|
|
color map.
|
|
On all displays that support this call, values range from 0 for minimum
|
|
intensity to 255 for maximum intensity, even if the display does not use
|
|
eight bits internally to represent intensity.
|
|
.It Dv WSDISPLAYIO_PUTCMAP Pq Li "struct wsdisplay_cmap"
|
|
Change the display's color map.
|
|
The argument structure is the same as for
|
|
.Dv WSDISPLAYIO_GETCMAP ,
|
|
but
|
|
.Va red ,
|
|
.Va green ,
|
|
and
|
|
.Va blue
|
|
are taken as pointers to the values to use to set the color map.
|
|
This call is not available on displays with fixed color maps.
|
|
.It Dv WSDISPLAYIO_GVIDEO Pq Li int
|
|
Get the current state of the display's video output.
|
|
Possible values are:
|
|
.Bl -tag -width Dv
|
|
.It Dv WSDISPLAYIO_VIDEO_OFF
|
|
The display is blanked.
|
|
.It Dv WSDISPLAYIO_VIDEO_ON
|
|
The display is enabled.
|
|
.El
|
|
.It Dv WSDISPLAYIO_SVIDEO Pq Li int
|
|
Set the state of the display's video output.
|
|
See
|
|
.Dv WSDISPLAYIO_GVIDEO
|
|
above for possible values.
|
|
.It Dv WSDISPLAYIO_GCURPOS Pq Li "struct wsdisplay_curpos"
|
|
Retrieve the current position of the hardware cursor.
|
|
The returned structure
|
|
is as follows:
|
|
.Bd -literal -offset indent
|
|
struct wsdisplay_curpos {
|
|
u_int x, y;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va x
|
|
and
|
|
.Va y
|
|
members count the number of pixels right and down, respectively, from
|
|
the top-left corner of the display to the hot spot of the cursor.
|
|
This call is not available on displays without a hardware cursor.
|
|
.It Dv WSDISPLAYOP_SCURPOS Pq Li "struct wsdisplay_curpos"
|
|
Set the current cursor position. The argument structure, and its semantics,
|
|
are the same as for
|
|
.Dv WSDISPLAYIO_GCURPOS .
|
|
This call is not available on displays without a hardware cursor.
|
|
.It Dv WSDISPLAYIO_GCURMAX Pq Li "struct wsdisplay_curpos"
|
|
Retrieve the maximum size of cursor supported by the display.
|
|
The
|
|
.Va x
|
|
and
|
|
.Va y
|
|
members of the returned structure indicate the maximum number of pixel rows
|
|
and columns, respectively, in a hardware cursor on this display.
|
|
This call is not available on displays without a hardware cursor.
|
|
.It Dv WSDISPLAYIO_GCURSOR Pq Li "struct wsdisplay_cursor"
|
|
Retrieve some or all of the hardware cursor's attributes.
|
|
The argument structure is as follows:
|
|
.Bd -literal -offset indent
|
|
struct wsdisplay_cursor {
|
|
u_int which;
|
|
u_int enable;
|
|
struct wsdisplay_curpos pos;
|
|
struct wsdisplay_curpos hot;
|
|
struct wsdisplay_cmap cmap;
|
|
struct wsdisplay_curpos size;
|
|
u_char *image;
|
|
u_char *mask;
|
|
};
|
|
.Pp
|
|
.Ed
|
|
The
|
|
.Va which
|
|
member indicates which of the values the application requires to be returned.
|
|
It should contain the logical OR of the following flags:
|
|
.Bl -tag -width Dv
|
|
.It Dv WSDISPLAYIO_CURSOR_DOCUR
|
|
Get
|
|
.Va enable ,
|
|
which indicates whether the cursor is currently displayed (non-zero) or
|
|
not (zero).
|
|
.It Dv WSDISPLAYIO_CURSOR_DOPOS
|
|
Get
|
|
.Va pos ,
|
|
which indicates the current position of the cursor on the display, as
|
|
would be returned by
|
|
.Dv WSDISPLAYIO_GCURPOS .
|
|
.It Dv WSDISPLAYIO_CURSOR_DOHOT
|
|
Get
|
|
.Va hot ,
|
|
which indicates the location of the
|
|
.Dq hot spot
|
|
within the cursor.
|
|
This is the point on the cursor whose position on the display is treated
|
|
as being the position of the cursor by other calls.
|
|
Its location is counted in pixels from the top-right corner of the cursor.
|
|
.It Dv WSDISPLAYIO_CURSOR_DOCMAP
|
|
Get
|
|
.Va cmap ,
|
|
which indicates the current cursor color map.
|
|
Unlike in a call to
|
|
.Dv WSDISPLAYIO_GETCMAP ,
|
|
.Va cmap
|
|
here need not have its
|
|
.Va index
|
|
and
|
|
.Va count
|
|
members initialized.
|
|
They will be set to 0 and 2 respectively by the call.
|
|
This means that
|
|
.Va cmap . Ns Va red ,
|
|
.Va cmap . Ns Va green ,
|
|
and
|
|
.Va cmap . Ns Va blue
|
|
must each point to at least enough space to hold two
|
|
.Li u_char Ns s .
|
|
.It Dv WSDISPLAYIO_CURSOR_DOSHAPE
|
|
Get
|
|
.Va size , image ,
|
|
and
|
|
.Va mask .
|
|
These are, respectively, the dimensions of the cursor in pixels, the
|
|
bitmap of set pixels in the cursor and the bitmap of opaque pixels in
|
|
the cursor.
|
|
The format in which these bitmaps are returned, and hence the amount of
|
|
space that must be provided by the application, are device-dependent.
|
|
.It Dv WSDISPLAYIO_CURSOR_DOALL
|
|
Get all of the above.
|
|
.El
|
|
.Pp
|
|
The device may elect to return information that was not requested by the user,
|
|
so those elements of
|
|
.Li "struct wsdisplay_cursor"
|
|
which are pointers should be initialized to
|
|
.Dv NULL
|
|
if not otherwise used.
|
|
This call is not available on displays without a hardware cursor.
|
|
.It Dv WSDISPLAYIO_SCURSOR Pq Li "struct wsdisplay_cursor"
|
|
Set some or all of the hardware cursor's attributes.
|
|
The argument structure is the same as for
|
|
.Dv WSDISPLAYIO_GCURSOR .
|
|
The
|
|
.Va which
|
|
member specifies which attributes of the cursor are to be changed.
|
|
It should contain the logical OR of the following flags:
|
|
.Bl -tag -width Dv
|
|
.It Dv WSDISPLAYIO_CURSOR_DOCUR
|
|
If
|
|
.Va enable
|
|
is zero, hide the cursor.
|
|
Otherwise, display it.
|
|
.It Dv WSDISPLAYIO_CURSOR_DOPOS
|
|
Set the cursor's position on the display to
|
|
.Va pos ,
|
|
the same as
|
|
.Dv WSDISPLAYIO_SCURPOS .
|
|
.It Dv WSDISPLAYIO_CURSOR_DOHOT
|
|
Set the
|
|
.Dq hot spot
|
|
of the cursor, as defined above, to
|
|
.Va hot .
|
|
.It Dv WSDISPLAYIO_CURSOR_DOCMAP
|
|
Set some or all of the cursor color map based on
|
|
.Va cmap .
|
|
The
|
|
.Va index
|
|
and
|
|
.Va count
|
|
elements of
|
|
.Va cmap
|
|
indicate which color map entries to set, and the entries themselves come from
|
|
.Va cmap . Ns Va red ,
|
|
.Va cmap . Ns Va green ,
|
|
and
|
|
.Va cmap . Ns Va blue .
|
|
.It Dv WSDISPLAYIO_CURSOR_DOSHAPE
|
|
Set the cursor shape from
|
|
.Va size , image ,
|
|
and
|
|
.Va mask .
|
|
See above for their meanings.
|
|
.It Dv WSDISPLAYIO_CURSOR_DOALL
|
|
Do all of the above.
|
|
.El
|
|
.Pp
|
|
This call is not available on displays without a hardware cursor.
|
|
.It Dv WSDISPLAYIO_GMODE Pq Li u_int
|
|
Get the current mode of the display.
|
|
Possible results include:
|
|
.Bl -tag -width Dv
|
|
.It Dv WSDISPLAYIO_MODE_EMUL
|
|
The display is in emulating (text) mode.
|
|
.It Dv WSDISPLAYIO_MODE_MAPPED
|
|
The display is in mapped (graphics) mode.
|
|
.It Dv WSDISPLAYIO_MODE_DUMBFB
|
|
The display is in mapped (frame buffer) mode.
|
|
.El
|
|
.Pp
|
|
.It Dv WSDISPLAYIO_SMODE Pq Li u_int
|
|
Set the current mode of the display.
|
|
For possible arguments, see
|
|
.Dv WSDISPLAYIO_GMODE .
|
|
.Pp
|
|
.It Dv WSDISPLAYIO_LINEBYTES Pq Li u_int
|
|
Get the number of bytes per row, which may be the same as the number of pixels.
|
|
.It Dv WSDISPLAYIO_GMSGATTRS Pq Li struct wsdisplay_msgattrs
|
|
Get the attributes (colors and flags) used to print console messages, including
|
|
separate fields for default output and kernel output.
|
|
The returned structure is as follows:
|
|
.Bd -literal -offset indent
|
|
struct wsdisplay_msgattrs {
|
|
int default_attrs, default_bg, default_fg;
|
|
int kernel_attrs, kernel_bg, kernel_fg;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va default_attrs
|
|
and
|
|
.Va kernel_attrs
|
|
variables are a combination of
|
|
.Va WSATTR_*
|
|
bits, and specify the attribues used to draw messages.
|
|
The
|
|
.Va default_bg ,
|
|
.Va default_fg ,
|
|
.Va kernel_bg
|
|
and
|
|
.Va kernel_fg
|
|
variables specify the colors used to print messages, being
|
|
.Sq _bg
|
|
for the background and
|
|
.Sq _fg
|
|
for the foreground; their values are one of all the
|
|
.Va WSCOL_*
|
|
macros available.
|
|
.It Dv WSDISPLAYIO_SMSGATTRS Pq Li struct wsdisplay_msgattrs
|
|
Set the attributes (colors and flags) used to print console messages, including
|
|
separate fields for default output and kernel output.
|
|
The argument structure is the same as for
|
|
.Dv WSDISPLAYIO_GMSGATTRS .
|
|
.It Dv WSDISPLAYIO_GBORDER Pq Li u_int
|
|
Retrieve the color of the screen border.
|
|
This number corresponds to an ANSI standard color.
|
|
.It Dv WSDISPLAYIO_SBORDER Pq Li u_int
|
|
Set the color of the screen border, if applicable.
|
|
This number corresponds to an ANSI standard color.
|
|
Not all drivers support this feature.
|
|
.It Dv WSDISPLAYIO_GETWSCHAR Pq Li struct wsdisplay_char
|
|
Gets a single character from the screen, specified by its position.
|
|
The structure used is as follows:
|
|
.Bd -literal -offset indent
|
|
struct wsdisplay_char {
|
|
int row, col;
|
|
uint16_t letter;
|
|
uint8_t background, foreground;
|
|
char flags;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va row
|
|
and
|
|
.Va col
|
|
parameters are used as input; the rest of the structure is filled by the
|
|
ioctl and is returned to you.
|
|
.Va letter
|
|
is the ASCII code of the letter found at the specified position,
|
|
.Va background
|
|
and
|
|
.Va foreground
|
|
are its colors and
|
|
.Va flags
|
|
is a combination of
|
|
.Sq WSDISPLAY_CHAR_BRIGHT
|
|
and/or
|
|
.Sq WSDISPLAY_CHAR_BLINK .
|
|
.It Dv WSDISPLAYIO_PUTWSCHAR Pq Li struct wsdisplay_char
|
|
Puts a character on the screen.
|
|
The structure has the same meaning as described in
|
|
.Dv WSDISPLAY_GETWSCHAR ,
|
|
although all of its fields are treated as input.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -item
|
|
.It
|
|
.Pa /dev/ttyE*
|
|
Terminal devices (per screen).
|
|
.It
|
|
.Pa /dev/ttyEcfg
|
|
Control device.
|
|
.It
|
|
.Pa /dev/ttyEstat
|
|
Status device.
|
|
.It
|
|
.Pa /usr/include/dev/wscons/wsconsio.h
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ioctl 2 ,
|
|
.Xr ega 4 ,
|
|
.Xr pcdisplay 4 ,
|
|
.Xr tty 4 ,
|
|
.Xr vga 4 ,
|
|
.Xr wscons 4 ,
|
|
.Xr wsconscfg 8 ,
|
|
.Xr wsconsctl 8 ,
|
|
.Xr wsfontload 8 ,
|
|
.Xr wsdisplay 9
|
|
.Sh BUGS
|
|
The
|
|
.Nm
|
|
code currently limits the number of screens on one display to 8.
|
|
.Pp
|
|
The terms
|
|
.Dq wscons
|
|
and
|
|
.Dq wsdisplay
|
|
are not cleanly distinguished in the code and in manual pages.
|
|
.Pp
|
|
.Dq non-emulating
|
|
display devices are not tested.
|