DEVELOPERS-HINTS

   1 This is intend to be a document to help new developers get started.
   2 Existing developers should feel free to add there comments.
   3
   4 RESERVING WINE PROJECT ARES:
   5
   6 If you wish to work on a specific set of API functions.  Send
   7 mail to wine-project@amscons.com.  The automatic mail handler
   8 will provide you with instructions.
   9
  10 SUBMITTING YOUR WORK:
  11
  12 Submissions of code for inclussion into Wine should be sent to
  13 bob@amscons.com (Bob Amstadt).  You MUST provide a suitable
  14 ChangeLog entry for any work that you submit.  I prefer new code
  15 to be submitted as diffs off of the latest release.  Releases are
  16 every Tuesday evening (approximately 19:00 PST or Wednesday 03:00 GMT).
  17
  18 MEMORY AND SEGMENTS:
  19
  20 NE (Win16) executables consist of multiple segments.  The Wine loader
  21 loads each segment into a unique location the Wine processes memory
  22 and assigns a selector to that segment.  To make address conversion
  23 simpler, Wine loads the segments in such a way that the segmented
  24 address (16:16) is stored in memory the same way as the 32-bit linear
  25 address.  For example, the segmented address 1237:89AB can be at the
  26 address 0x123789AB in the Wine process space.
  27
  28 This also implies that a Win16 program cannot access any arbitrary
  29 memory location.  If a pointer needs to be returned to a Win16 program,
  30 then the memory block must be allocated using either GlobalAlloc()
  31 or HEAP_Alloc().  The HEAP_* functions are faster than the Global*
  32 functions but are only capable of managing a 64k memory block.  The
  33 HEAP_* functions are used to implement local heaps.  Wine should
  34 never call Local* functions.  These functions are reserved for use
  35 by Win16 programs only!
  36
  37 The following code fragment should be used to establish a new Wine
  38 local heap:
  39
  40         #include "heap.h"
  41
  42         #define MY_HEAP_SIZE    0x10000         /* Must be <= 64k */
  43
  44         int MyHeapHandle;
  45         void *MyHeapBase;
  46         MDESC *MyHeap;
  47
  48                 ...
  49
  50         int InitMyHeap()
  51         {
  52             MyHeapHandle = GlobalAlloc(GMEM_FIXED, MY_HEAP_SIZE);
  53             if (MyHeapHandle == 0)
  54                 return -1;
  55             MyHeapBase = GlobalLock(MyHeapHandle);
  56             HEAP_Init(&MyHeap, MyHeapBase, MY_HEAP_SIZE);
  57             return 0;
  58         }
  59
  60 Memory blocks greater than 64 kilobytes in length must be allocated
  61 using GlobalAlloc().  Because of our special memory mapping, GlobalLock()
  62 cannot be used to obtain the address of a linearly accessible memory
  63 block that is greater than 64kB in length.  Instead GlobalLinearLock()
  64 should be used.  The inverse function GlobalLinearUnlock() must be
  65 called before the block can be freed with GlobalFree().
  66
  67 API ENTRY POINTS:
  68
  69 Because Win16 programs use a 16-bit stack and because they can only
  70 call 16:16 addressed functions, all API entry points must be at low
  71 address offsets and must have the arguments translated and moved to
  72 Wines 32-bit stack.  This task is handled by the code in the "if1632"
  73 directory.  To define a new API entry point handler you must place a
  74 new entry in the appropriate API specification file.  These files are
  75 named *.spec.  For example, the API specification file for the USER DLL
  76 is contained in the file user.spec.  These entries are processed by
  77 the "build" program to create dll_*.s and dll_tab_*.c.  The dll_*.s
  78 files contain the entry point code for each API call, and the dll_tab_*.s
  79 files contain tables used by relay.c to translate arguments and transfer
  80 control to the proper handler.  The format of the *.spec files is
  81 documented in the file "tools/build-spec.txt".