PCVT(4)                   OpenBSD Programmer's Manual                  PCVT(4)

NAME
     pcvt - PC console virtual screen system

SYNOPSIS
     [option ``PCVT_NSCREENS = number'']
     [option ``PCVT_XXXX''] (see Configuration below)

     vt0 at isa? port 0x60 irq 1

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

     Note: As of OpenBSD 2.6, pcvt does not do character mapping by default in
     favor of a traditional PC display where 16 colors are available and the
     standard IBM font is used.  See the -o flag in scon(1) to toggle between
     this mode and the old mode.

   VT Keys
     Despite the complexity of options, if installed in a normal OpenBSD con-
     figuration with the default options, on a standard i386 architecture sys-
     tem, you can use multiple virtual terminals.  The key sequence used to
     move among virtual terminals are, at least on a North American keyboard,
     CTRL+ALT+Fn, where n can be from one to four on the standard system or
     higher if you have created additional /dev/ttyC* entries.

     To use the scrollback feature, press SHIFT+PGUP/PGDN (more info further
     on this further down).

   Features
     The pcvt driver includes the following features:

     o   Almost full DEC VT220 (TM) functionality (moving towards VT320 (TM))
     o   Completely independent virtual terminals for MDA/HGC/CGA/EGA and VGA
     o   25, 28, 35, 40, 43 or 50x80 screen resolution for each virtual screen
     o   Fully remappable keyboard to support national keyboards
     o   All VT220 character sets plus ISO Latin-1 and DEC technical supported
     o   VT220 downloadable character set supported when run on EGA/VGA
     o   VT220 user defined keys for each virtual terminal
     o   Display function codes functionality
     o   Support for MDA, CGA, EGA, and VGA display adaptors
     o   Support for 132 column operation on some VGA chipsets
     o   Scrollback buffer
     o   Console mouse support
     o   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:

     o   No double wide/high characters
     o   No softscroll
     o   No inverse background
     o   No VT220 printer output support
     o   No VT52 support at all
     o   No 8-bit controls
     o   Only limited AT-keyboard (84 keys) support

   Configuration
     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 option lines within the config file, possibly
     overriding the built-in default values.  Therefore it is possible to com-
     pile 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 arch/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 de-
     fault is assumed.

     PCVT_NSCREENS
             Defines the number of virtual screens.
             Default: 8

     PCVT_SCREENSAVER
             Enables the built-in 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: off

     PCVT_CTRL_ALT_DEL
             If enabled, the key combination <Ctrl> <Alt> <Del> invokes a CPU
             reset.
             Default: off (To change this, check sysctl.conf , set value of
             machdep.kbdreset to 1)

     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) de-
             faults 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 be-
             tween the 24- and 25-lines' display by the scon(1) utility.
             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 modi-
             fier.  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 arch/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 its argument.  They manipulate the driv-
     er's internal keyboard repetition flag, possible values are: KBD_RE-
     PEATOFF or KBD_REPEATON.

           KBDGLEDS              get LED state, and
           KBDSLEDS              set LED state manipulate the keyboard indica-
                                 tors, but do not influence the driver's 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

     These functions should be used in a same manner to get/set the driver's
     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.  They take a pointer to a struct kbd_ovlkey ar-
     gument as described below.  In addition,

           KBDRMKEY              removes a key assignment, taking a pointer to
                                 an int as its argument which contains the af-
                                 fected 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.

     Downloadable character set interface

     EGA and VGA video adaptors provide the capability of downloadable soft-
     ware 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

     These functions are used to manipulate the driver's information about a
     downloaded font.  They take pointers to a struct vgafontattr as their ar-
     guments:

     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 simultane-
     ously 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 its 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 screen_size;    /* screen size                         */
                             /* on write, if -1, no change          */
         int force_24lines;  /* force 24 lines if 25 lines VT 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 happens on write ...        */
         int vga_type;       /* if adaptor_type = VGA, this reflects*/
                             /* the chipset after a read            */
                             /* nothing happens on write ...        */
         int vga_132;        /* set to 1 if driver has support for  */
                             /* 132 column operation for chipset    */
                             /* currently ignored on write          */
     };

           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 on-
     ly 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 its major and minor re-
                                 vision numbers.  The call is taking a pointer
                                 to the following structure as its 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 its compile time op-
                                 tions.  The call is taking a pointer to the
                                 following structure as its 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 sysbeepf;                 /* PCVT_SYSBEEPF */

     /* 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 its argument.  Despite of its command
     name, this is available on any kind of adaptor if configured in by the
     config(8) option ``PCVT_SCREENSAVER''

     Scrollback buffer

     It is often useful to be able to review text that has already scrolled
     off the screen.  By default, 8 pages of scrollback buffer are available
     by navigating with the SHIFT+PGUP/PGDN keys.  The scrollback buffer is
     destroyed when switching virtual terminals, changing line modes, or
     switching between 80/132 columns.  To increase the number of pages
     stored, see the -b option for scon(1).

     Scrollback support was added in OpenBSD 2.6.

     Compatibility commands for USL-style VT's

     Release 3.00 of this pcvt driver supports a subset of the USL-style com-
     mands used to control the virtual terminal interface.  This feature is
     mainly intended to allow XFree86, release 2.0 or higher, to switch be-
     tween 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   ioctl(2) function call definitions
     /dev/ttyC?                          individual virtual terminal devices
     /dev/console                        device node for pcvt access
     /dev/pcvtctl                        moused(8) communication device
     /sys/arch/i386/isa/pcvt/pcvt_hdr.h  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 pc(4)
                                           implementation
                                           (ljolitz@cardio.ucsf.edu)
                                           Holger Veit (veit@du9ds3.uni-
                                           duisburg.de, now veit@first.gmd.de)

SEE ALSO
     cursor(1), fed(1), fontedit(1), kcon(1), loadfont(1), mcon(1), scon(1),
     intro(2), ioctl(2), config(8), ispcvt(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 F11/F12 keys [they have 84
     keys, and a separate numeric keypad, they don't have] because the emula-
     tor 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.

OpenBSD 2.8                     August 10, 1998                              8
