1

CWSDPMI is Copyright (C) 1995-2000  Charles W Sandmann (sandmann@clio.rice.edu)

     2

                                    1206 Braelinn, Sugar Land, TX 77479

     3

     4

This is release 5.  The files in this binary distribution may be redistributed

     5

under the GPL (with source) or without the source code provided:

     6

     7

* CWSDPMI.EXE or CWSDPR0.EXE are not modified in any way except via CWSPARAM.

     8

     9

* CWSDSTUB.EXE internal contents are not modified in any way except via

    10

  CWSPARAM or STUBEDIT.  It may have a COFF image plus data appended to it.

    11

    12

* Notice to users that they have the right to receive the source code and/or

    13

  binary updates for CWSDPMI.  Distributors should indicate a site for the

    14

  source in their documentation.

    15

    16

-------------------------------------------------------------------------------

    17

    18

CWSDPMI was written to provide DPMI services for V2 of DJGPP.  It currently

    19

does not support 16-bit DPMI applications, or DPMI applications requiring a

    20

built in extender.  It does support virtual memory and hardware interrupt

    21

reflection from real mode to protected mode.  DJGPP V1.1x and RSX applications

    22

will also run using this server, which can be used to provide enhanced control

    23

over hardware interrupts.  Some DPMI 1.0 extensions (0x506, 0x507, 0x508) have

    24

been implemented.

    25

    26

CWSDPR0.EXE is an alternate version which runs at ring 0 with virtual memory

    27

disabled.  It may be used if access to ring-0 features are desired.  It

    28

currently does not switch stacks on HW interrupts, so some DJGPP features

    29

such as SIGINT and SIGFPE are not supported and will generate a double fault

    30

or stack fault error (to be fixed someday).

    31

    32

CWSDSTUB.EXE is a stub loader image for DJGPP which includes CWSDPMI.  This

    33

allows single executable image distributions.  You can use the EXE2COFF

    34

program and COPY /B CWSDSTUB.EXE+yourimage yourimage.exe to create a

    35

standalone executable image.

    36

    37

Some of the internal tuning and configuration parameters may be modified

    38

in the image using CWSPARAM.EXE (see CWSPARAM.DOC).

    39

    40

If you want to use CWSDPMI with DJGPP, you expand the distribution into the

    41

DJGPP directory tree.  CWSDPMI.EXE will be put in the BIN directory with your

    42

DJGPP images and it will automatically be loaded when they run.

    43

    44

Directions for use (server can be used in either of two different ways):

    45

    46

1) "cwsdpmi" alone with no parameters will terminate and stay resident

    47

   FOR A SINGLE DPMI PROCESS.  This means it unloads itself when your

    48

   DPMI application exits.  This mode is useful in software which needs

    49

   DPMI services, since CWSDPMI can be exec'ed and then will unload on exit.

    50

    51

2) "cwsdpmi -p" will terminate and stay resident until you remove it.

    52

   It can be loaded into UMBs with LH.  "cwsdpmi -u" will unload the TSR.

    53

    54

3) The file used for virtual memory swapping, if desired, is controlled

    55

   by the "-sc:\cwsdpmi.swp" syntax on the command line.  You must specify

    56

   either a file with full disk/directory syntax, or "-s-" which disables

    57

   virtual memory.

    58

    59

4) The default swap file name is c:\cwsdpmi.swp, but this can be changed

    60

   with the CWSPARAM image, as can some other parameters.

    61

    62

5) You can disable the DPMI 1.0 extensions by starting the image with the

    63

   "cwsdpmi -x" syntax.  This feature allows you to run programs developed

    64

   under other DPMI providers which do not behave properly with these

    65

   extensions enabled (typically use of NULL pointers).

    66

    67

I would like to give special thanks to DJ Delorie who wrote the original

    68

GO32 code on which CWSDPMI is based.  Morten Welinder also provided and

    69

improved much of the code in this program.

    70

    71

-------------------------------------------------------------------------------

    72

    73

This section contains a list of the error messages you might see out of

    74

CWSDPMI and some details on what they mean.

    75

    76

Exceptions are only handled by CWSDPMI if the application does not establish

    77

an exception handler, exceptions nest 5 deep, or the error is particularly bad:

    78

    79

"Page fault" -

    80

  1) an illegal page fault happens in a RMCB or HW interrupt, (lock all pages!)

    81

  2) all available pages have been locked,

    82

  3) the application is using non-committed pages for null pointer protection.

    83

"Double Fault" - multiple exceptions occurred

    84

"Invalid TSS" - typically due to RMCB or HW interrupt being called after the

    85

   selectors/memory have been deallocated (remember to reset the mouse)

    86

"General Protection Fault" - bad parameter sent to a DPMI call

    87

    88

"80386 required."

    89

    90

Since 80286 and lesser processors don't have the hardware necessary to

    91

run CWSDPMI.  No workaround, upgrade.

    92

    93

"DOS 3 required."

    94

    95

A few interrupts are used which need DOS 3.0 or higher.  I don't expect to

    96

ever see this message, since 80386 machines were introduced after DOS 3.0

    97

and that check is made first.

    98

    99

"CWSDPMI V0.90+ (r5) Copyright (C) 2000 CW Sandmann  ABSOLUTELY NO WARRANTY"

   100

   101

An informational message displayed if the program is not run in one-pass mode.

   102

   103

"Protected mode not accessible."

   104

   105

This message should only be displayed if running CWSDPMI in a protected

   106

environment with no access to protected mode.  In this case, DPMI should

   107

already be available and CWSDPMI would not be needed.  This might happen if

   108

a 16-bit DPMI client is loaded and a DJGPP image attempts to load CWSDPMI

   109

to provide 32-bit DPMI services under Windows.

   110

   111

"Warning: cannot open swap file c:\cwsdpmi.swp"

   112

   113

Maybe you are out of file handles, or the swap file name is incorrectly

   114

specified in the image (change the name with cwsparam).

   115

   116

"No swap space!"

   117

   118

This message means you tried to use more paging file than CWSDPMI was

   119

configured to handle.  Since this is protected against in the memory

   120

allocation code, you should never see this message.

   121

   122

"Swap disk full!"

   123

   124

This means the paging file could not be expanded when trying to page

   125

memory out to disk.  This would normally not be seen, unless you are

   126

writing output to the same disk which holds the paging file.  Decrease

   127

the amount of memory your DPMI application is using or free up disk space.

   128

   129

"Interrupt 0x??"

   130

   131

Your application tried to call an interrupt from protected mode which

   132

normally shouldn't be called (something like a data pointer).  If the

   133

request was allowed to continue it would likely hang your machine.  If you

   134

see this message and think the interrupt should be allowed to continue, let

   135

me know.

   136

   137

"Error: Using XMS switched CPU into V86 mode."

   138

   139

This message might be seen if you have your memory manager in AUTO mode.  The

   140

only workaround in this case is to stop using AUTO mode.

   141

   142

"Error: could not allocate page table memory"

   143

   144

The page table memory (a minimum of 16Kb) is allocated from conventional

   145

memory (either in the 640Kb region or UMBs).  If CWSDPMI cannot allocate the

   146

minimum necessary memory, you would see this message.  Free up some

   147

conventional memory.  You may also see this message if a page directory needs

   148

to be faulted in, and there are no available pages.  This means too many pages

   149

have been locked for the allocated page tables available.  While CWSDPMI

   150

tries to dynamically allocate these if needed, this effort failed.  You need

   151

to increase the number of page tables with CWSPARAM, or increase the amount

   152

of free conventional memory if it is low.  If the application which calls

   153

CWSDPMI internally manages all the DOS memory, the page tables may need to

   154

be pre-allocated at DPMI startup time (if this is needed, try using the

   155

run option flag 2 in cwsparam).

   156

   157

"16-bit DPMI unsupported."

   158

   159

CWSDPMI is a 32-bit only DPMI server.  Ideally, on the request to enter DPMI's

   160

PM with a 16-bit request, we would just fail the call setting the carry bit

   161

like the DPMI specification describes.  Some buggy 16-bit compiler tools don't

   162

check the return status and will hang the machine in this case.  So, I issue

   163

an error message and exit the image instead.

   164

   165

"Descriptors exhausted."

   166

   167

An attempt to nest a DPMI client failed in the setup phase due to insufficient

   168

free selectors in the LDT.

   169

   170

"CWSDPMI not removed"

   171

   172

When the -u parameter is specified, if DPMI is not detected this message is

   173

printed.  Informational.