PCVT(4)

NAME
pcvt, vt - PC console virtual screen system

SYNOPSIS
options “ PCVT_FREEBSD = version | PCVT_NETBSD = version ”
[options “PCVT_NSCREENS = number”]
[options “PCVT_XXXX”] ( see Configuration below)

device vt0 at isa? port “IO_KBD” tty irq 1 vector pcrint

DESCRIPTION

  Overview
The pcvt driver provides a virtual screen system with several additional features not available in historic console drivers. Besides the ability of handling multiple virtual screens, the probably most important is an emulation of a wide range of DEC VT-220 (TM) functionality. See Features for a detailed description.

  Features

•   Almost full DEC VT220 (TM) functionality ( moving towards VT320 (TM))

•   Completely independent virtual terminals for MDA/HGC/CGA/EGA and VGA

•   25, 28, 35, 40, 43 or 50x80 screen resolution for each virtual screen

•   Fully remappable keyboard to support national keyboards

•   All VT220 character sets plus ISO Latin-1 and DEC technical supported

•   VT220 downloadable character set supported when run on EGA/VGA

•   VT220 user defined keys for each virtual terminal

•   Optional function key label support la Hewlett-Packard

•   Display function codes functionality

•   Support for MDA, CGA, EGA and VGA display adaptors

•   Support for 132 column operation on VGA chipsets

•   X Window Support for XFree86 >= 1.2 using the pccons model, or for XFree86 >= 2.0 using the syscons model ( requires PCVT_USL_VT_COMPAT to be configured)
What it cannot:

•   No double wide/high characters

•   No softscroll

•   No inverse background

•   No VT220 printer output support

•   No VT52 support at all

•   No 8-bit controls

•   Only limited AT-keyboard (84 keys) support (yet)

•   Help you to make money...

  Configuration
The pcvt console driver is currently available for the Intel-based BSD operating systems NetBSD/i386 (release 0.9 or higher), and FreeBSD (release 1.0-GAMMA or higher) . In order to get the appropriate system support, one of the options PCVT_NETBSD, or PCVT_FREEBSD must be defined in the system's config file (see config(8)). In addition, for the FreeBSD and NetBSD operating systems, it is necessary to set this option to the operating system's version number. For FreeBSD this version number must be expressed as a 3-digit number. E. g., if you are running the 1.0 release (which is actually version 1.0.2), you should define PCVT_FREEBSD = 102 For NetBSD this version number must be expressed as 9 if you are running NetBSD 0.9 and anything greater than 9 for NetBSD-current (pre 1.0). It is recommended to use (as with FreeBSD) 100 for NetBSD 1.0 and 999 for NetBSD-current. E.g., if you are running the NetBSD 1.0 release, you should define PCVT_NETBSD = 100 The pcvt driver has been designed to be highly configurable in order to satisfy everyone's needs. The preferred way for those configurations is to provide appropriate options lines within the config file, possibly overriding the built-in default values. Therefore it is possible to compile several distinct kernels with different driver behaviour on a single machine. The following list gives a short overview of the available configuration options. Refer to the file i386/isa/pcvt/pcvt_hdr.h in the kernel source tree for detailed documentation. Note: the following conventions apply to all the Boolean options. If an option is given with no value, a value of 1 (activated) is substituted. If an option value is given as 0, this options is deactivated. Any other value is substituted by 1, too. If an option is omitted, a built-in default is assumed.
PCVT_NSCREENS
    Defines the number of virtual screens.
    Default: 8
PCVT_VT220KEYB
    If activated, a keyboard layout resembling a DEC VT200 (TM) is generated. If deactivated, a mixture between VT220 and HP is used. See the files Keyboard.VT and Keyboard.HP in the pcvt documentation directory for a full description.
    Default: off
PCVT_SCREENSAVER
    Enables the builtin screensaver feature.
    Default: on
PCVT_PRETTYSCRNS
    If enabled, a blinking-star screensaver is used. If disabled, the screen is simply blanked (which might be useful for energy-saving monitors).
    Default: on
PCVT_CTRL_ALT_DEL
    If enabled, the key combination <Ctrl> <Alt> <Del> invokes a CPU reset.
    Default: off
PCVT_USEKBDSEC
    Do NOT override a security lock for the keyboard.
    Default: on
PCVT_24LINESDEF
    If enabled, the 25-line modi ( VT emulation with 25 lines, and HP emulation with 28 lines) default to 24 lines only to provide a better compatibility to the original DEV VT220 (TM). Thus it should be possible to use the terminal information for those terminals without further changes. Note that this is a startup option; it is possible to toggle between the 24- and 25-lines' display by the scon(1) utility.
    Default: off
PCVT_EMU_MOUSE
    Emulate a three-button mouse via the keypad. Useful for notebooks when running XFree86. See Mouse emulation below.
    Default: off
PCVT_META_ESC
    If enabled, a sequence composed of <esc>, followed by the normal key code is emitted if a key is pressed with the <Alt> key modifier. If disabled, then normal key code with the value 0x80 added is sent.
    Default: off
Note that there are further options available which are mainly used for debugging purposes or as a workaround for hardware problems. They are found in i386/isa/pcvt/pcvt_hdr.h along with their documentation.

  Internal Functions
The functionality described below may be accessed via ioctl(2) system calls with a file descriptor opened on a device node related to the pcvt driver. To make use of them, a program should contain the following line:
    #include <machine/pcvt_ioctl.h>
Any parameter definitions cited below can be found in that file. Keyboard related functions Three functions are related to basic keyboard hardware:
KBDRESET
    reset keyboard, set defaults;
KBDGTPMAT
    get current typematic value, parameter is a pointer to int where the values is stored to;
KBDSTPMAT
    set current typematic value, similar to above command.
Symbolic values are available for the appropriate constants. To specify the initial typematic delay time, they are KBD_TPD250 for 250 ms through KBD_TPD1000 for 1000 ms, in steps of 250 ms. The typematic repeat rates are KBD_TPM300, specifying 30.0 characters per second through KBD_TPM20 for 2.0 characters per second. The intermediate values are: 30.0, 26.7, 24.0, 21.8, 20.0, 18.5, 17.1, 16.0, 15.0, 13.3, 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, 4.0, 3.7, 3.3, 3.0, 2.7, 2.5, 2.3, 2.1, 2.0 characters per second.
KBDGREPSW
    get key repetition switch, and
KBDSREPSW
    set key repetition switch
again take a pointer to int as argument. They manipulate the drivers internal keyboard repetition flag, possible values are: KBD_REPEATOFF or KBD_REPEATON.
KBDGLEDS
    get LED state, and
KBDSLEDS
    set LED state manipulate the keyboard indicators, but do not influence the drivers idea of lock key state.
The int where the argument points to may have the values KBD_SCROLLLOCK, KBD_NUMLOCK, KBD_CAPSLOCK, which may be used in any conjunction.
KBDGLOCK
    gets state of SCROLL,NUM,CAPS, and
KBDSLOCK
    sets state of SCROLL,NUM,CAPS + LEDs
should be used in a same manner to get/set the drivers internal LED flags. Keyboard remapping One important feature of the pcvt driver is its ability to overload the built in key definition.
KBDGCKEY
    get current key values,
KBDSCKEY
    set new key assignment values, and
KBDGOKEY
    get original key assignment values
arrange those functions. The take a pointer to a struct kbd_ovlkey as argument as described below. In addition,
KBDRMKEY
    removes a key assignment, taking a pointer to an int as argument which contains the affected key number;
KBDDEFAULT
    removes all key assignments.

    struct kbd_ovlkey                /* complete definition of a key */
    {
        u_short keynum;                      /* the key itself */
        u_short type;                        /* type of key, see below */
        u_char  subu;                        /* subtype, ignored on write */
        char    unshift[KBDMAXOVLKEYSIZE+1]; /* emitted string, unshifted */
        u_char  subs;                        /* subtype, ignored on write */
        char    shift[KBDMAXOVLKEYSIZE+1];   /* emitted string, shifted */
        u_char  subc;                        /* subtype, ignored on write */
        char    ctrl[KBDMAXOVLKEYSIZE+1];    /* emitted string, control */
        u_char  suba;                        /* subtype, ignored on write */
        char    altgr[KBDMAXOVLKEYSIZE+1];   /* emitted string, altgr */
    };

The appropriate values for the type field are:
KBD_NONE
    no function, key is disabled,
KBD_SHIFT
    keyboard shift,
KBD_META
    alternate shift, sets bit8 to ASCII code,
KBD_NUM
    numeric shift, keypad numeric / application mode,
KBD_CTL
    control code generation,
KBD_CAPS
    caps shift - swaps case of letter,
KBD_ASCII
    ASCII code generating key,
KBD_SCROLL
    stop output,
KBD_FUNC
    function key,
KBD_KP
    keypad keys,
KBD_BREAK
    ignored,
KBD_ALTGR
    AltGr translation feature,
KBD_SHFTLOCK
    shift lock,
KBD_CURSOR
    cursor keys, and
KBD_RETURN
    “Return” or “Enter” keys.
The subtype field contains one of the values
KBD_SUBT_STR
    key is bound to a string, or
KBD_SUBT_FNC
    key is bound to a function.
Mouse emulation The mouse emulator (if configured in) fakes a three-button mouse using the Mouse Systems protocol. The first pcvt device node not used by a virtual screen is the mouse device. I. e., for the default value of 8 virtual screens, /dev/ttyv0 through /dev/ttyv7 would refer to the virtual screens, and /dev/ttyv8 were the mouse emulator device. The mouse emulation is turned on by pressing the <NumLock> key. The pointer is moved by the numerical keypad keys, into the obvious directions. The pointer is initially moved in single steps, and is accelerated after an adjustable time (default: 500 ms) by about 6 times. The mouse buttons are emulated by three normal keys, by default the function keys <F1>, <F2>, and <F3>. There are two selectable flavors available: normal and “sticky” buttons. Normal buttons behave as expected. “Sticky” buttons are notified as button-press on the first keypress. They “stick” until the key is pressed again (or another button-emulating key instead). Button presses and releases are notified to the user by a simple “pling”, or “plong”, respectively, generated from the PC's built-in speaker. The following commands control the emulation.
KBDMOUSEGET
    get the current definitions, and
KBDMOUSESET
    set new definitions.
Both accept a struct mousedefs * as the third argument to the ioctl call:

    struct mousedefs {
        int leftbutton;     /* (PC) scan code for "left button" key     */
        int middlebutton;   /* (PC) scan code for "mid button" key      */
        int rightbutton;    /* (PC) scan code for "right button" key    */
        int stickybuttons;  /* if true, the buttons are "sticky"        */
        int acceltime;      /* timeout in microseconds to start pointer */
                            /* movement acceleration                    */
        /* defaults to: scan(F1), scan(F2), scan(F3), false, 500000     */
    };

Downloadable character set interface EGA and VGA video adaptors provide the capability of downloadable software fonts. Since the ‘native character set’ of any IBM-compatible PC video board does not allow the full interpretation of DEC multinational character set or ISO Latin-1 (ISO 8859-1), this might be very useful for a U**X environment.
VGASETFONTATTR
    set font attr, and
VGAGETFONTATTR
    get font attr
are used to manipulate the drivers information about a downloaded font. The take a pointer to a struct vgafontattr as argument:

    struct vgafontattr {
        int character_set;          /* VGA character set */
        int font_loaded;            /* Mark font loaded or unloaded */
        int screen_size;            /* Character rows per screen */
        int character_scanlines;    /* Scanlines per character - 1 */
        int screen_scanlines;       /* Scanlines per screen - 1 byte */
    };

Each character of each font is to be downloaded with
VGALOADCHAR
    load vga char,
taking a pointer to struct vgaloadchar as its argument:

    struct vgaloadchar {
        int character_set;       /* VGA character set to load into */
        int character;           /* Character to load */
        int character_scanlines; /* Scanlines per character */
        u_char char_table[32];   /* VGA character shape table */
    };

The field character_set takes the values CH_SET0, CH_SET1, CH_SET2, CH_SET3 on EGA's or VGA's. Since VGA's might have up to eight simultaneously loaded fonts, they can take CH_SET4, CH_SET5, CH_SET6, or CH_SET7, too. Note that there's a dependence between the font size and a possible screen height (in character rows), depending on the video adaptor used:

    Screen size (rows) on:          EGA             VGA
    Font size
    8 x 8                           43              50
    8 x 10                          35              40
    8 x 14                          25              28
    8 x 16                          not             25
                                    applicable

General screen manipulation commands
VGACURSOR
    sets cursor shape,
taking a pointer to the following structure as argument:

    struct cursorshape {
        int screen_no; /* screen number for which to set,               */
                       /*  or -1 to set on current active screen        */
        int start;     /* top scanline, range 0... Character Height - 1 */
        int end;       /* end scanline, range 0... Character Height - 1 */
    };

VGASETSCREEN
    set screen info, and
VGAGETSCREEN
    get screen info,
provide an interface to some general driver internal variables which might modify the behaviour of the screens, or which might simply be used to force the driver to switch to one certain screen. Their argument is a pointer to the structure:

    struct screeninfo {
        int adaptor_type;   /* type of video adaptor installed     */
                            /* read only, ignored on write (yet!)  */
        int totalfonts;     /* no of downloadable fonts            */
                            /* read only, ignored on write         */
        int totalscreens;   /* no of virtual screens               */
                            /* read only, ignored on write         */
        int screen_no;      /* screen number, this was got from    */
                            /* on write, if -1, apply pure_vt_mode */
                            /* and/or screen_size to current screen*/
                            /* else to screen_no supplied          */
        int current_screen; /* screen number, which is displayed.  */
                            /* on write, if -1, make this screen   */
                            /* the current screen, else set current*/
                            /* displayed screen to parameter       */
        int pure_vt_mode;   /* flag, pure VT mode or HP/VT mode    */
                            /* on write, if -1, no change          */
        int screen_size;    /* screen size                         */
                            /* on write, if -1, no change          */
        int force_24lines;  /* force 24 lines if 25 lines VT mode  */
                            /* or 28 lines HP mode to get pure     */
                            /* VT220 screen size                   */
                            /* on write, if -1, no change          */
        int vga_family;     /* if adaptor_type = VGA, this reflects*/
                            /* the chipset family after a read     */
                            /* nothing happenes on write ...       */
        int vga_type;       /* if adaptor_type = VGA, this reflects*/
                            /* the chipset after a read            */
                            /* nothing happenes on write ...       */
        int vga_132;        /* set to 1 if driver has support for  */
                            /* 132 column operation for chipset    */
                            /* currently ignored on write          */
    };

Its field pure_vt_mode may take the values M_HPVT for a mixed VTxxx and HP Mode, with function key labels and a status line, or M_PUREVT for only VTxxx sequences recognized, with no labels.
VGASETCOLMS
    sets the number of columns for the current screen,
its parameter is a pointer to an integer containing either a value of 80, or a value of 132. Note that setting the number of columns to 132 is only supported on VGA adaptors. Any unsupported numbers cause the ioctl to fail with errno (see intro(2)) being set to EINVAL. VGA color palette interface Only on VGA adaptors, there's a color palette register at the output. It is responsible for the red, green and blue output voltage provided for each of the 256 internal color codes, each lying in the range of 0 through 63 (with 63 representing the brightest value for a base color). Thus, these adaptors map each color code to a color of a “palette” out of 262144 colors. The commands
VGAREADPEL
    read VGA palette entry, and
VGAWRITEPEL
    write VGA palette entry
establish an interface to these palette registers. Their argument is a pointer to:

    struct vgapel {
        unsigned idx;      /* index into palette, 0 .. 255 valid   */
        unsigned r, g, b;  /* RGB values, masked by VGA_PMASK (63) */
    };

Driver identification
VGAPCVTID
    returns information if the current compiled in driver is pcvt and it's major and minor revision numbers. the call is taking a pointer to the following structure as argument:

    struct pcvtid {
    #define PCVTIDNAMELN  16		/* driver id - string length */
    	char name[PCVTIDNAMELN];	/* driver name, == PCVTIDSTR	*/
    #define PCVTIDNAME    "pcvt"		/* driver id - string */
    	int rmajor;			/* revision number, major	*/
    #define PCVTIDMAJOR   3
    	int rminor;			/* revision number, minor	*/
    #define PCVTIDMINOR   00
    };

VGAPCVTINFO
    returns information if the current compiled in driver is pcvt and it's compile time options. the call is taking a pointer to the following structure as argument:

    struct pcvtinfo {
    	u_int opsys;			/* PCVT_xxx(x)BSD */
    #define CONF_UNKNOWNOPSYS	0
    #define CONF_386BSD		1	/* unsupported !!! */
    #define CONF_NETBSD		2
    #define CONF_FREEBSD		3
    	u_int opsysrel;			/* Release for NetBSD/FreeBSD */
    	u_int nscreens;			/* PCVT_NSCREENS */
    	u_int scanset;			/* PCVT_SCANSET */
    	u_int updatefast;		/* PCVT_UPDATEFAST */
    	u_int updateslow;		/* PCVT_UPDATESLOW */
    	u_int sysbeepf;			/* PCVT_SYSBEEPF */
    	u_int pcburst;			/* PCVT_PCBURST */
    	u_int kbd_fifo_sz;		/* PCVT_KBD_FIFO_SZ */
    /* config booleans */
    	u_long compile_opts;		/* PCVT_xxxxxxxxxxxxxxx */
    };

Screen saver Depending on the configuration of a pcvt driver, their might be a simple screen saver available. It is controlled by the command
VGASCREENSAVER
    set timeout for screen saver in seconds; 0 turns it off,
taking a pointer to an integer as argument. Despite of its command name, this is available on any kind of adaptor if configured in by the config(8) option “PCVT_SCREENSAVER” Compatibility commands for USL-style VT's Release 3.00 of this pcvt driver supports a subset of the USL-style commands used to control the virtual terminal interface. This feature is mainly intended to allow XFree86, release 2.0 or higher, to switch between virtual screens even when running an X server. They are ugly with respect to the implied semantics (i. e., they break Berkeley semantics) and are therefore not recommended for common use. See the file i386/include/pcvt_ioctl.h for their documentation.

FILES

/usr/include/machine/pcvt_ioctl.h
    Definitions for ioctl(2) function calls

/dev/ttyv?

/dev/console
    Device nodes to access the pcvt driver

i386/isa/pcvt/pcvt_hdr.h
    (relative to the kernel source tree) Documents the various compile-time options to tailor pcvt.

HISTORY
The pcvt driver has been developed for and contributed to 386BSD release 0.1. Since release 3.00 explicit support is provided for NetBSD 0.9. It is expected that no further development on pcvt is done for 386BSD 0.1 after release 3.00, in fact, 386BSD support was dropped with release 3.20.

AUTHORS

Written by:
    Hellmuth Michaelis (hm@hcshh.hcs.de)

With much help from:
    Brian Dunford-Shore (brian@morpheus.wustl.edu)
    Joerg Wunsch (joerg_wunsch@uriah.sax.de)

This driver is based on several people's previous

work, notably by:
    William Jolitz' and Don Ahn's historic pccons(4) implementation (ljolitz@cardio.ucsf.edu)
    Holger Veit (veit@du9ds3.uni-duisburg.de, now veit@first.gmd.de)

SEE ALSO
intro(2), ioctl(2), keyboard(4), screen(4), config(8).

BUGS
Certainly existent. See the file BugList in the Documentation directory for an up-to-date list.

  Tested Video Boards

    Manufacturer                    Chipset                 Monitor
    2theMax (?)                     ET4000                  VGA Color
    Video7 Inc.                     Video 7                 VGA Color
    Diamond Stealth VRAM            S3                      NEC 3FGx
    Trident                         TVGA 8800CS             NEC 3D
    Data General                    C&T P82C604             VGA Color
    NoName Hercules                 W86855AF                Mono
    Kyocera (Mainboard)		WD90C11			Sony Color
    unknown				ET3000			NEC 3D

  Tested Keyboards

    Manufacturer                    Type                    Layout
    Cherry                          MF II                   US
    Cherry/Tandon                   MF II                   German
    Hewlett-Packard                 MF II                   US
    Hewlett-Packard                 MF II                   German
    Tatung                          AT                      German

There is absolutely NO support for the ancient PC-keyboards (they had 83 keys). There is only limited support for AT-keyboards [ they have 84 keys, and a separate numeric keypad, they don't have F11/F12 keys] because the emulator needs F9 through F12 for control functions, and due to the current design of the keyboard driver there is no (full) support for national keyboards because of the lack of an ALtGr key. MF-keyboards are fully supported, 101- and 102-key versions.