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 DEBUG MESSAGES:
  61
  62 To display a message only during debugging, you normally write something
  63 like this:
  64
  65 #ifdef DEBUG_WIN
  66         printf("abc...");
  67 #endif
  68
  69 You can write this shorter (and better) in this way:
  70
  71         dprintf_win(stddeb,"abc...");
  72
  73 All symbols of the form dprintf_xxxx are macros defined in include/debug.h .
  74 The macro-definitions are generated by the shell-script tools/make_debug. It
  75 scans the source code for symbols of this forms and puts the necessary
  76 macro definitions in include/debug.h and include/stddebug.h . These macros
  77 test for the symbol DEBUG_XXXX (e.g. dprintf_win refers to DEBUG_WIN) being
  78 defined and thus decided whether to actually display the text. If you want
  79 to enable specific types of messages, simply put the corresponding
  80 #define DEBUG_XXXX in include/stddebug.h . If you want to enable or disable
  81 a specific type of message in just one c-source-file, put the corresponding
  82 #define DEBUG_XXXX or #undefine DEBUG_XXXX between #include<stddebug.h> and
  83 #include <debug.h> in that specific file. In addition you can change the
  84 types of displayed messages by supplying the "-debugmsg" option to Wine.
  85 If your debugging code is more complex than just printf, you can use the
  86 symbols debugging_XXX as well. These are true when XXX is enabled, either
  87 permanent or in the command line. So instead of writing
  88
  89 #ifdef DEBUG_WIN
  90         DumpSomeStructure(&str);
  91 #endif
  92
  93 write
  94         if(debugging_win)DumpSomeStructure(&str);
  95 Don't worry about the inefficiency of the test. If it is permanently
  96 disabled (thus debugging_win is 0 at compile time), the compiler will
  97 eliminate the dead code.
  98
  99 The file handle "stddeb" is intended for displaying standard informational
 100 messages, whereas "stdnimp" is intended for displaying messages concerning
 101 not yet implemented functions.
 102
 103 You have to start tools/make_debug only if you introduced a new macro,
 104 e.g.  dprintf_win32s - not if you just changed one of the #define
 105 DEBUG_XXX's in include/stddebug.h or in a specific file.