2 .\" Copyright (c) 1992, 2000 Hellmuth Michaelis, Brian Dunford-Shore,
3 .\" Joerg Wunsch and Holger Veit.
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by Hellmuth Michaelis,
18 .\" Brian Dunford-Shore, Joerg Wunsch and Holger Veit.
19 .\" 4. The name authors may not be used to endorse or promote products
20 .\" derived from this software without specific prior written permission.
22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
23 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
24 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
25 .\" IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
27 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
31 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 .\" Last Edit-Date: [Sun Jan 9 09:43:04 2000]
35 .\" $FreeBSD: src/share/man/man4/pcvt.4,v 1.22.2.5 2002/03/19 18:24:07 schweikh Exp $
36 .\" $DragonFly: src/share/man/man4/Attic/pcvt.4,v 1.3 2004/03/11 12:28:55 hmp Exp $
38 .\" Man page pcvt(4) created after pcvt_ioctl.h on 13-Jan-93
47 .Nd PC console virtual screen system
49 .Cd "options ""PCVT_FREEBSD=version" | "PCVT_NETBSD=version"""
50 .Cd "options ""PCVT_NSCREENS=number"""
51 .Cd "options PCVT_XXXX" No ( see Sx Configuration No below )
53 .Cd "device vt0 at isa?"
58 driver provides a virtual screen system with several additional
59 features not available in historic console drivers.
60 Besides the ability of handling
61 multiple virtual screens,
62 the probably most important is an emulation of a wide range
68 for a detailed description.
72 driver requires the keyboard driver
74 to be also configured in the kernel.
86 Completely independent virtual terminals for MDA/HGC/CGA/EGA and VGA
88 25, 28, 35, 40, 43 or 50x80 screen resolution for each virtual screen
90 Fully remappable keyboard to support national keyboards
92 All VT220 character sets plus ISO Latin-1 and DEC technical supported
94 VT220 downloadable character set supported when run on EGA/VGA
96 VT220 user defined keys for each virtual terminal
98 Optional function key label support
99 \('a la Hewlett-Packard
101 Display function codes functionality
103 Support for MDA, CGA, EGA and VGA display adaptors
105 Support for 132 column operation on VGA chipsets
107 X Window Support for XFree86 >= 1.2 using the pccons model, or
108 for XFree86 >= 2.0 using the syscons model
111 .Em PCVT_USL_VT_COMPAT
120 No double wide/high characters
124 No inverse background
126 No VT220 printer output support
128 No VT52 support at all
132 Only limited AT-keyboard
137 Help you to make money...
142 virtual terminal now has 8 pages of memory attached which are used as a
143 scrollback buffer (definition of SCROLLBACK_PAGES).
149 it is possible to scroll the screen back and forward.
154 users: for the purposes of the following documentation, pretend you're
155 using a FreeBSD system, pending possible implemention changes.
159 console driver is currently available for the Intel-based BSD operating
162 (release 0.9 or higher),
165 (release 1.0-GAMMA or higher) .
166 In order to get the appropriate system support, one of the options
170 must be defined in the system's config file
171 .Pq see Xr config 8 .
176 operating systems, it is necessary to set this option to the operating
177 system's version number.
180 this version number must be expressed as a 3-digit number.
181 E.\& g., if you are running the 1.0 release
182 .Pq which is actually version 1.0.2 ,
185 .Em PCVT_FREEBSD = 102
189 this version number must be expressed as 9 if you are running
191 and anything greater than 9 for NetBSD-current (pre 1.0). It is recommended
198 E.g., if you are running the
200 release, you should define
202 .Em PCVT_NETBSD = 100
206 driver has been designed to be highly configurable in order to satisfy
208 The preferred way for those configurations is to
211 lines within the config file, possibly overriding the built-in default
213 Therefore it is possible to compile several distinct kernels
214 with different driver behaviour on a single machine.
216 The following list gives a short overview of the available configuration
219 .Pa i386/isa/pcvt/pcvt_hdr.h
220 in the kernel source tree for detailed documentation.
222 Note: the following conventions apply to all the Boolean options.
223 If an option is given with no value, a value of 1
226 If an option value is given as 0, this options is
228 Any other value is substituted by 1, too.
230 is omitted, a built-in default is assumed.
231 .Bl -tag -width indent
233 Defines the number of virtual screens.
236 .It Em PCVT_VT220KEYB
237 If activated, a keyboard layout resembling a DEC VT200 (TM) is generated.
238 If deactivated, a mixture between VT220 and HP is used.
245 documentation directory for a full description.
248 .It Em PCVT_SCREENSAVER
249 Enables the builtin screensaver feature.
252 .It Em PCVT_PRETTYSCRNS
253 If enabled, a blinking-star screensaver is used.
254 If disabled, the screen
256 .Pq which might be useful for energy-saving monitors .
259 .It Em PCVT_CTRL_ALT_DEL
260 If enabled, the key combination
267 .It Em PCVT_USEKBDSEC
268 Do NOT override a security lock for the keyboard.
271 .It Em PCVT_24LINESDEF
272 If enabled, the 25-line modi
274 VT emulation with 25 lines, and HP emulation with 28 lines
276 default to 24 lines only to provide a better compatibility to the
277 original DEV VT220 (TM). Thus it should be possible to use the
278 terminal information for those terminals without further changes.
279 Note that this is a startup option; it is possible to toggle between
280 the 24- and 25-lines' display by the
285 .It Em PCVT_EMU_MOUSE
286 Emulate a three-button mouse via the keypad.
287 Useful for notebooks when
295 If enabled, a sequence composed of
297 followed by the normal key code is emitted if a key is pressed with the
300 If disabled, then normal key code with the value
307 Note that there are further options available which are mainly used for
308 debugging purposes or as a workaround for hardware problems.
311 .Pa i386/isa/pcvt/pcvt_hdr.h
312 along with their documentation.
313 .Ss Internal Functions
314 The functionality described below may be accessed via
316 system calls with a file descriptor opened on a device node
320 To make use of them, a program should contain the following line:
322 .Dl #include <machine/pcvt_ioctl.h>
324 Any parameter definitions cited below can be found in that file.
326 .Em Keyboard related functions
328 Three functions are related to basic keyboard hardware:
330 .Bl -tag -width 20n -offset indent -compact
332 reset keyboard, set defaults;
334 get current typematic value, parameter is a pointer to int where
335 the values is stored to;
337 set current typematic value, similar to above command.
340 Symbolic values are available for the appropriate constants.
341 To specify the initial typematic delay time, they are
342 KBD_TPD250 for 250 ms through
343 KBD_TPD1000 for 1000 ms, in steps of 250 ms.
346 KBD_TPM300, specifying 30.0 characters per second through
347 KBD_TPM20 for 2.0 characters per second.
348 The intermediate values
349 are: 30.0, 26.7, 24.0, 21.8, 20.0, 18.5, 17.1, 16.0, 15.0, 13.3,
350 12.0, 10.9, 10.0, 9.2, 8.6, 8.0, 7.5, 6.7, 6.0, 5.5, 5.0, 4.6, 4.3,
351 4.0, 3.7, 3.3, 3.0, 2.7, 2.5, 2.3, 2.1, 2.0 characters per second.
353 .Bl -tag -width 20n -offset indent -compact
355 get key repetition switch, and
357 set key repetition switch
360 again take a pointer to int as argument.
362 drivers internal keyboard repetition flag, possible values are:
363 KBD_REPEATOFF or KBD_REPEATON.
365 .Bl -tag -width 20n -offset indent -compact
369 set LED state manipulate the keyboard indicators, but do not influence
370 the drivers idea of lock key state.
373 The int where the argument points to
375 KBD_SCROLLLOCK, KBD_NUMLOCK, KBD_CAPSLOCK, which may be used in any
378 .Bl -tag -width 20n -offset indent -compact
380 gets state of SCROLL,NUM,CAPS, and
382 sets state of SCROLL,NUM,CAPS + LEDs
385 should be used in a same manner to get/set the drivers internal
388 .Em Keyboard remapping
390 One important feature of the
392 driver is its ability to overload the built in key definition.
394 .Bl -tag -width 20n -offset indent -compact
396 get current key values,
398 set new key assignment values, and
400 get original key assignment values
403 arrange those functions.
404 The take a pointer to a
405 .Em struct kbd_ovlkey
406 as argument as described below.
409 .Bl -tag -width 20n -offset indent -compact
411 removes a key assignment, taking a pointer to an int as argument which
412 contains the affected key number;
414 removes all key assignments.
417 struct kbd_ovlkey /* complete definition of a key */
419 u_short keynum; /* the key itself */
420 u_short type; /* type of key, see below */
421 u_char subu; /* subtype, ignored on write */
422 char unshift[KBDMAXOVLKEYSIZE+1]; /* emitted string, unshifted */
423 u_char subs; /* subtype, ignored on write */
424 char shift[KBDMAXOVLKEYSIZE+1]; /* emitted string, shifted */
425 u_char subc; /* subtype, ignored on write */
426 char ctrl[KBDMAXOVLKEYSIZE+1]; /* emitted string, control */
427 u_char suba; /* subtype, ignored on write */
428 char altgr[KBDMAXOVLKEYSIZE+1]; /* emitted string, altgr */
432 The appropriate values for the
436 .Bl -tag -width 20n -offset indent -compact
438 no function, key is disabled,
442 alternate shift, sets bit8 to ASCII code,
444 numeric shift, keypad numeric / application mode,
446 control code generation,
448 caps shift - swaps case of letter,
450 ASCII code generating key,
460 AltGr translation feature,
474 field contains one of the values
476 .Bl -tag -width 20n -offset indent -compact
478 key is bound to a string, or
480 key is bound to a function.
487 fakes a three-button mouse using the Mouse Systems protocol.
490 device node not used by a virtual screen is the mouse device.
492 for the default value of 8 virtual screens,
496 would refer to the virtual screens, and
498 were the mouse emulator device.
499 The mouse emulation is turned on by
503 The pointer is moved by the numerical keypad keys, into the
505 The pointer is initially moved in single steps,
506 and is accelerated after an adjustable time
509 The mouse buttons are emulated by three normal
510 keys, by default the function keys
515 There are two selectable flavors available: normal and
518 Normal buttons behave as expected.
520 buttons are notified as button-press on the first keypress.
523 until the key is pressed again
524 .Pq or another button-emulating key instead .
525 Button presses and releases are notified to the user by a simple
529 respectively, generated from the PC's built-in speaker.
531 The following commands control the emulation.
533 .Bl -tag -width 20n -offset indent -compact
535 get the current definitions, and
541 .Li struct mousedefs *
542 as the third argument to the ioctl call:
545 int leftbutton; /* (PC) scan code for "left button" key */
546 int middlebutton; /* (PC) scan code for "mid button" key */
547 int rightbutton; /* (PC) scan code for "right button" key */
548 int stickybuttons; /* if true, the buttons are "sticky" */
549 int acceltime; /* timeout in microseconds to start pointer */
550 /* movement acceleration */
551 /* defaults to: scan(F1), scan(F2), scan(F3), false, 500000 */
555 .Em Downloadable character set interface
557 EGA and VGA video adaptors provide the capability of downloadable
560 .Sq native character set
561 of any IBM-compatible PC video board does not allow the full interpretation
562 of DEC multinational character set or ISO Latin-1
564 this might be very useful for a U**X environment.
566 .Bl -tag -width 20n -offset indent -compact
573 are used to manipulate the drivers information about a downloaded
575 The take a pointer to a
576 .Em struct vgafontattr
580 int character_set; /* VGA character set */
581 int font_loaded; /* Mark font loaded or unloaded */
582 int screen_size; /* Character rows per screen */
583 int character_scanlines; /* Scanlines per character - 1 */
584 int screen_scanlines; /* Scanlines per screen - 1 byte */
588 Each character of each font is to be downloaded with
590 .Bl -tag -width 20n -offset indent -compact
596 .Em struct vgaloadchar
600 int character_set; /* VGA character set to load into */
601 int character; /* Character to load */
602 int character_scanlines; /* Scanlines per character */
603 u_char char_table[32]; /* VGA character shape table */
610 CH_SET0, CH_SET1, CH_SET2, CH_SET3 on EGA's or VGA's. Since VGA's
611 might have up to eight simultaneously loaded fonts, they can take
612 CH_SET4, CH_SET5, CH_SET6, or CH_SET7, too.
614 Note that there's a dependence between the font size
615 and a possible screen height
616 .Pq in character rows ,
617 depending on the video adaptor used:
619 Screen size (rows) on: EGA VGA
629 .Em General screen manipulation commands
631 .Bl -tag -width 20n -offset indent -compact
636 taking a pointer to the following structure as argument:
639 int screen_no; /* screen number for which to set, */
640 /* or -1 to set on current active screen */
641 int start; /* top scanline, range 0... Character Height - 1 */
642 int end; /* end scanline, range 0... Character Height - 1 */
646 .Bl -tag -width 20n -offset indent -compact
653 provide an interface to some general driver internal variables
654 which might modify the behaviour of the screens,
655 or which might simply be used to force the driver to switch
656 to one certain screen.
657 Their argument is a pointer to the structure:
660 int adaptor_type; /* type of video adaptor installed */
661 /* read only, ignored on write (yet!) */
662 int totalfonts; /* no of downloadable fonts */
663 /* read only, ignored on write */
664 int totalscreens; /* no of virtual screens */
665 /* read only, ignored on write */
666 int screen_no; /* screen number, this was got from */
667 /* on write, if -1, apply pure_vt_mode */
668 /* and/or screen_size to current screen*/
669 /* else to screen_no supplied */
670 int current_screen; /* screen number, which is displayed. */
671 /* on write, if -1, make this screen */
672 /* the current screen, else set current*/
673 /* displayed screen to parameter */
674 int pure_vt_mode; /* flag, pure VT mode or HP/VT mode */
675 /* on write, if -1, no change */
676 int screen_size; /* screen size */
677 /* on write, if -1, no change */
678 int force_24lines; /* force 24 lines if 25 lines VT mode */
679 /* or 28 lines HP mode to get pure */
680 /* VT220 screen size */
681 /* on write, if -1, no change */
682 int vga_family; /* if adaptor_type = VGA, this reflects*/
683 /* the chipset family after a read */
684 /* nothing happens on write ... */
685 int vga_type; /* if adaptor_type = VGA, this reflects*/
686 /* the chipset after a read */
687 /* nothing happenes on write ... */
688 int vga_132; /* set to 1 if driver has support for */
689 /* 132 column operation for chipset */
690 /* currently ignored on write */
696 may take the values M_HPVT for a mixed VTxxx and HP Mode, with function
697 key labels and a status line, or M_PUREVT for only VTxxx sequences
698 recognized, with no labels.
700 .Bl -tag -width 20n -offset indent -compact
702 sets the number of columns for the current screen,
705 its parameter is a pointer to an integer containing either a value of 80,
707 Note that setting the number of columns to 132 is
708 only supported on VGA adaptors.
709 Any unsupported numbers cause the ioctl
716 .Em VGA color palette interface
718 Only on VGA adaptors, there's a color palette register at the output.
719 It is responsible for the red, green and blue output voltage provided
720 for each of the 256 internal color codes, each lying in the range of
721 0 through 63 (with 63 representing the brightest value for a base color).
722 Thus, these adaptors map each color code to a color of a
724 out of 262144 colors.
727 .Bl -tag -width 20n -offset indent -compact
729 read VGA palette entry, and
731 write VGA palette entry
734 establish an interface to these palette registers.
739 unsigned idx; /* index into palette, 0 .. 255 valid */
740 unsigned r, g, b; /* RGB values, masked by VGA_PMASK (63) */
744 .Em Driver identification
746 .Bl -tag -width 20n -offset indent -compact
748 returns information if the current compiled in driver is pcvt and it's
749 major and minor revision numbers. the call is taking a pointer to the
750 following structure as argument:
754 #define PCVTIDNAMELN 16 /* driver id - string length */
755 char name[PCVTIDNAMELN]; /* driver name, == PCVTIDSTR */
756 #define PCVTIDNAME "pcvt" /* driver id - string */
757 int rmajor; /* revision number, major */
758 #define PCVTIDMAJOR 3
759 int rminor; /* revision number, minor */
760 #define PCVTIDMINOR 00
764 .Bl -tag -width 20n -offset indent -compact
766 returns information if the current compiled in driver is pcvt and it's
767 compile time options. the call is taking a pointer to the following
768 structure as argument:
772 u_int opsys; /* PCVT_xxx(x)BSD */
773 #define CONF_UNKNOWNOPSYS 0
774 #define CONF_386BSD 1 /* unsupported !!! */
775 #define CONF_NETBSD 2
776 #define CONF_FREEBSD 3
777 u_int opsysrel; /* Release for NetBSD/FreeBSD */
778 u_int nscreens; /* PCVT_NSCREENS */
779 u_int scanset; /* PCVT_SCANSET */
780 u_int updatefast; /* PCVT_UPDATEFAST */
781 u_int updateslow; /* PCVT_UPDATESLOW */
782 u_int sysbeepf; /* PCVT_SYSBEEPF */
783 u_int pcburst; /* PCVT_PCBURST */
784 u_int kbd_fifo_sz; /* PCVT_KBD_FIFO_SZ */
786 /* config booleans */
788 u_long compile_opts; /* PCVT_xxxxxxxxxxxxxxx */
794 Depending on the configuration of a
796 driver, their might be a simple screen saver available.
800 .Bl -tag -width 20n -offset indent -compact
802 set timeout for screen saver in seconds; 0 turns it off,
805 taking a pointer to an integer as argument.
806 Despite of its command name,
809 kind of adaptor if configured in by the
814 .Em Compatibility commands for USL-style VT's
818 driver supports a subset of the USL-style commands used to control
819 the virtual terminal interface.
820 This feature is mainly intended to
823 release 2.0 or higher, to switch between virtual screens even when
825 They are ugly with respect to the implied semantics
826 (i.e., they break Berkeley semantics)
827 and are therefore not recommended for common use.
829 .Pa i386/include/pcvt_ioctl.h
830 for their documentation.
832 .Bl -tag -width /usr/include/machine/pcvt_ioctl.h
833 .It Pa /usr/include/machine/pcvt_ioctl.h
839 Device nodes to access the
842 .It Pa i386/isa/pcvt/pcvt_hdr.h
843 .Pq relative to the kernel source tree
844 Documents the various compile-time options to tailor
850 driver has been developed for and contributed to 386BSD release 0.1. Since
851 release 3.00 explicit support is provided for NetBSD 0.9. It is expected
852 that no further development on pcvt is done for 386BSD 0.1 after release 3.00,
853 in fact, 386BSD support was dropped with release 3.20.
857 .An Hellmuth Michaelis Aq hm@hcs.de
859 .An Brian Dunford-Shore Aq brian@morpheus.wustl.edu
861 .An J\(:org Wunsch Aq joerg_wunsch@uriah.sax.de .
863 This driver is based on several people's previous
865 .An William Jolitz' Aq ljolitz@cardio.ucsf.edu
872 .An Holger Veit Aq veit@first.gmd.de
888 in the Documentation directory for an up-to-date list.
889 .Ss Tested Video Boards
891 Manufacturer Chipset Monitor
893 2theMax (?) ET4000 VGA Color
894 Video7 Inc. Video 7 VGA Color
895 Diamond Stealth VRAM S3 NEC 3FGx
896 Trident TVGA 8800CS NEC 3D
897 Data General C&T P82C604 VGA Color
898 NoName Hercules W86855AF Mono
899 Kyocera (Mainboard) WD90C11 Sony Color
900 unknown ET3000 NEC 3D
904 Manufacturer Type Layout
907 Cherry/Tandon MF II German
908 Hewlett-Packard MF II US
909 Hewlett-Packard MF II German
913 There is absolutely NO support for the ancient PC-keyboards
914 .Pq they had 83 keys .
916 There is only limited support for AT-keyboards
918 they have 84 keys, and a separate numeric keypad,
919 they don't have F11/F12 keys
921 because the emulator needs F9 through F12 for control functions, and due to
922 the current design of the keyboard driver there is no
924 support for national keyboards because
925 of the lack of an ALtGr key.
927 MF-keyboards are fully supported, 101- and 102-key versions.