| This document should help new developers get started. Like all of Wine, it |
| is a work in progress. |
| |
| SOURCE TREE STRUCTURE |
| ===================== |
| |
| The Wine source tree is loosely based on the original Windows modules. |
| Most of the source is concerned with implementing the Wine API, although |
| there are also various tools, documentation, sample Winelib code, and |
| code specific to the binary loader. |
| |
| Wine API directories: |
| --------------------- |
| |
| KERNEL: |
| |
| files/ - file I/O |
| loader/ - Win16-, Win32-binary loader |
| memory/ - memory management |
| msdos/ - DOS features and BIOS calls (interrupts) |
| scheduler/ - process and thread management |
| |
| GDI: |
| |
| graphics/ - graphics drivers |
| graphics/x11drv/ - X11 display driver |
| graphics/metafiledrv/ - metafile driver |
| objects/ - logical objects |
| |
| USER: |
| |
| controls/ - built-in widgets |
| resources/ - built-in dialog resources |
| windows/ - window management |
| |
| Other DLLs: |
| |
| dlls/*/ - Other system DLLs implemented by Wine |
| |
| Miscellaneous: |
| |
| misc/ - shell, registry, winsock, etc. |
| multimedia/ - multimedia driver |
| ipc/ - SysV IPC based interprocess communication |
| win32/ - misc Win32 functions |
| |
| Tools: |
| ------ |
| |
| rc/ - old resource compiler |
| tools/ - relay code builder, new rc, etc. |
| documentation/ - some documentation |
| |
| |
| Binary loader specific directories: |
| ----------------------------------- |
| |
| debugger/ - built-in debugger |
| if1632/ - relay code |
| miscemu/ - hardware instruction emulation |
| graphics/win16drv/ - Win16 printer driver |
| |
| Winelib specific directories: |
| ----------------------------- |
| |
| library/ - Required code for programs using Winelib |
| libtest/ - Small samples and tests |
| programs/ - Extended samples / system utilities |
| |
| IMPLEMENTING NEW API CALLS |
| ========================== |
| |
| This is the simple version, and covers only Win32. Win16 is slightly uglier, |
| because of the Pascal heritage and the segmented memory model. |
| |
| All of the Win32 APIs known to Wine are listed in [relay32/*.spec]. An |
| unimplemented call will look like (from gdi32.spec) |
| 269 stub PolyBezierTo |
| To implement this call, you need to do the following four things. |
| |
| 1. Find the appropriate parameters for the call, and add a prototype to |
| [include/windows.h]. In this case, it might look like |
| BOOL32 WINAPI PolyBezierTo32(HDC32, LPCVOID, DWORD); |
| #define PolyBezierTo WINELIB_NAME(PolyBezierTo) |
| Note the use of the #define for Winelib. See below for discussion of |
| function naming conventions. |
| |
| 2. Modify the .spec file to tell Wine that the function has an |
| implementation, what the parameters look like and what Wine function |
| to use for the implementation. In Win32, things are simple--everything |
| is 32-bits. However, the relay code handles pointers and pointers to |
| strings slightly differently, so you should use 'str' and 'wstr' for |
| strings, 'ptr' for other pointer types, and 'long' for everything else. |
| 269 stdcall PolyBezierTo(long ptr long) PolyBezierTo32 |
| The 'PolyBezierTo32' at the end of the line is which Wine function to use |
| for the implementation. |
| |
| 3. Implement the function as a stub. Once you add the function to the .spec |
| file, you must add the function to the Wine source before it will link. |
| Add a function called 'PolyBezierTo32' somewhere. Good things to put |
| into a stub: |
| o a correct prototype, including the WINAPI |
| o header comments, including full documentation for the function and |
| arguments |
| o A FIXME message and an appropriate return value are good things to |
| put in a stub. |
| |
| /************************************************************ |
| * PolyBezierTo32 (GDI32.269) Draw many Bezier curves |
| * |
| * BUGS |
| * Unimplemented |
| */ |
| BOOL32 WINAPI PolyBezierTo32(HDC32 hdc, LPCVOID p, DWORD count) { |
| /* tell the user they've got a substandard implementation */ |
| FIXME(gdi, ":(%x,%p,%d): stub\n", hdc, p, count); |
| /* some programs may be able to compensate, |
| if they know what happened */ |
| SetLastError(ERROR_CALL_NOT_IMPLEMENTED); |
| return FALSE; /* error value */ |
| } |
| |
| 4. Implement and test the function. |
| |
| 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 are four ways to obtain a segmented pointer: |
| - Use the SEGPTR_* macros in include/heap.h (recommended). |
| - 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. |
| |
| |
| STRUCTURE PACKING |
| ================= |
| |
| Under Windows, data structures are tightly packed, i.e. there is no |
| padding between structure members. On the other hand, by default gcc |
| aligns structure members (e.g. WORDs are on a WORD boundary, etc.). |
| This means that a structure like |
| |
| struct { BYTE x; WORD y; }; |
| |
| will take 3 bytes under Windows, but 4 with gcc, because gcc will add a |
| dummy byte between x and y. To have the correct layout for structures |
| used by Windows code, you need to use the WINE_PACKED attribute; so you |
| would declare the above structure like this: |
| |
| struct { BYTE x; WORD y WINE_PACKED; }; |
| |
| You have to do this every time a structure member is not aligned |
| correctly under Windows (i.e. a WORD not on an even address, or a |
| DWORD on a address that is not a multiple of 4). |
| |
| |
| NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES |
| ============================================== |
| |
| In order to support both Win16 and Win32 APIs within the same source |
| code, the following convention must be used in naming all API |
| functions and types. If the Windows API uses the name 'xxx', the Wine |
| code must use: |
| |
| - 'xxx16' for the 16-bit version, |
| - 'xxx32' for the 32-bit version when no ASCII/Unicode strings are |
| involved, |
| - 'xxx32A' for the 32-bit version with ASCII strings, |
| - 'xxx32W' for the 32-bit version with Unicode strings. |
| |
| You should then use the macros WINELIB_NAME[_AW](xxx) or |
| DECL_WINELIB_TYPE[_AW](xxx) (defined in include/wintypes.h) to define |
| the correct 'xxx' function or type for Winelib. When compiling Wine |
| itself, 'xxx' is _not_ defined, meaning that code inside of Wine must |
| always specify explicitly the 16-bit or 32-bit version. |
| |
| If 'xxx' is the same in Win16 and Win32, or if 'xxx' is Win16 only, |
| you can simply use the same name as Windows, i.e. just 'xxx'. If |
| 'xxx' is Win32 only, you can use 'xxx' if there are no strings |
| involved, otherwise you must use the 'xxx32A' and 'xxx32W' forms. |
| |
| Examples: |
| |
| typedef short INT16; |
| typedef int INT32; |
| DECL_WINELIB_TYPE(INT); |
| |
| typedef struct { /* Win32 ASCII data structure */ } WNDCLASS32A; |
| typedef struct { /* Win32 Unicode data structure */ } WNDCLASS32W; |
| typedef struct { /* Win16 data structure */ } WNDCLASS16; |
| DECL_WINELIB_TYPE_AW(WNDCLASS); |
| |
| ATOM RegisterClass16( WNDCLASS16 * ); |
| ATOM RegisterClass32A( WNDCLASS32A * ); |
| ATOM RegisterClass32W( WNDCLASS32W * ); |
| #define RegisterClass WINELIB_NAME_AW(RegisterClass) |
| |
| The Winelib user can then say: |
| |
| INT i; |
| WNDCLASS wc = { ... }; |
| RegisterClass( &wc ); |
| |
| and this will use the correct declaration depending on the definition |
| of the symbols WINELIB and UNICODE. |
| |
| |
| 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 an assembly file containing the entry |
| point code for each API call. 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: |
| |
| TRACE(win,"abc..."); or |
| FIXME(win,"abc..."); or |
| WARN(win,"abc..."); or |
| ERR(win,"abc..."); |
| |
| depending on the seriousness of the problem. (documentation/degug-msgs |
| explains when it is appropriate to use each of them) |
| |
| These macros are 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/debugdefs.h. These macros |
| test whether the debugging "channel" associated with the first |
| argument of these macros (win in the above example) is enabled and |
| thus decide whether to actually display the text. 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 TRACE_ON(xxx), WARN_ON(xxx), |
| ERR_ON(xxx) and FIXME_ON(xxx) as well. These are true when channel xxx |
| is enabled, either permanent or in the command line. Thus, you can |
| write: |
| |
| if(TRACE_ON(win))DumpSomeStructure(&str); |
| |
| Don't worry about the inefficiency of the test. If it is permanently |
| disabled (that is TRACE_ON(win) is 0 at compile time), the compiler will |
| eliminate the dead code. |
| |
| You have to start tools/make_debug only if you introduced a new macro, |
| e.g. TRACE(win32). |
| |
| For more info about debugging messages, read: |
| |
| documentation/debug-msgs |
| |
| |
| MORE INFO |
| ========= |
| |
| 1. There is a FREE online version of the MSDN library (including |
| documentation for the Win32 API) on http://www.microsoft.com/msdn/ |
| |
| 2. http://www.sonic.net/~undoc/bookstore.html |
| |
| 3. In 1993 Dr. Dobbs Journal published a column called "Undocumented Corner". |
| |
| 4. You might want to check out BYTE from December 1983 as well :-) |
| |