DEVELOPERS-HINTS

   1 This is intended to be a document to help new developers get started.
   2 Existing developers should feel free to add their comments.
   3
   4 MEMORY AND SEGMENTS:
   5
   6 NE (Win16) executables consist of multiple segments.  The Wine loader
   7 loads each segment into a unique location in the Wine processes memory
   8 and assigns a selector to that segment.  Because of this, it's not
   9 possible to exchange addresses freely between 16-bit and 32-bit code.
  10 Addresses used by 16-bit code are segmented addresses (16:16), formed
  11 by a 16-bit selector and a 16-bit offset.  Those used by the Wine code
  12 are regular 32-bit linear addresses.
  13
  14 There's three ways to obtain a segmented pointer:
  15   - Allocate a block of memory from the global heap and use
  16     WIN16_GlobalLock to get its segmented address.
  17   - Allocate a block of memory from a local heap, and build the
  18     segmented address from the local heap selector (see the
  19     USER_HEAP_* macros for an example of this).
  20   - Declare the argument as 'segptr' instead of 'ptr' in the spec file
  21     for a given API function.
  22
  23 Once you have a segmented pointer, it must be converted to a linear
  24 pointer before you can use it from 32-bit code.  This can be done with
  25 the PTR_SEG_TO_LIN() and PTR_SEG_OFF_TO_LIN() macros.  The linear
  26 pointer can then be used freely with standard Unix functions like
  27 memcpy() etc. without worrying about 64k boundaries.  Note: there's no
  28 easy way to convert back from a linear to a segmented address.
  29
  30 In most cases, you don't need to worry about segmented address, as the
  31 conversion is made automatically by the callback code and the API
  32 functions only see linear addresses. However, in some cases it is
  33 necessary to manipulate segmented addresses; the most frequent cases
  34 are:
  35   - API functions that return a pointer
  36   - lParam of Windows messages that point to a structure
  37   - Pointers contained inside structures accessed by 16-bit code.
  38
  39 It is usually a good practice to used the type 'SEGPTR' for segmented
  40 pointers, instead of something like 'LPSTR' or 'char *'.  As SEGPTR is
  41 defined as a DWORD, you'll get a compilation warning if you mistakenly
  42 use it as a regular 32-bit pointer.
  43
  44 API ENTRY POINTS:
  45
  46 Because Win16 programs use a 16-bit stack and because they can only
  47 call 16:16 addressed functions, all API entry points must be at low
  48 address offsets and must have the arguments translated and moved to
  49 Wines 32-bit stack.  This task is handled by the code in the "if1632"
  50 directory.  To define a new API entry point handler you must place a
  51 new entry in the appropriate API specification file.  These files are
  52 named *.spec.  For example, the API specification file for the USER DLL
  53 is contained in the file user.spec.  These entries are processed by
  54 the "build" program to create dll_*.s and dll_tab_*.c.  The dll_*.s
  55 files contain the entry point code for each API call, and the dll_tab_*.s
  56 files contain tables used by relay.c to translate arguments and transfer
  57 control to the proper handler.  The format of the *.spec files is
  58 documented in the file "tools/build-spec.txt".
  59
  60 REGISTER FUNCTIONS:
  61
  62 Some functions are defined as type "register" in the DLL specification files.
  63 In order to return values in the registers to the WIN16 program, the handler
  64 function must exit by calling ReturnFromRegisterFunc().  Look at the function
  65 DOS3Call() for an example of how this works.
  66
  67 DEBUG MESSAGES:
  68
  69 To display a message only during debugging, you normally write something
  70 like this:
  71
  72 #ifdef DEBUG_WIN
  73         printf("abc...");
  74 #endif
  75
  76 You can write this shorter (and better) in this way:
  77
  78         dprintf_win(stddeb,"abc...");
  79
  80 All symbols of the form dprintf_xxxx are macros defined in include/debug.h .
  81 The macro-definitions are generated by the shell-script tools/make_debug. It
  82 scans the source code for symbols of this forms and puts the necessary
  83 macro definitions in include/debug.h and include/stddebug.h . These macros
  84 test for the symbol DEBUG_XXXX (e.g. dprintf_win refers to DEBUG_WIN) being
  85 defined and thus decided whether to actually display the text. If you want
  86 to enable specific types of messages, simply put the corresponding
  87 #define DEBUG_XXXX in include/stddebug.h . If you want to enable or disable
  88 a specific type of message in just one c-source-file, put the corresponding
  89 #define DEBUG_XXXX or #undefine DEBUG_XXXX between #include<stddebug.h> and
  90 #include <debug.h> in that specific file. In addition you can change the
  91 types of displayed messages by supplying the "-debugmsg" option to Wine.
  92 If your debugging code is more complex than just printf, you can use the
  93 symbols debugging_XXX as well. These are true when XXX is enabled, either
  94 permanent or in the command line. So instead of writing
  95
  96 #ifdef DEBUG_WIN
  97         DumpSomeStructure(&str);
  98 #endif
  99
 100 write
 101         if(debugging_win)DumpSomeStructure(&str);
 102 Don't worry about the inefficiency of the test. If it is permanently
 103 disabled (thus debugging_win is 0 at compile time), the compiler will
 104 eliminate the dead code.
 105
 106 The file handle "stddeb" is intended for displaying standard informational
 107 messages, whereas "stdnimp" is intended for displaying messages concerning
 108 not yet implemented functions.
 109
 110 You have to start tools/make_debug only if you introduced a new macro,
 111 e.g.  dprintf_win32s - not if you just changed one of the #define
 112 DEBUG_XXX's in include/stddebug.h or in a specific file.