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