Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WSDISPLAY(4)	       FreeBSD Kernel Interfaces Manual		  WSDISPLAY(4)

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 inter-
     face.

     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 in-
     terface.

     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	(some-
     times 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 num-
     bers and separate tty instances.  One screen possesses the	"focus", this
     means it is displayed on the display and its tty device will get the key-
     board 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 autocon-
     figuration	time.

     In	addition and with help from backend drivers the	following features are
     also provided:

     +o	 Loading, deleting and listing the loaded fonts.

     +o	 Browsing backwards in the screen output, the size of the buffer for
	 saved text is defined by the particular hardware driver.

     +o	 Blanking the screen by	timing out on inactivity in the	screen holding
	 the input focus.  Awakening activities	consist	of:

	 +o   pressing any keys on the keyboard;
	 +o   moving or clicking	the mouse;
	 +o   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	sup-
     ported 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	re-
	   turned 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 mem-
	   ber 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	char-
	   acter 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 val-
	   ues 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, re-
	   spectively, 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 num-
	   ber 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 ar-
	   gument 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 re-
	   quires 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 po-
		 sition	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.  Un-
		 like 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 di-
		 mensions 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 en-
		 tries 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	struc-
	   ture.  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	se-
	   lects 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 be-
	   fore	the screen is turned back on, in milliseconds.	The flags mem-
	   ber contains	a logical OR of	the following flags:

	   WSDISPLAY_BURN_VBLANK
		 When turning the display off, disable the vertical synchro-
		 nization 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	pro-
		 gram.

	   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.

FreeBSD	13.0		      September	18, 2020		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=wsdisplay&sektion=4&manpath=OpenBSD+6.9>

home | help