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.Bl -column "X:X" "<00000000>" "width" "bright foreground color" 331.Sy "bits# width meaning" 332.Li "7 <X0000000> 1 character blinking" 333.Li "6:4 <0XXX0000> 3 background color" 334.Li "3 <0000X000> 1 bright foreground color" 335.Li "2:0 <00000XXX> 3 foreground color" 336.El 337.Pp 338Here is a list of the three bit wide base colors: 339.Pp 340.Bl -hang -offset indent -compact 341.It 0 342Black 343.It 1 344Blue 345.It 2 346Green 347.It 3 348Cyan 349.It 4 350Red 351.It 5 352Magenta 353.It 6 354Brown 355.It 7 356Light Grey 357.El 358.Pp 359Base colors with bit 3 (the bright foreground flag) set: 360.Pp 361.Bl -hang -offset indent -compact 362.It 0 363Dark Grey 364.It 1 365Light Blue 366.It 2 367Light Green 368.It 3 369Light Cyan 370.It 4 371Light Red 372.It 5 373Light Magenta 374.It 6 375Yellow 376.It 7 377White 378.El 379.Pp 380For example, the two bytes 381.Pp 382.Dl "65 158" 383.Pp 384specify an uppercase A (character code 65), blinking 385(bit 7 set) in yellow (bits 3:0) on a blue background 386(bits 6:4). 387.Pp 388The 389.Nm 390output contains a small header which includes additional 391information which may be useful to utilities processing 392the output. 393.Pp 394The first 10 bytes are always arranged as follows: 395.Bl -column "Byte range" "Contents" -offset indent 396.It Sy "Byte Range Contents" 397.It "1 thru 8 Literal text" Dq Li SCRSHOT_ 398.It "9 File format version number" 399.It "10 Remaining number of bytes in the header" 400.El 401.Pp 402Subsequent bytes depend on the version number. 403.Bl -column "Version" "13 and up" -offset indent 404.It Sy "Version Byte Meaning" 405.It "1 11 Terminal width, in characters" 406.It " 12 Terminal depth, in characters" 407.It " 13 and up The snapshot data" 408.El 409.Pp 410So a dump of an 80x25 screen would start (in hex) 411.Bd -literal -offset indent 41253 43 52 53 48 4f 54 5f 01 02 50 19 413----------------------- -- -- -- -- 414 | | | | ` 25 decimal 415 | | | `--- 80 decimal 416 | | `------ 2 remaining bytes of header data 417 | `--------- File format version 1 418 `------------------------ Literal "SCRSHOT_" 419.Ed 420.Sh VIDEO OUTPUT CONFIGURATION 421.Ss Boot Time Configuration 422You may set the following variables in 423.Pa /etc/rc.conf 424or 425.Pa /etc/rc.conf.local 426in order to configure the video output at boot time. 427.Pp 428.Bl -tag -width foo_bar_var -compact 429.It Ar blanktime 430Sets the timeout value for the 431.Fl t 432option. 433.It Ar font8x16 , font8x14 , font8x8 434Specifies font files for the 435.Fl f 436option. 437.It Ar scrnmap 438Specifies a screen output map file for the 439.Fl l 440option. 441.El 442.Pp 443See 444.Xr rc.conf 5 445for more details. 446.Ss Driver Configuration 447The video card driver may let you change default configuration 448options, such as the default font, so that you do not need to set up 449the options at boot time. 450See video card driver manuals, (e.g.\& 451.Xr vga 4 ) 452for details. 453.Sh FILES 454.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact 455.It Pa /usr/share/syscons/fonts/* 456font files. 457.It Pa /usr/share/syscons/scrnmaps/* 458screen output map files. 459.El 460.Sh EXAMPLES 461If you want to load 462.Pa /usr/share/syscons/fonts/iso-8x16.fnt 463to the kernel, run 464.Nm 465as: 466.Pp 467.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt 468.Pp 469So long as the font file is in 470.Pa /usr/share/syscons/fonts , 471you may abbreviate the file name as 472.Pa iso-8x16 : 473.Pp 474.Dl vidcontrol -f 8x16 iso-8x16 475.Pp 476Furthermore, you can also omit font size 477.Dq Li 8x16 : 478.Pp 479.Dl vidcontrol -f iso-8x16 480.Pp 481Moreover, the suffix specifying the font size can be also omitted; in 482this case, 483.Nm 484will use the size of the currently displayed font to construct the 485suffix: 486.Pp 487.Dl vidcontrol -f iso 488.Pp 489Likewise, you can also abbreviate the screen output map file name for 490the 491.Fl l 492option if the file is found in 493.Pa /usr/share/syscons/scrnmaps . 494.Pp 495.Dl vidcontrol -l iso-8859-1_to_cp437 496.Pp 497The above command will load 498.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm . 499.Pp 500The following command will set-up a 100x37 raster text mode (useful for 501some LCD models): 502.Pp 503.Dl vidcontrol -g 100x37 VESA_800x600 504.Pp 505The following command will capture the contents of the first virtual 506terminal video buffer, and redirect the output to the 507.Pa shot.scr 508file: 509.Pp 510.Dl vidcontrol -p < /dev/ttyv0 > shot.scr 511.Pp 512The following command will dump contents of the fourth virtual terminal 513video buffer 514to the standard output in the human readable format: 515.Pp 516.Dl vidcontrol -P < /dev/ttyv3 517.Sh SEE ALSO 518.Xr kbdcontrol 1 , 519.Xr vidfont 1 , 520.Xr keyboard 4 , 521.Xr screen 4 , 522.Xr syscons 4 , 523.Xr vga 4 , 524.Xr rc.conf 5 , 525.Xr kldload 8 , 526.Xr moused 8 , 527.Xr watch 8 528.Pp 529The various 530.Pa scr2* 531utilities in the 532.Pa graphics 533and 534.Pa textproc 535categories of the 536.Em "Ports Collection" . 537.Sh AUTHORS 538.An S\(/oren Schmidt Aq sos@FreeBSD.org 539.An Sascha Wildner 540.Sh CONTRIBUTORS 541.An Maxim Sobolev Aq sobomax@FreeBSD.org , 542.An Nik Clayton Aq nik@FreeBSD.org 543