1.\" $NetBSD: wsdisplay.4,v 1.35 2010/03/22 18:58:31 joerg Exp $ 2.\" 3.\" Copyright (c) 1999 Matthias Drochner. 4.\" Copyright (c) 2002 Ben Harris. 5.\" Copyright (c) 2004 Julio M. Merino Vidal. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd February 19, 2009 30.Dt WSDISPLAY 4 31.Os 32.Sh NAME 33.Nm wsdisplay 34.Nd generic display device support in wscons 35.Sh SYNOPSIS 36.Cd "wsdisplay* at ega? console ?" 37(EGA display on ISA) 38.Cd "wsdisplay* at vga? console ?" 39(VGA display on ISA or PCI) 40.Cd "wsdisplay* at pcdisplay? console ?" 41(generic PC (ISA) display) 42.Cd "wsdisplay* at tga? console ?" 43(DEC TGA display, alpha only) 44.Cd "wsdisplay* at pfb? console ?" 45(PCI framebuffer, bebox only) 46.Cd "wsdisplay0 at ofb? console ?" 47(Open Firmware framebuffer, macppc only) 48.Cd "wsdisplay* at nextdisplay? console ?" 49(NeXT display) 50.Cd "wsdisplay0 at smg0" 51(VAXstation small monochrome display) 52.Cd "wsdisplay* at ... kbdmux N" 53.Pp 54.Cd options WSDISPLAY_BORDER_COLOR=WSCOL_XXX 55.Cd options WSDISPLAY_CUSTOM_BORDER 56.Cd options WSDISPLAY_CUSTOM_OUTPUT 57.Cd options WSDISPLAY_DEFAULTSCREENS=N 58.Cd options WSDISPLAY_SCROLLSUPPORT 59.Sh DESCRIPTION 60The 61.Nm 62driver is an abstraction layer for display devices within the 63.Xr wscons 4 64framework. 65It attaches to the hardware specific display device driver and makes it 66available as a text terminal or graphics interface. 67.Pp 68A display device can have the ability to display characters on it 69(without the help of an X server), either directly by hardware or through 70software putting pixel data into the display memory. 71Such displays are called 72.Dq emulating , 73the 74.Nm 75driver will connect a terminal emulation module and provide a tty-like 76software interface. 77In contrary, non-emulating displays can only be used by special programs 78like X servers. 79.Pp 80The 81.Em console 82locator in the configuration line refers to the device's use as the output 83part of the operating system console. 84A device specification containing a positive value here will only match if 85the device is in use as the system console. 86(The console device selection in early system startup is not influenced.) 87This way, the console device can be connected to a known wsdisplay device 88instance. 89(Naturally, only 90.Dq emulating 91display devices are usable as console.) 92.Pp 93The 94.Em kbdmux 95locator in the configuration line refers to the 96.Xr wsmux 4 97that will be used to get keyboard events. 98If this locator is -1 no mux will be used. 99.Pp 100The logical unit of an independent contents displayed on a display 101(sometimes referred to as 102.Dq virtual terminal 103) is called a 104.Dq screen 105here. 106If the underlying device driver supports it, multiple screens can 107be used on one display. 108(As of this writing, only the 109.Xr vga 4 110and the 111.Tn VAX 112.Dq smg 113display drivers provide this ability.) 114Screens have different minor device numbers and separate tty instances. 115One screen possesses the 116.Dq focus , 117this means it is visible and its tty device will get 118the keyboard input. 119(In some cases \- if no screen is set up or if a screen 120was just deleted \- it is possible that no focus is present at all.) 121The focus can be switched by either special keyboard input (typically 122.Tn CTRL-ALT-F Ns Ar n ) 123or an ioctl command issued by a user program. 124Screens are created and deleted through the 125.Pa /dev/ttyEcfg 126control device (preferably using the 127.Xr wsconscfg 8 128utility). 129Alternatively, the compile-time option 130.Dv WSDISPLAY_DEFAULTSCREENS Ns = Ns Ar n 131will also create (at autoconfiguration time) 132.Ar n 133initial screens of the display driver's default type with 134the system's default terminal emulator. 135.Ss Kernel options 136The following kernel options are available to configure the behavior of the 137.Nm 138driver: 139.Bl -tag -width xxxxxxxx 140.It Cd options WSDISPLAY_BORDER_COLOR=WSCOL_XXX 141Sets the border color at boot time. 142Possible values are defined in 143.Pa src/sys/dev/wscons/wsdisplayvar.h . 144Defaults to 145.Sq WSCOL_BLACK . 146.It Cd options WSDISPLAY_CUSTOM_BORDER 147Enables the 148.Dv WSDISPLAYIO_GBORDER 149and 150.Dv WSDISPLAYIO_SBORDER 151ioctls, which allow the customization of the border color from userland 152(after boot). 153See 154.Xr wsconsctl 8 . 155.It Cd options WSDISPLAY_CUSTOM_OUTPUT 156Enables the 157.Dv WSDISPLAYIO_GMSGATTRS 158and 159.Dv WSDISPLAYIO_SMSGATTRS 160ioctls, which allow the customization of the console output and kernel 161messages from userland (after boot). 162See 163.Xr wsconsctl 8 . 164.It Cd options WSDISPLAY_DEFAULTSCREENS=N 165Sets the number of virtual screens to allocate at boot time. 166Useful for small root filesystems where the 167.Xr wsconscfg 8 168utility is not wanted. 169.It Cd options WSDISPLAY_SCROLLSUPPORT 170Enables scrolling support. 171The key combinations are 172.Ic LEFT SHIFT + PAGE UP 173and 174.Ic LEFT SHIFT + PAGE DOWN 175by default. 176Please note that this function may not work under the system console and 177is available depending on the framebuffer you are using. 178.El 179.Ss Ioctls 180The following 181.Xr ioctl 2 182calls are provided by the 183.Nm 184driver or by devices which use it. 185Their definitions are found in 186.In dev/wscons/wsconsio.h . 187.Bl -tag -width Dv 188.It Dv WSDISPLAYIO_GTYPE Pq Li int 189Retrieve the type of the display. 190The list of types is in 191.In dev/wscons/wsconsio.h . 192.It Dv WSDISPLAYIO_GINFO Pq Li "struct wsdisplay_fbinfo" 193Retrieve basic information about a framebuffer display. 194The returned structure is as follows: 195.Bd -literal -offset indent 196struct wsdisplay_fbinfo { 197 u_int height; 198 u_int width; 199 u_int depth; 200 u_int cmsize; 201}; 202.Ed 203.Pp 204The 205.Va height 206and 207.Va width 208members are counted in pixels. 209The 210.Va depth 211member indicates the number of bits per pixel, and 212.Va cmsize 213indicates the number of color map entries accessible through 214.Dv WSDISPLAYIO_GETCMAP 215and 216.Dv WSDISPLAYIO_PUTCMAP . 217This call is likely to be unavailable on text-only displays. 218.It Dv WSDISPLAYIO_GETCMAP Pq Li "struct wsdisplay_cmap" 219Retrieve the current color map from the display. 220This call needs the 221following structure set up beforehand: 222.Bd -literal -offset indent 223struct wsdisplay_cmap { 224 u_int index; 225 u_int count; 226 u_char *red; 227 u_char *green; 228 u_char *blue; 229}; 230.Ed 231.Pp 232The 233.Va index 234and 235.Va count 236members specify the range of color map entries to retrieve. 237The 238.Va red , 239.Va green , 240and 241.Va blue 242members should each point to an array of 243.Va count 244.Li u_char Ns s . 245On return, these will be filled in with the appropriate entries from the 246color map. 247On all displays that support this call, values range from 0 for minimum 248intensity to 255 for maximum intensity, even if the display does not use 249eight bits internally to represent intensity. 250.It Dv WSDISPLAYIO_PUTCMAP Pq Li "struct wsdisplay_cmap" 251Change the display's color map. 252The argument structure is the same as for 253.Dv WSDISPLAYIO_GETCMAP , 254but 255.Va red , 256.Va green , 257and 258.Va blue 259are taken as pointers to the values to use to set the color map. 260This call is not available on displays with fixed color maps. 261.It Dv WSDISPLAYIO_GVIDEO Pq Li int 262Get the current state of the display's video output. 263Possible values are: 264.Bl -tag -width Dv 265.It Dv WSDISPLAYIO_VIDEO_OFF 266The display is blanked. 267.It Dv WSDISPLAYIO_VIDEO_ON 268The display is enabled. 269.El 270.It Dv WSDISPLAYIO_SVIDEO Pq Li int 271Set the state of the display's video output. 272See 273.Dv WSDISPLAYIO_GVIDEO 274above for possible values. 275.It Dv WSDISPLAYIO_GCURPOS Pq Li "struct wsdisplay_curpos" 276Retrieve the current position of the hardware cursor. 277The returned structure 278is as follows: 279.Bd -literal -offset indent 280struct wsdisplay_curpos { 281 u_int x, y; 282}; 283.Ed 284.Pp 285The 286.Va x 287and 288.Va y 289members count the number of pixels right and down, respectively, from 290the top-left corner of the display to the hot spot of the cursor. 291This call is not available on displays without a hardware cursor. 292.It Dv WSDISPLAYOP_SCURPOS Pq Li "struct wsdisplay_curpos" 293Set the current cursor position. 294The argument structure, and its semantics, are the same as for 295.Dv WSDISPLAYIO_GCURPOS . 296This call is not available on displays without a hardware cursor. 297.It Dv WSDISPLAYIO_GCURMAX Pq Li "struct wsdisplay_curpos" 298Retrieve the maximum size of cursor supported by the display. 299The 300.Va x 301and 302.Va y 303members of the returned structure indicate the maximum number of pixel rows 304and columns, respectively, in a hardware cursor on this display. 305This call is not available on displays without a hardware cursor. 306.It Dv WSDISPLAYIO_GCURSOR Pq Li "struct wsdisplay_cursor" 307Retrieve some or all of the hardware cursor's attributes. 308The argument structure is as follows: 309.Bd -literal -offset indent 310struct wsdisplay_cursor { 311 u_int which; 312 u_int enable; 313 struct wsdisplay_curpos pos; 314 struct wsdisplay_curpos hot; 315 struct wsdisplay_cmap cmap; 316 struct wsdisplay_curpos size; 317 u_char *image; 318 u_char *mask; 319}; 320.Pp 321.Ed 322The 323.Va which 324member indicates which of the values the application requires to be returned. 325It should contain the logical OR of the following flags: 326.Bl -tag -width Dv 327.It Dv WSDISPLAYIO_CURSOR_DOCUR 328Get 329.Va enable , 330which indicates whether the cursor is currently displayed (non-zero) or 331not (zero). 332.It Dv WSDISPLAYIO_CURSOR_DOPOS 333Get 334.Va pos , 335which indicates the current position of the cursor on the display, as 336would be returned by 337.Dv WSDISPLAYIO_GCURPOS . 338.It Dv WSDISPLAYIO_CURSOR_DOHOT 339Get 340.Va hot , 341which indicates the location of the 342.Dq hot spot 343within the cursor. 344This is the point on the cursor whose position on the display is treated 345as being the position of the cursor by other calls. 346Its location is counted in pixels from the top-right corner of the cursor. 347.It Dv WSDISPLAYIO_CURSOR_DOCMAP 348Get 349.Va cmap , 350which indicates the current cursor color map. 351Unlike in a call to 352.Dv WSDISPLAYIO_GETCMAP , 353.Va cmap 354here need not have its 355.Va index 356and 357.Va count 358members initialized. 359They will be set to 0 and 2 respectively by the call. 360This means that 361.Va cmap . Ns Va red , 362.Va cmap . Ns Va green , 363and 364.Va cmap . Ns Va blue 365must each point to at least enough space to hold two 366.Li u_char Ns s . 367.It Dv WSDISPLAYIO_CURSOR_DOSHAPE 368Get 369.Va size , image , 370and 371.Va mask . 372These are, respectively, the dimensions of the cursor in pixels, the 373bitmap of set pixels in the cursor and the bitmap of opaque pixels in 374the cursor. 375The format in which these bitmaps are returned, and hence the amount of 376space that must be provided by the application, are device-dependent. 377.It Dv WSDISPLAYIO_CURSOR_DOALL 378Get all of the above. 379.El 380.Pp 381The device may elect to return information that was not requested by the user, 382so those elements of 383.Li "struct wsdisplay_cursor" 384which are pointers should be initialized to 385.Dv NULL 386if not otherwise used. 387This call is not available on displays without a hardware cursor. 388.It Dv WSDISPLAYIO_SCURSOR Pq Li "struct wsdisplay_cursor" 389Set some or all of the hardware cursor's attributes. 390The argument structure is the same as for 391.Dv WSDISPLAYIO_GCURSOR . 392The 393.Va which 394member specifies which attributes of the cursor are to be changed. 395It should contain the logical OR of the following flags: 396.Bl -tag -width Dv 397.It Dv WSDISPLAYIO_CURSOR_DOCUR 398If 399.Va enable 400is zero, hide the cursor. 401Otherwise, display it. 402.It Dv WSDISPLAYIO_CURSOR_DOPOS 403Set the cursor's position on the display to 404.Va pos , 405the same as 406.Dv WSDISPLAYIO_SCURPOS . 407.It Dv WSDISPLAYIO_CURSOR_DOHOT 408Set the 409.Dq hot spot 410of the cursor, as defined above, to 411.Va hot . 412.It Dv WSDISPLAYIO_CURSOR_DOCMAP 413Set some or all of the cursor color map based on 414.Va cmap . 415The 416.Va index 417and 418.Va count 419elements of 420.Va cmap 421indicate which color map entries to set, and the entries themselves come from 422.Va cmap . Ns Va red , 423.Va cmap . Ns Va green , 424and 425.Va cmap . Ns Va blue . 426.It Dv WSDISPLAYIO_CURSOR_DOSHAPE 427Set the cursor shape from 428.Va size , image , 429and 430.Va mask . 431See above for their meanings. 432.It Dv WSDISPLAYIO_CURSOR_DOALL 433Do all of the above. 434.El 435.Pp 436This call is not available on displays without a hardware cursor. 437.It Dv WSDISPLAYIO_GMODE Pq Li u_int 438Get the current mode of the display. 439Possible results include: 440.Bl -tag -width Dv 441.It Dv WSDISPLAYIO_MODE_EMUL 442The display is in emulating (text) mode. 443.It Dv WSDISPLAYIO_MODE_MAPPED 444The display is in mapped (graphics) mode. 445.It Dv WSDISPLAYIO_MODE_DUMBFB 446The display is in mapped (frame buffer) mode. 447.El 448.Pp 449.It Dv WSDISPLAYIO_SMODE Pq Li u_int 450Set the current mode of the display. 451For possible arguments, see 452.Dv WSDISPLAYIO_GMODE . 453.Pp 454.It Dv WSDISPLAYIO_LINEBYTES Pq Li u_int 455Get the number of bytes per row, which may be the same as the number of pixels. 456.It Dv WSDISPLAYIO_GMSGATTRS Pq Li struct wsdisplay_msgattrs 457Get the attributes (colors and flags) used to print console messages, including 458separate fields for default output and kernel output. 459The returned structure is as follows: 460.Bd -literal -offset indent 461struct wsdisplay_msgattrs { 462 int default_attrs, default_bg, default_fg; 463 int kernel_attrs, kernel_bg, kernel_fg; 464}; 465.Ed 466.Pp 467The 468.Va default_attrs 469and 470.Va kernel_attrs 471variables are a combination of 472.Va WSATTR_* 473bits, and specify the attributes used to draw messages. 474The 475.Va default_bg , 476.Va default_fg , 477.Va kernel_bg 478and 479.Va kernel_fg 480variables specify the colors used to print messages, being 481.Sq _bg 482for the background and 483.Sq _fg 484for the foreground; their values are one of all the 485.Va WSCOL_* 486macros available. 487.It Dv WSDISPLAYIO_SMSGATTRS Pq Li struct wsdisplay_msgattrs 488Set the attributes (colors and flags) used to print console messages, including 489separate fields for default output and kernel output. 490The argument structure is the same as for 491.Dv WSDISPLAYIO_GMSGATTRS . 492.It Dv WSDISPLAYIO_GBORDER Pq Li u_int 493Retrieve the color of the screen border. 494This number corresponds to an ANSI standard color. 495.It Dv WSDISPLAYIO_SBORDER Pq Li u_int 496Set the color of the screen border, if applicable. 497This number corresponds to an ANSI standard color. 498Not all drivers support this feature. 499.It Dv WSDISPLAYIO_GETWSCHAR Pq Li struct wsdisplay_char 500Gets a single character from the screen, specified by its position. 501The structure used is as follows: 502.Bd -literal -offset indent 503struct wsdisplay_char { 504 int row, col; 505 uint16_t letter; 506 uint8_t background, foreground; 507 char flags; 508}; 509.Ed 510.Pp 511The 512.Va row 513and 514.Va col 515parameters are used as input; the rest of the structure is filled by the 516ioctl and is returned to you. 517.Va letter 518is the ASCII code of the letter found at the specified position, 519.Va background 520and 521.Va foreground 522are its colors and 523.Va flags 524is a combination of 525.Sq WSDISPLAY_CHAR_BRIGHT 526and/or 527.Sq WSDISPLAY_CHAR_BLINK . 528.It Dv WSDISPLAYIO_PUTWSCHAR Pq Li struct wsdisplay_char 529Puts a character on the screen. 530The structure has the same meaning as described in 531.Dv WSDISPLAY_GETWSCHAR , 532although all of its fields are treated as input. 533.\" Splash screen control 534.It Dv WSDISPLAYIO_SSPLASH Pq Li u_int 535Toggle the splash screen. 536This call is only available with the 537.Dv SPLASHSCREEN 538kernel option. 539.It Dv WSDISPLAYIO_SPROGRESS Pq Li u_int 540Update the splash animation. 541This call is only available with the 542.Dv SPLASHSCREEN 543and 544.Dv SPLASHSCREEN_PROGRESS 545kernel options. 546.El 547.Sh FILES 548.Bl -item 549.It 550.Pa /dev/ttyE* 551Terminal devices (per screen). 552.It 553.Pa /dev/ttyEcfg 554Control device. 555.It 556.Pa /dev/ttyEstat 557Status device. 558.It 559.Pa /usr/include/dev/wscons/wsconsio.h 560.El 561.Sh SEE ALSO 562.Xr ioctl 2 , 563.\" .Xr ega 4 , 564.Xr pcdisplay 4 , 565.Xr tty 4 , 566.Xr vga 4 , 567.Xr wscons 4 , 568.Xr wsconscfg 8 , 569.Xr wsconsctl 8 , 570.Xr wsfontload 8 , 571.Xr wsdisplay 9 572.Sh BUGS 573The 574.Nm 575code currently limits the number of screens on one display to 8. 576.Pp 577The terms 578.Dq wscons 579and 580.Dq wsdisplay 581are not cleanly distinguished in the code and in manual pages. 582.Pp 583.Dq non-emulating 584display devices are not tested. 585