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