NAME
wsdisplay
—
generic display device support in
wscons
SYNOPSIS
wsdisplay* at ...
option WSDISPLAY_DEFAULTSCREENS=N
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 text terminal or graphics
interface.
Display devices have the ability to display characters on them
(without help of an X server), either directly by hardware or through
software drawing pixel data into the display memory. The
wsdisplay
driver will connect a terminal emulation
module and provide a tty-like software interface.
The
console locator
in the configuration line refers to the device's use as 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 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.
The mux 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
lcd(4) and vga(4) display drivers provide this ability.) Screens have
different minor device numbers and separate tty instances. One screen
possesses the “focus”, this means it is displayed on the
display 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 CTL-ALT-Fn) or an ioctl command issued by a user
program. Screens are set up or deleted through the
/dev/ttyCcfg control device (preferably using the
wsconscfg(8) utility). Alternatively, the compile-time
option WSDISPLAY_DEFAULTSCREENS=N
will set up N
screens of the display driver's default type and using the system's default
terminal emulator at autoconfiguration time.
In addition and with help from backend drivers the following features are also provided:
- Loading, deleting and listing the loaded fonts.
- Browsing backwards in the screen output, the size of the buffer for saved text is defined by the particular hardware driver.
- Blanking the screen by timing out on inactivity in the screen holding the
input focus. Awakening activities consist of:
- pressing any keys on the keyboard;
- moving or clicking the mouse;
- any output to the screen.
Blanking the screen is usually done by disabling the horizontal sync signal on video output, but may also include blanking the vertical sync in which case most monitors go into power saving mode. See wsconsctl(8) for controlling variables.
Consult the back-end drivers' documentation for which features are supported for each particular hardware type.
IOCTL INTERFACE
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
u_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
andWSDISPLAYIO_PUTCMAP
. This call is likely to be unavailable on text-only displays. WSDISPLAYIO_GETSCREENTYPE
struct wsdisplay_screentype- Retrieve basic information about a screen. The returned structure is as
follows:
struct wsdisplay_screentype { int idx; int nidx; char name[WSSCREEN_NAME_SIZE]; int ncols, nrows; int fontwidth, fontheight; };
The idx field indicates the index of the screen. The nidx field indicates the number of screens. The name field contains a human readable string used to identify the screen. The ncols and nrows fields indicate the available number of columns and rows. The fontwidth and fontheight fields indicate the dimensions of a character cell, in pixels.
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_chars. 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
u_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
u_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.
WSDISPLAYIO_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; };
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-left 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_chars. 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, 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_LDFONT
struct wsdisplay_font- Loads a font specified by the wsdisplay_font structure.
struct wsdisplay_font { char name[WSFONT_NAME_SIZE]; int index; int firstchar, numchars; int encoding; u_int fontwidth, fontheight, stride; int bitorder, byteorder; void *cookie; void *data; };
The name field contains a human readable string used to identify the font. The index field may be used to select a driver-specific font resource (for non-raster frame buffers). A value of -1 will pick the first available slot. The firstchar field contains the index of the first character in the font, starting at zero. The numchars field contains the number of characters in the font. The encoding field describes the font character encoding, using one of the following values:
WSDISPLAY_FONTENC_ISO
- ISO-8859-1 encoding (also known as Latin-1). This is the preferred encoding for raster frame buffers.
WSDISPLAY_FONTENC_IBM
- IBM code page number 437. This is the preferred encoding for text-mode displays.
The fontwidth and fontheight fields specify the dimensions of a character cell. The stride field specify the number of bytes of font data per character cell line (usually fontwidth rounded up to a byte boundary). The bitorder and byteorder fields specify the bit- and byte-ordering of the font data, using either one of the following values:
WSDISPLAY_FONTORDER_L2R
- Leftmost data contained in the most significant bits (left-to-right ordering). This is the most commonly encountered case.
WSDISPLAY_FONTORDER_R2L
- Leftmost data contained in the least significant bits (right-to-left ordering).
The data field contains the font character data to be loaded. The cookie field is reserved for internal purposes.
WSDISPLAYIO_LSFONT
struct wsdisplay_font- Retrieves the data for a loaded font into the wsdisplay_font structure.
The index field is set to the font resource to
query. For the argument structure, see
WSDISPLAYIO_LDFONT
. WSDISPLAYIO_USEFONT
struct wsdisplay_font- Selects the font specified in the name field. An
empty name selects the next available font. For the
argument structure, see
WSDISPLAYIO_LDFONT
. WSDISPLAYIO_GBURNER
struct wsdisplay_burner- Retrieves the state of the screen burner. The returned structure is as
follows:
struct wsdisplay_burner { u_int off; u_int on; u_int flags; };
The off member contains the inactivity time before the screen is turned off, in milliseconds. The on member contains the time before the screen is turned back on, in milliseconds. The flags member contains a logical OR of the following flags:
WSDISPLAY_BURN_VBLANK
- When turning the display off, disable the vertical synchronization signal.
WSDISPLAY_BURN_KBD
- Monitor keyboard activity.
WSDISPLAY_BURN_MOUSE
- Monitor mouse activity (this only works for mice using the wsmouse(4) driver).
WSDISPLAY_BURN_OUTPUT
- Monitor display output activity.
If none of the activity source flags are set, the screen burner is disabled.
WSDISPLAYIO_SBURNER
struct wsdisplay_burner- Sets the state of the screen burner. The argument structure, and its
semantics, are the same as for
WSDISPLAYIO_GBURNER
. WSDISPLAYIO_ADDSCREEN
struct wsdisplay_addscreendata- Creates a new screen.
struct wsdisplay_addscreendata { int idx; /* screen index */ char screentype[WSSCREEN_NAME_SIZE]; char emul[WSEMUL_NAME_SIZE]; };
The idx field is the index of the screen to be configured. The screentype field is matched against builtin screen types, which will be driver-dependent. The emul field indicates the terminal emulation type. Available terminal emulations are:
- sun
- Sun terminal emulation. This is the default on the sparc64 architecture.
- vt100
- Dec VT100 terminal emulation, with some VT220 features. This is the default on all other architectures.
- dumb
- Dumb terminal.
An empty string will select the default emulation.
WSDISPLAYIO_DELSCREEN
struct wsdisplay_delscreendata- Deletes an existing screen.
struct wsdisplay_delscreendata { int idx; /* screen index */ int flags; };
The idx field indicates the index of the screen to be deleted. The flags field is a logical OR of zero or more of the following:
WSDISPLAY_DELSCR_FORCE
- Force deletion of screen even if in use by a userspace program.
WSDISPLAY_DELSCR_QUIET
- Don't report deletion to console.
WSDISPLAYIO_GETSCREEN
struct wsdisplay_addscreendata- Returns information on the screen indicated by idx
or the current screen if idx is -1. The screen and
emulation types are returned in the same structure (see
WSDISPLAYIO_GETPARAM
). WSDISPLAYIO_SETSCREEN
u_int- Switch to the screen with the given index.
WSDISPLAYIO_WSMOUSED
struct wscons_event- This call is used by the wsmoused(8) daemon to inject mouse events gathered from serial mice, as well as various control events.
WSDISPLAYIO_GETPARAM
struct wsdisplay_param- Retrieves the state of a display parameter. This call needs the following
structure set up beforehand:
struct wsdisplay_param { int param; int min, max, curval; int reserved[4]; };
The param member should be set with the parameter to be returned. The following parameters are supported:
WSDISPLAYIO_PARAM_BACKLIGHT
- The intensity of the display backlight (usually on laptop computers).
WSDISPLAYIO_PARAM_BRIGHTNESS
- The brightness level.
WSDISPLAYIO_PARAM_CONTRAST
- The contrast level.
On return, min and max specify the allowed range for the value, while curval specifies the current setting. Not all parameters are supported by all display drivers.
WSDISPLAYIO_SETPARAM
struct wsdisplay_param- Sets a display parameter. The argument structure is the same as for
WSDISPLAYIO_GETPARAM
, with the param and curval members filled in. Not all parameters are supported by all display drivers. WSDISPLAYIO_LINEBYTES
u_int- Get the number of bytes per row when the device is in
WSDISPLAYIO_MODE_DUMBFB
mode.
FILES
- /dev/tty[C-F]*
- terminal devices (per screen)
- /dev/tty[C-F]cfg
- control device (per screen)
- /usr/include/dev/wscons/wsconsio.h
SEE ALSO
intro(4), tty(4), wscons(4), wsmux(4), wsconscfg(8), wsconsctl(8), wsfontload(8)
BUGS
The wsdisplay
code currently limits the
number of screens on one display to 12.
The terms “wscons” and “wsdisplay” are not cleanly distinguished in the code and in manual pages.