1.\" $NetBSD: wsdisplay.4,v 1.19 2003/06/27 18:54:09 wiz Exp $ 2.\" 3.\" Copyright (c) 1999 Matthias Drochner. 4.\" Copyright (c) 2002 Ben Harris. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd June 22, 2002 29.Os 30.Dt WSDISPLAY 4 31.Sh NAME 32.Nm wsdisplay 33.Nd generic display device support in wscons 34.Sh SYNOPSIS 35.Cd "wsdisplay* at ega? console ?" 36(EGA display on ISA) 37.Cd "wsdisplay* at vga? console ?" 38(VGA display on ISA or PCI) 39.Cd "wsdisplay* at pcdisplay? console ?" 40(generic PC (ISA) display) 41.Cd "wsdisplay* at tga? console ?" 42(DEC TGA display, alpha only) 43.Cd "wsdisplay* at pfb? console ?" 44(PCI framebuffer, bebox only) 45.Cd "wsdisplay0 at ofb? console ?" 46(Open Firmware framebuffer, macppc only) 47.Cd "wsdisplay* at nextdisplay? console ?" 48(NeXT display) 49.Cd "wsdisplay0 at smg0" 50(VAXstation small monochrome display) 51.Cd "wsdisplay* at ... kbdmux N" 52.Cd options WSDISPLAY_DEFAULTSCREENS=N 53.Cd options WSDISPLAY_CHARFUNCS 54.Sh DESCRIPTION 55The 56.Nm 57driver is an abstraction layer for display devices within the 58.Xr wscons 4 59framework. It attaches to the hardware specific display device 60driver and and makes it available as text terminal or graphics 61interface. 62.Pp 63A display device can have the ability to display characters on it 64(without help of an X server), either directly by hardware or through 65software putting pixel data into the display memory. 66Such displays are called 67.Dq emulating , 68the 69.Nm 70driver will connect a terminal emulation module and provide a 71tty-like software interface. In contrary, non-emulating displays can only 72be used by special programs like X servers. 73.Pp 74The 75.Em console 76locator in the configuration line refers to the device's use as output 77part of the operating system console. A device specification containing 78a positive value here will only match if the device is in use as system 79console. (The console device selection in early system startup is not 80influenced.) This way, the console device can be connected to a known 81wsdisplay device instance. (Naturally, only 82.Dq emulating 83display devices are usable as console.) 84.Pp 85The 86.Em kbdmux 87locator in the configuration line refers to the 88.Xr wsmux 4 89that will be used to get keyboard events. If this locator is -1 no 90mux will be used. 91.Pp 92The logical unit of an independent contents displayed on a display 93(sometimes referred to as 94.Dq virtual terminal 95) is called a 96.Dq screen 97here. If the underlying device driver supports it, multiple screens can 98be used on one display. (As of this writing, only the 99.Xr vga 4 100and the 101.Tn VAX 102.Dq smg 103display drivers provide this ability.) 104Screens have different minor device numbers and separate tty instances. 105One screen possesses the 106.Dq focus , 107this means it is visible and its tty device will get 108the keyboard input. (In some cases \- if no screen is set up or if a screen 109was just deleted \- it is possible that no focus is present at all.) 110The focus can be switched by either special keyboard input (typically 111.Tn CTRL-ALT-F Ns Ar n ) 112or an ioctl command issued by a user program. 113Screens are created and deleted through the 114.Pa /dev/ttyEcfg 115control device (preferably using the 116.Xr wsconscfg 8 117utility). Alternatively, the compile-time option 118.Dv WSDISPLAY_DEFAULTSCREENS Ns = Ns Ar n 119will also create (at autoconfiguration time) 120.Ar n 121initial screens of the display driver's default type with 122the system's default terminal emulator. 123.Sh IOCTLS 124The following 125.Xr ioctl 2 126calls are provided by the 127.Nm 128driver or by devices which use it. Their definitions are found in 129.Aq Pa dev/wscons/wsconsio.h . 130.Bl -tag -width Dv 131.It Dv WSDISPLAYIO_GTYPE Pq Li int 132Retrieve the type of the display. The list of types is in 133.Aq Pa dev/wscons/wsconsio.h . 134.It Dv WSDISPLAYIO_GINFO Pq Li "struct wsdisplay_fbinfo" 135Retrieve basic information about a framebuffer display. 136The returned structure is as follows: 137.Bd -literal -offset indent 138struct wsdisplay_fbinfo { 139 u_int height; 140 u_int width; 141 u_int depth; 142 u_int cmsize; 143}; 144.Ed 145.Pp 146The 147.Va height 148and 149.Va width 150members are counted in pixels. The 151.Va depth 152member indicates the number of bits per pixel, and 153.Va cmsize 154indicates the number of color map entries accessible through 155.Dv WSDISPLAYIO_GETCMAP 156and 157.Dv WSDISPLAYIO_PUTCMAP . 158This call is likely to be unavailable on text-only displays. 159.It Dv WSDISPLAYIO_GETCMAP Pq Li "struct wsdisplay_cmap" 160Retrieve the current color map from the display. This call needs the 161following structure set up beforehand: 162.Bd -literal -offset indent 163struct wsdisplay_cmap { 164 u_int index; 165 u_int count; 166 u_char *red; 167 u_char *green; 168 u_char *blue; 169}; 170.Ed 171.Pp 172The 173.Va index 174and 175.Va count 176members specify the range of color map entries to retrieve. The 177.Va red , 178.Va green , 179and 180.Va blue 181members should each point to an array of 182.Va count 183.Li u_char Ns s . 184On return, these will be filled in with the appropriate entries from the 185color map. On all displays that support this call, values range from 0 186for minimum intensity to 255 for maximum intensity, even if the display 187does not use eight bits internally to represent intensity. 188.It Dv WSDISPLAYIO_PUTCMAP Pq Li "struct wsdisplay_cmap" 189Change the display's color map. The argument structure is the same as for 190.Dv WSDISPLAYIO_GETCMAP , 191but 192.Va red , 193.Va green , 194and 195.Va blue 196are taken as pointers to the values to use to set the color map. 197This call is not available on displays with fixed color maps. 198.It Dv WSDISPLAYIO_GVIDEO Pq Li int 199Get the current state of the display's video output. Possible values are: 200.Bl -tag -width Dv 201.It Dv WSDISPLAYIO_VIDEO_OFF 202The display is blanked. 203.It Dv WSDISPLAYIO_VIDEO_ON 204The display is enabled. 205.El 206.It Dv WSDISPLAYIO_SVIDEO Pq Li int 207Set the state of the display's video output. See 208.Dv WSDISPLAYIO_GVIDEO 209above for possible values. 210.It Dv WSDISPLAYIO_GCURPOS Pq Li "struct wsdisplay_curpos" 211Retrieve the current position of the hardware cursor. The returned structure 212is as follows: 213.Bd -literal -offset indent 214struct wsdisplay_curpos { 215 u_int x, y; 216}; 217.Ed 218.Pp 219The 220.Va x 221and 222.Va y 223members count the number of pixels right and down, respectively, from 224the top-left corner of the display to the hot spot of the cursor. 225This call is not available on displays without a hardware cursor. 226.It Dv WSDISPLAYOP_SCURPOS Pq Li "struct wsdisplay_curpos" 227Set the current cursor position. The argument structure, and its semantics, 228are the same as for 229.Dv WSDISPLAYIO_GCURPOS . 230This call is not avilable on displays without a hardware cursor. 231.It Dv WSDISPLAYIO_GCURMAX Pq Li "struct wsdisplay_curpos" 232Retrieve the maximum size of cursor supported by the display. The 233.Va x 234and 235.Va y 236members of the returned structure indicate the maximum number of pixel rows 237and columns, respectively, in a hardware cursor on this display. 238This call is not available on displays without a hardware cursor. 239.It Dv WSDISPLAYIO_GCURSOR Pq Li "struct wsdisplay_cursor" 240Retrieve some or all of the hardware cursor's attributes. The argument 241structure is as follows: 242.Bd -literal -offset indent 243struct wsdisplay_cursor { 244 u_int which; 245 u_int enable; 246 struct wsdisplay_curpos pos; 247 struct wsdisplay_curpos hot; 248 struct wsdisplay_cmap cmap; 249 struct wsdisplay_curpos size; 250 u_char *image; 251 u_char *mask; 252}; 253.Pp 254.Ed 255The 256.Va which 257member indicates which of the values the application requires to be returned. 258It should contain the logical OR of the following flags: 259.Bl -tag -width Dv 260.It Dv WSDISPLAYIO_CURSOR_DOCUR 261Get 262.Va enable , 263which indicates whether the cursor is currently displayed (non-zero) or 264not (zero). 265.It Dv WSDISPLAYIO_CURSOR_DOPOS 266Get 267.Va pos , 268which indicates the current position of the cursor on the display, as 269would be returned by 270.Dv WSDISPLAYIO_GCURPOS . 271.It Dv WSDISPLAYIO_CURSOR_DOHOT 272Get 273.Va hot , 274which indicates the location of the 275.Dq hot spot 276within the cursor. This is the point on the cursor whose position on the 277display is treated as being the position of the cursor by other calls. 278Its location is counted in pixels from the top-right corner of the cursor. 279.It Dv WSDISPLAYIO_CURSOR_DOCMAP 280Get 281.Va cmap , 282which indicates the current cursor color map. 283Unlike in a call to 284.Dv WSDISPLAYIO_GETCMAP , 285.Va cmap 286here need not have its 287.Va index 288and 289.Va count 290members initialized. They will be set to 0 and 2 respectively by the call. 291This means that 292.Va cmap . Ns Va red , 293.Va cmap . Ns Va green , 294and 295.Va cmap . Ns Va blue 296must each point to at least enough space to hold two 297.Li u_char Ns s . 298.It Dv WSDISPLAYIO_CURSOR_DOSHAPE 299Get 300.Va size , image , 301and 302.Va mask . 303These are, respectively, the dimensions of the cursor in pixels, the 304bitmap of set pixels in the cursor and the bitmap of opaque pixels in 305the cursor. The format in which these bitmaps are returned, and hence 306the amount of space that must be provided by the application, are 307device-dependent. 308.It Dv WSDISPLAYIO_CURSOR_DOALL 309Get all of the above. 310.El 311.Pp 312The device may elect to return information that was not requested by the user, 313so those elements of 314.Li "struct wsdisplay_cursor" 315which are pointers should be initialized to 316.Dv NULL 317if not otherwise used. 318This call is not available on displays without a hardware cursor. 319.It Dv WSDISPLAYIO_SCURSOR Pq Li "struct wsdisplay_cursor" 320Set some or all of the hardware cursor's attributes. The argument structure 321is the same as for 322.Dv WSDISPLAYIO_GCURSOR . 323The 324.Va which 325member specifies which attributes of the cursor are to be changed. 326It should contain the logical OR of the following flags: 327.Bl -tag -width Dv 328.It Dv WSDISPLAYIO_CURSOR_DOCUR 329If 330.Va enable 331is zero, hide the cursor. Otherwise, display it. 332.It Dv WSDISPLAYIO_CURSOR_DOPOS 333Set the cursor's position on the display to 334.Va pos , 335the same as 336.Dv WSDISPLAYIO_SCURPOS . 337.It Dv WSDISPLAYIO_CURSOR_DOHOT 338Set the 339.Dq hot spot 340of the cursor, as defined above, to 341.Va hot . 342.It Dv WSDISPLAYIO_CURSOR_DOCMAP 343Set some or all of the cursor color map based on 344.Va cmap . 345The 346.Va index 347and 348.Va count 349elements of 350.Va cmap 351indicate which color map entries to set, and the entries themselves come from 352.Va cmap . Ns Va red , 353.Va cmap . Ns Va green , 354and 355.Va cmap . Ns Va blue . 356.It Dv WSDISPLAYIO_CURSOR_DOSHAPE 357Set the cursor shape from 358.Va size , image , 359and 360.Va mask . 361See above for their meanings. 362.It Dv WSDISPLAYIO_CURSOR_DOALL 363Do all of the above. 364.El 365.Pp 366This call is not available on displays without a hardware cursor. 367.It Dv WSDISPLAYIO_GMODE Pq Li u_int 368Get the current mode of the display. Possible results include: 369.Bl -tag -width Dv 370.It Dv WSDISPLAYIO_MODE_EMUL 371The display is in emulating (text) mode. 372.It Dv WSDISPLAYIO_MODE_MAPPED 373The display is in mapped (graphics) mode. 374.El 375.Pp 376.It Dv WSDISPLAYIO_SMODE Pq Li u_int 377Set the current mode of the display. For possible arguments, see 378.Dv WSDISPLAYIO_GMODE . 379.El 380.Sh FILES 381.Bl -item 382.It 383.Pa /dev/ttyE* 384Terminal devices (per screen). 385.It 386.Pa /dev/ttyEcfg 387Control device. 388.It 389.Pa /dev/ttyEstat 390Status device. 391.It 392.Pa /usr/include/dev/wscons/wsconsio.h 393.El 394.Sh SEE ALSO 395.Xr ioctl 2 , 396.Xr ega 4 , 397.Xr pcdisplay 4 , 398.Xr tty 4 , 399.Xr vga 4 , 400.Xr wscons 4 , 401.Xr wsconscfg 8 , 402.Xr wsconsctl 8 , 403.Xr wsfontload 8 , 404.Xr wsdisplay 9 405.Sh BUGS 406The 407.Nm 408code currently limits the number of screens on one display to 8. 409.Pp 410The terms 411.Dq wscons 412and 413.Dq wsdisplay 414are not cleanly distinguished in the code and in manual pages. 415.Pp 416.Dq non-emulating 417display devices are not tested. 418