--- name: "wsdisplay" section: "4" platform: "openbsd" package: "man" version: "8.0-current-20261101" release: "OpenBSD 8.0-current (2026-11-01)" platforms: ["openbsd"] url: "https://new.carta.tech/wsdisplay" --- # wsdisplay(4) generic display device support in wscons ## 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)](/wscons/4.md) 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)](/wsmux/4.md) 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)](/lcd/4.md) and [vga(4)](/vga/4.md) 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)](/wsconscfg/8.md) 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)](/wsconsctl/8.md) 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)](/ioctl/2.md) 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 and WSDISPLAYIO\_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\_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 *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; }; ``` 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-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\_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*, *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)](/wsmouse/4.md) 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)](/wsmoused/8.md) 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)](/intro/4.md), [tty(4)](/tty/4.md), [wscons(4)](/wscons/4.md), [wsmux(4)](/wsmux/4.md), [wsconscfg(8)](/wsconscfg/8.md), [wsconsctl(8)](/wsconsctl/8.md), [wsfontload(8)](/wsfontload/8.md) ## 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.