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