.\" $NetBSD: wsdisplay.4,v 1.50 2020/12/23 06:10:13 uwe Exp $
.\"
.\" Copyright (c) 1999 Matthias Drochner.
.\" Copyright (c) 2002 Ben Harris.
.\" Copyright (c) 2004 Julio M. Merino Vidal.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd May 16, 2020
.Dt WSDISPLAY 4
.Os
.Sh NAME
.Nm wsdisplay
.Nd generic display device support in wscons
.Sh SYNOPSIS
.Cd "wsdisplay* at ega? console ?"
(EGA display on ISA)
.Cd "wsdisplay* at vga? console ?"
(VGA display on ISA or PCI)
.Cd "wsdisplay* at pcdisplay? console ?"
(generic PC (ISA) display)
.Cd "wsdisplay* at tga? console ?"
(DEC TGA display, alpha only)
.Cd "wsdisplay* at pfb? console ?"
(PCI framebuffer, bebox only)
.Cd "wsdisplay0 at ofb? console ?"
(Open Firmware framebuffer, macppc only)
.Cd "wsdisplay* at nextdisplay? console ?"
(NeXT display)
.Cd "wsdisplay0 at smg0"
(VAXstation small monochrome display)
.Cd "wsdisplay* at ... kbdmux N"
.Pp
.Cd options WSDISPLAY_BORDER_COLOR=WSCOL_XXX
.Cd options WSDISPLAY_CUSTOM_BORDER
.Cd options WSDISPLAY_CUSTOM_OUTPUT
.Cd options WSDISPLAY_DEFAULTSCREENS=N
.Cd options WSDISPLAY_SCROLLSUPPORT
.Sh DESCRIPTION
The
.Nm
driver is an abstraction layer for display devices within the
.Xr wscons 4
framework.
It attaches to the hardware specific display device driver and makes it
available as a text terminal or graphics interface.
.Pp
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
.Dq emulating ,
the
.Nm
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.
.Pp
The
.Cd 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
.Dq emulating
display devices are usable as console.)
.Pp
The
.Cd kbdmux
locator in the configuration line refers to the
.Xr wsmux 4
that will be used to get keyboard events.
If this locator is -1 no mux will be used.
.Pp
The logical unit of an independent contents displayed on a display
(sometimes referred to as
.Dq virtual terminal )
is called a
.Dq screen
here.
If the underlying device driver supports it, multiple screens can
be used on one display.
(As of this writing, only the
.Xr vga 4
and the VAX
.Dq smg
display drivers provide this ability.)
Screens have different minor device numbers and separate tty instances.
One screen possesses the
.Dq 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
.Ao "Ctrl" Ac Ns \| Ns Ao "Alt" Ac Ns \| Ns Ao "F" Ns Ar "n" Ac ,
.Ao "Stop" Ac Ns \| Ns Ao "F" Ns Ar "n" Ac
on Sun hardware,
.Ao "Command" Ac Ns \| Ns Ao "F" Ns Ar "n" Ac
on ADB keyboards)
or an ioctl command issued by a user program.
Screens are created and deleted through the
.Pa /dev/ttyEcfg
control device (preferably using the
.Xr wsconscfg 8
utility).
Alternatively, the compile-time option
.Dv WSDISPLAY_DEFAULTSCREENS Ns = Ns Ar n
will also create (at autoconfiguration time)
.Ar n
initial screens of the display driver's default type with
the system's default terminal emulator.
.Ss Kernel options
The following kernel options are available to configure the behavior of the
.Nm
driver:
.Bl -tag -width xxxxxxxx
.It Cd options WSDISPLAY_BORDER_COLOR=WSCOL_XXX
Sets the border color at boot time.
Possible values are defined in
.Pa src/sys/dev/wscons/wsdisplayvar.h .
Defaults to
.Dv WSCOL_BLACK .
.It Cd options WSDISPLAY_CUSTOM_BORDER
Enables the
.Dv WSDISPLAYIO_GBORDER
and
.Dv WSDISPLAYIO_SBORDER
ioctls, which allow the customization of the border color from userland
(after boot).
See
.Xr wsconsctl 8 .
.It Cd options WSDISPLAY_CUSTOM_OUTPUT
Enables the
.Dv WSDISPLAYIO_GMSGATTRS
and
.Dv WSDISPLAYIO_SMSGATTRS
ioctls, which allow the customization of the console output and kernel
messages from userland (after boot).
See
.Xr wsconsctl 8 .
.It Cd options WSDISPLAY_DEFAULTSCREENS=N
Sets the number of virtual screens to allocate at boot time.
Useful for small root filesystems where the
.Xr wsconscfg 8
utility is not wanted.
.It Cd options WSDISPLAY_SCROLLSUPPORT
Enables scrolling support.
The key combinations are
.Ao "Left\ Shift" Ac Ns \| Ns Ao "Page\ Up" Ac
and
.Ao "Left\ Shift" Ac Ns \| Ns Ao "Page\ Down" Ac
by default.
Please note that this function may not work under the system console and
is available depending on the framebuffer you are using.
.El
.Ss Ioctls
The following
.Xr ioctl 2
calls are provided by the
.Nm
driver or by devices which use it.
Their definitions are found in
.In dev/wscons/wsconsio.h .
.Bl -tag -width Dv
.It Dv WSDISPLAYIO_GTYPE Pq Li int
Retrieve the type of the display.
The list of types is in
.In dev/wscons/wsconsio.h .
.It Dv WSDISPLAYIO_GET_FBINFO Pq Li "struct wsdisplayio_fbinfo"
Retrieve extended information about a framebuffer display,
including the framebuffer's pixel packing layout.
The returned structure is as follows:
.Bd -literal -offset indent
struct wsdisplayio_fbinfo {
	uint64_t fbi_fbsize;
	uint64_t fbi_fboffset;
	uint32_t fbi_width;
	uint32_t fbi_height;
	uint32_t fbi_stride;
	uint32_t fbi_bitsperpixel;
	uint32_t fbi_pixeltype;
	union _fbi_subtype {
		struct _fbi_rgbmasks {
			uint32_t red_offset;
			uint32_t red_size;
			uint32_t green_offset;
			uint32_t green_size;
			uint32_t blue_offset;
			uint32_t blue_size;
			uint32_t alpha_offset;
			uint32_t alpha_size;
		} fbi_rgbmasks;
		struct _fbi_cmapinfo {
			uint32_t cmap_entries;
		} fbi_cmapinfo;
	} fbi_subtype;
	uint32_t fbi_flags;
};
.Ed
.Pp
For a "true colour" display, the
.Va fbi_pixeltype
field contains
.Dv WSFB_RGB
and the
.Va fbi_rgbmasks
field contains the pixel packing layout.
For a colour indexed display, the
.Va fbi_pixeltype
field contains
.Dv WSFB_CI
and the
.Va fbi_cmapinfo
field contains the number of color map entries.
.It Dv WSDISPLAYIO_GINFO Pq Li "struct wsdisplay_fbinfo"
Retrieve basic information about a framebuffer display.
The returned structure is as follows:
.Bd -literal -offset indent
struct wsdisplay_fbinfo {
	u_int	height;
	u_int	width;
	u_int	depth;
	u_int	cmsize;
};
.Ed
.Pp
The
.Va height
and
.Va width
members are counted in pixels.
The
.Va depth
member indicates the number of bits per pixel, and
.Va cmsize
indicates the number of color map entries accessible through
.Dv WSDISPLAYIO_GETCMAP
and
.Dv WSDISPLAYIO_PUTCMAP .
This call is likely to be unavailable on text-only displays.
.It Dv WSDISPLAYIO_GETCMAP Pq Li "struct wsdisplay_cmap"
Retrieve the current color map from the display.
This call needs the
following structure set up beforehand:
.Bd -literal -offset indent
struct wsdisplay_cmap {
	u_int	index;
	u_int	count;
	u_char	*red;
	u_char	*green;
	u_char	*blue;
};
.Ed
.Pp
The
.Va index
and
.Va count
members specify the range of color map entries to retrieve.
The
.Va red ,
.Va green ,
and
.Va blue
members should each point to an array of
.Va count
.Vt u_char Ns No \^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.
.It Dv WSDISPLAYIO_PUTCMAP Pq Li "struct wsdisplay_cmap"
Change the display's color map.
The argument structure is the same as for
.Dv WSDISPLAYIO_GETCMAP ,
but
.Va red ,
.Va green ,
and
.Va 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.
.It Dv WSDISPLAYIO_GVIDEO Pq Li int
Get the current state of the display's video output.
Possible values are:
.Bl -tag -width Dv
.It Dv WSDISPLAYIO_VIDEO_OFF
The display is blanked.
.It Dv WSDISPLAYIO_VIDEO_ON
The display is enabled.
.El
.It Dv WSDISPLAYIO_SVIDEO Pq Li int
Set the state of the display's video output.
See
.Dv WSDISPLAYIO_GVIDEO
above for possible values.
.It Dv WSDISPLAYIO_GCURPOS Pq Li "struct wsdisplay_curpos"
Retrieve the current position of the hardware cursor.
The returned structure
is as follows:
.Bd -literal -offset indent
struct wsdisplay_curpos {
        u_int x, y;
};
.Ed
.Pp
The
.Va x
and
.Va 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.
.It Dv WSDISPLAYOP_SCURPOS Pq Li "struct wsdisplay_curpos"
Set the current cursor position.
The argument structure, and its semantics, are the same as for
.Dv WSDISPLAYIO_GCURPOS .
This call is not available on displays without a hardware cursor.
.It Dv WSDISPLAYIO_GCURMAX Pq Li "struct wsdisplay_curpos"
Retrieve the maximum size of cursor supported by the display.
The
.Va x
and
.Va 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.
.It Dv WSDISPLAYIO_GCURSOR Pq Li "struct wsdisplay_cursor"
Retrieve some or all of the hardware cursor's attributes.
The argument structure is as follows:
.Bd -literal -offset indent
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;
};
.Pp
.Ed
The
.Va which
member indicates which of the values the application requires to be returned.
It should contain the logical OR of the following flags:
.Bl -tag -width Dv
.It Dv WSDISPLAY_CURSOR_DOCUR
Get
.Va enable ,
which indicates whether the cursor is currently displayed (non-zero) or
not (zero).
.It Dv WSDISPLAY_CURSOR_DOPOS
Get
.Va pos ,
which indicates the current position of the cursor on the display, as
would be returned by
.Dv WSDISPLAYIO_GCURPOS .
.It Dv WSDISPLAY_CURSOR_DOHOT
Get
.Va hot ,
which indicates the location of the
.Dq 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.
.It Dv WSDISPLAY_CURSOR_DOCMAP
Get
.Va cmap ,
which indicates the current cursor color map.
Unlike in a call to
.Dv WSDISPLAYIO_GETCMAP ,
.Va cmap
here need not have its
.Va index
and
.Va count
members initialized.
They will be set to 0 and 2 respectively by the call.
This means that
.Va cmap . Ns Va red ,
.Va cmap . Ns Va green ,
and
.Va cmap . Ns Va blue
must each point to at least enough space to hold two
.Vt u_char Ns No \^s .
.It Dv WSDISPLAY_CURSOR_DOSHAPE
Get
.Va size , image ,
and
.Va 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.
.It Dv WSDISPLAY_CURSOR_DOALL
Get all of the above.
.El
.Pp
The device may elect to return information that was not requested by the user,
so those elements of
.Li "struct wsdisplay_cursor"
which are pointers should be initialized to
.Dv NULL
if not otherwise used.
This call is not available on displays without a hardware cursor.
.It Dv WSDISPLAYIO_SCURSOR Pq Li "struct wsdisplay_cursor"
Set some or all of the hardware cursor's attributes.
The argument structure is the same as for
.Dv WSDISPLAYIO_GCURSOR .
The
.Va which
member specifies which attributes of the cursor are to be changed.
It should contain the logical OR of the following flags:
.Bl -tag -width Dv
.It Dv WSDISPLAY_CURSOR_DOCUR
If
.Va enable
is zero, hide the cursor.
Otherwise, display it.
.It Dv WSDISPLAY_CURSOR_DOPOS
Set the cursor's position on the display to
.Va pos ,
the same as
.Dv WSDISPLAYIO_SCURPOS .
.It Dv WSDISPLAY_CURSOR_DOHOT
Set the
.Dq hot spot
of the cursor, as defined above, to
.Va hot .
.It Dv WSDISPLAY_CURSOR_DOCMAP
Set some or all of the cursor color map based on
.Va cmap .
The
.Va index
and
.Va count
elements of
.Va cmap
indicate which color map entries to set, and the entries themselves come from
.Va cmap . Ns Va red ,
.Va cmap . Ns Va green ,
and
.Va cmap . Ns Va blue .
.It Dv WSDISPLAY_CURSOR_DOSHAPE
Set the cursor shape from
.Va size , image ,
and
.Va mask .
See above for their meanings.
.It Dv WSDISPLAY_CURSOR_DOALL
Do all of the above.
.El
.Pp
This call is not available on displays without a hardware cursor.
.It Dv WSDISPLAYIO_GMODE Pq Li u_int
Get the current mode of the display.
Possible results include:
.Bl -tag -width Dv
.It Dv WSDISPLAYIO_MODE_EMUL
The display is in emulating (text) mode.
.It Dv WSDISPLAYIO_MODE_MAPPED
The display is in mapped (graphics) mode.
.It Dv WSDISPLAYIO_MODE_DUMBFB
The display is in mapped (frame buffer) mode.
.El
.It Dv WSDISPLAYIO_SMODE Pq Li u_int
Set the current mode of the display.
For possible arguments, see
.Dv WSDISPLAYIO_GMODE .
.It Dv WSDISPLAYIO_LINEBYTES Pq Li u_int
Get the number of bytes per row, which may be the same as the number of pixels.
.It Dv WSDISPLAYIO_GMSGATTRS Pq Li 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:
.Bd -literal -offset indent
struct wsdisplay_msgattrs {
	int default_attrs, default_bg, default_fg;
	int kernel_attrs, kernel_bg, kernel_fg;
};
.Ed
.Pp
The
.Va default_attrs
and
.Va kernel_attrs
variables are a combination of
.Dv WSATTR_ Ns Ar *
bits, and specify the attributes used to draw messages.
The
.Va default_bg ,
.Va default_fg ,
.Va kernel_bg
and
.Va kernel_fg
variables specify the colors used to print messages, being
.Sq _bg
for the background and
.Sq _fg
for the foreground; their values are one of all the
.Dv WSCOL_ Ns Ar *
macros available.
.It Dv WSDISPLAYIO_SMSGATTRS Pq Li 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
.Dv WSDISPLAYIO_GMSGATTRS .
.It Dv WSDISPLAYIO_GBORDER Pq Li u_int
Retrieve the color of the screen border.
This number corresponds to an ANSI standard color.
.It Dv WSDISPLAYIO_SBORDER Pq Li 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.
.It Dv WSDISPLAYIO_GETWSCHAR Pq Li struct wsdisplay_char
Gets a single character from the screen, specified by its position.
The structure used is as follows:
.Bd -literal -offset indent
struct wsdisplay_char {
	int row, col;
	uint16_t letter;
	uint8_t background, foreground;
	char flags;
};
.Ed
.Pp
The
.Va row
and
.Va col
parameters are used as input; the rest of the structure is filled by the
ioctl and is returned to you.
.Va letter
is the ASCII code of the letter found at the specified position,
.Va background
and
.Va foreground
are its colors and
.Va flags
is a combination of
.Dv WSDISPLAY_CHAR_BRIGHT
and/or
.Dv WSDISPLAY_CHAR_BLINK .
.It Dv WSDISPLAYIO_PUTWSCHAR Pq Li struct wsdisplay_char
Puts a character on the screen.
The structure has the same meaning as described in
.Dv WSDISPLAY_GETWSCHAR ,
although all of its fields are treated as input.
.\" Splash screen control
.It Dv WSDISPLAYIO_SSPLASH Pq Li u_int
Toggle the splash screen.
This call is only available with the
.Dv SPLASHSCREEN
kernel option.
.It Dv WSDISPLAYIO_GET_EDID Pq Li struct wsdisplayio_edid_info
Retrieve EDID data from a driver.
.Bd -literal -offset indent
struct wsdisplayio_edid_info {
	uint32_t buffer_size;
	uint32_t data_size;
	void *edid_data;
};
.Ed
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
.Er 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.
.It Dv WSDISPLAYIO_SETVERSION Pq Li "int"
Set the wscons_event protocol version.
The default is 0 for binary compatibility.
The latest version is
always available as
.Dv 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.
.Bd -literal -offset indent
int ver = WSDISPLAYIO_EVENT_VERSION;
if (ioctl(fd, WSDISPLAYIO_SETVERSION, &ver) == -1)
    err(EXIT_FAILURE, "cannot set version");
.Ed
.El
.Sh FILES
.Bl -tag -width "/dev/ttyEstat" -compact
.It Pa /dev/ttyE*
Terminal devices (per screen).
.It Pa /dev/ttyEcfg
Control device.
.It Pa /dev/ttyEstat
Status device.
.Pp
.It Pa /usr/include/dev/wscons/wsconsio.h
.El
.Sh SEE ALSO
.Xr ioctl 2 ,
.\" .Xr ega 4 ,
.Xr pcdisplay 4 ,
.Xr tty 4 ,
.Xr vga 4 ,
.Xr wscons 4 ,
.Xr wsconscfg 8 ,
.Xr wsconsctl 8 ,
.Xr wsfontload 8 ,
.Xr wsdisplay 9
.Sh BUGS
The
.Nm
code currently limits the number of screens on one display to 8.
.Pp
The terms
.Dq wscons
and
.Dq wsdisplay
are not cleanly distinguished in the code and in manual pages.
.Pp
.Dq non-emulating
display devices are not tested.