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