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. 197.Nm 198writes contents of the video buffer to the standard 199output in a raw binary format. 200For details about that 201format see 202.Sx Format of Video Buffer Dump 203below. 204.It Fl P 205Same as 206.Fl p , 207but dump contents of the video buffer in a plain text format 208ignoring nonprintable characters and information about text 209attributes. 210.It Fl r Ar foreground background 211Change reverse mode colors to 212.Ar foreground 213and 214.Ar background . 215.It Fl s Ar number 216Set the current vty to 217.Ar number . 218.It Fl t Ar N | Cm off 219Set the screensaver timeout to 220.Ar N 221seconds, or turns it 222.Cm off . 223.It Fl x 224Use hexadecimal digits for output. 225.El 226.Ss Video Mode Support 227Note that not all modes listed above may be supported by the video 228hardware. 229You can verify which mode is supported by the video hardware, using the 230.Fl i Cm mode 231option. 232.Pp 233The VESA BIOS support must be linked to the kernel 234or loaded as a KLD module if you wish to use VESA video modes 235or 132 column modes 236(see 237.Xr vga 4 ) . 238.Pp 239You need to compile your kernel with the 240.Ar VGA_WIDTH90 241option if you wish to use VGA 90 column modes 242(see 243.Xr vga 4 ) . 244.Pp 245Video modes other than 25 and 30 line modes may require specific size of font. 246Use 247.Fl f 248option above to load a font file to the kernel. 249If the required size of font has not been loaded to the kernel, 250.Nm 251will fail if the user attempts to set a new video mode. 252.Pp 253.Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact 254.Sy Modes Ta Sy Font size 255.Li 25 line modes Ta 8x16 (VGA), 8x14 (EGA) 256.Li 30 line modes Ta 8x16 257.Li 43 line modes Ta 8x8 258.Li 50 line modes Ta 8x8 259.Li 60 line modes Ta 8x8 260.El 261.Pp 262It is better to always load all three sizes (8x8, 8x14 and 8x16) 263of the same font. 264.Pp 265You may set variables in 266.Pa /etc/rc.conf 267or 268.Pa /etc/rc.conf.local 269so that desired font files will be automatically loaded 270when the system starts up. 271See below. 272.Pp 273If you want to use the raster text mode 274.Ar VESA_800x600 , 275you need to recompile your kernel with the 276.Dv SC_PIXEL_MODE 277option. 278See 279.Xr syscons 4 280for more details on this kernel option. 281.Ss Format of Video Buffer Dump 282The 283.Nm 284utility uses the 285.Xr syscons 4 286.Dv CONS_SCRSHOT 287.Xr ioctl 2 288to capture the current contents of the video buffer. 289.Nm 290writes version and additional information to the standard 291output, followed by the contents of the terminal device. 292.Pp 293VGA video memory is typically arranged in two byte tuples, 294one per character position. 295In each tuple, the first byte will be the character code, 296and the second byte is the character's color attribute. 297.Pp 298The VGA color attribute byte looks like this: 299.Pp 300.Bl -column "X:X" "<00000000>" "width" "bright foreground color" 301.Sy "bits# width meaning" 302.Li "7 <X0000000> 1 character blinking" 303.Li "6:4 <0XXX0000> 3 background color" 304.Li "3 <0000X000> 1 bright foreground color" 305.Li "2:0 <00000XXX> 3 foreground color" 306.El 307.Pp 308Here is a list of the three bit wide base colors: 309.Pp 310.Bl -hang -offset indent -compact 311.It 0 312Black 313.It 1 314Blue 315.It 2 316Green 317.It 3 318Cyan 319.It 4 320Red 321.It 5 322Magenta 323.It 6 324Brown 325.It 7 326Light Grey 327.El 328.Pp 329Base colors with bit 3 (the bright foreground flag) set: 330.Pp 331.Bl -hang -offset indent -compact 332.It 0 333Dark Grey 334.It 1 335Light Blue 336.It 2 337Light Green 338.It 3 339Light Cyan 340.It 4 341Light Red 342.It 5 343Light Magenta 344.It 6 345Yellow 346.It 7 347White 348.El 349.Pp 350For example, the two bytes 351.Pp 352.Dl "65 158" 353.Pp 354specify an uppercase A (character code 65), blinking 355(bit 7 set) in yellow (bits 3:0) on a blue background 356(bits 6:4). 357.Pp 358The 359.Nm 360output contains a small header which includes additional 361information which may be useful to utilities processing 362the output. 363.Pp 364The first 10 bytes are always arranged as follows: 365.Bl -column "Byte range" "Contents" -offset indent 366.It Sy "Byte Range Contents" 367.It "1 thru 8 Literal text" Dq Li SCRSHOT_ 368.It "9 File format version number" 369.It "10 Remaining number of bytes in the header" 370.El 371.Pp 372Subsequent bytes depend on the version number. 373.Bl -column "Version" "13 and up" -offset indent 374.It Sy "Version Byte Meaning" 375.It "1 11 Terminal width, in characters" 376.It " 12 Terminal depth, in characters" 377.It " 13 and up The snapshot data" 378.El 379.Pp 380So a dump of an 80x25 screen would start (in hex) 381.Bd -literal -offset indent 38253 43 52 53 48 4f 54 5f 01 02 50 19 383----------------------- -- -- -- -- 384 | | | | ` 25 decimal 385 | | | `--- 80 decimal 386 | | `------ 2 remaining bytes of header data 387 | `--------- File format version 1 388 `------------------------ Literal "SCRSHOT_" 389.Ed 390.Sh VIDEO OUTPUT CONFIGURATION 391.Ss Boot Time Configuration 392You may set the following variables in 393.Pa /etc/rc.conf 394or 395.Pa /etc/rc.conf.local 396in order to configure the video output at boot time. 397.Pp 398.Bl -tag -width foo_bar_var -compact 399.It Ar blanktime 400Sets the timeout value for the 401.Fl t 402option. 403.It Ar font8x16 , font8x14 , font8x8 404Specifies font files for the 405.Fl f 406option. 407.It Ar scrnmap 408Specifies a screen output map file for the 409.Fl l 410option. 411.El 412.Pp 413See 414.Xr rc.conf 5 415for more details. 416.Ss Driver Configuration 417The video card driver may let you change default configuration 418options, such as the default font, so that you do not need to set up 419the options at boot time. 420See video card driver manuals, (e.g.\& 421.Xr vga 4 ) 422for details. 423.Sh FILES 424.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact 425.It Pa /usr/share/syscons/fonts/* 426font files. 427.It Pa /usr/share/syscons/scrnmaps/* 428screen output map files. 429.El 430.Sh EXAMPLES 431If you want to load 432.Pa /usr/share/syscons/fonts/iso-8x16.fnt 433to the kernel, run 434.Nm 435as: 436.Pp 437.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt 438.Pp 439So long as the font file is in 440.Pa /usr/share/syscons/fonts , 441you may abbreviate the file name as 442.Pa iso-8x16 : 443.Pp 444.Dl vidcontrol -f 8x16 iso-8x16 445.Pp 446Furthermore, you can also omit font size 447.Dq Li 8x16 : 448.Pp 449.Dl vidcontrol -f iso-8x16 450.Pp 451Likewise, you can also abbreviate the screen output map file name for 452the 453.Fl l 454option if the file is found in 455.Pa /usr/share/syscons/scrnmaps . 456.Pp 457.Dl vidcontrol -l iso-8859-1_to_cp437 458.Pp 459The above command will load 460.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm . 461.Pp 462The following command will set-up a 100x37 raster text mode (useful for 463some LCD models): 464.Pp 465.Dl vidcontrol -g 100x37 VESA_800x600 466.Pp 467The following command will capture the contents of the first virtual 468terminal, and redirect the output to the 469.Pa shot.scr 470file: 471.Pp 472.Dl vidcontrol -p < /dev/ttyv0 > shot.scr 473.Pp 474The following command will dump contents of the forth virtual terminal 475to the standard output in the human readable format: 476.Pp 477.Dl vidcontrol -P < /dev/ttyv3 478.Sh SEE ALSO 479.Xr kbdcontrol 1 , 480.Xr vidfont 1 , 481.Xr keyboard 4 , 482.Xr screen 4 , 483.Xr syscons 4 , 484.Xr vga 4 , 485.Xr rc.conf 5 , 486.Xr kldload 8 , 487.Xr moused 8 , 488.Xr watch 8 489.Pp 490The various 491.Li scr2* 492utilities in the 493.Li graphics 494and 495.Li textproc 496categories of the 497.Em "Ports Collection" . 498.Sh AUTHORS 499.An S\(/oren Schmidt Aq sos@FreeBSD.org 500.Sh CONTRIBUTORS 501.An Maxim Sobolev Aq sobomax@FreeBSD.org , 502.An Nik Clayton Aq nik@FreeBSD.org 503