1.\" $OpenBSD: wsdisplay.4,v 1.54 2019/05/25 11:02:19 otto Exp $ 2.\" $NetBSD: wsdisplay.4,v 1.5 2000/05/13 15:22:19 mycroft Exp $ 3.\" 4.\" Copyright (c) 2005, Miodrag Vallat. 5.\" Copyright (c) 1999 Matthias Drochner. 6.\" Copyright (c) 2002 Ben Harris. 7.\" All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: May 25 2019 $ 31.Dt WSDISPLAY 4 32.Os 33.Sh NAME 34.Nm wsdisplay 35.Nd generic display device support in wscons 36.Sh SYNOPSIS 37.Cd "wsdisplay* at ..." 38.Cd "option WSDISPLAY_DEFAULTSCREENS=N" 39.Sh DESCRIPTION 40The 41.Nm 42driver is an abstraction layer for display devices within the 43.Xr wscons 4 44framework. 45It attaches to the hardware specific display device driver and 46makes it available as text terminal or graphics interface. 47.Pp 48Display devices have the ability to display characters on them 49(without help of an X server), either directly by hardware or through 50software drawing pixel data into the display memory. 51The 52.Nm 53driver will connect a terminal emulation module and provide a 54tty-like software interface. 55.Pp 56The 57.Em console 58locator in the configuration line refers to the device's use as output 59part of the operating system console. 60A device specification containing a positive value here will only match 61if the device is in use as system console. 62(The console device selection in early system startup is not influenced.) 63This way, the console device can be connected to a known 64.Nm wsdisplay 65device instance. 66.Pp 67The 68.Em mux 69locator in the configuration line refers to the 70.Xr wsmux 4 71that will be used to get keyboard events. 72If this locator is -1 no mux will be used. 73.Pp 74The logical unit of an independent contents displayed on a display 75(sometimes referred to as 76.Dq virtual terminal ) 77is called a 78.Dq screen 79here. 80If the underlying device driver supports it, multiple screens can 81be used on one display. 82(As of this writing, only the 83.Xr lcd 4 84and 85.Xr vga 4 86display drivers provide this ability.) 87Screens have different minor device numbers and separate tty instances. 88One screen possesses the 89.Dq focus , 90this means it is displayed on the display and its tty device will get 91the keyboard input. 92(In some cases, if no screen is set up or if a screen 93was just deleted, it is possible that no focus is present at all.) 94The focus can be switched by either special keyboard input (typically 95CTL-ALT-Fn) or an ioctl command issued by a user program. 96Screens are set up or deleted through the 97.Pa /dev/ttyCcfg 98control device (preferably using the 99.Xr wsconscfg 8 100utility). 101Alternatively, the compile-time 102.Cd "option WSDISPLAY_DEFAULTSCREENS=N" 103will set up N screens of the display driver's default type and using 104the system's default terminal emulator at autoconfiguration time. 105.Pp 106In addition and with help from backend drivers the following features 107are also provided: 108.Bl -bullet 109.It 110Loading, deleting and listing the loaded fonts. 111.It 112Browsing backwards in the screen output, the size of the 113buffer for saved text is defined by the particular hardware driver. 114.It 115Blanking the screen by timing out on inactivity in the 116screen holding the input focus. 117Awakening activities consist of: 118.Pp 119.Bl -bullet -compact 120.It 121pressing any keys on the keyboard; 122.It 123moving or clicking the mouse; 124.It 125any output to the screen. 126.El 127.Pp 128Blanking the screen is usually done by disabling the horizontal sync 129signal on video output, but may also include blanking the vertical 130sync in which case most monitors go into power saving mode. 131See 132.Xr wsconsctl 8 133for controlling variables. 134.El 135.Pp 136Consult the back-end drivers' documentation for which features are supported 137for each particular hardware type. 138.Ss IOCTL INTERFACE 139The following 140.Xr ioctl 2 141calls are provided by the 142.Nm 143driver or by devices which use it. 144Their definitions are found in 145.In dev/wscons/wsconsio.h . 146.Bl -tag -width 4n 147.It Dv WSDISPLAYIO_GTYPE Fa u_int 148Retrieve the type of the display. 149The list of types is in 150.In dev/wscons/wsconsio.h . 151.It Dv WSDISPLAYIO_GINFO Fa "struct wsdisplay_fbinfo" 152Retrieve basic information about a framebuffer display. 153The returned structure is as follows: 154.Bd -literal -offset indent 155struct wsdisplay_fbinfo { 156 u_int height; 157 u_int width; 158 u_int depth; 159 u_int cmsize; 160}; 161.Ed 162.Pp 163The 164.Va height 165and 166.Va width 167members are counted in pixels. 168The 169.Va depth 170member indicates the number of bits per pixel, and 171.Va cmsize 172indicates the number of color map entries accessible through 173.Dv WSDISPLAYIO_GETCMAP 174and 175.Dv WSDISPLAYIO_PUTCMAP . 176This call is likely to be unavailable on text-only displays. 177.It Dv WSDISPLAYIO_GETCMAP Fa "struct wsdisplay_cmap" 178Retrieve the current color map from the display. 179This call needs the 180following structure set up beforehand: 181.Bd -literal -offset indent 182struct wsdisplay_cmap { 183 u_int index; 184 u_int count; 185 u_char *red; 186 u_char *green; 187 u_char *blue; 188}; 189.Ed 190.Pp 191The 192.Va index 193and 194.Va count 195members specify the range of color map entries to retrieve. 196The 197.Va red , 198.Va green , 199and 200.Va blue 201members should each point to an array of 202.Va count 203.Vt u_char Ns s . 204On return, these will be filled in with the appropriate entries from the 205color map. 206On all displays that support this call, values range from 0 for minimum 207intensity to 255 for maximum intensity, even if the display does not use 208eight bits internally to represent intensity. 209.It Dv WSDISPLAYIO_PUTCMAP Fa "struct wsdisplay_cmap" 210Change the display's color map. 211The argument structure is the same as for 212.Dv WSDISPLAYIO_GETCMAP , 213but 214.Va red , 215.Va green , 216and 217.Va blue 218are taken as pointers to the values to use to set the color map. 219This call is not available on displays with fixed color maps. 220.It Dv WSDISPLAYIO_GVIDEO Fa u_int 221Get the current state of the display's video output. 222Possible values are: 223.Bl -tag -width 21n 224.It Dv WSDISPLAYIO_VIDEO_OFF 225The display is blanked. 226.It Dv WSDISPLAYIO_VIDEO_ON 227The display is enabled. 228.El 229.It Dv WSDISPLAYIO_SVIDEO Fa u_int 230Set the state of the display's video output. 231See 232.Dv WSDISPLAYIO_GVIDEO 233above for possible values. 234.It Dv WSDISPLAYIO_GCURPOS Fa "struct wsdisplay_curpos" 235Retrieve the current position of the hardware cursor. 236The returned structure 237is as follows: 238.Bd -literal -offset indent 239struct wsdisplay_curpos { 240 u_int x, y; 241}; 242.Ed 243.Pp 244The 245.Va x 246and 247.Va y 248members count the number of pixels right and down, respectively, from 249the top-left corner of the display to the hot spot of the cursor. 250This call is not available on displays without a hardware cursor. 251.It Dv WSDISPLAYIO_SCURPOS Fa "struct wsdisplay_curpos" 252Set the current cursor position. 253The argument structure, and its semantics, 254are the same as for 255.Dv WSDISPLAYIO_GCURPOS . 256This call is not available on displays without a hardware cursor. 257.It Dv WSDISPLAYIO_GCURMAX Fa "struct wsdisplay_curpos" 258Retrieve the maximum size of cursor supported by the display. 259The 260.Va x 261and 262.Va y 263members of the returned structure indicate the maximum number of pixel rows 264and columns, respectively, in a hardware cursor on this display. 265This call is not available on displays without a hardware cursor. 266.It Dv WSDISPLAYIO_GCURSOR Fa "struct wsdisplay_cursor" 267Retrieve some or all of the hardware cursor's attributes. 268The argument structure is as follows: 269.Bd -literal -offset indent 270struct wsdisplay_cursor { 271 u_int which; 272 u_int enable; 273 struct wsdisplay_curpos pos; 274 struct wsdisplay_curpos hot; 275 struct wsdisplay_cmap cmap; 276 struct wsdisplay_curpos size; 277 u_char *image; 278 u_char *mask; 279}; 280.Pp 281.Ed 282The 283.Va which 284member indicates which of the values the application requires to be returned. 285It should contain the logical OR of the following flags: 286.Bl -tag -width 4n 287.It Dv WSDISPLAY_CURSOR_DOCUR 288Get 289.Va enable , 290which indicates whether the cursor is currently displayed (non-zero) or 291not (zero). 292.It Dv WSDISPLAY_CURSOR_DOPOS 293Get 294.Va pos , 295which indicates the current position of the cursor on the display, as 296would be returned by 297.Dv WSDISPLAYIO_GCURPOS . 298.It Dv WSDISPLAY_CURSOR_DOHOT 299Get 300.Va hot , 301which indicates the location of the 302.Dq hot spot 303within the cursor. 304This is the point on the cursor whose position on the display is treated 305as being the position of the cursor by other calls. 306Its location is counted in pixels from the top-left corner of the cursor. 307.It Dv WSDISPLAY_CURSOR_DOCMAP 308Get 309.Va cmap , 310which indicates the current cursor color map. 311Unlike in a call to 312.Dv WSDISPLAYIO_GETCMAP , 313.Va cmap 314here need not have its 315.Va index 316and 317.Va count 318members initialized. 319They will be set to 0 and 2 respectively by the call. 320This means that 321.Va cmap . Ns Va red , 322.Va cmap . Ns Va green , 323and 324.Va cmap . Ns Va blue 325must each point to at least enough space to hold two 326.Vt u_char Ns s . 327.It Dv WSDISPLAY_CURSOR_DOSHAPE 328Get 329.Va size , image , 330and 331.Va mask . 332These are, respectively, the dimensions of the cursor in pixels, the 333bitmap of set pixels in the cursor and the bitmap of opaque pixels in 334the cursor. 335The format in which these bitmaps are returned, and hence the amount of 336space that must be provided by the application, are device-dependent. 337.It Dv WSDISPLAY_CURSOR_DOALL 338Get all of the above. 339.El 340.Pp 341The device may elect to return information that was not requested by the user, 342so those elements of 343.Vt struct wsdisplay_cursor 344which are pointers should be initialized to 345.Dv NULL 346if not otherwise used. 347This call is not available on displays without a hardware cursor. 348.It Dv WSDISPLAYIO_SCURSOR Fa "struct wsdisplay_cursor" 349Set some or all of the hardware cursor's attributes. 350The argument structure is the same as for 351.Dv WSDISPLAYIO_GCURSOR . 352The 353.Va which 354member specifies which attributes of the cursor are to be changed. 355It should contain the logical OR of the following flags: 356.Bl -tag -width 4n 357.It Dv WSDISPLAY_CURSOR_DOCUR 358If 359.Va enable 360is zero, hide the cursor. 361Otherwise, display it. 362.It Dv WSDISPLAY_CURSOR_DOPOS 363Set the cursor's position on the display to 364.Va pos , 365the same as 366.Dv WSDISPLAYIO_SCURPOS . 367.It Dv WSDISPLAY_CURSOR_DOHOT 368Set the 369.Dq hot spot 370of the cursor, as defined above, to 371.Va hot . 372.It Dv WSDISPLAY_CURSOR_DOCMAP 373Set some or all of the cursor color map based on 374.Va cmap . 375The 376.Va index 377and 378.Va count 379elements of 380.Va cmap 381indicate which color map entries to set, and the entries themselves come from 382.Va cmap . Ns Va red , 383.Va cmap . Ns Va green , 384and 385.Va cmap . Ns Va blue . 386.It Dv WSDISPLAY_CURSOR_DOSHAPE 387Set the cursor shape from 388.Va size , image , 389.Va mask . 390See above for their meanings. 391.It Dv WSDISPLAY_CURSOR_DOALL 392Do all of the above. 393.El 394.Pp 395This call is not available on displays without a hardware cursor. 396.It Dv WSDISPLAYIO_GMODE Fa u_int 397Get the current mode of the display. 398Possible results include: 399.Bl -tag -width 4n 400.It Dv WSDISPLAYIO_MODE_EMUL 401The display is in emulating (text) mode. 402.It Dv WSDISPLAYIO_MODE_MAPPED 403The display is in mapped (graphics) mode. 404.It Dv WSDISPLAYIO_MODE_DUMBFB 405The display is in mapped (frame buffer) mode. 406.El 407.It Dv WSDISPLAYIO_SMODE Fa u_int 408Set the current mode of the display. 409For possible arguments, see 410.Dv WSDISPLAYIO_GMODE . 411.It Dv WSDISPLAYIO_LDFONT Fa "struct wsdisplay_font" 412Loads a font specified by the wsdisplay_font structure. 413.Bd -literal -offset indent 414struct wsdisplay_font { 415 char name[WSFONT_NAME_SIZE]; 416 int index; 417 int firstchar, numchars; 418 int encoding; 419 u_int fontwidth, fontheight, stride; 420 int bitorder, byteorder; 421 void *cookie; 422 void *data; 423}; 424.Ed 425.Pp 426The 427.Va name 428field contains a human readable string used to identify the font. 429The 430.Va index 431field may be used to select a driver-specific font resource (for non-raster 432frame buffers). 433A value of -1 will pick the first available slot. 434The 435.Va firstchar 436field contains the index of the first character in the font, starting at zero. 437The 438.Va numchars 439field contains the number of characters in the font. 440The 441.Va encoding 442field describes the font character encoding, using one of the following values: 443.Bl -tag -width 4n 444.It Dv WSDISPLAY_FONTENC_ISO 445ISO-8859-1 encoding 446.Pq also known as Latin-1 . 447This is the preferred encoding for raster frame buffers. 448.It Dv WSDISPLAY_FONTENC_IBM 449IBM code page number 437. 450This is the preferred encoding for text-mode displays. 451.El 452.Pp 453The 454.Va fontwidth 455and 456.Va fontheight 457fields specify the dimensions of a character cell. 458The 459.Va stride 460field specify the number of bytes of font data per character cell line (usually 461.Va fontwidth 462rounded up to a byte boundary). 463The 464.Va bitorder 465and 466.Va byteorder 467fields specify the bit- and byte-ordering of the font data, using either one of 468the following values: 469.Bl -tag -width 4n 470.It Dv WSDISPLAY_FONTORDER_L2R 471Leftmost data contained in the most significant bits (left-to-right ordering). 472This is the most commonly encountered case. 473.It Dv WSDISPLAY_FONTORDER_R2L 474Leftmost data contained in the least significant bits (right-to-left ordering). 475.El 476.Pp 477The 478.Va data 479field contains the font character data to be loaded. 480The 481.Va cookie 482field is reserved for internal purposes. 483.It Dv WSDISPLAYIO_LSFONT Fa "struct wsdisplay_font" 484Retrieves the data for a loaded font into the wsdisplay_font structure. 485The 486.Va index 487field is set to the font resource to query. 488For the argument structure, see 489.Dv WSDISPLAYIO_LDFONT . 490.\" Dv WSDISPLAYIO_DELFONT Fa "struct wsdisplay_font" 491.It Dv WSDISPLAYIO_USEFONT Fa "struct wsdisplay_font" 492Selects the font specified in the 493.Va name 494field. 495An empty 496.Va name 497selects the next available font. 498For the argument structure, see 499.Dv WSDISPLAYIO_LDFONT . 500.It Dv WSDISPLAYIO_GBURNER Fa "struct wsdisplay_burner" 501Retrieves the state of the screen burner. 502The returned structure is as follows: 503.Bd -literal -offset indent 504struct wsdisplay_burner { 505 u_int off; 506 u_int on; 507 u_int flags; 508}; 509.Ed 510.Pp 511The 512.Va off 513member contains the inactivity time before the screen is turned off, 514in milliseconds. 515The 516.Va on 517member contains the time before the screen is turned back on, 518in milliseconds. 519The 520.Va flags 521member contains a logical OR of the following flags: 522.Bl -tag -width 4n 523.It Dv WSDISPLAY_BURN_VBLANK 524When turning the display off, disable the vertical synchronization signal. 525.It Dv WSDISPLAY_BURN_KBD 526Monitor keyboard activity. 527.It Dv WSDISPLAY_BURN_MOUSE 528Monitor mouse activity 529(this only works for mice using the 530.Xr wsmouse 4 531driver). 532.It Dv WSDISPLAY_BURN_OUTPUT 533Monitor display output activity. 534.El 535.Pp 536If none of the activity source flags are set, the screen burner is disabled. 537.It Dv WSDISPLAYIO_SBURNER Fa "struct wsdisplay_burner" 538Sets the state of the screen burner. 539The argument structure, and its semantics, are the same as for 540.Dv WSDISPLAYIO_GBURNER . 541.It Dv WSDISPLAYIO_ADDSCREEN Fa "struct wsdisplay_addscreendata" 542Creates a new screen. 543.Bd -literal -offset indent 544struct wsdisplay_addscreendata { 545 int idx; /* screen index */ 546 char screentype[WSSCREEN_NAME_SIZE]; 547 char emul[WSEMUL_NAME_SIZE]; 548}; 549.Ed 550.Pp 551The 552.Va idx 553field is the index of the screen to be configured. 554The 555.Va screentype 556field is matched against builtin screen types, which will be driver-dependent. 557The 558.Va emul 559field indicates the terminal emulation type. 560Available terminal emulations are: 561.Bl -tag -width 5n 562.It sun 563Sun terminal emulation. 564This is the default on the sparc64 architecture. 565.It vt100 566Dec VT100 terminal emulation, with some VT220 features. 567This is the default on all other architectures. 568.It dumb 569Dumb terminal. 570.El 571.Pp 572An empty string will select the default emulation. 573.It Dv WSDISPLAYIO_DELSCREEN Fa "struct wsdisplay_delscreendata" 574Deletes an existing screen. 575.Bd -literal -offset indent 576struct wsdisplay_delscreendata { 577 int idx; /* screen index */ 578 int flags; 579}; 580.Ed 581.Pp 582The 583.Va idx 584field indicates the index of the screen to be deleted. 585The 586.Va flags 587field is a logical OR of zero or more of the following: 588.Bl -tag -width 4n 589.It Dv WSDISPLAY_DELSCR_FORCE 590Force deletion of screen even if in use by a userspace program. 591.It Dv WSDISPLAY_DELSCR_QUIET 592Don't report deletion to console. 593.El 594.It Dv WSDISPLAYIO_GETSCREEN Fa "struct wsdisplay_addscreendata" 595Returns information on the screen indicated by 596.Va idx 597or the current screen if 598.Va idx 599is -1. 600The screen and emulation types are returned in the same structure 601.Pq see Dv WSDISPLAYIO_GETPARAM . 602.It Dv WSDISPLAYIO_SETSCREEN Fa u_int 603Switch to the screen with the given index. 604.It Dv WSDISPLAYIO_WSMOUSED Fa "struct wscons_event" 605This call is used by the 606.Xr wsmoused 8 607daemon to inject mouse events gathered from serial mice, as well as 608various control events. 609.It Dv WSDISPLAYIO_GETPARAM Fa "struct wsdisplay_param" 610Retrieves the state of a display parameter. 611This call needs the following structure set up beforehand: 612.Bd -literal -offset indent 613struct wsdisplay_param { 614 int param; 615 int min, max, curval; 616 int reserved[4]; 617}; 618.Ed 619.Pp 620The 621.Va param 622member should be set with the parameter to be returned. 623The following parameters are supported: 624.Bl -tag -width 4n 625.It Dv WSDISPLAYIO_PARAM_BACKLIGHT 626The intensity of the display backlight (usually on laptop computers). 627.It Dv WSDISPLAYIO_PARAM_BRIGHTNESS 628The brightness level. 629.It Dv WSDISPLAYIO_PARAM_CONTRAST 630The contrast level. 631.El 632.Pp 633On return, 634.Va min 635and 636.Va max 637specify the allowed range for the value, while 638.Va curval 639specifies the current setting. 640Not all parameters are supported by all display drivers. 641.It Dv WSDISPLAYIO_SETPARAM Fa "struct wsdisplay_param" 642Sets a display parameter. 643The argument structure is the same as for 644.Dv WSDISPLAYIO_GETPARAM , 645with the 646.Va param 647and 648.Va curval 649members filled in. 650Not all parameters are supported by all display drivers. 651.It Dv WSDISPLAYIO_LINEBYTES Fa u_int 652Get the number of bytes per row when the device is in 653.Dv WSDISPLAYIO_MODE_DUMBFB 654mode. 655.El 656.Sh FILES 657.Bl -tag -width /usr/include/dev/wscons/wsconsio.h -compact 658.It Pa /dev/tty[C-F]* 659terminal devices (per screen) 660.It Pa /dev/tty[C-F]cfg 661control device (per screen) 662.It Pa /usr/include/dev/wscons/wsconsio.h 663.El 664.Sh SEE ALSO 665.Xr intro 4 , 666.Xr tty 4 , 667.Xr wscons 4 , 668.Xr wsmux 4 , 669.Xr wsconscfg 8 , 670.Xr wsconsctl 8 , 671.Xr wsfontload 8 672.Sh BUGS 673The 674.Nm 675code currently limits the number of screens on one display to 12. 676.Pp 677The terms 678.Dq wscons 679and 680.Dq wsdisplay 681are not cleanly distinguished in the code and in manual pages. 682