diff options
Diffstat (limited to 'static/netbsd/man4/wsdisplay.4')
| -rw-r--r-- | static/netbsd/man4/wsdisplay.4 | 652 |
1 files changed, 652 insertions, 0 deletions
diff --git a/static/netbsd/man4/wsdisplay.4 b/static/netbsd/man4/wsdisplay.4 new file mode 100644 index 00000000..031c1d56 --- /dev/null +++ b/static/netbsd/man4/wsdisplay.4 @@ -0,0 +1,652 @@ +.\" $NetBSD: wsdisplay.4,v 1.51 2024/09/02 13:41:33 gutteridge 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 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. |