* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
The following documemtation was derived from the VESA puplication.  

Super VGA Protected Mode Interface
Standard #VS911020
October 20, 1991

Purpose:

To standardize a common software interface for protected mode applications
(those that do not have access to a real mode BIOS) to VGA video adapters.

Summary:

This standard provides a set of functions which an application program can use
to obtain information about the capabilities and characteristics of a specific
VGA implementation and to control the operation of such hardware without using 
a video BIOS.

The goal is to allow an application to take full advantage of the features
provided by a variety of display adapters.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

Contents:
    1.  Introduction
            1.1  Scope of Standard
            1.2  Document Overview
            
    2.  CPU Video Memory Windows
            2.1  Hardware Window Types
            
    3.  Color Handling
    
    4.  SVPMI Files
            4.1  File Location
            4.2  File Structure
            4.3  Syntax
            
    5.  Variables
    
    6.  Video Environment Information
            6.1  Data Sections
            
    7.  Programming Support
            7.1  Command Sections
            
    8.  Commands
            8.1  Simple Commands
            8.2  Complex Commands
            
    9.  SVPMI File Structure
    
    10. Creating SVPMI Files
    
    11. The "svpmi" Utility
            11.1 Command Line Syntax
            11.2 Extensions and Limitations
            11.3 QNX SVPMI Extensions
            11.4 Error Messages
            
    12. Further Information
    
1. Introduction

The IBM VGA is a defacto standard in the PC graphics world.  A multitude of
different VGA offerings exist in the marketplace, each one providing 
compatibility with the IBM VGA and implementing various extensions to the VGA 
standard.  These extensions range from higher resolutions and more colors to
improved performance and even some graphics processing capabilities.

Several problems face a software developer who intends to take advantage of
these "Super VGA" environments.  Because there is no standard hardware 
implementation for the VGA extensions, designing applications for these
environments is costly and technically difficult.  Except for applications 
supported by OEM specific display drivers, it is difficult for a software
developer to take advantage of the power and capabilities of a variety of
Super VGA products.

To remedy this, VESA developed the VESA VGA BIOS Extension.  Designed for the
real mode environment, this standard focuses on returning information about 
the video environment to the application and assisting the application in
initializing and programming the hardware.  Unfortunatly, due to its design
as a set of real mode functions, this standard cannot be used by developers 
working in a protected mode environment.  To address this problem, VESA has
defined the Super VGA Protected Mode Interface or SVPMI.

SVPMI has been developed to minimize the need for board specific device drivers 
by providing runtime specification of hardware dependant variables and 
procedures in a text file.  The text file will be supplied by the display 
adapter manufacturer.  Applications will be written to load this file during 
initialization and will use the information contained in the file to determine
video capabilities and to set up the graphics hardware in one of the available
display modes.

This is expected to be used mainly in protected mode environments such as Unix,
OS/2, Windows and QNX, however it may also be used in a real mode environment.  
The SVPMI is essentially the protected mode "sister" of the VESA Super VGA BIOS
Extensions.

Readers of this document should be familiar with programming the VGA and Intel
Microprocessor hardware.

1.1 Scope of Standard

The SVPMI functions have been designed to put the performance insensitive,
nonstandard hardware functions into a text file that is interpreted while 
putting the performance sensitive, standard hardware functions into the
application.  This provides portability among VGA systems together with the
performance that comes from accessing the hardware directly.  In particular, 
the SVPMI is responsible for mapping video memory into the CPU address space
while the application is responsible for performing the actual memory read and
write operations.

Functions provided through SVPMI are limited to manipulating display "modes"
and do not include any capabilities such as drawing operations in graphics 
mode or font handling in text modes.  The SVPMI is intended to be used by an
application which already has knowledge of the underlying hardware, taking 
full control of that hardware after using SVPMI functions to establish a 
particular mode.

The SVPMI has been designed with the idea that an application may assume
underlying VGA hardware.  It may also be used with other types of hardware, 
though no such support should be considered as part of the standard.

Though this document refers to the program that interprets SVPMI files as an
application, it is expected that the majority of such applications will 
acutally be drivers for environments such as the X Window System, Microsoft
Windows, OS/2 and QNX.

1.2 Document Overview

This document is intended to be used in two ways.  First, by a display adapter 
manufacturer, as a guide to creating an SVPMI file; and second, by an 
application developer, as a guide to understanding the format of an SVPMI file
to aid in the implementation of an SVPMI interpreter.  Sections include 
introductory material, discussion of the concepts embodied in the standard, and
a full description of the contents of an SVPMI file.  Also included are several
sections to aid in creating SVPMI files and utilizing the QNX4 "svpmi" utility.

2. CPU Video Memory Windows

A standard VGA subsystem provides 256k bytes of memory and a corresponding 
mechanism to address this memory.  Super VGA's and their extended modes require
more than the standard 256k bytes of memory but also require that the address 
space for this memory be restricted to one megabyte due to limitations in the 
real mode environment.  CPU video memory windows provide a means of accessing 
this extended VGA memory within the standard CPU address space.

The standard VGA CPU address space for 16 color graphics modes is typically at
segment 0xA000 for 64k.  This gives access to the 256k bytes of a standard VGA,
i.e. 64k per plane.  Access to the extended video memory is accomplished by 
mapping portions of the video memory into the standard VGA CPU address space.

Every super VGA hardware implementation provides a mechanism for software to
specify the offset from the start of video memory which is to be mapped to the
start of the CPU video address space.  Providing both read and write access to 
the mapped memory provides the necessary support for an application to manipu-
late the extended video memory.  This section describes how several hardware 
implementations of CPU video memory windows operate.

The SVPMI informs the application of the parameters that control the hardware
mechanism of mapping the video memory into the CPU address space and then lets
the application control the mapping within those parameters.

2.1 Hardware Window Types

Different hardware implementations of CPU video memory windows can be supported
by the SVPMI.  The information necessary for an application to understand the
type of hardware implementation is provided by the SVPMI to the application.  
There are three basic types of hardware windowing implementations and they are
described below.  The types of windowing schemes described do not include
differences in granularity or window size.

2.1.1 Single Window Systems

Some hardware implementations only provide a single window.  This single window
will be readable as well as writeable.  However, this may cause performance
degradation when moving data in video memory a distance that is larger than the
CPU address space.

Many applications assume that a single read/write 64k window is available.  
Even if a particular product supports multiple windows, it is advisable to 
provide a single window mode in the SVPMI file for that product.

2.1.2 Dual Overlapping Windows

Some hardware implementations provide two windows, one for reading and one for
writing.  In this case, the windows can, and usually do, share the same CPU
address space with one window being read only and the other being write only.

2.1.3 Dual Non-Overlapping Windows

Another mechanism used by two window systems is to allow both windows to be 
read and written.  In this case, the windows must be mapped to different CPU
addresses.

3. Color Handling

The SVPMI defines a color description mechanism that will allow enough flexi-
bility to fully describe existing and future video adapters' methods for
providing color on a display.  This color model is based in large part on that 
used by the X Window System.

In a raster display, individual "dots" on the screen are represented as 1 or
more bits of data within a display adapter's video memory.  There are many ways
to implement the relationship between the data in video memory and how that 
data is displayed.  On the VGA, people commonly think of the "planer" and 
"packed-pixel" formats, but with the introduction of "HiColor" RAMDAC's which
provide no color palette, we can see that a more generalized system to describe
color must be used.  The SVPMI defines a group of elements to fully describe
the relationship between a pixel in video memory and what is displayed on a 
screen.

The first element in the color description is the color model.  This describes
the basic color handling capabilities of the display adapter such as whether
different hues or simply shades of gray are displayed and how the bits that
make up a pixel in video memory are used to produce an appropriate color to be
displayed on the screen.  There are three dirrerent color models:

  IndexedColor
    An IndexedColor model is one in which pixel values are used as indices into
    a color lookup table.  This color lookup table may be modified if the
    BitsRGB value is non-zero.  Most VGA display modes follow this color model
    (when the display adapter is connected to a color display).
    
  DirectColor
    A DirectColor model is one in which pixel values are broken into red, green
    and blue components each of which are used as an index into a separate
    color lookup table.  Each of these color lookup tables may be modified if
    the BitsRGB value is non-zero.
    
  GrayScale
    A GrayScale model is one in which pixel values are used as indices into a
    color lookup table that consists of only shades of gray.  This lookup
    table may be modified if the BitsRGB value is non-zero.  This may be 
    thought of as a IndexedColor model in which the reg, green and blue values
    for each palette entry are identical.  When connected to a analog mono-
    chrome monitor, most VGA modes use this color model.
    
The next element is the BitsPerPixel value.  This specifies the total number of
bits that are used to represent one pixel.  For example, a standard VGA 4 Plane 
16-color graphics mode would have a 4 in this field and a packed pixel 256-
color graphics mode would specify 8 in this field.

The next color specification element is NumberOfColors.  This specifies the
number of colors available to software in this mode.  This is not necessarily
equal to 2 to the power of BitsPerPixel (2^BitsPerPixel) because some modes may 
have bits within a pixel that are unused.  For example, a 15 bit color mode 
would probably have 16 bits per pixel, but only has 32,768 colors.

BitsRGB specifies the number of bits of reg, green and blue that are available
in the color palette for this display mode.  For example, a standard VGA mode
would set this value to 6, while a board supporting an 8-bit DAC would set it
to 8.  If the BitsRGB value is zero, the color lookup table is read-only.

If the color model is DirectColor, the RedSize, RedPosition, GreenSize, Green-
Position, BlueSize, BluePostion, ReservedSize and ReservedPosition elements 
define the bits that make up the red, green, blue and reserved components of
the pixel value respectively.  The bits within each component are contiguous
and are not shared with other components.  For example, a 15 bit DirectColor
mode where the top bit is unused might have values of (5,0), (5,5), (5,10), 
(1,15) for the Reg, Green, Blue and Reserved Size and Position elements.  If
bit 11 of the ModeAttributes value is 1, the memory referenced by the reserved
component of the pixel value may be used by the application.

The MemoryModel specifies the general type of memory organization used in this
mode such as planar vs. packed pixel.

If the BitsRGB value indicates that the color lookup table is read-only, the
BlackPixel and WhitePixel elements contain the pixel values that will display
black and white on the monitor.  While most displays have linearly increasing
color ramps so that a pixel of all 0's is black and a pixel of all 1's is white,
some display adapters (most notably black and white monochrome displays) use 1
for black and 0 for white, making this definition necessary.

4. SVPMI Files

The SVPMI is based upon a command interpreter which is embedded in an appli-
cation.  The SVPMI interpreter operates in combination with an ASCII data file 
written in the SVPMI language, which specifies runtime options and parameters
for supported graphics display adapters.  Parameter settings are grouped by
symbolic names in the SVPMI text file.

4.1 File Location

An SVPMI file will be provided on a DOS diskette by the manufacturer of the
display adapter supported by the file.  This file may be generated by a utility
supplied by the manufacturer based on the amount of memory available, the type
of DAC, information supplied by the BIOS, etc.  As provided on the DOS diskette,
the file will be identified with the filename of "\vesa.pmi".  The application
must provide some mechanism for the user to install the SVPMI file in the
protected mode environment.

In the destination environment, the location and name of the SVPMI file is 
defined by the application.
* Under QNX4, SVPMI files are stored in the directory, /usr/lib/svpmi.
* Node specific precompiled scripts are stored as 
    /etc/config/graphics/SVPMImodes."node number"
    
4.2 File Structure

SVPMI Files are made up of a number of sections.  There are two types of 
sections, data and command.  Data sections contain statements that provide 
information to the application in the form of variable assignments, for example,
mode dependant information such as resolution and memory format.  Command 
sections contain statements to be interpreted by the application, such as AND
(logical AND function), OUTB (write a byte to an IO port) and BOUTB (write a 
buffer of data to an IO port).

The section name specifiers indicate the sections of the SVPMI file to be used 
by the application, and the data to be used for a given display mode.  The 
specifiers are used to set up a hierarchical structure in which statements 
common to a group of sections need only appear at one place in the file.

4.3 Syntax

SVPMI files consist of lines of ASCII text terminated with a carriage return
(0xD) and a line feed (0xA).  Lines may be no more than 80 characters long.

* The "svpmi" utility will accept the standard QNX4/UNIX text file format.

There is no end of file indication.  The DOS end of file character, control-Z
(0x1A), is treated as white space.  The purpose of these file format conventions
is to allow users on both DOS and Unix systems to easily view SVPMI files.

As described above, an SVPMI file is made up of sections.  Sections are defined
by a token enclosed in square brackets (eg. [TOKEN]) on a line by itself.  
Within a section, there may be one or more statements.  A statement may appear
anywhere on a line in either upper or lower case and are terminated with a
semicolon (";").  Statements may not cross lines.

Numeric values may be specified in decimal or hexidecimal.  The C language 
format is used to specify hexidecimal numbers (eg. "0x3D4").

Individual tokens within a statement must be separated by white space, which
consists of the following: 
    a space
    a tab
    a comma ,
    an open or close parentheses ()
    an open or close brace {}
    
Comments may appear anywhere in the text.  Following C++ language conventions,
comments begin with a // and continue to the end of the current line.  Note the
distinction between comments in the SVPMI file and the [COMMENT] section which 
is used to display comment messages to the user.
 
5. Variables

The first type of variable is used by the SVPMI interpreter for informational 
purposes.  These variables are set in the SVPMI file's data sections.  Another 
type is used by the interpreter when executing command sections.  The SVPMI 
commands may reference these variables.  There are two types of variables used 
in the command sections:

    Variables used in a command are in a form resembling registers, as if the
    configuration file were a machine with 64 32 bit registers named R0 through
    R63.  The QNX4 SVPMI implimentation provides 256 registers, R0 through R255.
    
    References to absolute locations within the memory buffer for any particular
    section are made by using the memory pointer variables P0 through Pn, where
    "n" is the size of the buffer minus 1.  Variable P0 refers to the first byte
    of the buffer, P1 to the next, etc.  The current version of the "svpmi"
    utility does not provide this facility.
    
6. Video Environment Information

In a real mode environment, the video BIOS is used to provide a common interface
to the features provided by a particular board such as extended resolution.
Because a protected mode application does not have access to the video BIOS to
initialize display modes, it is difficult and time consuming to take advantage
of any extended features of the underlying hardware.

In most protected mode environments, an application has no standard mechanism to
determine what hardware is available.  Only by knowing OEM specific features can
an application determine the presence of a particular video board.  This often
involves reading and testing registers located at I/O addresses unique to each 
OEM.  As new boards are introduced, additional code must be added to recognize
and support these boards.  In many cases, it is not possible to distinguish
between boards made by different manufacturers, based on the same VGA chip set.

To address this problem, the VESA SVPMI data sections provide information about
the video environment.  This includes such information as display adapter type,
resolution, number of colors, physical memory used, etc.

6.1 Data Sections

Reserved fields have been defined to support future SVPMI extensions and will
always be set to zero in this version.

[VERSION]
    The version section contains a single number which defines the revision of
    the SVPMI specification the file refers to.  The first revision is 1.0.  The
    SVPMI interpreter built into an application should check the version number
    to ensure it will be capable of processing the remainder of the file.
    This section is required and should be the first section in the SVPMI file.
    
[ACTIVE_ADAPTER]
    An SVPMI file may contain information for several adapters.  The active
    adapter section is used to specify which one of the adapters supported in
    the SVPMI text file is to be used.  Other adapter sections in the file are 
    to be ignored.  It contains a single line of information defined by the OEM
    such as the product name of the display adapter to be used.
    This section is required and may only appear once in an SVPMI file.
    
[GRAPHICS_MODE]
    The graphics mode specifier is a single number indicating the display mode
    in which the specified adapter is to be operated if the SVPMI application
    has no other mechanism to determine which mode to use.  Sections containing
    the commands and data necessary to operate the adapter in this mode must
    appear elsewhere in the file.
    This section is required and may only appear once in an SVPMI file.
    When the "svpmi" utility is run in compact mode (-C), this specifies the
    only graphics mode included in the output.
    
[TEXT_MODE]
    The text mode specifier is a single number indicating which text mode is to
    be used on the chosen adapter if the SVPMI application has no other mechan-
    ism to determine which mode to use.  Sections containing the commands and 
    data necessary to operate the adapter in this mode must appear elsewhere
    in the file.
    This section is required and may only appear once in an SVPMI file.
    When the "svpmi" utility is run in compact mode (-C), this specifies the
    only text mode included in the output.
    
[ADAPTER]
    The adapter section denotes that the following sections, commands and data
    are specific to the indicated adapter.  It contains a single line of infor-
    mation defined by the OEM such as the product name of the display adapter
    used.  The statements following this section will only be executed if the 
    adapter named is the one specified in the [ACTIVE_ADAPTER] section.
    There may be multiple adapter sections in an SVPMI file.
    
[COMMENT]
    The comment section allows the SVPMI file to describe any information that
    is unique to a particular display adapter.  The application may choose to
    display this comment during installation or configuration.  In this case, 
    the comment will be displayed in a mono-spaced 7-bit ASCII encoded font. 
    The comment is limited to 15 rows of 40 columns of text each.
    The comment section is optional.  There may be one comment section for each
    adapter described in an SVPMI file.
    
[ADAPTER_INFO]
    The adapter info section describes characteristics of the adapter that are
    common to all modes.  The following variables are defined in this section:
    
    BoardType  Indicates the type of adapter described by the SVPMI file.
        Currently defined types are: EGA, VGA
        
    SaveSize  Specifies the number of bytes required to save the state of the
        adapter.  When an application wishes to save the state of the display
        adapter, it must allocate a buffer of this size and call the function
        defined by the [SAVESTATE] section.
        
    PaletteSize  Specifies the number of bytes required to save the state of the
        analog palette.  When an application wishes to save the state of the 
        palette, it must allocate a buffer of this size and either save the
        palette itself (by assuming underlying VGA hardware) or call the 
        function defined by the [GETPALETTE] section.
        
    There must be an adapter info section for each adapter described in the
    SVPMI file.
    
[MODE]
    The mode section denotes the beginning of a series of sections that are
    specific to the indicated display mode.  It consists of a single mode 
    number.  The [GRAPHICS_MODE] and [TEXT_MODE] sections described earlier in
    the SVPMI file may be used to select which mode section is to be used, or
    the aplication may use other information to make this selection.  For 
    example, the application may use an environment variable to allow the user
    to define the resolution desired.  The application would search the modes
    available in the SVPMI file to find one that matches the resolution 
    specified by the user.
    There must be a graphics and text mode section for each adapter described
    in the SVPMI file.
    
[MODEINFO]
    The modeinfo section describes important characteristics of the mode.  The
    following are defined in this section:
    
    ModeAttributes  A word of data describing basic information about the mode.
        Bits within the word have the following meaning:
        D0  Reserved
        D1  Reserved
        D2  Reserved
        D3  Monochrome/Color mode
                0-Monochrome mode
                1-Color mode
        D4  Mode type
                0-Text mode
                1-Graphics mode
        D5  Reserved
        D6  Register locking        
                0-not lockable
                1-lockable
        D7  Reserved
        D8  Right hand Offscreen memory available
                0-not available
                1-available
            This bit is for cases where the BytesPerScanline value exceeds
            the amount required to contain one scanline of video data.
        D9  Order of bits within a byte
                0-Least significant bit first
                1-Most significant bit first
        D10 Order of bytes within a word
                0-Least significant byte first
                1-Most significant byte first
        D11 Reserved bits of DirectColor pixel available
                0-Memory not available
                1-Memory available
        D12 Reserved
        D13 Reserved
        D14 Reserved
        D15 Reserved
    
    WinAAtributes
    WinBAtributes  These describe the characteristics of the CPU windowing 
        scheme, such as whether the windows exist and are readable or writeable,
        as follows:
        D0  Window supported
                0-Window is not suppoted
                1-Window is suppoted
        D1  Window is readable
                0-Window is not readable
                1-Window is readable
        D2  Window is writeable
                0-Window is not writeable
                1-Window is writeable
        D3-D7 are Reserved
    
    WinAGranularity
    WinBGranularity  Specifies the smallest boundry, in KB, on which a window
        can be placed in video memory.
        
    WinASize  The size of the primary window in KB, A standard VGA window is 64.  

    WinBSize  The size of the secondary window in KB.  If only one window is 
        available, this value should be 0.
    
    WinABase
    WinBBase  The 32-bit base address of a window.
    
    BytesPerScanline  Specifies how many bytes each logical scanline consists
        of.  The logical scanline could be equal to or larger than the display
        scanline.
        
    XResolution  Specifies the horizontal resolution in pixels or characters in
        graphics and text mode respectively.
        
    YResolution  Specifies the vertical resolution in pixels or characters in
        graphics and text mode respectively.
        
    XCharSize  Specifies character cell width in pixels.
    
    YCharSize  Specifies character cell height in pixels.
    
    ColorModel  Specifies the way colors are represented by the display.  The 
        following color models are available:
        0-Gray
            Describes a color model in which pixel values are used as indices
            into a color lookup table that consists of only shades of gray.
        1-IndexedColor
            Describes a color model in which pixel values are used as indices
            into a color lookup table (RAMDAC).
        2-DirectColor
            Describes a color model in which pixel values are broken into red,
            green and blue components each of which are used as an index into
            a color lookup table.
    
    BitsPerPixel  Specifies the total number of bits that define the color of 
        one pixel.  For example, a standard VGA 4 Plane, 16-color graphics mode
        would have a 4 in this field and a packed pixel, 256-color graphics mode
        would specify 8.
        
    NumberOfColors  Specifies the number of colors available to software in that
        mode.  This is not necessarily equal to (2^BitsPerPixel) because some
        modes may have bits within a pixel that are unused.  For example, a 15-
        bit color mode has 16 bits per pixel, but only has 32,768 colors.
        
    BitsRGB  Specifies the number of bits of red, green and blue that are 
        available in the color palette for this display mode.  For example, a 
        standard VGA mode would set this value to 6.  If this value is 0, the
        color lookup is read only.
        
    RedSize
    GreenSize
    BlueSize  If the color model is DirectColor, these values define the number
        of bits that make up the corresponding component of the pixel value.
        
    RedPosition
    GreenPosition
    BluePosition  If the color model is DirectColor, these values define the 
         offset from the least significant bit of the pixel value for the
         corresponding color component.
         
    ReservedSize  If the color model is DirectColor, this value defines bits
        of the pixel value that are reserved.  If bit 11 of the ModeAttributes
        is 1, the reserved bits may be used by the application.
        
    ReservedPosition  If the color model is DirectColor, this value defines the
        offset from the least significant bit of the pixel for the reserved
        portion of the pixel value.
        
    BlackPixel
    WhitePixel  If the color lookup is read-only, these values specify the pixel
        value required to generate the corresponding color on the display.
        
    NumberOfBanks  The number of banks in which scanlines are grouped.  This
        value describes how many memory banks are interleaved to generate the
        display.  The value for VGA is 1, CGA is 2 and Hercules Graphics is 4.
        
    BankSize  The size of a bank (group of scanlines) in units of 1KB.  For CGA
        and Hercules graphics modes the value is 8 or 8192 bytes.  For modes 
        that don't have scanline banks (such as VGA modes 0xD-0x13), this field
        should be set to 0.  Note that in the terminology used here, a "bank" is
        a group of scanlines while a "window" is a region in video memory.
        
    MemoryModel  Specifies the general type of memory organization used in this
        mode.  The following models have been defined:
        0x0     Text mode
        0x1     CGA Graphics
        0x2     Hercules Graphics
        0x3     VGA 4-plane planar
        0x4     VGA 8-bit packed pixel
        0x5     Non-chain 4, 256 color (RIX Mode)
        0x6     Generic packed pixel
        0x7-0xF Reserved by and for VESA
        
    ImagePages  Specifies the number of complete display images that will fit 
        into the VGA's memory, at one time, in this mode.  The application may
        load more then one image into the VGA's memory if this field is non-
        zero, and flip the display between them.
        
    There must be a modeinfo section for each mode described in the SVPMI file.
    
[ADDRESSES]
    The addresses section specifies all physical memory and I/O address which
    need to be accessed in order to operate the display adapter in this mode.
    Two special types of statements are used in this section:
    
    MEMORY addr-addr [,addr-addr]
        Declare physical memory localtions that this mode needs access to.  The
        declaration is specified as a 32 bit base address, a "-" delimiter, and
        a 32 bit ending address.  A list of address ranges may be specified by
        separating the range with commas.
        
    PORT val[-val][,val]
        Declare I/O ports that this mode needs access to.  A list of values or
        value ranges may be specified.
        
    For Example:
        MEMORY( 0xA0000 - 0xAFFFF );    // Standard VGA video memory
        PORT( 0x3D4, 0x3D5 );
        PORT( 0x3C6 - 0x3C9 );
        
    There must be an address section for each mode described in the SVPMI file
    however the current "svpmi" utility ignores this section.
    
[PALETTEDATA]
    The palettedata section contains default data used to program the DAC for
    this mode for applications which do not manage the palette internally.  The
    number of entries in this section is specified by the NumberOfColors 
    variable defined in the modeinfo section for this mode.  For each color,
    there are three values; blue, green and red.
    
    For example:
        0, 0, 0         //  color 0
        80, 0, 0        //  color 1
        0, 80, 0        //  color 2
        80, 80, 0       //  color 3
        0, 0, 80        //  color 4
      //etc
      
    The DAC is always programmed starting with register 0.  If the palettedata
    section is not present, the DAC will not be programmed when the mode is set.
    It is acceptable for an application to handle palette programming 
    internally, ignoring the information provided in this section.
    
    This section is optional and may appear once per mode.

7. Programming Support

Due to the fact that different Super VGA products have different hardware 
implementations, application software has great difficulty in adapting to each
environment.  However, since each is based on the VGA hardware architecture,
differences are most often in video mode initalization and memory mapping.  The
rest of the architecture is usually kept intact, including I/O mapping 
registers, video buffer location in the CPU address space, DAC location and
DAC function.

The SVPMI provides several functions to interface to the different Super VGA
hardware implementations.  These functions take the form of simple commands
that are interpreted by the application; the most important of these sets the 
display hardware into a particular mode.  This function isolates the application
from the details of setting up a video mode on an arbitrary display adapter.
Other functions include selecting the video memory window and setting the 
palette.

7.1 Command Sections

Each of the command sections is actually a function defined by the SVPMI file.
When the application wishes to execute one of these functions, it fills in the
arguments and calls the SVPMI command interpreter to execute the section.  There
are at most four arguments and return values, these are passed in the variables
R0 through R3 for all SVPMI functions.  All arguments are assumed to be valid.

On entry to a function, the variables R0 through R255 are uninitalized except
in cases where a variable is being used to pass an argument.  For functions that
reference the pointer variables P0 through Pn, the variable P0 will point to the
first byte of the buffer, P1 to the next and so on.

[MODEDETECT]
    The modedetect section is a set of commands which can be executed to 
    determine the presence of the hardware required to use the specific mode.
    The application should always execute the mode select section before using
    any other command sections for a particular mode.
    
    Input:
        (none)
    Output:
        R0 = 0 mode is not available
             1 mode is available

    There must be a mode detect for each mode defined in the SVPMI file.  It is
    acceptable for the mode detect section to simply assign the variable R0 to
    one if it is difficult or unnecessary to check for the availability of a
    given mode.
    
    Where possible, it is desirable that the mode detect section not change the
    display seen by the user in any way.  The mode detect section must always
    leave the display in the same state as it was before the execution of the 
    function.
    
[SETMODE]
    The setmode section contains the commands necessary to set the display 
    adapter into the mode specified by the last preceding [MODE] section.  This
    section should set all display adapter registers required for the mode with
    the exception of the analog palette and the text mode character set.
    
    Input:
        (none)
    Output:
        (none)
    
    There must be a set mode section for each mode defined in the SVPMI file.
    
[GETCOLOR]
    The getcolor section contains the commands necessary to retrieve one color
    from the analog palette.
    
    Input:
        R0 = Palette index of color to read
    Output:
        R0 = Red component of color
        R1 = Green component of color
        R2 = Blue component of color
    
    The get color section should appear once for each mode that has a different
    color access mechanism from the VGA standard.

[SETCOLOR]
    The setcolor section contains the commands necessary to set one color in 
    the analog palette.
    
    Input:
        R0 = Palette index of color to set
        R1 = Red component of color
        R2 = Green component of color
        R3 = Blue component of color
    Output:
        (none)
    
    The set color section should appear once for each mode that has a different
    color access mechanism from the VGA standard.
    
[GETPALETTE]
    The getpalette section contains the commands necessary to save the analog
    palette.  This will be used mainly when saving the entire state of the 
    display adapter.
    
    Input:
        P0 = Pointer to a buffer large enough to save the entire palette as
            defined by the PaletteSize variable in the [ADAPTER_INFO] section.
    Output:
        (none)
    
    The get palette section should appear once for each mode that has a 
    different color access mechanism from the VGA standard.

[SETPALETTE]
    The setpalette section contains the commands necessary to restore the 
    analog palette.
    
    Input:
        P0 = Pointer to a buffer containing the palette data.
    Output:
        (none)
    
    The set palette section should appear once for each mode that has a 
    different color access mechanism from the VGA standard.

[GETWINDOW]
    The getwindow section contains the commands necessary to find the current
    position of the specified window in video memory.  Only simple commands may
    be included in the get window section.
    
    Input:
        R0 = 0 to retrieve the position of Window A
             1 to retrieve the position of Window B
    Output:
        R0 = Position of the window in "WinGranularity" units
    
    There must be a get window section for each mode described in the SVPMI file
    that supports windows unless it is impossible to determine the current 
    window from the hardware.

[SETWINDOW]
    The setwindow section contains the commands necessary to set the position
    of the specified window in video memory.  Only simple commands may be 
    included in this section.  For performance reasons, it is important that 
    this section do as little as possible since it can be called during actual
    drawing operations.  In systems supporting two windows, only the position
    of the window specified may be modified.  The other window must remain
    unchanged.
    
    Input:
        R0 = Position of window in "WinGranularity" units
        R1 = 0 to set the position of Window A
             1 to set the position of Window B
    Output:
    
    There must be a set window section for each mode that supports windows
    described in the SVPMI file.
    
[SAVESTATE]
    The savestate section contains the commands necessary to completely save
    the current state of the VGA's registers with the exception of the analog
    palette registers.  
    
    Input:
        P0 = Pointer to a buffer large enough to save the entire state based on
            the size specified by the SaveSize variable in the [ADAPTER_INFO] 
            section.
    Output:
        (none)
        
[RESTORESTATE]
    the restorestate section contains the commands necessary to completely
    restore the state of the VGA's registers from the save buffer created by the
    [SAVESTATE] section.
    
    Input:
        P0 = Pointer to a buffer containing previously saved state
    Output:
        (none)
    
[UNLOCKREGS]
    The unlockregs section contains the necessary commands to allow access to
    all of the VGA's registers.
    
    Input:
        (none)
    Output:
        (none)
    
    This section will only be present if Bit D6 of the ModeAttributes, in the
    [MODEINFO] section, is set.
    
[LOCKREGS]
    The lockregs section contains the commands necessary to prevent access to
    some or all of the VGA's registers.

    Input:
        (none)
    Output:
        (none)
    
    This section will only be present if Bit D6 of the ModeAttributes, in the
    [MODEINFO] section, is set.

8. Commands

Unless otherwise noted, arguments specified with commands may be either 
variables or numeric values.

8.1 Simple Commands

Simple commands may appear in any command section.  With the exception of the
assignment command, the memory pointer variables (P0-Pn) may not be used in
simple commands.

var = val
    Assign a value to a variable.
    
AND var, val
    Bitwise AND of a variable and a value, the result is placed in var.

OR var, val
    Bitwise OR of a variable and a value, the result is placed in var.
    
NOT var
    Bitwise NOT of a variable
    
XOR var, val
    Bitwise XOR of a variable and a value, the result is placed in var.

SHR var, count
    Logical shift right of var by count bits
    
SHL var, count
    Logical shift left of var by count bits
    
ADD var, val
    Add the val to var
    
SUB var, val
    Subtract val from var
    
MUL var, val
    Multiply var by val
    
DIV var, val
    Divide var by val
    
REM var, val
    The remainder of dividing var by val
    
OUTB port, val
    Output the byte val to an IO port

OUTW port, val
    Output the word val to an IO port
    
INB var, port
    Read a byte from an IO port into var
    
INW var, port
    Read a word from an IO port into var
    
var - any variable R0 through R255
val - any variable or a constant
count - any variable or a constant, the value should be less then 256
port - the address of an I/O port, either a variable or a constant

8.2 Complex Commands

Complex commands are limited to the following sections: [GETPALETTE], 
[SETPALETTE], [SAVESTATE], [RESTORESTATE] and [SETMODE].  The "svpmi" utility
allows any commands in any command section.

BOUTB count, index_port, data_port
    Block byte output of R0 through R(count-1).  This command first outputs the
    register number to the index_port and then the contents of the register to
    the data_port for all specified registers.  All parameters for this command
    must be constants.
    
BOUTB count, first_reg, index_port, data_port
    This command is identical to the first form of BOUTB except that it may 
    start from any register and thus start at any index_port value.  All 
    parameters for this command must be constants.
    
RMWB index_port, data_port, index_value, and_mask, or_mask
    Read-Modify-Write-Back.  This command outputs the index_value to the 
    index_port, reads a byte from the data_port, logically AND's the value with
    the and_mask, logically OR's the value with the or_mask and the writes the
    modified value back to the data_port.
    
IOUTB index_port, data_port, index_value, data_value
    The index_value is written to the index_port then the data_value is written
    to the data_port.
    
9. SVPMI File Structure

A SVPMI file contains four types of objects:

    Section Name Specifiers
    Commands
    Data
    Comments
    
The following sequence illustrates the basic organization of a SVPMI text file:

//
// These first four sections occur only once in the file
//

[VERSION]
    1.0;
    
[ACTIVE_ADAPTER]
    acme deluxe
    
[GRAPHICS_MODE]
    0x66            // 800x600 - 16 color
    
[TEXT_MODE]
    3               // 80x25
    
//
// The following sections repeat for various adapters and modes.
//

[ADAPTER]
    acme deluxe
    
[ADAPTER_INFO]
    variable = value;
    variable = value;
    
[COMMENT]
Be sure the switches are set correctly
for the type of monitor you are using.

[MODE]
    0x66        // 800x600 - 16 color
    
[MODEINFO]
    variable = value;
    variable = value;

[MODEDETECT]
    command;
    command;
    
// other sections such as [ADDRESSES], [SETWINDOW] or [SETPALETTE]

[MODE]
    0x67        // 800x600 - 256 color
    
// same types of sections as previous example

[ADAPTER]
    acme super-deluxe       //  different adapter
    
[MODE]
    0x66        // 800x600 - 16 color
    
// same as above but for the "acme super-deluxe" instead of the "acme deluxe"

10. Creating SVPMI Files

This section is targeted at the person who must create a new SVPMI file.

The "svpmi" utility will only use the command sections [MODEDETECT], [SETMODE] 
and [SETWINDOW].  If the mode is for the "gr.vga" graphics driver, the mode
must be the standard VGA 16 color with a maximum resolution of 800x600.  Modes
of higher resolutions will be available in the future but for a different
graphics driver.

It is important to make the [SETWINDOW] function as small as possible.  The 
efficiency of this function can have a dramatic effect on the performance of
the graphics driver.

11. The "svpmi" utility

The "svpmi" utility is a simple compiler that generates executable code and data
in a proprietary format.  The code and data can then be either written to a file
or passed directly to a program that spawned the utility.  

11.1 Command Line Syntax

Syntax: svpmi [options] [input_file]
Options:
  -o flnm   Force the generated data to be written to "flnm".
  -i flnm   Force the script file to be read from "flnm".
  -t n      Override the mode specified in the [TEXT_MODE] section.
  -g n      Override the mode specified in the [GRAPHICS_MODE] section.
  -C        Compact mode, only include code specified by the [GRAPHICS_MODE]
            and [TEXT_MODE] sections.
  -X        Create an executable segment and pass that segment to the 
            application that spawned the utility.
            This should never be used from the shell directly.
  -W        Write the compiled script to the file:
             /etc/config/graphics/SVPMImodes."node_number"
  -3        Generate 386, 32-bit code
  -v        Verbose; display all sections encountered in the script file.
  -vv       More Verbose; display additional information about variable 
            assignments and commands.
            

11.2 Extensions and Limitations

With the advent of newer Super VGA cards, it became evident that the 64 register
model was too limiting since the BOUTB command will only output a register to an
index port of the register's number; thus the total number of registers 
supported by the "svpmi" utility has been increased to 256.  Another feature 
that became evident was some method of storing information between calls, this 
is accomplished by maintaining the array of registers and passing the same array 
to every SVPMI function.  

Some limitations have been introduced in this implementation with the hope that
they will not impact the performance of the SVPMI functions.  The total number
of video modes defined in an SVPMI script must not exceed 64 and the size of the
compiled script must not exceed 64K.  Also note that not all of the SVPMI 
commands have been implemented, for a complete list of supported commands, see
section 8 (Commands) of this document.


11.3 QNX SVPMI Extensions

Since the code required to program standard VGA modes is almost the same for all
video cards, this implimentation allows base files to be included.  With most
Super VGA cards, special registers need to be programmed to enable or disable
the extended modes.  A Special section intended for disabling the extended modes
has been added, called [NORMALIZE].  The code in the [NORMALIZE] section is
invoked by the "normalize()", usually the first command in a [SETMODE] section.
To indicate that a secondary file is to be included, use the [INCLUDE] section
where one file may be listed per line.


11.4 Error Messages

Errors will be in one of the following forms...
    SVPMI [#]: "error message"
        An error occured while compiling the script file.  The number, in 
        square brackets, will be the line number the error occured on.
        
    SVPMI "...": "error message"
        An error occured during program interface operations.  The text before
        the error message will describe why the error was produced and may
        contain the related command line option.

    SVPMI: "error message"
        An error occured during utility internal operations
        
The error messages may be any standard QNX4 error message or one of the 
following extensions:
        
    Illegal Script File Format
        Expecting a specific delimiter such as the closing square bracket of
        a section token.

    Illegal Script Instruction
        The script contains an illegal command or an unsupported command.
    
    Unrecognized Digit in Number
        A constant includes non-numeric characters.

    Incorrect Number of Parameters
        The command requires additional or fewer parameters.
    
    Instruction Format Not Supported
        The combination of parameters is not supported.  Destinations for 
        logical and arithmetic operations must be variables, as well, most 
        complex commands only support constants as parameters.

    Syntax Error
        The script contains unexpected characters.
    
    Script too complex
        Compiled script exceeded 64K or contains more then 64 video modes.
    
    Incomplete Script
        Important sections were missing from the SVPMI script, such as, 
        default text and graphics modes.

    Internal Error
        This messages should never happen, if it does, please forward the
        SVPMI script to QNX Software Systems.

    General Script File Read Error
    General Write Failure
        These message should never happen.  It means that a non-recoverable
        error occured other then system IO errors.  If this error persists,
        contact QNX Software Systems.


12. Further Information

VESA is a not-for-profit organization to promote industry-wide standards for
video graphics.  They welcome any inquiries and may be contacted at the 
following address:

VESA - Video Electronics Standards Association
2150 North First Street, Suite 360
San Jose, CA 95131-2020
Phone: (408) 435-0333
Fax: (408) 435-8225

For further information on VGA and Super VGA standards and programming 
techniques, I recommend the publication:

Programmer's Guide to the EGA and VGA Cards
Second Edition
Richard F. Ferraro
Addison-Wesley Publishing Company, Inc.
ISBN 0-201-57025-4

* The term "Super VGA" is used in this document as a term for video graphics
products implementing a superset of the standard IBM VGA display adapter.

* IBM and VGA are trademarks of International Business Machines Corporation.

* Intel is a registered trademark of Intel Corporation.

* Microsoft and OS/2 are trademarks of Microsoft Corporation.

* Hercules is a registered trademark of Hercules Computer Technology.
