* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 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.