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