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