WSDISPLAY(4) | Device Drivers Manual | WSDISPLAY(4) |
wsdisplay
—
generic display device support in wscons
wsdisplay* at ...
option WSDISPLAY_DEFAULTSCREENS=N
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:
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.
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<dev/wscons/wsconsio.h>
.WSDISPLAYIO_GINFO
struct wsdisplay_fbinfostruct 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_GETSCREENTYPE
struct wsdisplay_screentypestruct 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_cmapstruct 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_cmapWSDISPLAYIO_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_intWSDISPLAYIO_VIDEO_OFF
WSDISPLAYIO_VIDEO_ON
WSDISPLAYIO_SVIDEO
u_intWSDISPLAYIO_GVIDEO
above for possible values.WSDISPLAYIO_GCURPOS
struct wsdisplay_curposstruct 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_curposWSDISPLAYIO_GCURPOS
. This call is not available on
displays without a hardware cursor.WSDISPLAYIO_GCURMAX
struct wsdisplay_curposWSDISPLAYIO_GCURSOR
struct wsdisplay_cursorstruct 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
WSDISPLAY_CURSOR_DOPOS
WSDISPLAYIO_GCURPOS
.WSDISPLAY_CURSOR_DOHOT
WSDISPLAY_CURSOR_DOCMAP
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
WSDISPLAY_CURSOR_DOALL
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_cursorWSDISPLAYIO_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
WSDISPLAY_CURSOR_DOPOS
WSDISPLAYIO_SCURPOS
.WSDISPLAY_CURSOR_DOHOT
WSDISPLAY_CURSOR_DOCMAP
WSDISPLAY_CURSOR_DOSHAPE
WSDISPLAY_CURSOR_DOALL
This call is not available on displays without a hardware cursor.
WSDISPLAYIO_GMODE
u_intWSDISPLAYIO_MODE_EMUL
WSDISPLAYIO_MODE_MAPPED
WSDISPLAYIO_MODE_DUMBFB
WSDISPLAYIO_SMODE
u_intWSDISPLAYIO_GMODE
.WSDISPLAYIO_LDFONT
struct wsdisplay_fontstruct 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
WSDISPLAY_FONTENC_IBM
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
WSDISPLAY_FONTORDER_R2L
The data field contains the font character data to be loaded. The cookie field is reserved for internal purposes.
WSDISPLAYIO_LSFONT
struct wsdisplay_fontWSDISPLAYIO_LDFONT
.WSDISPLAYIO_USEFONT
struct wsdisplay_fontWSDISPLAYIO_LDFONT
.WSDISPLAYIO_GBURNER
struct wsdisplay_burnerstruct 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
WSDISPLAY_BURN_KBD
WSDISPLAY_BURN_MOUSE
WSDISPLAY_BURN_OUTPUT
If none of the activity source flags are set, the screen burner is disabled.
WSDISPLAYIO_SBURNER
struct wsdisplay_burnerWSDISPLAYIO_GBURNER
.WSDISPLAYIO_ADDSCREEN
struct wsdisplay_addscreendatastruct 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:
An empty string will select the default emulation.
WSDISPLAYIO_DELSCREEN
struct wsdisplay_delscreendatastruct 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
WSDISPLAY_DELSCR_QUIET
WSDISPLAYIO_GETSCREEN
struct wsdisplay_addscreendataWSDISPLAYIO_GETPARAM
).WSDISPLAYIO_SETSCREEN
u_intWSDISPLAYIO_WSMOUSED
struct wscons_eventWSDISPLAYIO_GETPARAM
struct wsdisplay_paramstruct 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
WSDISPLAYIO_PARAM_BRIGHTNESS
WSDISPLAYIO_PARAM_CONTRAST
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_paramWSDISPLAYIO_GETPARAM
, with the
param and curval members
filled in. Not all parameters are supported by all display drivers.WSDISPLAYIO_LINEBYTES
u_intWSDISPLAYIO_MODE_DUMBFB
mode.intro(4), tty(4), wscons(4), wsmux(4), wsconscfg(8), wsconsctl(8), wsfontload(8)
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.
September 18, 2020 | OpenBSD-current |