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