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 May 27, 2001 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 Ar number 40.Op Fl t Ar N | Cm off 41.Op Ar mode 42.Op Ar foreground Op Ar background 43.Op Cm show 44.Sh DESCRIPTION 45The 46.Nm 47command is used to set various options for the 48.Xr syscons 4 49console driver, 50such as video mode, colors, cursor shape, screen output map, font and screen 51saver timeout. 52.Pp 53The following command line options are supported: 54.Bl -tag -width indent 55.It Ar mode 56Select a new video mode. 57The modes currently recognized are: 58.Ar 80x25 , 59.Ar 80x30 , 60.Ar 80x43 , 61.Ar 80x50 , 62.Ar 80x60 , 63.Ar 132x25 , 64.Ar 132x30 , 65.Ar 132x43 , 66.Ar 132x50 , 67.Ar 132x60 , 68.Ar VGA_40x25 , 69.Ar VGA_80x25 , 70.Ar VGA_80x30 , 71.Ar VGA_80x50 , 72.Ar VGA_80x60 , 73.Ar VGA_90x25 , 74.Ar VGA_90x30 , 75.Ar VGA_90x43 , 76.Ar VGA_90x50 , 77.Ar VGA_90x60 , 78.Ar EGA_80x25 , 79.Ar EGA_80x43 , 80.Ar VESA_132x25 , 81.Ar VESA_132x43 , 82.Ar VESA_132x50 , 83.Ar VESA_132x60 . 84.\"The graphic mode 85.\".Ar VGA_320x200 86.\"and 87The raster text mode 88.Ar VESA_800x600 89can also be chosen. 90See 91.Sx Video Mode Support 92below. 93.It Ar foreground Op Ar background 94Change colors when displaying text. 95Specify the foreground color 96(e.g.\& 97.Dq vidcontrol white ) , 98or both a foreground and background colors 99(e.g.\& 100.Dq vidcontrol yellow blue ) . 101Use the 102.Cm show 103command below to see available colors. 104.It Cm show 105See the supported colors on a given platform. 106.It Fl b Ar color 107Set border color to 108.Ar color . 109This option may not be always supported by the video driver. 110.It Fl C 111Clear the history buffer. 112.It Fl c Cm normal | blink | destructive 113Change the cursor appearance. 114The cursor is either an inverting block 115.Pq Cm normal 116that can optionally 117.Cm blink , 118or it can be like the old hardware cursor 119.Pq Cm destructive . 120The latter is actually a simulation. 121.It Fl d 122Print out current output screen map. 123.It Xo 124.Fl f 125.Op Ar size 126.Ar file 127.Xc 128Load font 129.Ar file 130for 131.Ar size 132(currently, only 133.Cm 8x8 , 134.Cm 8x14 135or 136.Cm 8x16 ) . 137The font file can be either uuencoded or in raw binary format. 138You can also use the menu-driven 139.Xr vidfont 1 140command to load the font of your choice. 141.Pp 142.Ar Size 143may be omitted, in this case 144.Nm 145will try to guess it from the size of font file. 146.Pp 147Note that older video cards, such as MDA and CGA, do not support 148software font. 149See also 150.Sx Video Mode Support 151and 152.Sx EXAMPLES 153below and the man page for 154.Xr syscons 4 . 155.It Fl g Ar geometry 156Set the 157.Ar geometry 158of the text mode for the modes with selectable 159geometry. 160Currently only raster modes, such as 161.Ar VESA_800x600 , 162support this option. 163See also 164.Sx Video Mode Support 165and 166.Sx EXAMPLES 167below. 168.It Fl h Ar size 169Set the size of the history (scrollback) buffer to 170.Ar size 171lines. 172.It Fl i Cm adapter 173Shows info about the current video adapter. 174.It Fl i Cm mode 175Shows the possible video modes with the current video hardware. 176.It Fl l Ar screen_map 177Install screen output map file from 178.Ar screen_map . 179See also 180.Xr syscons 4 . 181.It Fl L 182Install default screen output map. 183.It Fl M Ar char 184Sets the base character used to render the mouse pointer to 185.Ar char . 186.It Fl m Cm on | off 187Switch the mouse pointer 188.Cm on 189or 190.Cm off . 191Used together with the 192.Xr moused 8 193daemon for text mode cut & paste functionality. 194.It Fl p 195Capture the current contents of the video buffer corresponding 196to the terminal device referred to by standard input. 197The 198.Nm 199utility writes contents of the video buffer to the standard 200output in a raw binary format. 201For details about that 202format see 203.Sx Format of Video Buffer Dump 204below. 205.It Fl P 206Same as 207.Fl p , 208but dump contents of the video buffer in a plain text format 209ignoring nonprintable characters and information about text 210attributes. 211.It Fl r Ar foreground background 212Change reverse mode colors to 213.Ar foreground 214and 215.Ar background . 216.It Fl s Ar number 217Set the current vty to 218.Ar number . 219.It Fl t Ar N | Cm off 220Set the screensaver timeout to 221.Ar N 222seconds, or turns it 223.Cm off . 224.It Fl x 225Use hexadecimal digits for output. 226.El 227.Ss Video Mode Support 228Note that not all modes listed above may be supported by the video 229hardware. 230You can verify which mode is supported by the video hardware, using the 231.Fl i Cm mode 232option. 233.Pp 234The VESA BIOS support must be linked to the kernel 235or loaded as a KLD module if you wish to use VESA video modes 236or 132 column modes 237(see 238.Xr vga 4 ) . 239.Pp 240You need to compile your kernel with the 241.Ar VGA_WIDTH90 242option if you wish to use VGA 90 column modes 243(see 244.Xr vga 4 ) . 245.Pp 246Video modes other than 25 and 30 line modes may require specific size of font. 247Use 248.Fl f 249option above to load a font file to the kernel. 250If the required size of font has not been loaded to the kernel, 251.Nm 252will fail if the user attempts to set a new video mode. 253.Pp 254.Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact 255.Sy Modes Ta Sy Font size 256.Li 25 line modes Ta 8x16 (VGA), 8x14 (EGA) 257.Li 30 line modes Ta 8x16 258.Li 43 line modes Ta 8x8 259.Li 50 line modes Ta 8x8 260.Li 60 line modes Ta 8x8 261.El 262.Pp 263It is better to always load all three sizes (8x8, 8x14 and 8x16) 264of the same font. 265.Pp 266You may set variables in 267.Pa /etc/rc.conf 268or 269.Pa /etc/rc.conf.local 270so that desired font files will be automatically loaded 271when the system starts up. 272See below. 273.Pp 274If you want to use the raster text mode 275.Ar VESA_800x600 , 276you need to recompile your kernel with the 277.Dv SC_PIXEL_MODE 278option. 279See 280.Xr syscons 4 281for more details on this kernel option. 282.Ss Format of Video Buffer Dump 283The 284.Nm 285utility uses the 286.Xr syscons 4 287.Dv CONS_SCRSHOT 288.Xr ioctl 2 289to capture the current contents of the video buffer. 290The 291.Nm 292utility writes version and additional information to the standard 293output, followed by the contents of the terminal device. 294.Pp 295VGA video memory is typically arranged in two byte tuples, 296one per character position. 297In each tuple, the first byte will be the character code, 298and the second byte is the character's color attribute. 299.Pp 300The VGA color attribute byte looks like this: 301.Pp 302.Bl -column "X:X" "<00000000>" "width" "bright foreground color" 303.Sy "bits# width meaning" 304.Li "7 <X0000000> 1 character blinking" 305.Li "6:4 <0XXX0000> 3 background color" 306.Li "3 <0000X000> 1 bright foreground color" 307.Li "2:0 <00000XXX> 3 foreground color" 308.El 309.Pp 310Here is a list of the three bit wide base colors: 311.Pp 312.Bl -hang -offset indent -compact 313.It 0 314Black 315.It 1 316Blue 317.It 2 318Green 319.It 3 320Cyan 321.It 4 322Red 323.It 5 324Magenta 325.It 6 326Brown 327.It 7 328Light Grey 329.El 330.Pp 331Base colors with bit 3 (the bright foreground flag) set: 332.Pp 333.Bl -hang -offset indent -compact 334.It 0 335Dark Grey 336.It 1 337Light Blue 338.It 2 339Light Green 340.It 3 341Light Cyan 342.It 4 343Light Red 344.It 5 345Light Magenta 346.It 6 347Yellow 348.It 7 349White 350.El 351.Pp 352For example, the two bytes 353.Pp 354.Dl "65 158" 355.Pp 356specify an uppercase A (character code 65), blinking 357(bit 7 set) in yellow (bits 3:0) on a blue background 358(bits 6:4). 359.Pp 360The 361.Nm 362output contains a small header which includes additional 363information which may be useful to utilities processing 364the output. 365.Pp 366The 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 374Subsequent 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 382So a dump of an 80x25 screen would start (in hex) 383.Bd -literal -offset indent 38453 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 394You may set the following variables in 395.Pa /etc/rc.conf 396or 397.Pa /etc/rc.conf.local 398in order to configure the video output at boot time. 399.Pp 400.Bl -tag -width foo_bar_var -compact 401.It Ar blanktime 402Sets the timeout value for the 403.Fl t 404option. 405.It Ar font8x16 , font8x14 , font8x8 406Specifies font files for the 407.Fl f 408option. 409.It Ar scrnmap 410Specifies a screen output map file for the 411.Fl l 412option. 413.El 414.Pp 415See 416.Xr rc.conf 5 417for more details. 418.Ss Driver Configuration 419The video card driver may let you change default configuration 420options, such as the default font, so that you do not need to set up 421the options at boot time. 422See video card driver manuals, (e.g.\& 423.Xr vga 4 ) 424for details. 425.Sh FILES 426.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact 427.It Pa /usr/share/syscons/fonts/* 428font files. 429.It Pa /usr/share/syscons/scrnmaps/* 430screen output map files. 431.El 432.Sh EXAMPLES 433If you want to load 434.Pa /usr/share/syscons/fonts/iso-8x16.fnt 435to the kernel, run 436.Nm 437as: 438.Pp 439.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt 440.Pp 441So long as the font file is in 442.Pa /usr/share/syscons/fonts , 443you may abbreviate the file name as 444.Pa iso-8x16 : 445.Pp 446.Dl vidcontrol -f 8x16 iso-8x16 447.Pp 448Furthermore, you can also omit font size 449.Dq Li 8x16 : 450.Pp 451.Dl vidcontrol -f iso-8x16 452.Pp 453Moreover, the suffix specifying the font size can be also omitted; in 454this case, 455.Nm 456will use the size of the currently displayed font to construct the 457suffix: 458.Pp 459.Dl vidcontrol -f iso 460.Pp 461Likewise, you can also abbreviate the screen output map file name for 462the 463.Fl l 464option 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 469The above command will load 470.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm . 471.Pp 472The following command will set-up a 100x37 raster text mode (useful for 473some LCD models): 474.Pp 475.Dl vidcontrol -g 100x37 VESA_800x600 476.Pp 477The following command will capture the contents of the first virtual 478terminal, and redirect the output to the 479.Pa shot.scr 480file: 481.Pp 482.Dl vidcontrol -p < /dev/ttyv0 > shot.scr 483.Pp 484The following command will dump contents of the fourth virtual terminal 485to 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 500The various 501.Li scr2* 502utilities in the 503.Li graphics 504and 505.Li textproc 506categories of the 507.Em "Ports Collection" . 508.Sh AUTHORS 509.An S\(/oren Schmidt Aq sos@FreeBSD.org 510.Sh CONTRIBUTORS 511.An Maxim Sobolev Aq sobomax@FreeBSD.org , 512.An Nik Clayton Aq nik@FreeBSD.org 513