pmodew.doc

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

  Another group of variables that has meaning only under clean/XMS/VCPI
execution specify the number of selectors and DPMI callbacks you want PMODE/W
to make available. The more selectors and callbacks you ask for, the more low
memory is used by PMODE/W, though the amount of low memory used for each is
quite low so that large numbers of each can be specified. There will usually
be a little less than the number of selectors and callbacks you request
available to your program due to the protected mode system and C/C++ code
using some of them. For this reason you should request 20h-40h more selectors
and 2-4 more callbacks than you will need in your program.

  There are four other miscellaneous parameters that can be set. There is a
maximum number of page tables to use under a VCPI system. Each page table
allocated requires 4k of low memory to be used by PMODE/W and maps 4M of
memory. This directly affects the maximum amount of extended memory available
under a VCPI system. This parameter is only the maximum number of page tables
to allow. At run-time, only as many page tables will be allocated as are
needed. Under a clean/XMS system, no page tables are required, so this
parameter has no meaning. But under VCPI, you may want to restrict the number
of page tables to save low memory if you do not need more than a certain
amount of extended memory. This puts a maximum ceiling on extended memory
under VCPI which may be lower than the maximum actually specified in the other
variable. The second parameter specifies the order of DPMI and VCPI detection.
By default, VCPI will be checked before DPMI, but you may set DPMI to be
checked before VCPI so that under a system which supports both VCPI and DPMI,
DPMI will be used. The third variable specifies how many pages to reserve for
physical address mapping calls (INT 31h function 0800h) under VCPI. Under XMS
or a clean system, paging is not enabled, and PMODE/W does not need pages for
physical address mapping. Each page will allow you to map up to 4M of address
space and takes up 4k of extended memory. So for example, if you intend to map
a 2M frame buffer of a video card, you will need only one page. You may set
this parameter to zero if you do not intend to map any physical addresses.
The fourth parameter specifies whether PMODE/W displays its banner at startup.
This may be desirable to indicate that the program is indeed running, and has
not crashed, as allocating memory from certain VCPI servers can be a slow
process.

1.6 - Terms for non-commercial use:
-----------------------------------

  You are hereby permitted to use this DOS extender in any and all
non-commercial and non-shareware software programs free of any financial
obligation to us, provided that if the program is distributed, it is
distributed to the public, free of any charge for the program itself. There is
no restriction on what kind of reselling of the above mentioned program is
done (shareware houses, CD-ROMs, etc...), as long as the program is available
to the public with no financial obligation to the author(s). The only thing we
ask in this case is that you credit us in your production for the DOS
extender. It would also be nice, but not necessary, if you dropped us a note
informing us of your use of PMODE/W in some production.

1.7 - Licensing PMODE/W for commercial use:
-------------------------------------------

  If you wish to use PMODE/W in a commercial, shareware, or any program which
is to be sold or has attached to it an obligation to buy something, you MUST
purchase a commercial distribution license. This license will allow royalty
free distribution of any and all applications using PMODE/W created and owned
by the holder of the license. A separate license is NOT required for each
application in which PMODE/W is used. This license is non-transferrable (you
cannot sell, give, loan, or otherwise transfer it to someone else).

  The license fee is $500 U.S. for commercial or shareware programs. Once
purchased, this license is valid for any and all programs created and owned by
the person or company purchasing the license until the end of time. The
license is a one time fee, with no restrictions on how many programs PMODE/W
can be used in. There is a special discount available to students on PMODE/W.
The license can be purchased by university students for $100 U.S.

1.8 - Contact information:
--------------------------

  If you are interested in licensing PMODE/W for a commercial or shareware
program, you may contact us in the following manner:

) Send mail to:

    Ryan Cramer
    8300 Riding Ridge Place
    McLean, VA  22102
    USA

) Send E-mail to:

    [e-mail]

) On the World Wide Web:

    http://www.di.net/pmw (Official page)
    http://www.dorsai.org/~daredevi/pmw (Latest version download only)

) Drop a note to the sysop on the Data Connection BBS at:

    [phone]
    [phone]

) For technical questions, drop a note to the following address:

    [e-mail]

------------------------------------------------------------------------------
------------------- 2 - Supported DPMI INT 31h functions ---------------------
------------------------------------------------------------------------------

  PMODE/W duplicates a subset of DPMI protected mode functions. These
functions are available ONLY in protected through INT 31h. They provide
descriptor services, extended memory services, interrupt services, translation
services, and some other miscellaneous things. A function is called by setting
AX to the function code, setting any other registers for the function, and
executing INT 31h. Upon return, the carry flag will be clear if the function
was successful. If the carry flag is set, the function failed. All other
registers are preserved unless otherwise specified. In addition to the
functions listed here, functions 0600h, 0601h, 0702h, and 0703h will return
with the carry flag clear to stay compatible with code that uses those
particular DPMI functions.

2.0 - Function 0000h - Allocate Descriptors:
--------------------------------------------

  Allocates one or more descriptors in the client's descriptor table. The
descriptor(s) allocated must be initialized by the application with other
function calls.

In:
  AX     = 0000h
  CX     = number of descriptors to allocate

Out:
  if successful:
    carry flag clear
    AX	   = base selector

  if failed:
    carry flag set

Notes:
) If more that one descriptor was requested, the function returns a base
  selector referencing the first of a contiguous array of descriptors. The
  selector values for subsequent descriptors in the array can be calculated
  by adding the value returned by INT 31h function 0003h.

) The allocated descriptor(s) will be set to expand-up writeable data, with
  the present bit set and a base and limit of zero. The privilege level of the
  descriptor(s) will match the client's code segment privilege level.

2.1 - Function 0001h - Free Descriptor:
---------------------------------------

  Frees a descriptor.

In:
  AX     = 0001h
  BX     = selector for the descriptor to free

Out:
  if successful:
    carry flag clear

  if failed:
    carry flag set

Notes:
) Each descriptor allocated with INT 31h function 0000h must be freed
  individually with the function. Even if it was previously allocated as part
  of a contiguous array of descriptors.

) Under DPMI 1.0/VCPI/XMS/raw, any segment registers which contain the
  selector being freed are zeroed by this function.

2.2 - Function 0002h - Segment to Descriptor:
---------------------------------------------

  Converts a real mode segment into a protected mode descriptor.

In:
  AX     = 0002h
  BX     = real mode segment

Out:
  if successful:
    carry flag clear
    AX     = selector

  if failed:
    carry flag set

Notes:
) Multiple calls for the same real mode segment return the same selector.

) The returned descriptor should never be modified or freed.

2.3 - Function 0003h - Get Selector Increment Value:
----------------------------------------------------

  The Allocate Descriptors function (0000h) can allocate an array of
contiguous descriptors, but only return a selector for the first descriptor.
The value returned by this function can be used to calculate the selectors for
subsequent descriptors in the array.

In:
  AX     = 0003h

Out:
  always successful:
    carry flag clear
    AX	   = selector increment value

Notes:
) The increment value is always a power of two.

2.4 - Function 0006h - Get Segment Base Address:
------------------------------------------------

  Returns the 32bit linear base address from the descriptor table for the
specified segment.

In:
  AX     = 0006h
  BX     = selector

Out:
  if successful:
    carry flag clear
    CX:DX  = 32bit linear base address of segment

  if failed:
    carry flag set

Notes:
) Client programs must use the LSL instruction to query the limit for a
  descriptor.

2.5 - Function 0007h - Set Segment Base Address:
------------------------------------------------

  Sets the 32bit linear base address field in the descriptor for the specified
segment.

In:
  AX     = 0007h
  BX     = selector
  CX:DX  = 32bit linear base address of segment

Out:
  if successful:
    carry flag clear

  if failed:
    carry flag set

Notes:
) Under DPMI 1.0/VCPI/XMS/raw, any segment register which contains the
  selector specified in register BX will be reloaded. DPMI 0.9 may do this,
  but it is not guaranteed.

) We hope you have enough sense not to try to modify your current CS or SS
  descriptor.

2.6 - Function 0008h - Set Segment Limit:
-----------------------------------------

  Sets the limit field in the descriptor for the specified segment.

In:
  AX     = 0008h
  BX     = selector
  CX:DX  = 32bit segment limit

Out:
  if successful:
    carry flag clear

  if failed:
    carry flag set

Notes:
) The value supplied to the function in CX:DX is the byte length of the
  segment-1.

) Segment limits greater than or equal to 1M must be page aligned. That is,
  they must have the low 12 bits set.

) This function has an implicit effect on the "G" bit in the segment's
  descriptor.

) Client programs must use the LSL instruction to query the limit for a
  descriptor.

) Under DPMI 1.0/VCPI/XMS/raw, any segment register which contains the
  selector specified in register BX will be reloaded. DPMI 0.9 may do this,
  but it is not guaranteed.

) We hope you have enough sense not to try to modify your current CS or SS
  descriptor.

2.7 - Function 0009h - Set Descriptor Access Rights:
----------------------------------------------------

  Modifies the access rights field in the descriptor for the specified
segment.

In:
  AX     = 0009h
  BX     = selector
  CX     = access rights/type word

Out:
  if successful:
    carry flag clear

  if failed:
    carry flag set

Notes:
) The access rights/type word passed to the function in CX has the following
  format:

    Bit: 15  14  13  12  11  10   9   8   7   6   5   4   3   2   1   0
       +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
       | G |B/D| 0 | ? |       ?       | 1 |  DPL  | 1 |C/D|E/C|W/R| A |
       +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

    G   - 0=byte granular, 1=page granular
    B/D - 0=default 16bit, 1=default 32bit
    DPL - must be equal to caller's CPL
    C/D - 0=data, 1=code
    E/C - data: 0=expand-up, 1=expand-down
          code: must be 0 (non-conforming)
    W/R - data: 0=read, 1=read/write
          code: must be 1 (readable)
    A   - 0=not accessed, 1=accessed
    0   - must be 0
    1   - must be 1
    ?   - ignored

) Client programs should use the LAR instruction to examine the access rights
  of a descriptor.

) Under DPMI 1.0/VCPI/XMS/raw, any segment register which contains the
  selector specified in register BX will be reloaded. DPMI 0.9 may do this,
  but it is not guaranteed.

) We hope you have enough sense not to try to modify your current CS or SS
  descriptor.