1.\" $OpenBSD: wsdisplay.4,v 1.49 2015/03/29 19:26:02 jmc 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: March 29 2015 $ 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 option 102.Cm 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 Pq Li 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 Pq Li "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 Pq Li "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.Li 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 Pq Li "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 Pq Li 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 Pq Li 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 Pq Li "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 Pq Li "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 Pq Li "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 Pq Li "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.Li 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.Li "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 Pq Li "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 Pq Li 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 Pq Li u_int 408Set the current mode of the display. 409For possible arguments, see 410.Dv WSDISPLAYIO_GMODE . 411.It Dv WSDISPLAYIO_LDFONT Pq Li 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.\" .It Dv WSDISPLAY_FONTENC_PCVT 452.\" Old 453.\" .Nm pcvt 454.\" driver encoding (deprecated). 455.\" .It Dv WSDISPLAY_FONTENC_ISO7 456.\" ISO-8859-7. 457.El 458.Pp 459The 460.Va fontwidth 461and 462.Va fontheight 463fields specify the dimensions of a character cell. 464The 465.Va stride 466field specify the number of bytes of font data per character cell line (usually 467.Va fontwidth 468rounded up to a byte boundary). 469The 470.Va bitorder 471and 472.Va byteorder 473fields specify the bit- and byte-ordering of the font data, using either one of 474the following values: 475.Bl -tag -width 4n 476.It Dv WSDISPLAY_FONTORDER_L2R 477Leftmost data contained in the most significant bits (left-to-right ordering). 478This is the most commonly encountered case. 479.It Dv WSDISPLAY_FONTORDER_R2L 480Leftmost data contained in the least significant bits (right-to-left ordering). 481.El 482.Pp 483The 484.Va data 485field contains the font character data to be loaded. 486The 487.Va cookie 488field is reserved for internal purposes. 489.It Dv WSDISPLAYIO_LSFONT Pq Li struct wsdisplay_font 490Retrieves the data for a loaded font into the wsdisplay_font structure. 491The 492.Va index 493field is set to the font resource to query. 494For the argument structure, see 495.Dv WSDISPLAYIO_LDFONT . 496.\" WSDISPLAYIO_DELFONT Pq Li struct wsdisplay_font 497.It WSDISPLAYIO_USEFONT Pq Li struct wsdisplay_font 498Selects the font specified in the 499.Va name 500field. 501An empty 502.Va name 503selects the next available font. 504For the argument structure, see 505.Dv WSDISPLAYIO_LDFONT . 506.It Dv WSDISPLAYIO_GBURNER Pq Li struct wsdisplay_burner 507Retrieves the state of the screen burner. 508The returned structure is as follows: 509.Bd -literal -offset indent 510struct wsdisplay_burner { 511 u_int off; 512 u_int on; 513 u_int flags; 514}; 515.Ed 516.Pp 517The 518.Va off 519member contains the inactivity time before the screen is turned off, 520in milliseconds. 521The 522.Va on 523member contains the time before the screen is turned back on, 524in milliseconds. 525The 526.Va flags 527member contains a logical OR of the following flags: 528.Bl -tag -width 4n 529.It Dv WSDISPLAY_BURN_VBLANK 530When turning the display off, disable the vertical synchronization signal. 531.It Dv WSDISPLAY_BURN_KBD 532Monitor keyboard activity. 533.It Dv WSDISPLAY_BURN_MOUSE 534Monitor mouse activity 535(this only works for mice using the 536.Xr wsmouse 4 537driver). 538.It Dv WSDISPLAY_BURN_OUTPUT 539Monitor display output activity. 540.El 541.Pp 542If none of the activity source flags are set, the screen burner is disabled. 543.It Dv WSDISPLAYIO_SBURNER Pq Li struct wsdisplay_burner 544Sets the state of the screen burner. 545The argument structure, and its semantics, are the same as for 546.Dv WSDISPLAYIO_GBURNER . 547.It Dv WSDISPLAYIO_ADDSCREEN Pq Li struct wsdisplay_addscreendata 548Creates a new screen. 549.Bd -literal -offset indent 550struct wsdisplay_addscreendata { 551 int idx; /* screen index */ 552 char screentype[WSSCREEN_NAME_SIZE]; 553 char emul[WSEMUL_NAME_SIZE]; 554}; 555.Ed 556.Pp 557The 558.Va idx 559field is the index of the screen to be configured. 560The 561.Va screentype 562field is matched against builtin screen types, which will be driver-dependent. 563The 564.Va emul 565field indicates the terminal emulation type. 566Available terminal emulations are: 567.Bl -tag -width 5n 568.It sun 569Sun terminal emulation. 570This is the default on sparc and sparc64 architectures. 571.It vt100 572Dec VT100 terminal emulation, with some VT220 features. 573This is the default on all other architectures. 574.It dumb 575Dumb terminal. 576.El 577.Pp 578An empty string will select the default emulation. 579.It Dv WSDISPLAYIO_DELSCREEN Pq Li struct wsdisplay_delscreendata 580Deletes an existing screen. 581.Bd -literal -offset indent 582struct wsdisplay_delscreendata { 583 int idx; /* screen index */ 584 int flags; 585}; 586.Ed 587.Pp 588The 589.Va idx 590field indicates the index of the screen to be deleted. 591The 592.Va flags 593field is a logical OR of zero or more of the following: 594.Bl -tag -width 4n 595.It Dv WSDISPLAY_DELSCR_FORCE 596Force deletion of screen even if in use by a userspace program. 597.It Dv WSDISPLAY_DELSCR_QUIET 598Don't report deletion to console. 599.El 600.It Dv WSDISPLAYIO_GETSCREEN Pq Li struct wsdisplay_addscreendata 601Returns information on the screen indicated by 602.Va idx 603or the current screen if 604.Va idx 605is -1. 606The screen and emulation types are returned in the same structure 607.Pq see Dv WSDISPLAYIO_GETPARAM . 608.It Dv WSDISPLAYIO_SETSCREEN Pq Li u_int 609Switch to the screen with the given index. 610.It Dv WSDISPLAYIO_WSMOUSED Pq Li struct wscons_event 611This call is used by the 612.Xr wsmoused 8 613daemon to inject mouse events gathered from serial mice, as well as 614various control events. 615.It Dv WSDISPLAYIO_GETPARAM Pq Li struct wsdisplay_param 616Retrieves the state of a display parameter. 617This call needs the following structure set up beforehand: 618.Bd -literal -offset indent 619struct wsdisplay_param { 620 int param; 621 int min, max, curval; 622 int reserved[4]; 623}; 624.Ed 625.Pp 626The 627.Va param 628member should be set with the parameter to be returned. 629The following parameters are supported: 630.Bl -tag -width 4n 631.It Dv WSDISPLAYIO_PARAM_BACKLIGHT 632The intensity of the display backlight (usually on laptop computers). 633.It Dv WSDISPLAYIO_PARAM_BRIGHTNESS 634The brightness level. 635.It Dv WSDISPLAYIO_PARAM_CONTRAST 636The contrast level. 637.El 638.Pp 639On return, 640.Va min 641and 642.Va max 643specify the allowed range for the value, while 644.Va curval 645specifies the current setting. 646Not all parameters are supported by all display drivers. 647.It Dv WSDISPLAYIO_SETPARAM Pq Li struct wsdisplay_param 648Sets a display parameter. 649The argument structure is the same as for 650.Dv WSDISPLAYIO_GETPARAM , 651with the 652.Va param 653and 654.Va curval 655members filled in. 656Not all parameters are supported by all display drivers. 657.It Dv WSDISPLAYIO_LINEBYTES Pq Li u_int 658Get the number of bytes per row when the device is in 659.Dv WSDISPLAYIO_MODE_DUMBFB 660mode. 661.El 662.Sh FILES 663.Bl -tag -width /usr/include/dev/wscons/wsconsio.h -compact 664.It Pa /dev/tty[C-F]* 665terminal devices (per screen) 666.It Pa /dev/tty[C-F]cfg 667control device (per screen) 668.It Pa /usr/include/dev/wscons/wsconsio.h 669.El 670.Sh SEE ALSO 671.Xr intro 4 , 672.Xr tty 4 , 673.Xr wscons 4 , 674.Xr wsmux 4 , 675.Xr wsconscfg 8 , 676.Xr wsconsctl 8 , 677.Xr wsfontload 8 678.Sh BUGS 679The 680.Nm 681code currently limits the number of screens on one display to 8. 682.Pp 683The terms 684.Dq wscons 685and 686.Dq wsdisplay 687are not cleanly distinguished in the code and in manual pages. 688