usr.sbin/vidcontrol/vidcontrol.1

   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