pmodew.doc

来自「开放源码的编译器open watcom 1.6.0版的源代码」· DOC 代码 · 共 1,716 行 · 第 1/5 页

------------------------------------------------------------------------------
---------------------- PMODE For Watcom C/C++ - v1.33 ------------------------
------------------------------------------------------------------------------

  This is the documentation for PMODE for Watcom C/C++ - v1.33, henceforth
referred to as PMODE/W. PMODE/W is Copyright (c) 1994-1997, Charles Scheffold
and Thomas Pytel. All rights reserved.

Contents:
---------

1 - Overview
    1.0  - Legal disclaimer
    1.1  - Description
    1.2  - Usage
    1.3  - Performance and compatibility
    1.4  - PMODE/W protected mode
    1.5  - PMODE/W execution
    1.6  - Terms for non-commercial use
    1.7  - Licensing PMODE/W for commercial use
    1.8  - Contact information

2 - Supported DPMI INT 31h functions
    2.0  - Function 0000h - Allocate Descriptors
    2.1  - Function 0001h - Free Descriptor
    2.2  - Function 0002h - Segment to Descriptor
    2.3  - Function 0003h - Get Selector Increment Value
    2.4  - Function 0006h - Get Segment Base Address
    2.5  - Function 0007h - Set Segment Base Address
    2.6  - Function 0008h - Set Segment Limit
    2.7  - Function 0009h - Set Descriptor Access Rights
    2.8  - Function 000Ah - Create Alias Descriptor
    2.9  - Function 000Bh - Get Descriptor
    2.10 - Function 000Ch - Set Descriptor
    2.11 - Function 0100h - Allocate DOS Memory Block
    2.12 - Function 0101h - Free DOS Memory Block
    2.13 - Function 0102h - Resize DOS Memory Block
    2.14 - Function 0200h - Get Real Mode Interrupt Vector
    2.15 - Function 0201h - Set Real Mode Interrupt Vector
    2.16 - Function 0202h - Get Processor Exception Handler Vector
    2.17 - Function 0203h - Set Processor Exception Handler Vector
    2.18 - Function 0204h - Get Protected Mode Interrupt Vector
    2.19 - Function 0205h - Set Protected Mode Interrupt Vector
    2.20 - Function 0300h - Simulate Real Mode Interrupt
    2.21 - Function 0301h - Call Real Mode Procedure With Far Return Frame
    2.22 - Function 0302h - Call Real Mode Procedure With IRET Frame
    2.23 - Function 0303h - Allocate Real Mode Callback Address
    2.24 - Function 0304h - Free Real Mode Callback Address
    2.25 - Function 0305h - Get State Save/Restore Addresses
    2.26 - Function 0306h - Get Raw Mode Switch Addresses
    2.27 - Function 0400h - Get Version
    2.28 - Function 0500h - Get Free Memory Information
    2.29 - Function 0501h - Allocate Memory Block
    2.30 - Function 0502h - Free Memory Block
    2.31 - Function 0503h - Resize Memory Block
    2.32 - Function 0800h - Physical Address Mapping
    2.33 - Function 0801h - Free Physical Address Mapping
    2.34 - Function 0900h - Get and Disable Virtual Interrupt State
    2.35 - Function 0901h - Get and Enable Virtual Interrupt State
    2.36 - Function 0902h - Get Virtual Interrupt State
    2.37 - Function EEFFh - Get DOS Extender Information

3 - Supported DOS extended INT 21h functions
    3.0  - Function 09h - Write String to Standard Output
    3.1  - Function 1Ah - Set Disk Transfer Area
    3.2  - Function 1Bh - Get Allocation Information for Default Drive
    3.3  - Function 1Ch - Get Allocation Information for Specific Drive
    3.4  - Function 1Fh - Get Drive Parameter Block for Default Drive
    3.5  - Function 25h - Set Interrupt Vector
    3.6  - Function 2Fh - Get Disk Transfer Area
    3.7  - Function 32h - Get Drive Parameter Block for Specific Drive
    3.8  - Function 34h - Get Address of InDOS Flag
    3.9  - Function 35h - Get Interrupt Vector
    3.10 - Function 39h - Create Subdirectory
    3.11 - Function 3Ah - Remove Subdirectory
    3.12 - Function 3Bh - Set Directory
    3.13 - Function 3Ch - Create File
    3.14 - Function 3Dh - Open File
    3.15 - Function 3Fh - Read From File
    3.16 - Function 40h - Write to File
    3.17 - Function 41h - Delete File
    3.18 - Function 43h - Get/Set File Attributes
    3.19 - Function 47h - Get Directory Path
    3.20 - Function 48h - Allocate Memory Block
    3.21 - Function 49h - Free Memory Block
    3.22 - Function 4Ah - Resize Memory Block
    3.23 - Function 4Bh - Sub-Function 00h - Load and Execute Program
    3.24 - Function 4Eh - Search for First Filename Match
    3.25 - Function 4Fh - Search for Next Filename Match
    3.26 - Function 56h - Rename File
    3.27 - Function 62h - Get PSP Address

4 - Supported mouse extended INT 33h functions
    4.0  - Function 0009h - Define Graphics Cursor
    4.1  - Function 000Ch - Define Interrupt Subroutine Parameters
    4.2  - Function 0016h - Save Driver State
    4.3  - Function 0017h - Restore Driver State

------------------------------------------------------------------------------
------------------------------ 1 - Overview ----------------------------------
------------------------------------------------------------------------------

  This section will give you all the information you will need to plug PMODE/W
right into your Watcom C/C++ protected mode programs. All of the other things
you need to be aware of about using PMODE/W commercially and non-commercially
are also in this section. Specific information on INT 31h and INT 21h DOS
extended services supported by PMODE/W is in the following sections. Please
note that we have tested this extender with Watcom C/C++ versions 9.5, 10.0,
10.5, and 10.6.

1.0 - Legal disclaimer:
-----------------------

  We exclude any and all implied warranties, including warranties of
merchantability and fitness for a particular purpose. We make no warranty or
representation, either express or implied, with respect to PMODE/W, its
quality, performance, merchantability, or fitness for a particular purpose.
We shall have no liability for special, incidental, or consequential damages
arising out of or resulting from the use, misuse, or modification of PMODE/W.

  All trademarks used in this documentation are property of their respective
owners.

1.1 - Description:
------------------

  PMODE/W is a DOS extender for the Watcom C/C++ package. It allows DOS
programs to run in full 32 bit protected mode, with access to all memory
available in the system. PMODE/W basically extends the DOS environment to
protected mode and provides a simple interface to the real mode DOS system
services for your code. PMODE/W takes care of all aspects of running the
system in protected mode and maintaining compatibility with the underlying
real mode software. PMODE/W deals with low level necessities such as
descriptor tables, memory management, IRQ and interrupt redirection,
real/protected mode translation functions, exception handling, and other
miscellaneous aspects of running in protected mode. Your code does not need to
deal with specific aspects of different systems, such as XMS/EMS/VCPI/DPMI
availability. PMODE/W will run on top of almost any system and provide common
protected mode services to your program through the DPMI interface
specification, as well as most standard DOS functions extended for protected
mode use.

  PMODE/W replaces DOS/4GW extender in the Watcom C/C++ package. Whereas
DOS/4GW requires a stub and an large external extender, PMODE/W is the stub
and extender in one. The generated executable contains the PMODE/W extender
within it as the stub. When run, PMODE/W will take care of setting up the
system and executing the protected mode portion of the program. PMODE/W has
the added advantage of allowing you to compress you protected mode programs.
PMODE/W is also completely interchangeable with DOS/4GW. You may plug PMODE/W
into almost any Watcom C/C++ programs without worry. So long as the program
does not use any DOS/4GW specific functions, the code will work fine. This
allows you to switch directly back to DOS/4GW if for any reason you are not
satisfied with PMODE/W. This also allows you to debug PMODE/W programs unsing
the Watcom debugger, as any uncompressed PMODE/W executable can be run with
DOS/4GW simply by executing it with DOS4GW.EXE.

  Several years have gone into the development of PMODE/W. It is now a fairly
mature DOS extender, and has gone through its fair share of bugs and
incompatibilities. It is at this point, a very stable protected mode system.
Great pains have gone into the optimization and testing of PMODE/W. Our major
goals have been speed, size, and stability. We now feel that we have achieved
a good deal of those things. But don't take our word for it, try it yourself,
as you can do that very easily before you actually decide to buy PMODE/W. Just
plug PMODE/W into any popular program out there which uses DOS/4GW.

  To sum it up, if you are looking for a good solid, stable, and fast
extender, PMODE/W may be just what you need.

Here are the advantages of PMODE/W:

) No external extender required (everything needed to execute is in the EXE).
) Small size (less than 12k for the entire extender program).
) Compression of protected mode executables.
) Low extended memory overhead.
) Does not require ANY extended memory to load OR execute.
) Fast execution.
) Free for non-commercial use.

1.2 - Usage:
------------

  The following main files should be present in your PMODE/W archive:

) FILE_ID.DIZ   - BBS description file.
) UPDATES.DOC   - Information about updates/bug fixes.
) PMODEW.DOC    - The documentation you are now reading.
) PMODEW.EXE    - The actual PMODE/W DOS extender.
) PMODEW.FAQ    - Frequently asked questions.
) PMODEW.LNK    - Example linker initialization file for PMODE/W.
) PMWSETUP.EXE  - PMODE/W parameter setup utility.
) PMWBIND.EXE   - PMODE/W bind utility.
) PMWLITE.EXE   - PMODE/W protected mode executable compression utility.
) PMWVER.COM    - PMODE/W version check utility.
) UTILS.DOC     - Documentation on PMWSETUP, PMWBIND, PMWLITE, and PMWVER.
) EXAMPLES.ZIP  - Example files.

  You will probably want to add a new system, PMODE/W, to your WLSYSTEM.LNK
file. All you need to do in this case is add the contents of PMODEW.LNK to
your WLSYSTEM.LNK file, this will add the system 'pmodew' to your Watcom C/C++
setup. You may also just compile to a 'dos4g' system but replace the stub with
PMODEW.EXE.

1.3 - Performance and compatibility:
------------------------------------

  Our major concerns in developing PMODE/W were speed, size, and stability.
PMODE/W itself was written entirely in assembly. When running under PMODE/W,
your code will be running at a privilege level of zero, the highest and
fastest. PMODE/W does not virtualize what it does not need to, and does not
invoke any protected mode mechanism that is slow. For example, if the system
is running clean or under XMS, PMODE/W does not turn on paging. Under a memory
manager which provides both VCPI and DPMI services, PMODE/W will opt for VCPI
protected mode which is significantly faster than DPMI. When PMODE/W makes
calls to real mode, it switches the system into actual real mode rather than
the slower V86 mode (when it can, under VCPI this is not possible, control
must be passed back to the VCPI server). In terms of speed, when your code is
running under PMODE/W, it is running as fast as the system will allow.

  In terms of size on disk, we need say no more than for you to look at the
size of the PMODE/W executable and compare it to other extenders. In terms of
memory size, you may do tests yourself to confirm that PMODE/W does indeed
suck up a lot less memory at run-time than the competition. In fact, PMODE/W
will run even if there is absolutely no extended memory in the system
(assuming of course there is enough low memory for the program). To be fair,
we must say we squished the PMODE/W executable with our own compression
program written expressly for the purpose, this though demonstrates the extent
we took most of our optimizations to.

  As for compatibility, PMODE/W is almost fully compatible with DOS/4GW as far
as Watcom C/C++ is concerned. PMODE/W extends only those DOS functions
required by the Watcom C/C++ libraries, though this is a good deal of them.
The exception is BIOS INT 13h functions, which PMODE/W does not extend.
PMODE/W also provides a subset of DPMI 0.9 INT 31h functions in protected
mode. We do not emulate DOS/4GW though, as none of its API functions are
duplicated by PMODE/W. PMODE/W will run under a clean system, XMS, VCPI, or
DPMI. Though you should be aware that under a DPMI system, PMODE/W will not be
providing the DPMI functions, but rather the actual DPMI host in the system
will. You should also be aware that PMODE/W will leave the A20 line enabled
when calling real mode. Disabling the A20 for real mode is not really
necessary, it is a big slowdown during mode switches to have to enable/disable
the A20, so PMODE/W avoids it.

1.4 - PMODE/W protected mode:
-----------------------------

  When run under a clean system, XMS, or VCPI, PMODE/W has control of
protected mode. In this case, it can set up the system to run as fast as
possible under the various conditions. Under DPMI, the DPMI host of the system
will have full protected mode control and PMODE/W will install its DOS
extensions on top of that. If the system provides both VCPI and DPMI services,
PMODE/W will use the VCPI services for faster execution, unless instructed not
to by the setup program. When PMODE/W does have protected mode control under
clean/XMS/VCPI, it runs all code at a privilege level of zero. In addition,
under a clean or XMS system, paging will not be enabled. This is only a minor
speed increase, but there is no real need to manage paging.

  PMODE/W provides a subset of DPMI 0.9 function calls and general
functionality when a DPMI host is not present. PMODE/W will pass any software
interrupts from protected mode to their default real mode handlers, provided
no protected mode handlers have been installed for them, just as DPMI will.
The general registers will be passed on to the real mode handler, but the
segment registers can not be as they have different meanings in real mode and
protected mode. The flags will be passed back from the real mode handler. This
provides a simple interface to all real mode interrupt routines which do not
take parameters in the segment registers, for example, INT 16h function 00h.

  Any IRQs that occur in protected mode and have not been hooked by a
protected mode handler will be sent on to their real mode handlers. If an IRQ
occurs in real mode, and a protected mode handler has hooked that IRQ, it will
be sent to the protected mode handler first. The protected mode handler may
chain to the real mode handler for that IRQ by calling the previous protected
mode handler for that IRQ. This behavior is in accordance with the DPMI
standard. If you hook a protected mode IRQ (INT 31h function 0205h), then hook
the same IRQ in real mode (INT 31h function 0201h), the protected mode handler
will be called if the IRQ occurs in protected mode, and the real mode handler
will handle the IRQs if they occur in real mode. Setting up two handlers like
this assures minimal latency. This means a handler will get control when the
IRQ occurs as soon as physically possible. PMODE/W does have to intervene in
the IRQ process, however, when the low 8 IRQs are mapped to INTs 08h-15h to
differentiate IRQs from CPU exceptions.

  In accordance with DPMI specifications, PMODE/W will pass up software
interrupts 1ch (BIOS timer tick), 23h (DOS CTRL+C), and 24h (DOS critical
error) from real mode to protected mode. This means that those interrupts can
be hooked directly in protected mode without having to set up a callback
mechanism yourself. PMODE/W will also pass interrupt 1bh (BIOS CTRL+BREAK)
from real mode up to protected mode. This is not a DPMI requirement, but it is
necessary for the sake of compatibility with DOS/4GW.

  Another departure by PMODE/W from official DPMI specifications is in
extended memory allocation. DPMI documentation states that the block of
extended memory allocated through function 0501h is guaranteed at least
paragraph alignment. The PMODE/W DPMI implementation will enforce only DWORD
alignment.

1.5 - PMODE/W execution:
------------------------

  When a PMODE/W executable is run, PMODE/W will attempt to switch the system
into protected mode and load the protected mode portion of the same
executable. If there is some error, not enough memory, or a system
incompatibility, PMODE/W will exit with an error message. If loading was
successful, PMODE/W will pass execution control on to the program. PMODE/W
will load any 16 bit code and data into low memory, but 32 bit code and data
may be loaded into low or extended memory depending on avaliability.

  There are a number of modifiable parameters in the PMODE/W extender
executable that affect protected mode execution. For the most part, these
parameters deal with memory. PMODE/W allocates one large block of extended
memory for its pool from which it provides memory to its client program. There
is a maximum value for the extended memory to be allocated. By default, the
maximum is all of the extended memory in the system. The maximum value
reflects the size of the block you want PMODE/W to take from the system, not
necessarily the size of the largest block available to the default C/C++
malloc functions. You may set the maximum to zero to indicate you do not want
PMODE/W to allocate ANY extended memory. The amount of memory that you allow
PMODE/W to allocate from the system determines how much extended memory will
be left to other if you shell out of your PMODE/W program.

  Another variable specifies the amount of low memory for PMODE/W to TRY to
keep free. If PMODE/W can, it will accommodate this value by loading 32 bit
code and data into extended memory. If there is not enough extended memory
available for this, 32 bit code and data will be loaded into low memory
anyway. If PMODE/W can not keep this much low memory free, it will not exit
with an error message. Setting this parameter to a high value will, in effect,
duplicate the DOS/4GW behavior of loading all 32 bit code and data into
extended memory. If you do not necessarily need any extra low memory free
during the execution of your program, you may set this value to zero.

  There is a group of parameters that specify the number and size of nested
mode switch stacks. Whenever you make a call to real mode, or a callback or
IRQ is passed from real mode to its routine in protected mode, a nested stack
is used. These parameters have meaning only if the program is not run under a
DPMI system. If a DPMI host is in place when the program is run, it provides
its own nested stacks for mode switches. The number of nested stacks directly
affects the number of nested mode switches your program can make using the
various mode switch methods. The size of both the real mode and protected mode
nested stacks can also be specified. By default, these values are high enough
for normal operation. However, if you intend to use a lot of stack variables
in a protected mode IRQ handler, or a lot of recursive calls, you may need to
increase the size of the protected mode nested stacks. The more nested stacks
you specify, and the larger they are, the more low memory is needed by PMODE/W
during execution.