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