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