| 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 | |
| BOOL WINAPI PolyBezierTo(HDC, LPCVOID, DWORD); | |
| If the function has both an ASCII and a Unicode version, you need to | |
| define both and add a #define WINELIB_NAME_AW declaration. 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) PolyBezierTo | |
| The 'PolyBezierTo' 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 'PolyBezierTo' 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. | |
| /************************************************************ | |
| * PolyBezierTo (GDI32.269) Draw many Bezier curves | |
| * | |
| * BUGS | |
| * Unimplemented | |
| */ | |
| BOOL WINAPI PolyBezierTo(HDC 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 Win16 version, | |
| - 'xxx' for the Win32 version when no ASCII/Unicode strings are | |
| involved, | |
| - 'xxxA' for the Win32 version with ASCII strings, | |
| - 'xxxW' for the Win32 version with Unicode strings. | |
| If the function has both ASCII and Unicode version, 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 ASCII or Unicode version. | |
| If 'xxx' is the same in Win16 and Win32, you can simply use the same | |
| name as Windows, i.e. just 'xxx'. If 'xxx' is Win16 only, you could | |
| use the name as is, but it's preferable to use 'xxx16' to make it | |
| clear it is a Win16 function. | |
| Examples: | |
| typedef struct { /* Win32 ASCII data structure */ } WNDCLASSA; | |
| typedef struct { /* Win32 Unicode data structure */ } WNDCLASSW; | |
| typedef struct { /* Win16 data structure */ } WNDCLASS16; | |
| DECL_WINELIB_TYPE_AW(WNDCLASS); | |
| ATOM RegisterClass16( WNDCLASS16 * ); | |
| ATOM RegisterClassA( WNDCLASSA * ); | |
| ATOM RegisterClassW( WNDCLASSW * ); | |
| #define RegisterClass WINELIB_NAME_AW(RegisterClass) | |
| The Winelib user can then say: | |
| WNDCLASS wc = { ... }; | |
| RegisterClass( &wc ); | |
| and this will use the correct declaration depending on the definition | |
| of the UNICODE symbol. | |
| 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 :-) | |