106 lines
4.9 KiB
Plaintext
106 lines
4.9 KiB
Plaintext
This is intended to be a document to help new developers get started.
|
|
Existing developers should feel free to add their comments.
|
|
|
|
MEMORY AND SEGMENTS:
|
|
|
|
NE (Win16) executables consist of multiple segments. The Wine loader
|
|
loads each segment into a unique location in the Wine processes memory
|
|
and assigns a selector to that segment. Because of this, it's not
|
|
possible to exchange addresses freely between 16-bit and 32-bit code.
|
|
Addresses used by 16-bit code are segmented addresses (16:16), formed
|
|
by a 16-bit selector and a 16-bit offset. Those used by the Wine code
|
|
are regular 32-bit linear addresses.
|
|
|
|
There's three ways to obtain a segmented pointer:
|
|
- Allocate a block of memory from the global heap and use
|
|
WIN16_GlobalLock to get its segmented address.
|
|
- Allocate a block of memory from a local heap, and build the
|
|
segmented address from the local heap selector (see the
|
|
USER_HEAP_* macros for an example of this).
|
|
- Declare the argument as 'segptr' instead of 'ptr' in the spec file
|
|
for a given API function.
|
|
|
|
Once you have a segmented pointer, it must be converted to a linear
|
|
pointer before you can use it from 32-bit code. This can be done with
|
|
the PTR_SEG_TO_LIN() and PTR_SEG_OFF_TO_LIN() macros. The linear
|
|
pointer can then be used freely with standard Unix functions like
|
|
memcpy() etc. without worrying about 64k boundaries. Note: there's no
|
|
easy way to convert back from a linear to a segmented address.
|
|
|
|
In most cases, you don't need to worry about segmented address, as the
|
|
conversion is made automatically by the callback code and the API
|
|
functions only see linear addresses. However, in some cases it is
|
|
necessary to manipulate segmented addresses; the most frequent cases
|
|
are:
|
|
- API functions that return a pointer
|
|
- lParam of Windows messages that point to a structure
|
|
- Pointers contained inside structures accessed by 16-bit code.
|
|
|
|
It is usually a good practice to used the type 'SEGPTR' for segmented
|
|
pointers, instead of something like 'LPSTR' or 'char *'. As SEGPTR is
|
|
defined as a DWORD, you'll get a compilation warning if you mistakenly
|
|
use it as a regular 32-bit pointer.
|
|
|
|
API ENTRY POINTS:
|
|
|
|
Because Win16 programs use a 16-bit stack and because they can only
|
|
call 16:16 addressed functions, all API entry points must be at low
|
|
address offsets and must have the arguments translated and moved to
|
|
Wines 32-bit stack. This task is handled by the code in the "if1632"
|
|
directory. To define a new API entry point handler you must place a
|
|
new entry in the appropriate API specification file. These files are
|
|
named *.spec. For example, the API specification file for the USER DLL
|
|
is contained in the file user.spec. These entries are processed by
|
|
the "build" program to create dll_*.s and dll_tab_*.c. The dll_*.s
|
|
files contain the entry point code for each API call, and the dll_tab_*.s
|
|
files contain tables used by relay.c to translate arguments and transfer
|
|
control to the proper handler. The format of the *.spec files is
|
|
documented in the file "tools/build-spec.txt".
|
|
|
|
DEBUG MESSAGES:
|
|
|
|
To display a message only during debugging, you normally write something
|
|
like this:
|
|
|
|
#ifdef DEBUG_WIN
|
|
printf("abc...");
|
|
#endif
|
|
|
|
You can write this shorter (and better) in this way:
|
|
|
|
dprintf_win(stddeb,"abc...");
|
|
|
|
All symbols of the form dprintf_xxxx are macros defined in include/debug.h .
|
|
The macro-definitions are generated by the shell-script tools/make_debug. It
|
|
scans the source code for symbols of this forms and puts the necessary
|
|
macro definitions in include/debug.h and include/stddebug.h . These macros
|
|
test for the symbol DEBUG_XXXX (e.g. dprintf_win refers to DEBUG_WIN) being
|
|
defined and thus decided whether to actually display the text. If you want
|
|
to enable specific types of messages, simply put the corresponding
|
|
#define DEBUG_XXXX in include/stddebug.h . If you want to enable or disable
|
|
a specific type of message in just one c-source-file, put the corresponding
|
|
#define DEBUG_XXXX or #undefine DEBUG_XXXX between #include<stddebug.h> and
|
|
#include <debug.h> in that specific file. In addition you can change the
|
|
types of displayed messages by supplying the "-debugmsg" option to Wine.
|
|
If your debugging code is more complex than just printf, you can use the
|
|
symbols debugging_XXX as well. These are true when XXX is enabled, either
|
|
permanent or in the command line. So instead of writing
|
|
|
|
#ifdef DEBUG_WIN
|
|
DumpSomeStructure(&str);
|
|
#endif
|
|
|
|
write
|
|
if(debugging_win)DumpSomeStructure(&str);
|
|
Don't worry about the inefficiency of the test. If it is permanently
|
|
disabled (thus debugging_win is 0 at compile time), the compiler will
|
|
eliminate the dead code.
|
|
|
|
The file handle "stddeb" is intended for displaying standard informational
|
|
messages, whereas "stdnimp" is intended for displaying messages concerning
|
|
not yet implemented functions.
|
|
|
|
You have to start tools/make_debug only if you introduced a new macro,
|
|
e.g. dprintf_win32s - not if you just changed one of the #define
|
|
DEBUG_XXX's in include/stddebug.h or in a specific file.
|