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