| blob | 2abaa1e1997258e7bed670b343b70b9b7325e183 |
1 .\"
2 .\" vidcontrol - a utility for manipulating the syscons video driver
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\"
13 .\" @(#)vidcontrol.1
14 .\" $FreeBSD$
15 .\"
16 .Dd December 23, 2006
17 .Dt VIDCONTROL 1
18 .Os
19 .Sh NAME
20 .Nm vidcontrol
21 .Nd system console control and configuration utility
22 .Sh SYNOPSIS
23 .Nm
24 .Op Fl CdLHPpx
25 .Op Fl b Ar color
26 .Op Fl c Ar appearance
27 .Oo
28 .Fl f
29 .Op Ar size
30 .Ar file
31 .Oc
32 .Op Fl g Ar geometry
33 .Op Fl h Ar size
34 .Op Fl i Cm adapter | mode
35 .Op Fl l Ar screen_map
36 .Op Fl M Ar char
37 .Op Fl m Cm on | off
38 .Op Fl r Ar foreground Ar background
39 .Op Fl S Cm on | off
40 .Op Fl s Ar number
41 .Op Fl t Ar N | Cm off
42 .Op Ar mode
43 .Op Ar foreground Op Ar background
44 .Op Cm show
45 .Sh DESCRIPTION
46 The
47 .Nm
48 utility is used to set various options for the
49 .Xr syscons 4
50 console driver,
51 such as video mode, colors, cursor shape, screen output map, font and screen
52 saver timeout.
53 .Pp
54 The following command line options are supported:
55 .Bl -tag -width indent
56 .It Ar mode
57 Select a new video mode.
58 The modes currently recognized are:
59 .Ar 80x25 ,
60 .Ar 80x30 ,
61 .Ar 80x43 ,
62 .Ar 80x50 ,
63 .Ar 80x60 ,
64 .Ar 132x25 ,
65 .Ar 132x30 ,
66 .Ar 132x43 ,
67 .Ar 132x50 ,
68 .Ar 132x60 ,
69 .Ar VGA_40x25 ,
70 .Ar VGA_80x25 ,
71 .Ar VGA_80x30 ,
72 .Ar VGA_80x50 ,
73 .Ar VGA_80x60 ,
74 .Ar VGA_90x25 ,
75 .Ar VGA_90x30 ,
76 .Ar VGA_90x43 ,
77 .Ar VGA_90x50 ,
78 .Ar VGA_90x60 ,
79 .Ar EGA_80x25 ,
80 .Ar EGA_80x43 ,
81 .Ar VESA_132x25 ,
82 .Ar VESA_132x43 ,
83 .Ar VESA_132x50 ,
84 .Ar VESA_132x60 .
85 .\"The graphic mode
86 .\".Ar VGA_320x200
87 .\"and
88 The raster text mode
89 .Ar VESA_800x600
90 can also be chosen.
91 Alternatively, a mode can be specified with its number by using a mode name of
92 the form
93 .Li MODE_ Ns Aq Ar NUMBER .
94 A list of valid mode numbers can be obtained with the
95 .Fl i Cm mode
96 option.
97 See
98 .Sx Video Mode Support
99 below.
100 .It Ar foreground Op Ar background
101 Change colors when displaying text.
102 Specify the foreground color
103 (e.g.\&
104 .Dq vidcontrol white ) ,
105 or both a foreground and background colors
106 (e.g.\&
107 .Dq vidcontrol yellow blue ) .
108 Use the
109 .Cm show
110 command below to see available colors.
111 .It Cm show
112 See the supported colors on a given platform.
113 .It Fl b Ar color
114 Set border color to
115 .Ar color .
116 This option may not be always supported by the video driver.
117 .It Fl C
118 Clear the history buffer.
119 .It Fl c Cm normal | blink | destructive
120 Change the cursor appearance.
121 The cursor is either an inverting block
122 .Pq Cm normal
123 that can optionally
124 .Cm blink ,
125 or it can be like the old hardware cursor
126 .Pq Cm destructive .
127 The latter is actually a simulation.
128 .It Fl d
129 Print out current output screen map.
130 .It Xo
131 .Fl f
132 .Op Ar size
133 .Ar file
134 .Xc
135 Load font
136 .Ar file
137 for
138 .Ar size
139 (currently, only
140 .Cm 8x8 ,
141 .Cm 8x14
142 or
143 .Cm 8x16 ) .
144 The font file can be either uuencoded or in raw binary format.
145 You can also use the menu-driven
146 .Xr vidfont 1
147 command to load the font of your choice.
148 .Pp
149 .Ar Size
150 may be omitted, in this case
151 .Nm
152 will try to guess it from the size of font file.
153 .Pp
154 Note that older video cards, such as MDA and CGA, do not support
155 software font.
156 See also
157 .Sx Video Mode Support
158 and
159 .Sx EXAMPLES
160 below and the man page for
161 .Xr syscons 4 .
162 .It Fl g Ar geometry
163 Set the
164 .Ar geometry
165 of the text mode for the modes with selectable
166 geometry.
167 Currently only raster modes, such as
168 .Ar VESA_800x600 ,
169 support this option.
170 See also
171 .Sx Video Mode Support
172 and
173 .Sx EXAMPLES
174 below.
175 .It Fl h Ar size
176 Set the size of the history (scrollback) buffer to
177 .Ar size
178 lines.
179 .It Fl i Cm adapter
180 Shows info about the current video adapter.
181 .It Fl i Cm mode
182 Shows the possible video modes with the current video hardware.
183 .It Fl l Ar screen_map
184 Install screen output map file from
185 .Ar screen_map .
186 See also
187 .Xr syscons 4 .
188 .It Fl L
189 Install default screen output map.
190 .It Fl M Ar char
191 Sets the base character used to render the mouse pointer to
192 .Ar char .
193 .It Fl m Cm on | off
194 Switch the mouse pointer
195 .Cm on
196 or
197 .Cm off .
198 Used together with the
199 .Xr moused 8
200 daemon for text mode cut & paste functionality.
201 .It Fl p
202 Capture the current contents of the video buffer corresponding
203 to the terminal device referred to by standard input.
204 The
205 .Nm
206 utility writes contents of the video buffer to the standard
207 output in a raw binary format.
208 For details about that
209 format see
210 .Sx Format of Video Buffer Dump
211 below.
212 .It Fl P
213 Same as
214 .Fl p ,
215 but dump contents of the video buffer in a plain text format
216 ignoring nonprintable characters and information about text
217 attributes.
218 .It Fl H
219 When used with
220 .Fl p
221 or
222 .Fl P ,
223 it instructs
224 .Nm
225 to dump full history buffer instead of visible portion of
226 the video buffer only.
227 .It Fl r Ar foreground background
228 Change reverse mode colors to
229 .Ar foreground
230 and
231 .Ar background .
232 .It Fl S Cm on | off
233 Turn vty switching on or off.
234 When vty switching is off,
235 attempts to switch to a different virtual terminal will fail.
236 (The default is to permit vty switching.)
237 This protection can be easily bypassed when the kernel is compiled with
238 the
239 .Dv DDB
240 option.
241 However, you probably should not compile the kernel debugger on a box which
242 is supposed to be physically secure.
243 .It Fl s Ar number
244 Set the current vty to
245 .Ar number .
246 .It Fl t Ar N | Cm off
247 Set the screensaver timeout to
248 .Ar N
249 seconds, or turns it
250 .Cm off .
251 .It Fl x
252 Use hexadecimal digits for output.
253 .El
254 .Ss Video Mode Support
255 Note that not all modes listed above may be supported by the video
256 hardware.
257 You can verify which mode is supported by the video hardware, using the
258 .Fl i Cm mode
259 option.
260 .Pp
261 The VESA BIOS support must be linked to the kernel
262 or loaded as a KLD module if you wish to use VESA video modes
263 or 132 column modes
264 (see
265 .Xr vga 4 ) .
266 .Pp
267 You need to compile your kernel with the
268 .Ar VGA_WIDTH90
269 option if you wish to use VGA 90 column modes
270 (see
271 .Xr vga 4 ) .
272 .Pp
273 Video modes other than 25 and 30 line modes may require specific size of font.
274 Use
275 .Fl f
276 option above to load a font file to the kernel.
277 If the required size of font has not been loaded to the kernel,
278 .Nm
279 will fail if the user attempts to set a new video mode.
280 .Pp
281 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
282 .Sy Modes Ta Sy Font size
283 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
284 .No 30 line modes Ta 8x16
285 .No 43 line modes Ta 8x8
286 .No 50 line modes Ta 8x8
287 .No 60 line modes Ta 8x8
288 .El
289 .Pp
290 It is better to always load all three sizes (8x8, 8x14 and 8x16)
291 of the same font.
292 .Pp
293 You may set variables in
294 .Pa /etc/rc.conf
295 or
296 .Pa /etc/rc.conf.local
297 so that desired font files will be automatically loaded
298 when the system starts up.
299 See below.
300 .Pp
301 If you want to use any of the raster text modes you need to recompile your
302 kernel with the
303 .Dv SC_PIXEL_MODE
304 option.
305 See
306 .Xr syscons 4
307 for more details on this kernel option.
308 .Ss Format of Video Buffer Dump
309 The
310 .Nm
311 utility uses the
312 .Xr syscons 4
313 .Dv CONS_SCRSHOT
314 .Xr ioctl 2
315 to capture the current contents of the video buffer.
316 The
317 .Nm
318 utility writes version and additional information to the standard
319 output, followed by the contents of the video buffer.
320 .Pp
321 VGA video memory is typically arranged in two byte tuples,
322 one per character position.
323 In each tuple, the first byte will be the character code,
324 and the second byte is the character's color attribute.
325 .Pp
326 The VGA color attribute byte looks like this:
327 .Pp
328 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
329 .Sy "bits# width meaning"
330 .Li "7 <X0000000> 1 character blinking"
331 .Li "6:4 <0XXX0000> 3 background color"
332 .Li "3 <0000X000> 1 bright foreground color"
333 .Li "2:0 <00000XXX> 3 foreground color"
334 .El
335 .Pp
336 Here is a list of the three bit wide base colors:
337 .Pp
338 .Bl -hang -offset indent -compact
339 .It 0
340 Black
341 .It 1
342 Blue
343 .It 2
344 Green
345 .It 3
346 Cyan
347 .It 4
348 Red
349 .It 5
350 Magenta
351 .It 6
352 Brown
353 .It 7
354 Light Grey
355 .El
356 .Pp
357 Base colors with bit 3 (the bright foreground flag) set:
358 .Pp
359 .Bl -hang -offset indent -compact
360 .It 0
361 Dark Grey
362 .It 1
363 Light Blue
364 .It 2
365 Light Green
366 .It 3
367 Light Cyan
368 .It 4
369 Light Red
370 .It 5
371 Light Magenta
372 .It 6
373 Yellow
374 .It 7
375 White
376 .El
377 .Pp
378 For example, the two bytes
379 .Pp
380 .Dl "65 158"
381 .Pp
382 specify an uppercase A (character code 65), blinking
383 (bit 7 set) in yellow (bits 3:0) on a blue background
384 (bits 6:4).
385 .Pp
386 The
387 .Nm
388 output contains a small header which includes additional
389 information which may be useful to utilities processing
390 the output.
391 .Pp
392 The first 10 bytes are always arranged as follows:
393 .Bl -column "Byte range" "Contents" -offset indent
394 .It Sy "Byte Range Contents"
395 .It "1 thru 8 Literal text" Dq Li SCRSHOT_
396 .It "9 File format version number"
397 .It "10 Remaining number of bytes in the header"
398 .El
399 .Pp
400 Subsequent bytes depend on the version number.
401 .Bl -column "Version" "13 and up" -offset indent
402 .It Sy "Version Byte Meaning"
403 .It "1 11 Terminal width, in characters"
404 .It " 12 Terminal depth, in characters"
405 .It " 13 and up The snapshot data"
406 .El
407 .Pp
408 So a dump of an 80x25 screen would start (in hex)
409 .Bd -literal -offset indent
410 53 43 52 53 48 4f 54 5f 01 02 50 19
411 ----------------------- -- -- -- --
412 | | | | ` 25 decimal
413 | | | `--- 80 decimal
414 | | `------ 2 remaining bytes of header data
415 | `--------- File format version 1
416 `------------------------ Literal "SCRSHOT_"
417 .Ed
418 .Sh VIDEO OUTPUT CONFIGURATION
419 .Ss Boot Time Configuration
420 You may set the following variables in
421 .Pa /etc/rc.conf
422 or
423 .Pa /etc/rc.conf.local
424 in order to configure the video output at boot time.
425 .Pp
426 .Bl -tag -width foo_bar_var -compact
427 .It Ar blanktime
428 Sets the timeout value for the
429 .Fl t
430 option.
431 .It Ar font8x16 , font8x14 , font8x8
432 Specifies font files for the
433 .Fl f
434 option.
435 .It Ar scrnmap
436 Specifies a screen output map file for the
437 .Fl l
438 option.
439 .El
440 .Pp
441 See
442 .Xr rc.conf 5
443 for more details.
444 .Ss Driver Configuration
445 The video card driver may let you change default configuration
446 options, such as the default font, so that you do not need to set up
447 the options at boot time.
448 See video card driver manuals, (e.g.\&
449 .Xr vga 4 )
450 for details.
451 .Sh FILES
452 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
453 .It Pa /usr/share/syscons/fonts/*
454 font files.
455 .It Pa /usr/share/syscons/scrnmaps/*
456 screen output map files.
457 .El
458 .Sh EXAMPLES
459 If you want to load
460 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
461 to the kernel, run
462 .Nm
463 as:
464 .Pp
465 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
466 .Pp
467 So long as the font file is in
468 .Pa /usr/share/syscons/fonts ,
469 you may abbreviate the file name as
470 .Pa iso-8x16 :
471 .Pp
472 .Dl vidcontrol -f 8x16 iso-8x16
473 .Pp
474 Furthermore, you can also omit font size
475 .Dq Li 8x16 :
476 .Pp
477 .Dl vidcontrol -f iso-8x16
478 .Pp
479 Moreover, the suffix specifying the font size can be also omitted; in
480 this case,
481 .Nm
482 will use the size of the currently displayed font to construct the
483 suffix:
484 .Pp
485 .Dl vidcontrol -f iso
486 .Pp
487 Likewise, you can also abbreviate the screen output map file name for
488 the
489 .Fl l
490 option if the file is found in
491 .Pa /usr/share/syscons/scrnmaps .
492 .Pp
493 .Dl vidcontrol -l iso-8859-1_to_cp437
494 .Pp
495 The above command will load
496 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
497 .Pp
498 The following command will set-up a 100x37 raster text mode (useful for
499 some LCD models):
500 .Pp
501 .Dl vidcontrol -g 100x37 VESA_800x600
502 .Pp
503 The following command will capture the contents of the first virtual
504 terminal video buffer, and redirect the output to the
505 .Pa shot.scr
506 file:
507 .Pp
508 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
509 .Pp
510 The following command will dump contents of the fourth virtual terminal
511 video buffer
512 to the standard output in the human readable format:
513 .Pp
514 .Dl vidcontrol -P < /dev/ttyv3
515 .Sh SEE ALSO
516 .Xr kbdcontrol 1 ,
517 .Xr vidfont 1 ,
518 .Xr keyboard 4 ,
519 .Xr screen 4 ,
520 .Xr syscons 4 ,
521 .Xr vga 4 ,
522 .Xr rc.conf 5 ,
523 .Xr kldload 8 ,
524 .Xr moused 8 ,
525 .Xr watch 8
526 .Pp
527 The various
528 .Pa scr2*
529 utilities in the
530 .Pa graphics
531 and
532 .Pa textproc
533 categories of the
534 .Em "Ports Collection" .
535 .Sh AUTHORS
536 .An S\(/oren Schmidt Aq sos@FreeBSD.org
537 .An Sascha Wildner
538 .Sh CONTRIBUTORS
539 .An Maxim Sobolev Aq sobomax@FreeBSD.org ,
540 .An Nik Clayton Aq nik@FreeBSD.org