NAME
wsdisplay —
generic display device
support in wscons
SYNOPSIS
wsdisplay* at ega? console ? (EGA display on ISA)
wsdisplay* at vga? console ? (VGA display on ISA or PCI)
wsdisplay* at pcdisplay? console ? (generic PC (ISA) display)
wsdisplay* at tga? console ? (DEC TGA display, alpha only)
wsdisplay* at pfb? console ? (PCI framebuffer, bebox only)
wsdisplay0 at ofb? console ? (Open Firmware framebuffer,
macppc only)
wsdisplay* at nextdisplay? console ? (NeXT display)
wsdisplay0 at smg0 (VAXstation small monochrome display)
wsdisplay* at ... kbdmux N
options WSDISPLAY_BORDER_COLOR=WSCOL_XXX
options WSDISPLAY_CUSTOM_BORDER
options WSDISPLAY_CUSTOM_OUTPUT
options WSDISPLAY_DEFAULTSCREENS=N
options WSDISPLAY_SCROLLSUPPORT
DESCRIPTION
The
wsdisplay driver is an abstraction layer for display
devices within the
wscons(4)
framework. It attaches to the hardware specific display device driver and
makes it available as a text terminal or graphics interface.
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
“emulating”, the
wsdisplay 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.
The
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 “emulating”
display devices are usable as console.)
The
kbdmux locator in the configuration line refers to the
wsmux(4) that will be used to get
keyboard events. If this locator is -1 no mux will be used.
The logical unit of an independent contents displayed on a display (sometimes
referred to as “virtual terminal” ) is called a
“screen” here. If the underlying device driver supports it,
multiple screens can be used on one display. (As of this writing, only the
vga(4) and the VAX
“smg” display drivers provide this ability.) Screens have
different minor device numbers and separate tty instances. One screen
possesses the “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
CTRL-ALT-F
n, STOP-Fn on Sun hardware,
Command-Fn on ADB keyboards ) or an ioctl command
issued by a user program. Screens are created and deleted through the
/dev/ttyEcfg control device (preferably using the
wsconscfg(8) utility).
Alternatively, the compile-time option
WSDISPLAY_DEFAULTSCREENS
=
n will
also create (at autoconfiguration time)
n initial
screens of the display driver's default type with the system's default
terminal emulator.
Kernel options
The following kernel options are available to configure the behavior of the
wsdisplay driver:
-
-
- options
WSDISPLAY_BORDER_COLOR=WSCOL_XXX
- Sets the border color at boot time. Possible values are
defined in src/sys/dev/wscons/wsdisplayvar.h. Defaults
to ‘WSCOL_BLACK’.
-
-
- options
WSDISPLAY_CUSTOM_BORDER
- Enables the
WSDISPLAYIO_GBORDER
and
WSDISPLAYIO_SBORDER
ioctls, which allow the
customization of the border color from userland (after boot). See
wsconsctl(8).
-
-
- options
WSDISPLAY_CUSTOM_OUTPUT
- Enables the
WSDISPLAYIO_GMSGATTRS
and WSDISPLAYIO_SMSGATTRS
ioctls, which allow the
customization of the console output and kernel messages from userland
(after boot). See
wsconsctl(8).
-
-
- options
WSDISPLAY_DEFAULTSCREENS=N
- Sets the number of virtual screens to allocate at boot
time. Useful for small root filesystems where the
wsconscfg(8) utility is
not wanted.
-
-
- options
WSDISPLAY_SCROLLSUPPORT
- Enables scrolling support. The key combinations are
LEFT SHIFT + PAGE UP and LEFT SHIFT + PAGE
DOWN by default. Please note that this function may not work under the
system console and is available depending on the framebuffer you are
using.
Ioctls
The following
ioctl(2) calls are
provided by the
wsdisplay driver or by devices which use it.
Their definitions are found in
<dev/wscons/wsconsio.h>.
-
-
WSDISPLAYIO_GTYPE
(int
)
- Retrieve the type of the display. The list of types is in
<dev/wscons/wsconsio.h>.
-
-
WSDISPLAYIO_GINFO
(struct wsdisplay_fbinfo
)
- Retrieve basic information about a framebuffer display. The
returned structure is as follows:
struct wsdisplay_fbinfo {
u_int height;
u_int width;
u_int depth;
u_int cmsize;
};
The height and width members are
counted in pixels. The depth member indicates the
number of bits per pixel, and cmsize indicates the
number of color map entries accessible through
WSDISPLAYIO_GETCMAP
and
WSDISPLAYIO_PUTCMAP
. This call is likely to be
unavailable on text-only displays.
-
-
WSDISPLAYIO_GETCMAP
(struct wsdisplay_cmap
)
- Retrieve the current color map from the display. This call
needs the following structure set up beforehand:
struct wsdisplay_cmap {
u_int index;
u_int count;
u_char *red;
u_char *green;
u_char *blue;
};
The index and count members
specify the range of color map entries to retrieve. The
red, green, and
blue members should each point to an array of
count u_char
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.
-
-
WSDISPLAYIO_PUTCMAP
(struct wsdisplay_cmap
)
- Change the display's color map. The argument structure is
the same as for
WSDISPLAYIO_GETCMAP
, but
red, green, and
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.
-
-
WSDISPLAYIO_GVIDEO
(int
)
- Get the current state of the display's video output.
Possible values are:
-
-
WSDISPLAYIO_VIDEO_OFF
- The display is blanked.
-
-
WSDISPLAYIO_VIDEO_ON
- The display is enabled.
-
-
WSDISPLAYIO_SVIDEO
(int
)
- Set the state of the display's video output. See
WSDISPLAYIO_GVIDEO
above for possible values.
-
-
WSDISPLAYIO_GCURPOS
(struct wsdisplay_curpos
)
- Retrieve the current position of the hardware cursor. The
returned structure is as follows:
struct wsdisplay_curpos {
u_int x, y;
};
The x and 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.
-
-
WSDISPLAYOP_SCURPOS
(struct wsdisplay_curpos
)
- Set the current cursor position. The argument structure,
and its semantics, are the same as for
WSDISPLAYIO_GCURPOS
. This call is not available on
displays without a hardware cursor.
-
-
WSDISPLAYIO_GCURMAX
(struct wsdisplay_curpos
)
- Retrieve the maximum size of cursor supported by the
display. The x and 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.
-
-
WSDISPLAYIO_GCURSOR
(struct wsdisplay_cursor
)
- Retrieve some or all of the hardware cursor's attributes.
The argument structure is as follows:
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;
};
The which member indicates which of the values the
application requires to be returned. It should contain the logical OR of
the following flags:
-
-
WSDISPLAY_CURSOR_DOCUR
- Get enable, which indicates
whether the cursor is currently displayed (non-zero) or not
(zero).
-
-
WSDISPLAY_CURSOR_DOPOS
- Get pos, which indicates the
current position of the cursor on the display, as would be returned by
WSDISPLAYIO_GCURPOS
.
-
-
WSDISPLAY_CURSOR_DOHOT
- Get hot, which indicates the
location of the “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.
-
-
WSDISPLAY_CURSOR_DOCMAP
- Get cmap, which indicates the
current cursor color map. Unlike in a call to
WSDISPLAYIO_GETCMAP
,
cmap here need not have its
index and count members
initialized. They will be set to 0 and 2 respectively by the call.
This means that cmap.red,
cmap.green, and
cmap.blue must each point
to at least enough space to hold two
u_char
s.
-
-
WSDISPLAY_CURSOR_DOSHAPE
- Get size,
image, and 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.
-
-
WSDISPLAY_CURSOR_DOALL
- Get all of the above.
The device may elect to return information that was not requested by the
user, so those elements of struct wsdisplay_cursor
which are pointers should be initialized to NULL
if not otherwise used. This call is not available on displays without a
hardware cursor.
-
-
WSDISPLAYIO_SCURSOR
(struct wsdisplay_cursor
)
- Set some or all of the hardware cursor's attributes. The
argument structure is the same as for
WSDISPLAYIO_GCURSOR
. The
which member specifies which attributes of the
cursor are to be changed. It should contain the logical OR of the
following flags:
-
-
WSDISPLAY_CURSOR_DOCUR
- If enable is zero, hide the
cursor. Otherwise, display it.
-
-
WSDISPLAY_CURSOR_DOPOS
- Set the cursor's position on the display to
pos, the same as
WSDISPLAYIO_SCURPOS
.
-
-
WSDISPLAY_CURSOR_DOHOT
- Set the “hot spot” of the cursor, as
defined above, to hot.
-
-
WSDISPLAY_CURSOR_DOCMAP
- Set some or all of the cursor color map based on
cmap. The index and
count elements of cmap
indicate which color map entries to set, and the entries themselves
come from cmap.red,
cmap.green, and
cmap.blue.
-
-
WSDISPLAY_CURSOR_DOSHAPE
- Set the cursor shape from size,
image, and mask. See above
for their meanings.
-
-
WSDISPLAY_CURSOR_DOALL
- Do all of the above.
This call is not available on displays without a hardware cursor.
-
-
WSDISPLAYIO_GMODE
(u_int
)
- Get the current mode of the display. Possible results
include:
-
-
WSDISPLAYIO_MODE_EMUL
- The display is in emulating (text) mode.
-
-
WSDISPLAYIO_MODE_MAPPED
- The display is in mapped (graphics) mode.
-
-
WSDISPLAYIO_MODE_DUMBFB
- The display is in mapped (frame buffer) mode.
-
-
WSDISPLAYIO_SMODE
(u_int
)
- Set the current mode of the display. For possible
arguments, see
WSDISPLAYIO_GMODE
.
-
-
WSDISPLAYIO_LINEBYTES
(u_int
)
- Get the number of bytes per row, which may be the same as
the number of pixels.
-
-
WSDISPLAYIO_GMSGATTRS
(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:
struct wsdisplay_msgattrs {
int default_attrs, default_bg, default_fg;
int kernel_attrs, kernel_bg, kernel_fg;
};
The default_attrs and
kernel_attrs variables are a combination of
WSATTR_* bits, and specify the attributes used to
draw messages. The default_bg,
default_fg, kernel_bg and
kernel_fg variables specify the colors used to print
messages, being ‘_bg’ for the background and ‘_fg’
for the foreground; their values are one of all the
WSCOL_* macros available.
-
-
WSDISPLAYIO_SMSGATTRS
(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
WSDISPLAYIO_GMSGATTRS
.
-
-
WSDISPLAYIO_GBORDER
(u_int
)
- Retrieve the color of the screen border. This number
corresponds to an ANSI standard color.
-
-
WSDISPLAYIO_SBORDER
(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.
-
-
WSDISPLAYIO_GETWSCHAR
(struct wsdisplay_char
)
- Gets a single character from the screen, specified by its
position. The structure used is as follows:
struct wsdisplay_char {
int row, col;
uint16_t letter;
uint8_t background, foreground;
char flags;
};
The row and col parameters are
used as input; the rest of the structure is filled by the ioctl and is
returned to you. letter is the ASCII code of the
letter found at the specified position, background
and foreground are its colors and
flags is a combination of
‘WSDISPLAY_CHAR_BRIGHT’ and/or
‘WSDISPLAY_CHAR_BLINK’.
-
-
WSDISPLAYIO_PUTWSCHAR
(struct wsdisplay_char
)
- Puts a character on the screen. The structure has the same
meaning as described in
WSDISPLAY_GETWSCHAR
,
although all of its fields are treated as input.
-
-
WSDISPLAYIO_SSPLASH
(u_int
)
- Toggle the splash screen. This call is only available with
the
SPLASHSCREEN
kernel option.
-
-
WSDISPLAYIO_GET_EDID
(struct wsdisplay_edid_info
)
- Retrieve EDID data from a driver.
struct wsdisplayio_edid_info {
uint32_t buffer_size;
uint32_t data_size;
void *edid_data;
};
The caller is responsible for allocating a buffer of at least 128 bytes (the
minimum size of an EDID block) and set data_size to its size. If the EDID
block is bigger the call will fail with EAGAIN
and
the driver will set data_size to the required buffer size. Otherwise the
EDID block will be written into the buffer pointed at by edid_data and
data_size will be set to the number of bytes written.
-
-
WSDISPLAYIO_SETVERSION
(int
)
- Set the wscons_event protocol version. The default is 0 for
binary compatibility. The latest version is always available as
WSDISPLAYIO_EVENT_VERSION
, and is currently 1. All
new code should use a call similar to the below to ensure the correct
version is returned.
int ver = WSDISPLAY_EVENT_VERSION;
if (ioctl(fd, WSDISPLAYIO_SETVERSION, &ver) == -1)
err(EXIT_FAILURE, "cannot set version");
FILES
- /dev/ttyE* Terminal devices (per
screen).
- /dev/ttyEcfg Control device.
- /dev/ttyEstat Status device.
- /usr/include/dev/wscons/wsconsio.h
SEE ALSO
ioctl(2),
pcdisplay(4),
tty(4),
vga(4),
wscons(4),
wsconscfg(8),
wsconsctl(8),
wsfontload(8),
wsdisplay(9)
BUGS
The
wsdisplay code currently limits the number of screens on
one display to 8.
The terms “wscons” and “wsdisplay” are not cleanly
distinguished in the code and in manual pages.
“non-emulating” display devices are not tested.