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