1.\" $NetBSD: wsdisplay.4,v 1.20 2004/01/20 18:31:18 heas 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. 60It attaches to the hardware specific display device driver and makes it 61available as a text terminal or graphics interface. 62.Pp 63A display device can have the ability to display characters on it 64(without the 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 tty-like 71software interface. 72In contrary, non-emulating displays can only be used by special programs 73like X servers. 74.Pp 75The 76.Em console 77locator in the configuration line refers to the device's use as the output 78part of the operating system console. 79A device specification containing a positive value here will only match if 80the device is in use as the system console. 81(The console device selection in early system startup is not influenced.) 82This way, the console device can be connected to a known wsdisplay device 83instance. 84(Naturally, only 85.Dq emulating 86display devices are usable as console.) 87.Pp 88The 89.Em kbdmux 90locator in the configuration line refers to the 91.Xr wsmux 4 92that will be used to get keyboard events. 93If this locator is -1 no mux will be used. 94.Pp 95The logical unit of an independent contents displayed on a display 96(sometimes referred to as 97.Dq virtual terminal 98) is called a 99.Dq screen 100here. If the underlying device driver supports it, multiple screens can 101be used on one display. 102(As of this writing, only the 103.Xr vga 4 104and the 105.Tn VAX 106.Dq smg 107display drivers provide this ability.) 108Screens have different minor device numbers and separate tty instances. 109One screen possesses the 110.Dq focus , 111this means it is visible and its tty device will get 112the keyboard input. (In some cases \- if no screen is set up or if a screen 113was just deleted \- it is possible that no focus is present at all.) 114The focus can be switched by either special keyboard input (typically 115.Tn CTRL-ALT-F Ns Ar n ) 116or an ioctl command issued by a user program. 117Screens are created and deleted through the 118.Pa /dev/ttyEcfg 119control device (preferably using the 120.Xr wsconscfg 8 121utility). Alternatively, the compile-time option 122.Dv WSDISPLAY_DEFAULTSCREENS Ns = Ns Ar n 123will also create (at autoconfiguration time) 124.Ar n 125initial screens of the display driver's default type with 126the system's default terminal emulator. 127.Sh IOCTLS 128The following 129.Xr ioctl 2 130calls are provided by the 131.Nm 132driver or by devices which use it. 133Their definitions are found in 134.Aq Pa dev/wscons/wsconsio.h . 135.Bl -tag -width Dv 136.It Dv WSDISPLAYIO_GTYPE Pq Li int 137Retrieve the type of the display. 138The list of types is in 139.Aq Pa dev/wscons/wsconsio.h . 140.It Dv WSDISPLAYIO_GINFO Pq Li "struct wsdisplay_fbinfo" 141Retrieve basic information about a framebuffer display. 142The returned structure is as follows: 143.Bd -literal -offset indent 144struct wsdisplay_fbinfo { 145 u_int height; 146 u_int width; 147 u_int depth; 148 u_int cmsize; 149}; 150.Ed 151.Pp 152The 153.Va height 154and 155.Va width 156members are counted in pixels. 157The 158.Va depth 159member indicates the number of bits per pixel, and 160.Va cmsize 161indicates the number of color map entries accessible through 162.Dv WSDISPLAYIO_GETCMAP 163and 164.Dv WSDISPLAYIO_PUTCMAP . 165This call is likely to be unavailable on text-only displays. 166.It Dv WSDISPLAYIO_GETCMAP Pq Li "struct wsdisplay_cmap" 167Retrieve the current color map from the display. 168This call needs the 169following structure set up beforehand: 170.Bd -literal -offset indent 171struct wsdisplay_cmap { 172 u_int index; 173 u_int count; 174 u_char *red; 175 u_char *green; 176 u_char *blue; 177}; 178.Ed 179.Pp 180The 181.Va index 182and 183.Va count 184members specify the range of color map entries to retrieve. 185The 186.Va red , 187.Va green , 188and 189.Va blue 190members should each point to an array of 191.Va count 192.Li u_char Ns s . 193On return, these will be filled in with the appropriate entries from the 194color map. 195On all displays that support this call, values range from 0 for minimum 196intensity to 255 for maximum intensity, even if the display does not use 197eight bits internally to represent intensity. 198.It Dv WSDISPLAYIO_PUTCMAP Pq Li "struct wsdisplay_cmap" 199Change the display's color map. 200The argument structure is the same as for 201.Dv WSDISPLAYIO_GETCMAP , 202but 203.Va red , 204.Va green , 205and 206.Va blue 207are taken as pointers to the values to use to set the color map. 208This call is not available on displays with fixed color maps. 209.It Dv WSDISPLAYIO_GVIDEO Pq Li int 210Get the current state of the display's video output. 211Possible values are: 212.Bl -tag -width Dv 213.It Dv WSDISPLAYIO_VIDEO_OFF 214The display is blanked. 215.It Dv WSDISPLAYIO_VIDEO_ON 216The display is enabled. 217.El 218.It Dv WSDISPLAYIO_SVIDEO Pq Li int 219Set the state of the display's video output. 220See 221.Dv WSDISPLAYIO_GVIDEO 222above for possible values. 223.It Dv WSDISPLAYIO_GCURPOS Pq Li "struct wsdisplay_curpos" 224Retrieve the current position of the hardware cursor. 225The returned structure 226is as follows: 227.Bd -literal -offset indent 228struct wsdisplay_curpos { 229 u_int x, y; 230}; 231.Ed 232.Pp 233The 234.Va x 235and 236.Va y 237members count the number of pixels right and down, respectively, from 238the top-left corner of the display to the hot spot of the cursor. 239This call is not available on displays without a hardware cursor. 240.It Dv WSDISPLAYOP_SCURPOS Pq Li "struct wsdisplay_curpos" 241Set the current cursor position. The argument structure, and its semantics, 242are the same as for 243.Dv WSDISPLAYIO_GCURPOS . 244This call is not available on displays without a hardware cursor. 245.It Dv WSDISPLAYIO_GCURMAX Pq Li "struct wsdisplay_curpos" 246Retrieve the maximum size of cursor supported by the display. 247The 248.Va x 249and 250.Va y 251members of the returned structure indicate the maximum number of pixel rows 252and columns, respectively, in a hardware cursor on this display. 253This call is not available on displays without a hardware cursor. 254.It Dv WSDISPLAYIO_GCURSOR Pq Li "struct wsdisplay_cursor" 255Retrieve some or all of the hardware cursor's attributes. 256The argument structure is as follows: 257.Bd -literal -offset indent 258struct wsdisplay_cursor { 259 u_int which; 260 u_int enable; 261 struct wsdisplay_curpos pos; 262 struct wsdisplay_curpos hot; 263 struct wsdisplay_cmap cmap; 264 struct wsdisplay_curpos size; 265 u_char *image; 266 u_char *mask; 267}; 268.Pp 269.Ed 270The 271.Va which 272member indicates which of the values the application requires to be returned. 273It should contain the logical OR of the following flags: 274.Bl -tag -width Dv 275.It Dv WSDISPLAYIO_CURSOR_DOCUR 276Get 277.Va enable , 278which indicates whether the cursor is currently displayed (non-zero) or 279not (zero). 280.It Dv WSDISPLAYIO_CURSOR_DOPOS 281Get 282.Va pos , 283which indicates the current position of the cursor on the display, as 284would be returned by 285.Dv WSDISPLAYIO_GCURPOS . 286.It Dv WSDISPLAYIO_CURSOR_DOHOT 287Get 288.Va hot , 289which indicates the location of the 290.Dq hot spot 291within the cursor. 292This is the point on the cursor whose position on the display is treated 293as being the position of the cursor by other calls. 294Its location is counted in pixels from the top-right corner of the cursor. 295.It Dv WSDISPLAYIO_CURSOR_DOCMAP 296Get 297.Va cmap , 298which indicates the current cursor color map. 299Unlike in a call to 300.Dv WSDISPLAYIO_GETCMAP , 301.Va cmap 302here need not have its 303.Va index 304and 305.Va count 306members initialized. 307They will be set to 0 and 2 respectively by the call. 308This means that 309.Va cmap . Ns Va red , 310.Va cmap . Ns Va green , 311and 312.Va cmap . Ns Va blue 313must each point to at least enough space to hold two 314.Li u_char Ns s . 315.It Dv WSDISPLAYIO_CURSOR_DOSHAPE 316Get 317.Va size , image , 318and 319.Va mask . 320These are, respectively, the dimensions of the cursor in pixels, the 321bitmap of set pixels in the cursor and the bitmap of opaque pixels in 322the cursor. 323The format in which these bitmaps are returned, and hence the amount of 324space that must be provided by the application, are device-dependent. 325.It Dv WSDISPLAYIO_CURSOR_DOALL 326Get all of the above. 327.El 328.Pp 329The device may elect to return information that was not requested by the user, 330so those elements of 331.Li "struct wsdisplay_cursor" 332which are pointers should be initialized to 333.Dv NULL 334if not otherwise used. 335This call is not available on displays without a hardware cursor. 336.It Dv WSDISPLAYIO_SCURSOR Pq Li "struct wsdisplay_cursor" 337Set some or all of the hardware cursor's attributes. 338The argument structure is the same as for 339.Dv WSDISPLAYIO_GCURSOR . 340The 341.Va which 342member specifies which attributes of the cursor are to be changed. 343It should contain the logical OR of the following flags: 344.Bl -tag -width Dv 345.It Dv WSDISPLAYIO_CURSOR_DOCUR 346If 347.Va enable 348is zero, hide the cursor. 349Otherwise, display it. 350.It Dv WSDISPLAYIO_CURSOR_DOPOS 351Set the cursor's position on the display to 352.Va pos , 353the same as 354.Dv WSDISPLAYIO_SCURPOS . 355.It Dv WSDISPLAYIO_CURSOR_DOHOT 356Set the 357.Dq hot spot 358of the cursor, as defined above, to 359.Va hot . 360.It Dv WSDISPLAYIO_CURSOR_DOCMAP 361Set some or all of the cursor color map based on 362.Va cmap . 363The 364.Va index 365and 366.Va count 367elements of 368.Va cmap 369indicate which color map entries to set, and the entries themselves come from 370.Va cmap . Ns Va red , 371.Va cmap . Ns Va green , 372and 373.Va cmap . Ns Va blue . 374.It Dv WSDISPLAYIO_CURSOR_DOSHAPE 375Set the cursor shape from 376.Va size , image , 377and 378.Va mask . 379See above for their meanings. 380.It Dv WSDISPLAYIO_CURSOR_DOALL 381Do all of the above. 382.El 383.Pp 384This call is not available on displays without a hardware cursor. 385.It Dv WSDISPLAYIO_GMODE Pq Li u_int 386Get the current mode of the display. 387Possible results include: 388.Bl -tag -width Dv 389.It Dv WSDISPLAYIO_MODE_EMUL 390The display is in emulating (text) mode. 391.It Dv WSDISPLAYIO_MODE_MAPPED 392The display is in mapped (graphics) mode. 393.El 394.Pp 395.It Dv WSDISPLAYIO_SMODE Pq Li u_int 396Set the current mode of the display. 397For possible arguments, see 398.Dv WSDISPLAYIO_GMODE . 399.El 400.Sh FILES 401.Bl -item 402.It 403.Pa /dev/ttyE* 404Terminal devices (per screen). 405.It 406.Pa /dev/ttyEcfg 407Control device. 408.It 409.Pa /dev/ttyEstat 410Status device. 411.It 412.Pa /usr/include/dev/wscons/wsconsio.h 413.El 414.Sh SEE ALSO 415.Xr ioctl 2 , 416.Xr ega 4 , 417.Xr pcdisplay 4 , 418.Xr tty 4 , 419.Xr vga 4 , 420.Xr wscons 4 , 421.Xr wsconscfg 8 , 422.Xr wsconsctl 8 , 423.Xr wsfontload 8 , 424.Xr wsdisplay 9 425.Sh BUGS 426The 427.Nm 428code currently limits the number of screens on one display to 8. 429.Pp 430The terms 431.Dq wscons 432and 433.Dq wsdisplay 434are not cleanly distinguished in the code and in manual pages. 435.Pp 436.Dq non-emulating 437display devices are not tested. 438