DEVELOPERS-HINTS

   1 This is intend 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 the Wine processes memory
   8 and assigns a selector to that segment.  To make address conversion
   9 simpler, Wine loads the segments in such a way that the segmented
  10 address (16:16) is stored in memory the same way as the 32-bit linear
  11 address.  For example, the segmented address 1237:89AB can be at the
  12 address 0x123789AB in the Wine process space.
  13
  14 This also implies that a Win16 program cannot access any arbitrary
  15 memory location.  If a pointer needs to be returned to a Win16 program,
  16 then the memory block must be allocated using either GlobalAlloc()
  17 or HEAP_Alloc().  The HEAP_* functions are faster than the Global*
  18 functions but are only capable of managing a 64k memory block.  The
  19 HEAP_* functions are used to implement local heaps.  Wine should
  20 never call Local* functions.  These functions are reserved for use
  21 by Win16 programs only!
  22
  23 The following code fragment should be used to establish a new Wine
  24 local heap:
  25
  26         #include "heap.h"
  27
  28         #define MY_HEAP_SIZE    0x10000         /* Must be <= 64k */
  29
  30         int MyHeapHandle;
  31         void *MyHeapBase;
  32         MDESC *MyHeap;
  33
  34                 ...
  35
  36         int InitMyHeap()
  37         {
  38             MyHeapHandle = GlobalAlloc(GMEM_FIXED, MY_HEAP_SIZE);
  39             if (MyHeapHandle == 0)
  40                 return -1;
  41             MyHeapBase = GlobalLock(MyHeapHandle);
  42             HEAP_Init(&MyHeap, MyHeapBase, MY_HEAP_SIZE);
  43             return 0;
  44         }
  45
  46 Memory blocks greater than 64 kilobytes in length must be allocated
  47 using GlobalAlloc().  Because of our special memory mapping, GlobalLock()
  48 cannot be used to obtain the address of a linearly accessible memory
  49 block that is greater than 64kB in length.  Instead GlobalLinearLock()
  50 should be used.  The inverse function GlobalLinearUnlock() must be
  51 called before the block can be freed with GlobalFree().
  52
  53 API ENTRY POINTS:
  54
  55 Because Win16 programs use a 16-bit stack and because they can only
  56 call 16:16 addressed functions, all API entry points must be at low
  57 address offsets and must have the arguments translated and moved to
  58 Wines 32-bit stack.  This task is handled by the code in the "if1632"
  59 directory.  To define a new API entry point handler you must place a
  60 new entry in the appropriate API specification file.  These files are
  61 named *.spec.  For example, the API specification file for the USER DLL
  62 is contained in the file user.spec.  These entries are processed by
  63 the "build" program to create dll_*.s and dll_tab_*.c.  The dll_*.s
  64 files contain the entry point code for each API call, and the dll_tab_*.s
  65 files contain tables used by relay.c to translate arguments and transfer
  66 control to the proper handler.  The format of the *.spec files is
  67 documented in the file "tools/build-spec.txt".
  68
  69 REGISTER FUNCTIONS:
  70
  71 Some functions are defined as type "register" in the DLL specification files.
  72 Inorder to return values in the registers to the WIN16 program, the handler
  73 function must exit by calling ReturnFromRegisterFunc().  Look at the function
  74 DOS3Call() for an example of how this works.
  75
  76 DEBUG MESSAGES:
  77
  78 To display a message only during debugging, you normally write something
  79 like this:
  80
  81 #ifdef DEBUG_WIN
  82         printf("abc...");
  83 #endif
  84
  85 You can write this shorter (and better) in this way:
  86
  87         dprintf_win(stddeb,"abc...");
  88
  89 All symbols of the form dprintf_xxxx are macros defined in include/debug.h .
  90 The macro-definitions are generated by the shell-script tools/make_debug. It
  91 scans the source code for symbols of this forms and puts the necessary
  92 macro definitions in include/debug.h and include/stddebug.h . These macros
  93 test for the symbol DEBUG_XXXX (e.g. dprintf_win refers to DEBUG_WIN) being
  94 defined and thus decided whether to actually display the text. If you want
  95 to enable specific types of messages, simply put the corresponding
  96 #define DEBUG_XXXX in include/stddebug.h . If you want to enable or disable
  97 a specific type of message in just one c-source-file, put the corresponding
  98 #define DEBUG_XXXX or #undefine DEBUG_XXXX between #include<stddebug.h> and
  99 #include <debug.h> in that specific file. In addition you can change the
 100 types of displayed messages by supplying the "-debugmsg" option to Wine.
 101 If your debugging code is more complex than just printf, you can use the
 102 symbols debugging_XXX as well. These are true when XXX is enabled, either
 103 permanent or in the command line. So instead of writing
 104
 105 #ifdef DEBUG_WIN
 106         DumpSomeStructure(&str);
 107 #endif
 108
 109 write
 110         if(debugging_win)DumpSomeStructure(&str);
 111 Don't worry about the inefficiency of the test. If it is permanently
 112 disabled (thus debugging_win is 0 at compile time), the compiler will
 113 eliminate the dead code.
 114
 115 The file handle "stddeb" is intended for displaying standard informational
 116 messages, whereas "stdnimp" is intended for displaying messages concerning
 117 not yet implemented functions.
 118
 119 You have to start tools/make_debug only if you introduced a new macro,
 120 e.g.  dprintf_win32s - not if you just changed one of the #define
 121 DEBUG_XXX's in include/stddebug.h or in a specific file.