Processes and threads: in underlying OS and in Windows

Before going into the depths of debugging in Wine, here's a small overview of process and thread handling in Wine. It has to be clear that there are two different beasts: processes/threads from the Unix point of view and processes/threads from a Windows point of view.

Each Windows' thread is implemented as a Unix process (under Linux using the clone syscall), meaning that all threads of a same Windows' process share the same (unix) address space.

In the following:

• W-process means a process in Windows' terminology

• U-process means a process in Unix' terminology

• W-thread means a thread in Windows' terminology

A W-process is made of one or several W-threads. Each W-thread is mapped to one and only one U-process. All U-processes of a same W-process share the same address space.

Each Unix process can be identified by two values:

• the Unix process id (upid in the following)

• the Windows's thread id (tid)

Each Windows' process has also a Windows' process id (wpid in the following). It must be clear that upid and wpid are different and shall not be used instead of the other.

Wpid and tid are defined (Windows) system wide. They must not be confused with process or thread handles which, as any handle, is an indirection to a system object (in this case process or thread). A same process can have several different handles on the same kernel object. The handles can be defined as local (the values is only valid in a process), or system wide (the same handle can be used by any W-process).

Wine, debugging and WineDbg

When talking of debugging in Wine, there are at least two levels to think of:

• the Windows' debugging API.

• the Wine integrated debugger, dubbed WineDbg.

Wine implements most of the Windows' debugging API (the part in KERNEL32.DLL, not the one in IMAGEHLP.DLL), and allows any program (emulated or Winelib) using that API to debug a W-process.

WineDbg is a Winelib application making use of this API to allow debugging both any Wine or Winelib applications as well as Wine itself (kernel and all DLLs).

Starting a process

Any application (either a Windows' native executable, or a Winelib application) can be run through WineDbg. Command line options and tricks are the same as for wine:

winedbg telnet.exe
winedbg "hl.exe -windowed"
        

Attaching

WineDbg can also be launched without any command line argument: WineDbg is started without any attached process. You can get a list of running W-processes (and their wpid's) using the walk process command, and then, with the attach command, pick up the wpid of the W-process you want to debug. This is a neat feature as it allows you to debug an already started application.

On exceptions

When something goes wrong, Windows tracks this as an exception. Exceptions exist for segmentation violation, stack overflow, division by zero, etc.

When an exception occurs, Wine checks if the W-process is debugged. If so, the exception event is sent to the debugger, which takes care of it: end of the story. This mechanism is part of the standard Windows' debugging API.

If the W-process is not debugged, Wine tries to launch a debugger. This debugger (normally WineDbg, see III Configuration for more details), at startup, attaches to the W-process which generated the exception event. In this case, you are able to look at the causes of the exception, and either fix the causes (and continue further the execution) or dig deeper to understand what went wrong.

If WineDbg is the standard debugger, the pass and cont commands are the two ways to let the process go further for the handling of the exception event.

To be more precise on the way Wine (and Windows) generates exception events, when a fault occurs (segmentation violation, stack overflow...), the event is first sent to the debugger (this is known as a first chance exception). The debugger can give two answers:

since some of Wine's code uses exceptions and try/catch blocks to provide some functionality, WineDbg can be entered in such cases with segv exceptions. This happens, for example, with IsBadReadPtr function. In that case, the pass command shall be used, to let the handling of the exception to be done by the catch block in IsBadReadPtr.

Interrupting

You can stop the debugger while it's running by hitting Ctrl-C in its window. This will stop the debugged process, and let you manipulate the current context.

Quitting

Wine supports the new XP APIs, allowing for a debugger to detach from a program being debugged (see detach command). Unfortunately, as the debugger cannot, for now, neither clear its internal information, nor restart a new process, the debugger, after detaching itself, cannot do much except being quitted.

Crashes

These usually show up like this:

|Unexpected Windows program segfault - opcode = 8b
|Segmentation fault in Windows program 1b7:c41.
|Loading symbols from ELF file /root/wine/wine...
|....more Loading symbols from ...
|In 16 bit mode.
|Register dump:
| CS:01b7 SS:016f DS:0287 ES:0000
| IP:0c41 SP:878a BP:8796 FLAGS:0246
| AX:811e BX:0000 CX:0000 DX:0000 SI:0001 DI:ffff
|Stack dump:
|0x016f:0x878a:  0001 016f ffed 0000 0000 0287 890b 1e5b
|0x016f:0x879a:  01b7 0001 000d 1050 08b7 016f 0001 000d
|0x016f:0x87aa:  000a 0003 0004 0000 0007 0007 0190 0000
|0x016f:0x87ba:
|
|0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
|Backtrace:
|0 0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c)
|1 0x01b7:0x1e5b (PXSRV_FONPUTCATFONT+0x2cd)
|2 0x01a7:0x05aa
|3 0x01b7:0x0768 (PXSRV_FONINITFONTS+0x81)
|4 0x014f:0x03ed (PDOXWIN_@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
|5 0x013f:0x00ac
|
|0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c):  movw        %es:0x38(%bx),%dx
        

Steps to debug a crash. You may stop at any step, but please report the bug and provide as much of the information gathered to the bug report as feasible.

1. Get the reason for the crash. This is usually an access to an invalid selector, an access to an out of range address in a valid selector, popping a segment register from the stack or the like. When reporting a crash, report this whole crashdump even if it doesn't make sense to you.

   (In this case it is access to an invalid selector, for %es is 0000, as seen in the register dump).

2. Determine the cause of the crash. Since this is usually a primary/secondary reaction to a failed or misbehaving Wine function, rerun Wine with -debugmsg +relay added to the commandline. This will generate quite a lot of output, but usually the reason is located in the last call(s). Those lines usually look like this:

   |Call KERNEL.90: LSTRLEN(0227:0692 "text") ret=01e7:2ce7 ds=0227 ^^^^^^^^^ ^ ^^^^^^^^^ ^^^^^^ ^^^^^^^^^ ^^^^ | | | | | |Datasegment | | | | |Return address | | | |textual parameter | | | | | |Argument(s). This one is a win16 segmented pointer. | |Function called. |The module, the function is called in. In this case it is KERNEL. |Ret KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227 ^^^^^^ |Returnvalue is 16 bit and has the value 4.

3. If you have found a misbehaving function, try to find out why it misbehaves. Find the function in the source code. Try to make sense of the arguments passed. Usually there is a WINE_DEFAULT_DEBUG_CHANNEL(<channel>); at the beginning of the file. Rerun wine with -debugmsg +xyz,+relay added to the commandline.

   Occasionally there are additional debug channels defined at the beginning of the file in the form. WINE_DECLARE_DEBUG_CHANNEL(<channel>); If so the offending function may also uses one of these alternate channels. Look through the the function for TRACE_(<channel>)(" ... /n"); and add any additional channels to the commandline.

4. Additional information on how to debug using the internal debugger can be found in programs/winedbg/README.

5. If this information isn't clear enough or if you want to know more about what's happening in the function itself, try running wine with -debugmsg +all, which dumps ALL included debug information in wine.

6. If even that isn't enough, add more debug output for yourself into the functions you find relevant. See The section on Debug Logging in this guide for more information. You might also try to run the program in gdb instead of using the Wine debugger. If you do that, use handle SIGSEGV nostop noprint to disable the handling of seg faults inside gdb (needed for Win16).

7. You can also set a breakpoint for that function. Start wine useing winedbg instead of wine. Once the debugger is is running enter break KERNEL_LSTRLEN (replace by function you want to debug, CASE IS RELEVANT) to set a breakpoint. Then use continue to start normal program-execution. Wine will stop if it reaches the breakpoint. If the program isn't yet at the crashing call of that function, use continue again until you are about to enter that function. You may now proceed with single-stepping the function until you reach the point of crash. Use the other debugger commands to print registers and the like.

Program hangs, nothing happens

Start the program with winedbg instead of wine. When the program locks up switch to the winedbg terminal and press Ctrl-C. this will stop the program and let you debug the program as you would for a crash.

Program reports an error with a Messagebox

Sometimes programs are reporting failure using more or less nondescript messageboxes. We can debug this using the same method as Crashes, but there is one problem... For setting up a message box the program also calls Wine producing huge chunks of debug code.

Since the failure happens usually directly before setting up the Messagebox you can start winedbg and set a breakpoint at MessageBoxA (called by win16 and win32 programs) and proceed with continue. With --debugmsg +all Wine will now stop directly before setting up the Messagebox. Proceed as explained above.

You can also run wine using wine -debugmsg +relay program.exe 2>&1 | less -i and in less search for "MessageBox".

Disassembling programs:

You may also try to disassemble the offending program to check for undocumented features and/or use of them.

The best, freely available, disassembler for Win16 programs is Windows Codeback, archive name wcbxxx.zip (e.g. wcb105a.zip), which usually can be found in the Cica-Mirror subdirectory on the Wine ftp sites. (See ANNOUNCE).

Disassembling win32 programs is possible using Windows Disassembler 32. Look for a file called w32dsm87.zip (or similar) on http://www.winsite.com and mirrors. The shareware version does not allow saving of disassembly listings. You can also use the newer (and in the full version better) Interactive Disassembler (IDA) from the ftp sites mentioned at the end of the document. Understanding disassembled code is mostly a question of exercise.

Most code out there uses standard C function entries (for it is usually written in C). Win16 function entries usually look like that:

push bp
mov bp, sp
... function code ..
retf XXXX 	<--------- XXXX is number of bytes of arguments
        

This is a FAR function with no local storage. The arguments usually start at [bp+6] with increasing offsets. Note, that [bp+6] belongs to the rightmost argument, for exported win16 functions use the PASCAL calling convention. So, if we use strcmp(a,b) with a and b both 32 bit variables b would be at [bp+6] and a at [bp+10].

Most functions make also use of local storage in the stackframe:

enter 0086, 00
... function code ...
leave
retf XXXX
        

This does mostly the same as above, but also adds 0x86 bytes of stackstorage, which is accessed using [bp-xx]. Before calling a function, arguments are pushed on the stack using something like this:

push word ptr [bp-02]	<- will be at [bp+8]
push di			<- will be at [bp+6]
call KERNEL.LSTRLEN
        

Here first the selector and then the offset to the passed string are pushed.

Sample debugging session:

Let's debug the infamous Word SHARE.EXE messagebox:

|marcus@jet $ wine winword.exe
|            +---------------------------------------------+
|            | !  You must leave Windows and load SHARE.EXE|
|            |    before starting Word.                    |
|            +---------------------------------------------+
        

|marcus@jet $ wine winword.exe -debugmsg +relay -debug
|CallTo32(wndproc=0x40065bc0,hwnd=000001ac,msg=00000081,wp=00000000,lp=00000000)
|Win16 task 'winword': Breakpoint 1 at 0x01d7:0x001a
|CallTo16(func=0127:0070,ds=0927)
|Call WPROCS.24: TASK_RESCHEDULE() ret=00b7:1456 ds=0927
|Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x8672 ret=00b7:1456 ds=0927
|CallTo16(func=01d7:001a,ds=0927)
|     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=0927 BP=0000 ES=11f7
|Loading symbols: /home/marcus/wine/wine...
|Stopped on breakpoint 1 at 0x01d7:0x001a
|In 16 bit mode.
|Wine-dbg>break MessageBoxA                          <---- Set Breakpoint
|Breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|Wine-dbg>c                                            <---- Continue
|Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
|     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
|CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
|...                                                   <----- Much debugoutput
|Call KERNEL.136: GETDRIVETYPE(0x0000) ret=060f:097b ds=0927
                               ^^^^^^ Drive 0 (A:)
|Ret  KERNEL.136: GETDRIVETYPE() retval=0x0002 ret=060f:097b ds=0927
                                        ^^^^^^  DRIVE_REMOVEABLE
						(It is a floppy diskdrive.)

|Call KERNEL.136: GETDRIVETYPE(0x0001) ret=060f:097b ds=0927
                               ^^^^^^ Drive 1 (B:)
|Ret  KERNEL.136: GETDRIVETYPE() retval=0x0000 ret=060f:097b ds=0927
                                        ^^^^^^  DRIVE_CANNOTDETERMINE
						(I don't have drive B: assigned)

|Call KERNEL.136: GETDRIVETYPE(0x0002) ret=060f:097b ds=0927
                               ^^^^^^^ Drive 2 (C:)
|Ret  KERNEL.136: GETDRIVETYPE() retval=0x0003 ret=060f:097b ds=0927
                                        ^^^^^^ DRIVE_FIXED
                                               (specified as a harddisk)

|Call KERNEL.97: GETTEMPFILENAME(0x00c3,0x09278364"doc",0x0000,0927:8248) ret=060f:09b1 ds=0927
                                 ^^^^^^           ^^^^^        ^^^^^^^^^
                                 |                |            |buffer for fname
                                 |                |temporary name ~docXXXX.tmp
                                 |Force use of Drive C:.

|Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writeable.
|Please check your configuration file if this generates a failure.
        

Whoops, it even detects that something is wrong!

|Ret  KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
                                          ^^^^^^ Temporary storage ID

|Call KERNEL.74: OPENFILE(0x09278248"C:~doc9281.tmp",0927:82da,0x1012) ret=060f:09d8 ds=0927
                                    ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
                                    |filename        |OFSTRUCT |open mode:

                                       OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
        

This fails, since my C: drive is in this case mounted readonly.

|Ret  KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
                                   ^^^^^^ HFILE_ERROR16, yes, it failed.

|Call USER.1: MESSAGEBOX(0x0000,0x09278376"You must close Windows and load SHARE.EXE before you start Word.",0x00000000,0x1030) ret=060f:084f ds=0927
        

And MessageBox'ed.

|Stopped on breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|190     {		<- the sourceline
In 32 bit mode.
Wine-dbg>
        

The code seems to find a writeable harddisk and tries to create a file there. To work around this bug, you can define C: as a networkdrive, which is ignored by the code above.

Debugging Tips

Here are some additional debugging tips:

• If you have a program crashing at such an early loader phase that you can't use the Wine debugger normally, but Wine already executes the program's start code, then you may use a special trick. You should do a

  wine --debugmsg +relay program

  to get a listing of the functions the program calls in its start function. Now you do a

  winedbg winfile.exe

  This way, you get into winedbg. Now you can set a breakpoint on any function the program calls in the start function and just type c to bypass the eventual calls of Winfile to this function until you are finally at the place where this function gets called by the crashing start function. Now you can proceed with your debugging as usual.

• If you try to run a program and it quits after showing an error messagebox, the problem can usually be identified in the return value of one of the functions executed before MessageBox(). That's why you should re-run the program with e.g.

  wine --debugmsg +relay <program name> &>relmsg

  Then do a more relmsg and search for the last occurrence of a call to the string "MESSAGEBOX". This is a line like

  Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff

  In my example the lines before the call to MessageBox() look like that:

  Call KERNEL.96: FREELIBRARY(0x0347) ret=01cf:1033 ds=01ff CallTo16(func=033f:0072,ds=01ff,0x0000) Ret KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1033 ds=01ff Call KERNEL.96: FREELIBRARY(0x036f) ret=01cf:1043 ds=01ff CallTo16(func=0367:0072,ds=01ff,0x0000) Ret KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1043 ds=01ff Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff CallTo16(func=0317:0072,ds=01ff,0x0000) Ret KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:105c ds=01ff Call USER.171: WINHELP(0x02ac,0x01ff05b4 "COMET.HLP",0x0002,0x00000000) ret=01cf:1070 ds=01ff CallTo16(func=0117:0080,ds=01ff) Call WPROCS.24: TASK_RESCHEDULE() ret=00a7:0a2d ds=002b Ret WPROCS.24: TASK_RESCHEDULE() retval=0x0000 ret=00a7:0a2d ds=002b Ret USER.171: WINHELP() retval=0x0001 ret=01cf:1070 ds=01ff Call KERNEL.96: FREELIBRARY(0x01be) ret=01df:3e29 ds=01ff Ret KERNEL.96: FREELIBRARY() retval=0x0000 ret=01df:3e29 ds=01ff Call KERNEL.52: FREEPROCINSTANCE(0x02cf00ba) ret=01f7:1460 ds=01ff Ret KERNEL.52: FREEPROCINSTANCE() retval=0x0001 ret=01f7:1460 ds=01ff Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff

  I think that the call to MessageBox() in this example is not caused by a wrong result value of some previously executed function (it's happening quite often like that), but instead the messagebox complains about a runtime error at 0x0004:0x1056.

  As the segment value of the address is only 4, I think that that is only an internal program value. But the offset address reveals something quite interesting: Offset 1056 is very close to the return address of FREELIBRARY():

  Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff ^^^^

  Provided that segment 0x0004 is indeed segment 0x1cf, we now we can use IDA (available at http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip) to disassemble the part that caused the error. We just have to find the address of the call to FreeLibrary(). Some lines before that the runtime error occurred. But be careful! In some cases you don't have to disassemble the main program, but instead some DLL called by it in order to find the correct place where the runtime error occurred. That can be determined by finding the origin of the segment value (in this case 0x1cf).

• If you have created a relay file of some crashing program and want to set a breakpoint at a certain location which is not yet available as the program loads the breakpoint's segment during execution, you may set a breakpoint to GetVersion16/32 as those functions are called very often.

  Then do a c until you are able to set this breakpoint without error message.

• Some useful programs:

  IDA: http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip

  Very good DOS disassembler ! It's badly needed for debugging Wine sometimes.

  XRAY: http://garbo.uwasa.fi/pub/pc/sysinfo/xray15.zip

  Traces DOS calls (Int 21h, DPMI, ...). Use it with Windows to correct file management problems etc.

  pedump: ftp://ftp.simtel.net/pub/simtelnet/win95/prog/pedump.zip

  Dumps the imports and exports of a PE (Portable Executable) DLL.

  winedump:

  Dumps the imports and exports of a PE (Portable Executable) DLL (included in wine tree).

Some basic debugger usages:

After starting your program with

wine -debug myprog.exe
        

the program loads and you get a prompt at the program starting point. Then you can set breakpoints:

  b RoutineName      (by outine name) OR
  b *0x812575        (by address)
        

Then you hit c (continue) to run the program. It stops at the breakpoint. You can type

  step               (to step one line) OR
  stepi              (to step one machine instruction at a time;
                      here, it helps to know the basic 386
                      instruction set)
  info reg           (to see registers)
  info stack         (to see hex values in the stack)
  info local         (to see local variables)
  list <line number> (to list source code)
  x <variable name>  (to examine a variable; only works if code
                      is not compiled with optimization)
  x 0x4269978        (to examine a memory location)
  ?                  (help)
  q                  (quit)
        

By hitting Enter, you repeat the last command.

Registry configuration

The Windows' debugging API uses a registry entry to know which debugger to invoke when an unhandled exception occurs (see On exceptions for some details). Two values in key

"MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
        

Determine the behavior:

A regular Wine registry looks like:

[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
"Auto"=dword:00000001
"Debugger"="winedbg --debugmsg -all %ld %ld"
        

	Note 1
	creating this key is mandatory. Not doing so will not fire the debugger when an exception occurs.

	Note 2
	wineinstall (available in Wine source) sets up this correctly. However, due to some limitation of the registry installed, if a previous Wine installation exists, it's safer to remove the whole [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] key before running again wineinstall to regenerate this key.

WineDbg configuration

WineDbg can be configured through a number of options. Those options are stored in the registry, on a per user basis. The key is (in my registry)

[eric\\Software\\Wine\\WineDbg]
        

Those options can be read/written while inside WineDbg, as part of the debugger expressions. To refer to one of these options, its name must be prefixed by a $ sign. For example,

set $BreakAllThreadsStartup = 1
        

sets the option BreakAllThreadsStartup to TRUE.

All the options are read from the registry when WineDbg starts (if no corresponding value is found, a default value is used), and are written back to the registry when WineDbg exits (hence, all modifications to those options are automatically saved when WineDbg terminates).

Here's the list of all options:

Misc

abort		aborts the debugger
quit		exits the debugger

attach N	attach to a W-process (N is its ID). IDs can be
		obtained using the walk process command
detach          detach from a W-process. WineDbg will exit (this may
                be changed later on)
        

help		prints some help on the commands
help info	prints some help on info commands
        

mode 16		switch to 16 bit mode
mode 32		switch to 32 bit mode
        

Flow control

cont		continue execution until next breakpoint or exception.
pass		pass the exception event up to the filter chain.
step		continue execution until next C line of code (enters
		function call)
next 		continue execution until next C line of code (doesn't
		enter function call)
stepi		execute next assembly instruction (enters function
		call)
nexti		execute next assembly instruction (doesn't enter
		function call)
finish		do nexti commands until current function is exited
        

cont, step, next, stepi, nexti can be postfixed by a number (N), meaning that the command must be executed N times.

Breakpoints, watch points

enable N	enables (break|watch)point #N
disable N	disables (break|watch)point #N
delete N	deletes  (break|watch)point #N
cond N		removes any a existing condition to (break|watch)point N
cond N <expr>	adds condition <expr> to (break|watch)point N. <expr>
		will be evaluated each time the breakpoint is hit. If
		the result is a zero value, the breakpoint isn't
		triggered
break * N	adds a breakpoint at address N
break <id>	adds a breakpoint at the address of symbol <id>
break <id> N	adds a breakpoint at the address of symbol <id> (N ?)
break N		adds a breakpoint at line N of current source file
break		adds a breakpoint at current $pc address
watch * N	adds a watch command (on write) at address N (on 4 bytes)
watch <id>	adds a watch command (on write) at the address of
		symbol <id>
info break	lists all (break|watch)points (with state)
        

When setting a breakpoint on an <id>, if several symbols with this <id> exist, the debugger will prompt for the symbol you want to use. Pick up the one you want from its number.

Alternatively you can specify a DLL in the <id> (for example MYDLL.DLL.myFunc for function myFunc of G:\AnyPath\MyDll.dll).

You can use the symbol EntryPoint to stand for the entry point of the Dll.

When setting a break/watch-point by <id>, if the symbol cannot be found (for example, the symbol is contained in a not yet loaded module), winedbg will recall the name of the symbol and will try to set the breakpoint each time a new module is loaded (until it succeeds).

Stack manipulation

bt		print calling stack of current thread
bt N		print calling stack of thread of ID N (note: this
                doesn't change the position of the current frame as
		manipulated by the up & dn commands)
up		goes up one frame in current thread's stack
up N		goes up N frames in current thread's stack
dn		goes down one frame in current thread's stack
dn N		goes down N frames in current thread's stack
frame N		set N as the current frame for current thread's stack
info local	prints information on local variables for current
		function
        

Directory & source file manipulation

show dir
dir <pathname>
dir
symbolfile <pathname>   loads external symbol definition
symbolfile <pathname> N loads external symbol definition
                           (applying an offset of N to addresses)
        

list		lists 10 source lines from current position
list - 		lists 10 source lines before current position
list N		lists 10 source lines from line N in current file
list <path>:N	lists 10 source lines from line N in file <path>
list <id>	lists 10 source lines of function <id>
list * N	lists 10 source lines from address N
        

You can specify the end target (to change the 10 lines value) using the ','. For example:

list 123, 234 	lists source lines from line 123 up to line 234 in
		current file
list foo.c:1,56	lists source lines from line 1 up to 56 in file foo.c
        

Displaying

A display is an expression that's evaluated and printed after the execution of any WineDbg command.

display		lists the active displays
info display	(same as above command)
display <expr>	adds a display for expression <expr>
display /fmt <expr>	adds a display for expression <expr>. Printing
		evaluated <expr> is done using the given format (see
		print command for more on formats)
del display N	deletes display #N
undisplay N	(same as del display)
        

Disassembly

disas		disassemble from current position
disas <expr>	disassemble from address <expr>
disas <expr>,<expr>disassembles code between addresses specified by
		the two <expr>
        

Information on Wine's internals

info class <id> prints information on Windows's class <id>
walk class	lists all Windows' class registered in Wine
info share	lists all the dynamic libraries loaded the debugged
		program (including .so files, NE and PE DLLs)
info module <N> prints information on module of handle <N>
walk module	lists all modules loaded by debugged program
info regs	prints the value of CPU register
info segment <N>prints information on segment <N>
info segment	lists all allocated segments
info stack	prints the values on top of the stack
walk map	lists all virtual mappings used by the debugged
		program
walk map <N>    lists all virtual mappings used by the program of pid <N>
info wnd <N>    prints information of Window of handle <N>
walk wnd	lists all the window hierarchy starting from the
		desktop window
walk wnd <N>    lists all the window hierarchy starting from the
		window of handle <N>
walk process	lists all w-processes in Wine session
walk thread	lists all w-threads in Wine session
walk exception  lists the exception frames (starting from current
                stack frame)
        

Memory (reading, writing, typing)

x <expr>	examines memory at <expr> address
x /fmt <expr>	examines memory at <expr> address using format /fmt
print <expr>	prints the value of <expr> (possibly using its type)
print /fmt <expr>	prints the value of <expr> (possibly using its
		type)
set <lval>=<expr>	writes the value of <expr> in <lval>
whatis <expr>	prints the C type of expression <expr>
        

/fmt is either /<letter> or /<count><letter> letter can be

s => an ASCII string
u => an Unicode UTF16 string
i => instructions (disassemble)
x => 32 bit unsigned hexadecimal integer
d => 32 bit signed decimal integer
w => 16 bit unsigned hexadecimal integer
c => character (only printable 0x20-0x7f are actually printed)
b => 8 bit unsigned hexadecimal integer
g => GUID
        

Expressions

Expressions in Wine Debugger are mostly written in a C form. However, there are a few discrepancies:

• Identifiers can take a '.' in their names. This allow mainly to access symbols from different DLLs like USER32.DLL.CreateWindowA.

• The debugger will try to distinguish this writing with structure operations. Therefore, you can only use the previous writing in operations manipulating symbols ({break|watch}points, type information command...).

Debug channels

It is possible to turn on and off debug messages as you are debugging using the set command.

set + warn win	=> turn on warn on 'win' channel
set + win	=> turn on warn/fixme/err/trace on 'win' channel
set - win	=> turn off warn/fixme/err/trace on 'win' channel
set - fixme	=> turn off the 'fixme' class
            

GDB mode

WineDbg can act as a remote monitor for GDB. This allows to use all the power of GDB, but while debugging wine and/or any Win32 application. To enable this mode, just add --gdb to winedbg command line. You'll end up on a GDB prompt. You'll have to use the GDB commands (not the wine nes).

However, some limitation in GDB while debugging wine (see below) don't appear in this mode:

• GDB will correctly present Win32 thread information and breakpoint behavior

• Moreover, it also provides support for the Dwarf II debug format (which became the default format (instead of stabs) in gcc 3.1).

A few wine extensions available through the monitor command.

monitor wnd           lists all window in the Wine session
monitor proc          lists all processes in the Wine session
monitor mem           displays memory mapping of debugged process
                      (doesn't work)

Graphical frontends to gdb

This section will describe how you can debug wine using the GDB mode of winedbg and some graphical front ends to GDB for those of you who really like graphical debuggers.

Using other Unix debuggers

You can also use other debuggers (like gdb), but you must be aware of a few items:

You need to attach the unix debugger to the correct unix process (representing the correct windows thread) (you can "guess" it from a ps fax for example: When running the emulator, usually the first two upids are for the Windows' application running the desktop, the first thread of the application is generally the third upid; when running a Winelib program, the first thread of the application is generally the first upid)

Even if latest gdb implements the notion of threads, it won't work with Wine because the thread abstraction used for implementing Windows' thread is not 100% mapped onto the Linux POSIX threads implementation. It means that you'll have to spawn a different gdb session for each Windows' thread you wish to debug.

Here's how to get info about the current execution status of a certain Wine process:

Change into your Wine source dir and enter:

$ gdb wine
        

Switch to another console and enter ps ax | grep wine to find all wine processes. Inside gdb, repeat for all Wine processes:

(gdb) attach PID
        

with PID being the process ID of one of the Wine processes. Use

(gdb) bt
        

to get the backtrace of the current Wine process, i.e. the function call history. That way you can find out what the current process is doing right now. And then you can use several times:

(gdb) n
        

or maybe even

(gdb) b SomeFunction
        

and

(gdb) c
        

to set a breakpoint at a certain function and continue up to that function. Finally you can enter

(gdb) detach
        

to detach from the Wine process.

Using other Windows debuggers

You can use any Windows' debugging API compliant debugger with Wine. Some reports have been made of success with VisualStudio debugger (in remote mode, only the hub runs in Wine). GoVest fully runs in Wine.

Main differences between winedbg and regular Unix debuggers

Introduction to API Documentation

Wine includes a large amount of documentation on the API functions it implements. There are several reasons to want to document the Win32 API:

• To allow Wine developers to know what each function should do, should they need to update or fix it.

• To allow Winelib users to understand the functions that are available to their applications.

• To provide an alternative source of free documentation on the Win32 API.

• To provide more accurate documentation where the existing documentation is accidentally or deliberately vague or misleading.

To this end, a semi formalized way of producing documentation from the Wine source code has evolved. Since the primary users of API documentation are Wine developers themselves, documentation is usually inserted into the source code in the form of comments and notes. Good things to include in the documentation of a function include:

• The purpose of the function.

• The parameters of the function and their purpose.

• The return value of the function, in success as well as failure cases.

• Additional notes such as interaction with other parts of the system, differences between Wine's implementation and Win32s, errors in MSDN documentation, undocumented cases and bugs that Wine corrects or is compatible with.

Good documentation helps developers be aware of the effects of making changes. It also allows good tests to be written which cover all of the documented cases.

Note that you do not need to be a programmer to update the documentation in Wine. If you would like to contribute to the project, patches that improve the API documentation are welcome. The following describes how to format any documentation that you write so that the Wine documentation generator can extract it and make it available to other developers and users.

In general, if you did not write the function in question, you should be wary of adding comments to other peoples code. It is quite possible you may misunderstand or misrepresent what the original author intended! Adding API documentation on the other hand can be done by anybody, since in most cases there is plenty of information about what a function is supposed to do (if it isn't obvious) available in books and articles on the internet.

A final warning concerns copyright and must be noted. If you read MSDN or any publication in order to find out what an API call does, you must be aware that the text you are reading is copyrighted and in most cases cannot legally be reproduced without the authors permission. If you copy verbatim any information from such sources and submit it for inclusion into Wine, you open yourself up to potential legal liability. You must ensure that anything you submit is your own work, although it can be based on your understanding gleaned from reading other peoples work.

Basic API Documentation

The general form of an API comment in Wine is a block comment immediately before a function is implemented in the source code. General comments within a function body or at the top of an implementation file are ignored by the API documentation generator. Such comments are for the benefit of developers only, for example to explain what the source code is doing or to describe something that may not be obvious to the person reading the source code.

The following text uses the function PathRelativePathToA() from SHLWAPI.DLL as an example. You can find this function in the Wine source code tree in the file dlls/shlwapi/path.c.

The first line of the comment gives the name of the function, the DLL that the function is exported from, and its export ordinal number. This is the simplest (and most common type of) comment:

/*************************************************************************
 * PathRelativePathToA   [SHLWAPI.@]
 */
      

The functions name and the DLL name are obvious. The ordinal number takes one of two forms: Either @ as in the above, or a number if the export is exported by ordinal. You can see which to use by looking at the DLL's .spec file. If the line on which the function is listed begins with a number, use it, otherwise use the @ symbol, which indicates that this function is imported only by name.

Note also that round or square brackets can be used, and whitespace between the name and the DLL/ordinal is free form. Thus the following is equally valid:

/*************************************************************************
 *		PathRelativePathToA	(SHLWAPI.@)
 */
      

This basic comment will not get processed into documentation, since it contains no information. In order to produce documentation for the function, We must add some of the information listed above.

First we add a description of the function. This can be as long as you like, but typically contains only a brief description of what the function is meant to do in general terms. It is free form text:

/*************************************************************************
 * PathRelativePathToA   [SHLWAPI.@]
 *
 * Create a relative path from one path to another.
 */
      

To be truly useful however we must document the parameters to the function. There are two methods for doing this: In the comment, or in the function prototype.

Parameters documented in the comment should be formatted as follows:

/*************************************************************************
 * PathRelativePathToA   [SHLWAPI.@]
 *
 * Create a relative path from one path to another.
 *
 * PARAMS
 *  lpszPath   [O] Destination for relative path
 *  lpszFrom   [I] Source path
 *  dwAttrFrom [I] File attribute of source path
 *  lpszTo     [I] Destination path
 *  dwAttrTo   [I] File attributes of destination path
 *
 */
      

The parameters section starts with PARAMS on its own line. Each parameter is listed in the order they appear in the functions prototype, first with the parameters name, followed by its input/output status, followed by a free form text description of the comment.

The input/output status tells the programmer whether the value will be modified by the function (an output parameter), or only read (an input parameter). The status must be enclosed in square brackets to be recognized, otherwise, or if it is absent, anything following the parameter name is treated as the parameter description. This field is case insensitive and can be any of the following: [I], [In], [O], [Out], [I/O], [In/Out].

Parameters documented in the prototype should be formatted as follows:

/*************************************************************************
 * PathRelativePathToA   [SHLWAPI.@]
 *
 * Create a relative path from one path to another.
 *
 */
BOOL WINAPI PathRelativePathToA(
 LPSTR  lpszPath,   /* [O] Destination for relative path */
 LPCSTR lpszFrom,   /* [I] Source path */
 DWORD  dwAttrFrom, /* [I] File attribute of source path */
 LPCSTR lpszTo,     /* [I] Destination path */
 DWORD  dwAttrTo)   /* [I] File attributes of destination path */
      

The choice of which style to use is up to you, although for readability it is suggested you stick with the same style within a single source file.

Following the description and parameters come a number of optional sections, all in the same format. A section is defined as the section name, which is an all upper case section name on its own line, followed by free form text. You can create any sections you like, however for consistency it is recommended you use the following section names:

1. NOTES. Anything that needs to be noted about the function such as special cases and the effects of input arguments.

2. BUGS. Any bugs in the function that exist 'by design', i.e. those that will not be fixed or exist for compatibility with Windows.

3. TODO. Any unhandled cases or missing functionality in the Wine implementation of the function.

4. FIXME. Things that should be updated or addressed in the implementation of the function at some future date (perhaps dependent on other parts of Wine). Note that if this information is only relevant to Wine developers then it should probably be placed in the relevant code section instead.

Following or before the optional sections comes the RETURNS section which describes the return value of the function. This is free form text but should include what is returned on success as well as possible error return codes. Note that this section must be present for documentation to be generated for your comment.

Our final documentation looks like the following:

/*************************************************************************
 * PathRelativePathToA   [SHLWAPI.@]
 *
 * Create a relative path from one path to another.
 *
 * PARAMS
 *  lpszPath   [O] Destination for relative path
 *  lpszFrom   [I] Source path
 *  dwAttrFrom [I] File attribute of source path
 *  lpszTo     [I] Destination path
 *  dwAttrTo   [I] File attributes of destination path
 *
 * RETURNS
 *  TRUE  If a relative path can be formed. lpszPath contains the new path
 *  FALSE If the paths are not relative or any parameters are invalid
 *
 * NOTES
 *  lpszTo should be at least MAX_PATH in length.
 *  Calling this function with relative paths for lpszFrom or lpszTo may
 *  give erroneous results.
 *
 *  The Win32 version of this function contains a bug where the lpszTo string
 *  may be referenced 1 byte beyond the end of the string. As a result random
 *  garbage may be written to the output path, depending on what lies beyond
 *  the last byte of the string. This bug occurs because of the behaviour of
 *  PathCommonPrefix() (see notes for that function), and no workaround seems
 *  possible with Win32.
 *  This bug has been fixed here, so for example the relative path from "\\"
 *  to "\\" is correctly determined as "." in this implementation.
 */
      

Advanced API Documentation

There is no markup language for formatting API comments, since they should be easily readable by any developer working on the source file. A number of constructs are treated specially however, and are noted here. You can use these constructs to enhance the usefulness of the generated documentation by making it easier to read and referencing related documents.

Any valid c identifier that ends with () is taken to be an API function and is formatted accordingly. When generating documentation, this text will become a link to that API call, if the output type supports hyperlinks or their equivalent.

Similarly, any interface name starting with a capital I and followed by the words "reference" or "object" become a link to that objects documentation.

Where an Ascii and Unicode version of a function are available, it is recommended that you document only the Ascii version and have the Unicode version refer to the Ascii one, as follows:

/*************************************************************************
 * PathRelativePathToW   [SHLWAPI.@]
 *
 * See PathRelativePathToA.
 */
      

Alternately you may use the following form:

/*************************************************************************
 * PathRelativePathToW   [SHLWAPI.@]
 *
 * Unicode version of PathRelativePathToA.
 */
      

You may also use this construct in any other section, such as NOTES.

Any numbers and text in quotes ("") are highlighted.

Words in all uppercase are assumed to be API constants and are highlighted. If you want to emphasize something in the documentation, put it in a section by itself rather than making it upper case.

Blank lines in a section cause a new paragraph to be started. Blank lines at the start and end of sections are ignored.

Any comment line starting with ("*|") is treated as raw text and is not pre-processed before being output. This should be used for code listings, tables and any text that should remain unformatted.

Any line starting with a single word followed by a colon (:) is assumed to be case listing and is emphasized and put in its own paragraph. This is most often used for return values, as in the example section below.

 * RETURNS
 *  Success: TRUE. Something happens that is documented here.
 *  Failure: FALSE. The reasons why this call can fail are listed here.
      

Any line starting with a (-) is put into a paragraph by itself. this allows lists to avoid being run together.

If you are in doubt as to how your comment will look, try generating the API documentation and checking the output.

Extra API Documentation

Simply documenting the API calls available provides a great deal of information to developers working with the Win32 API. However additional documentation is needed before the API Guide can be considered truly useful or comprehensive. For example, COM objects that are available for developers use should be documented, along with the interface(s) that those objects export. Also, it would be helpful to document each dll, to provide some structure to the documentation.

To facilitate providing extra documentation, you can create comments that provide extra documentation on functions, or on keywords such as the name of a COM interface or a type definition.

These items are generated using the same formatting rules as described earlier. The only difference is the first line of the comment, which indicates to the generator that the documentation is supplemental and does not describe an export from the dll being processed.

Lets assume you have implemented a COM interface that you want to document; we'll use the name IExample as an example here. Your comment would look like the following (assuming you are exporting this object from EXAMPLE.DLL):

/*************************************************************************
 * IExample   {EXAMPLE}
 *
 * The IExample object provides lots of interesting functionality.
 * ...
 */
      

Format this documentation exactly as you would a standard export. The only difference is the use of curly brackets to mark this documentation as supplemental. The generator will output this documentation using the name given before the DLL name, and will link to it from the main DLL page. In addition, if you have referred to the comment name in other documentation using "IExample interface", "IExample object", or "IExample()", those references will point to this documentation.

If you document you COM interfaces this way then all following extra comments that follow in the same source file that begin with the same document title will be added as references to this comment before it is output. For an example of this see dlls/oleaut32/safearray.c. This uses an extra comment to document The SafeArray functions and link them together under one heading.

As a special case, if you use the DLL name as the comment name, the comment will be treated as documentation on the DLL itself. When the documentation for the DLL is processed, the contents of the comment will be placed before the generated statistics, exports and other information that makes up a DLL's documentation page.

Generating API Documentation

Having edited or added new API documentation to a source code file, you should generate the documentation to ensure that the result is what you expected. Wine includes a tool (slightly misleadingly) called c2man.pl in the tools/ directory which is used to generate the documentation from the source code.

You can run c2man.pl manually for testing purposes; it is a fairly simple perl script which parses .c files to create output in several formats. If you wish to try this you may want to run it with no arguments, which will cause it to print usage information.

An easier way is to use Wine's build system. To create man pages for a given dll, just type make man from within the dlls directory or type make manpages in the root directory of the Wine source tree. You can then check that a man page was generated for your function, it should be present in the documentation/man3w directory with the same name as the function.

Once you have generated the man pages from the source code, running make install will install them for you. By default they are installed in section 3w of the manual, so they don't conflict with any existing man page names. So, to read the man page you should use man -S 3w {name}. Alternately you can edit /etc/man.config and add 3w to the list of search paths given in the variable MANSECT.

You can also generate HTML output for the API documentation, in this case the make command is make doc-html in the dll directory, or make htmlpages from the root. The output will be placed by default under documentation/html. Similarly you can create SGML source code to produce the Wine Api Guide with the command make sgmlpages.

Writing Documentation with DocBook

DocBook is a flavour of SGML (Standard Generalized Markup Language), a syntax for marking up the contents of documents. HTML is another very common flavour of SGML; DocBook markup looks very similar to HTML markup, although the names of the markup tags differ.

---

Getting Started

	Why SGML?
	The simple answer to that is that SGML allows you to create multiple formats of a given document from a single source. Currently it is used to create HTML, PDF, PS (PostScript) and Text versions of the Wine books.

	What do I need?
	You need the SGML tools. There are various places where you can get them. The most generic way of getting them is from their source as discussed below.

	Quick instructions
	These are the basic steps to create the Wine books from the SGML source.

1. Go to http://www.sgmltools.org

2. Download all of the sgmltools packages

3. Install them all and build them (./configure; make; make install)

4. Switch to your toplevel Wine directory

5. Run ./configure (or make distclean && ./configure)

6. Switch to the documentation/ directory

7. run make html

8. View wine-user.html, wine-devel.html, etc. in your favorite browser

<book id="mybook">

<book id="mybook" status="draft">

<!doctype book PUBLIC "-//OASIS//DTD
            DocBook V3.1//EN" []> <book> ...
            </book>

<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
<article>
...
</article>

<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
<book id="index">
  <bookinfo>
    <title>A Poet's Guide to Nonsense</title>
  </bookinfo>

  <chapter id="chapter-one">
    <title>Blobs and Gribbles</title>

    <!-- This section contains only one major topic -->
    <sect1 id="blobs">
      <title>The Story Behind Blobs</title>
      <para>
        Blobs are often mistaken for ice cubes and rain
        puddles...
      </para>
    </sect1>

    <!-- This section contains embedded sub-sections -->
    <sect1 id="gribbles">
      <title>Your Friend the Gribble</title>
      <para>
        A Gribble is a cute, unassuming little fellow...
      </para>

      <sect2 id="gribble-temperament">
        <title>Gribble Temperament</title>
        <para>
          When left without food for several days...
        </para>
      </sect2>

      <sect2 id="gribble-appearance">
        <title>Gribble Appearance</title>
        <para>
          Most Gribbles have a shock of white fur running from...
        </para>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="chapter-two">
    <title>Phantasmagoria</title>

    <sect1 id="dretch-pools">
      <title>Dretch Pools</title>

      <para>
        When most poets think of Dretch Pools, they tend to...
      </para>
    </sect>
  </chapter>
</book>

Editing SGML Documents

You can write SGML/DocBook documents in any text editor you might find although some editors are more friendly for this task than others.

The most commonly used open source SGML editor is Emacs, with the PSGML mode, or extension. Emacs does not supply a GUI or WYSIWYG (What You See Is What You Get) interface, but it does provide many helpful shortcuts for creating SGML, as well as automatic formatting, validity checking, and the ability to create your own macros to simplify complex, repetitive actions.

Inline attachments with Outlook Express

Outlook Express is notorious for mangling attachments. Giving the patch a .txt extension and attaching will solve the problem for most mailers including Outlook. Also, there is a way to enable Outlook Express send .diff attachments.

You need following two things to make it work.

1. Make sure that .diff files have \r\n line ends, because if OE detects that there is no \r\n line endings it switches to quoted-printable format attachments.

2. Using regedit add key "Content Type" with value "text/plain" to the .diff extension under HKEY_CLASSES_ROOT (same as for .txt extension). This tells OE to use Content-Type: text/plain instead of application/octet-stream.

Item #1 is important. After you hit "Send" button, go to "Outbox" and using "Properties" verify the message source to make sure that the mail has correct format. You might want to send several test emails to yourself too.

Alexandre's Bottom Line

"The basic rules are: no attachments, no mime crap, no line wrapping, a single patch per mail. Basically if I can't do "cat raw_mail | patch -p0" it's in the wrong format."

Using pre-compiled binaries

Unfortunately there are no pre-compiled binaries yet. However if send an email to the Wine development list you can probably get someone to send them to you, and maybe motivate some kind soul to put in place a mechanism for publishing such binaries on a regular basis.

With Visual C++

• get the Wine sources

• Run msvcmaker to generate Visual C++ project files for the tests. 'msvcmaker' is a perl script so you may be able to run it on Windows.

  $ ./tools/winapi/msvcmaker --no-wine

• If the previous steps were done on your Linux development machine, make the Wine sources accessible to the Windows machine on which you are going to compile them. Typically you would do this using Samba but copying them altogether would work too.

• On the Windows machine, open the winetest.dsw workspace. This will load each test's project. For each test there are two configurations: one compiles the test with the Wine headers, and the other uses the Visual C++ headers. Some tests will compile fine with the former, but most will require the latter.

• Open the Build+Batch build... menu and select the tests and build configurations you want to build. Then click on Build.

• To run a specific test from Visual C++, go to Project+Settings.... There select that test's project and build configuration and go to the Debug tab. There type the name of the specific test to run (e.g. 'thread') in the Program arguments field. Validate your change by clicking on Ok and start the test by clicking the red exclamation mark (or hitting 'F5' or any other usual method).

• You can also run the tests from the command line. You will find them in either Output\Win32_Wine_Headers or Output\Win32_MSVC_Headers depending on the build method. So to run the kernel 'path' tests you would do:

  C:\>cd dlls\kernel\tests\Output\Win32_MSVC_Headers C:\dlls\kernel\tests\Output\Win32_MSVC_Headers>kernel32_test path

With MinGW

This needs to be documented. The best may be to ask on the Wine development mailing list and update this documentation with the result of your inquiry.

Cross compiling with MinGW on Linux

Here is how to generate Windows executables for the tests straight from the comfort of Linux.

• First you need to get the MinGW cross-compiler. On Debian all you need to do is type apt-get install mingw32.

• If you had already run configure, then delete config.cache and re-run configure. You can then run make crosstest. To sum up:

  $ rm config.cache $ ./configure $ make crosstest

• If you get an error when compiling winsock.h then you probably need to apply the following patch: http://www.winehq.org/hypermail/wine-patches/2002/12/0157.html

Wine Overview

Wine is often used as a recursive acronym, standing for "Wine Is Not an Emulator". Sometimes it is also known to be used for "Windows Emulator". In a way, both meanings are correct, only seen from different perspectives. The first meaning says that Wine is not a virtual machine, it does not emulate a CPU, and you are not supposed to install Windows nor any Windows device drivers on top of it; rather, Wine is an implementation of the Windows API, and can be used as a library to port Windows applications to Unix. The second meaning, obviously, is that to Windows binaries (.exe files), Wine does look like Windows, and emulates its behaviour and quirks rather closely.

Note

The "Emulator" perspective should not be thought of as if Wine is a typical inefficient emulation layer that means Wine can't be anything but slow - the faithfulness to the badly designed Windows API may of course impose a minor overhead in some cases, but this is both balanced out by the higher efficiency of the Unix platforms Wine runs on, and that other possible abstraction libraries (like Motif, GTK+, CORBA, etc) has a runtime overhead typically comparable to Wine's.

Win16 and Win32

Win16 and Win32 applications have different requirements; for example, Win16 apps expect cooperative multitasking among themselves, and to exist in the same address space, while Win32 apps expect the complete opposite, i.e. preemptive multitasking, and separate address spaces.

Wine now deals with this issue by launching a separate Wine process for each Win32 process, but not for Win16 tasks. Win16 tasks are now run as different intersynchronized threads in the same Wine process; this Wine process is commonly known as a WOW process, referring to a similar mechanism used by Windows NT. Synchronization between the Win16 tasks running in the WOW process is normally done through the Win16 mutex - whenever one of them is running, it holds the Win16 mutex, keeping the others from running. When the task wishes to let the other tasks run, the thread releases the Win16 mutex, and one of the waiting threads will then acquire it and let its task run.

The Wine server

The Wine server is among the most confusing concepts in Wine. What is its function in Wine? Well, to be brief, it provides Inter-Process Communication (IPC), synchronization, and process/thread management. When the wineserver launches, it creates a Unix socket for the current host based on (see below) your home directory's .wine subdirectory (or wherever the WINEPREFIX environment variable points) - all Wine processes launched later connects to the wineserver using this socket. (If a wineserver was not already running, the first Wine process will start up the wineserver in auto-terminate mode (i.e. the wineserver will then terminate itself once the last Wine process has terminated).)

In earlier versions of Wine the master socket mentioned above was actually created in the configuration directory; either your home directory's /wine subdirectory or wherever the WINEPREFIX environment variable points>. Since that might not be possible the socket is actually created within the /tmp directory with a name that reflects the configuration directory. This means that there can actually be several separate copies of the wineserver running; one per combination of user and configuration directory. Note that you should not have several users using the same configuration directory at the same time; they will have different copies of the wineserver running and this could well lead to problems with the registry information that they are sharing.

Every thread in each Wine process has its own request buffer, which is shared with the wineserver. When a thread needs to synchronize or communicate with any other thread or process, it fills out its request buffer, then writes a command code through the socket. The wineserver handles the command as appropriate, while the client thread waits for a reply. In some cases, like with the various WaitFor synchronization primitives, the server handles it by marking the client thread as waiting and does not send it a reply before the wait condition has been satisfied.

The wineserver itself is a single and separate process and does not have its own threading - instead, it is built on top of a large poll() loop that alerts the wineserver whenever anything happens, such as a client having sent a command, or a wait condition having been satisfied. There is thus no danger of race conditions inside the wineserver itself - it is often called upon to do operations that look completely atomic to its clients.

Because the wineserver needs to manage processes, threads, shared handles, synchronization, and any related issues, all the clients' Win32 objects are also managed by the wineserver, and the clients must send requests to the wineserver whenever they need to know any Win32 object handle's associated Unix file descriptor (in which case the wineserver duplicates the file descriptor, transmits it to the client, and leaves it to the client to close the duplicate when the client has finished with it).

Relays, Thunks, and DLL descriptors

Loading a Windows binary into memory isn't that hard by itself, the hard part is all those various DLLs and entry points it imports and expects to be there and function as expected; this is, obviously, what the entire Wine implementation is all about. Wine contains a range of DLL implementations. Each of the implemented (or half-implemented) DLLs (which can be found in the dlls/ directory) need to make themselves known to the Wine core through a DLL descriptor. These descriptors point to such things as the DLL's resources and the entry point table.

The DLL descriptor and entry point table is generated by the winebuild tool (previously just named build), taking DLL specification files with the extension .spec as input. The output file contains a global constructor that automatically registers the DLL's descriptor with the Wine core at runtime.

Once an application module wants to import a DLL, Wine will look through its list of registered DLLs (if it's not registered, it will look for it on disk). (Failing that, it will look for a real Windows .DLL file to use, and look through its imports, etc.) To resolve the module's imports, Wine looks through the entry point table and finds if it's defined there. (If not, it'll emit the error "No handler for ...", which, if the application called the entry point, is a fatal error.)

Since Wine is 32-bit code itself, and if the compiler supports Windows' calling convention, stdcall (gcc does), Wine can resolve imports into Win32 code by substituting the addresses of the Wine handlers directly without any thunking layer in between. This eliminates the overhead most people associate with "emulation", and is what the applications expect anyway.

However, if the user specified --debugmsg +relay, a thunk layer is inserted between the application imports and the Wine handlers; this layer is known as "relay" because all it does is print out the arguments/return values (by using the argument lists in the DLL descriptor's entry point table), then pass the call on, but it's invaluable for debugging misbehaving calls into Wine code. A similar mechanism also exists between Windows DLLs - Wine can optionally insert thunk layers between them, by using --debugmsg +snoop, but since no DLL descriptor information exists for non-Wine DLLs, this is less reliable and may lead to crashes.

For Win16 code, there is no way around thunking - Wine needs to relay between 16-bit and 32-bit code. These thunks switch between the app's 16-bit stack and Wine's 32-bit stack, copies and converts arguments as appropriate, and handles the Win16 mutex. Suffice to say that the kind of intricate stack content juggling this results in, is not exactly suitable study material for beginners.

Core and non-core DLLs

Wine must at least completely replace the "Big Three" DLLs (KERNEL/KERNEL32, GDI/GDI32, and USER/USER32), which all other DLLs are layered on top of. But since Wine is (for various reasons) leaning towards the NT way of implementing things, the NTDLL is another core DLL to be implemented in Wine, and many KERNEL32 and ADVAPI32 features will be implemented through the NTDLL. The wineserver and the service thread provide the backbone for the implementation of these core DLLs, and integration with the X11 driver (which provides GDI/GDI32 and USER/USER32 functionality along with the Windows standard controls). All non-core DLLs, on the other hand, are expected to only use routines exported by other DLLs (and none of these backbone services directly), to keep the code base as tidy as possible. An example of this is COMCTL32 (Common Controls), which should only use standard GDI32- and USER32-exported routines.

KERNEL Module

Needs some content...

GDI Module

USER Module

USER implements windowing and messaging subsystems. It also contains code for common controls and for other miscellaneous stuff (rectangles, clipboard, WNet, etc). Wine USER code is located in windows/, controls/, and misc/ directories.

   Desktop window			- root window
    |     \      `-.
    |      \        `-.
   popup -> wnd1  ->  wnd2		- top level windows    
    |       \   `-.      `-.
    |        \     `-.      `-.
   child1  child2 -> child3  child4     - child windows
          

child1->popup->child2->child3->wnd1->child4->wnd2->desktop.
          

    ________________________
   |_________               |  A and B are child windows of C
   |    A    |______        | 
   |         |      |       |
   |---------'      |       |
   |   |      B     |       |
   |   |            |       |
   |   `------------'       |
   |                   C    |
   `------------------------'
            

   .          ______ 
   :         |      |
   |   ,-----'      |
   |   |      B     | - visible region of B
   |   |            |
   :   `------------'
            

          ______
      ,--|--.   |     .    ,--. 
   ,--+--'  |   |     :   _:  |
   |  |   B |   |  => |  |    | - DC region where the painting will
   |  |     |   |     |  |    |   be visible
   `--|-----|---'     :  `----'
      `-----'
            

    ________________________       ...          / C update region
   |______                  |     :      .___ /
   | A    |_________        |  => |   ...|___|..
   |      |         |       |     |   :  |   |
   |------'         |       |     |   :  '---' 
   |   |      B     |       |     |   :      \
   |   |            |       |     :            \
   |   `------------'       |                    B update region
   |                   C    |
   `------------------------'
            

Pros of Native DLLs

Native DLLs of course guarantee 100% compatibility for routines they implement. For example, using the native USER DLL would maintain a virtually perfect and Windows 95-like look for window borders, dialog controls, and so on. Using the built-in Wine version of this library, on the other hand, would produce a display that does not precisely mimic that of Windows 95. Such subtle differences can be engendered in other important DLLs, such as the common controls library COMMCTRL or the common dialogs library COMMDLG, when built-in Wine DLLs outrank other types in load order.

More significant, less aesthetically-oriented problems can result if the built-in Wine version of the SHELL DLL is loaded before the native version of this library. SHELL contains routines such as those used by installer utilities to create desktop shortcuts. Some installers might fail when using Wine's built-in SHELL.

Cons of Native DLLs

Not every application performs better under native DLLs. If a library tries to access features of the rest of the system that are not fully implemented in Wine, the native DLL might work much worse than the corresponding built-in one, if at all. For example, the native Windows GDI library must be paired with a Windows display driver, which of course is not present under Intel Unix and Wine.

Finally, occasionally built-in Wine DLLs implement more features than the corresponding native Windows DLLs. Probably the most important example of such behavior is the integration of Wine with X provided by Wine's built-in USER DLL. Should the native Windows USER library take load-order precedence, such features as the ability to use the clipboard or drag-and-drop between Wine windows and X windows will be lost.

Deciding Between Native and Built-In DLLs

Clearly, there is no one rule-of-thumb regarding which load-order to use. So, you must become familiar with what specific DLLs do and which other DLLs or features a given library interacts with, and use this information to make a case-by-case decision.

Load Order for DLLs

Using the DLL sections from the wine configuration file, the load order can be tweaked to a high degree. In general it is advised not to change the settings of the configuration file. The default configuration specifies the right load order for the most important DLLs.

The default load order follows this algorithm: for all DLLs which have a fully-functional Wine implementation, or where the native DLL is known not to work, the built-in library will be loaded first. In all other cases, the native DLL takes load-order precedence.

The DefaultLoadOrder from the [DllDefaults] section specifies for all DLLs which version to try first. See manpage for explanation of the arguments.

The [DllOverrides] section deals with DLLs, which need a different-from-default treatment.

The [DllPairs] section is for DLLs, which must be loaded in pairs. In general, these are DLLs for either 16-bit or 32-bit applications. In most cases in Windows, the 32-bit version cannot be used without its 16-bit counterpart. For Wine, it is customary that the 16-bit implementations rely on the 32-bit implementations and cast the results back to 16-bit arguments. Changing anything in this section is bound to result in errors.

For the future, the Wine implementation of Windows DLL seems to head towards unifying the 16 and 32 bit DLLs wherever possible, resulting in larger DLLs. They are stored in the dlls/ subdirectory using the 32-bit name.

Understanding What DLLs Do

The following list briefly describes each of the DLLs commonly found in Windows whose load order may be modified during the configuration and compilation of Wine.

(See also ./DEVELOPER-HINTS or the dlls/ subdirectory to see which DLLs are currently being rewritten for Wine)

ADVAPI32.DLL:	   32-bit application advanced programming interfaces
                   like crypto, systeminfo, security and event logging
AVIFILE.DLL:	   32-bit application programming interfaces for the
                   Audio Video Interleave (AVI) Windows-specific
                   Microsoft audio-video standard
COMMCTRL.DLL:	   16-bit common controls
COMCTL32.DLL:	   32-bit common controls
COMDLG32.DLL:	   32-bit common dialogs
COMMDLG.DLL:	   16-bit common dialogs
COMPOBJ.DLL:	   OLE 16- and 32-bit compatibility libraries
CRTDLL.DLL:	   Microsoft C runtime
DCIMAN.DLL:	   16-bit
DCIMAN32.DLL:	   32-bit display controls
DDEML.DLL:	   DDE messaging
D3D*.DLL	   DirectX/Direct3D drawing libraries
DDRAW.DLL:	   DirectX drawing libraries
DINPUT.DLL:	   DirectX input libraries
DISPLAY.DLL:	   Display libraries
DPLAY.DLL, DPLAYX.DLL:  DirectX playback libraries
DSOUND.DLL:	   DirectX audio libraries
GDI.DLL:	   16-bit graphics driver interface
GDI32.DLL:	   32-bit graphics driver interface
IMAGEHLP.DLL:	   32-bit IMM API helper libraries (for PE-executables)
IMM32.DLL:	   32-bit IMM API
IMGUTIL.DLL:	   
KERNEL32.DLL	   32-bit kernel DLL
KEYBOARD.DLL:	   Keyboard drivers
LZ32.DLL:	   32-bit Lempel-Ziv or LZ file compression
                   used by the installshield installers (???).
LZEXPAND.DLL:	   LZ file expansion; needed for Windows Setup
MMSYSTEM.DLL:	   Core of the Windows multimedia system
MOUSE.DLL:	   Mouse drivers
MPR.DLL:	   32-bit Windows network interface
MSACM.DLL:	   Core of the Addressed Call Mode or ACM system
MSACM32.DLL:	   Core of the 32-bit ACM system
                   Audio Compression Manager ???
MSNET32.DLL	   32-bit network APIs
MSVFW32.DLL:	   32-bit Windows video system
MSVIDEO.DLL:	   16-bit Windows video system
OLE2.DLL:	   OLE 2.0 libraries
OLE32.DLL:	   32-bit OLE 2.0 components
OLE2CONV.DLL:	   Import filter for graphics files
OLE2DISP.DLL, OLE2NLS.DLL: OLE 2.1 16- and 32-bit interoperability
OLE2PROX.DLL:	   Proxy server for OLE 2.0
OLE2THK.DLL:	   Thunking for OLE 2.0
OLEAUT32.DLL	   32-bit OLE 2.0 automation
OLECLI.DLL:	   16-bit OLE client
OLECLI32.DLL:	   32-bit OLE client
OLEDLG.DLL:	   OLE 2.0 user interface support
OLESVR.DLL:	   16-bit OLE server libraries
OLESVR32.DLL:	   32-bit OLE server libraries
PSAPI.DLL:	   Proces Status API libraries
RASAPI16.DLL:	   16-bit Remote Access Services libraries
RASAPI32.DLL:	   32-bit Remote Access Services libraries
SHELL.DLL:	   16-bit Windows shell used by Setup
SHELL32.DLL:	   32-bit Windows shell (COM object?)
TAPI/TAPI32/TAPIADDR:  Telephone API (for Modems)
W32SKRNL:	   Win32s Kernel ? (not in use for Win95 and up!)
WIN32S16.DLL:	   Application compatibility for Win32s
WIN87EM.DLL:	   80387 math-emulation libraries
WINASPI.DLL:	   Advanced SCSI Peripheral Interface or ASPI libraries
WINDEBUG.DLL	   Windows debugger
WINMM.DLL:	   Libraries for multimedia thunking
WING.DLL:	   Libraries required to "draw" graphics
WINSOCK.DLL:	   Sockets APIs
WINSPOOL.DLL:	   Print spooler libraries
WNASPI32.DLL:	   32-bit ASPI libraries
WSOCK32.DLL:	   32-bit sockets APIs
        

Macros to define a COM interface

The goal of the following set of definitions is to provide a way to use the same header file definitions to provide both a C interface and a C++ object oriented interface to COM interfaces. The type of interface is selected automatically depending on the language but it is always possible to get the C interface in C++ by defining CINTERFACE.

It is based on the following assumptions:

• all COM interfaces derive from IUnknown, this should not be a problem.

• the header file only defines the interface, the actual fields are defined separately in the C file implementing the interface.

The natural approach to this problem would be to make sure we get a C++ class and virtual methods in C++ and a structure with a table of pointer to functions in C. Unfortunately the layout of the virtual table is compiler specific, the layout of g++ virtual tables is not the same as that of an egcs virtual table which is not the same as that generated by Visual C+. There are work arounds to make the virtual tables compatible via padding but unfortunately the one which is imposed to the Wine emulator by the Windows binaries, i.e. the Visual C++ one, is the most compact of all.

So the solution I finally adopted does not use virtual tables. Instead I use in-line non virtual methods that dereference the method pointer themselves and perform the call.

Let's take Direct3D as an example:

#define ICOM_INTERFACE IDirect3D
#define IDirect3D_METHODS \
    ICOM_METHOD1(HRESULT,Initialize,    REFIID,) \
    ICOM_METHOD2(HRESULT,EnumDevices,   LPD3DENUMDEVICESCALLBACK,, LPVOID,) \
    ICOM_METHOD2(HRESULT,CreateLight,   LPDIRECT3DLIGHT*,, IUnknown*,) \
    ICOM_METHOD2(HRESULT,CreateMaterial,LPDIRECT3DMATERIAL*,, IUnknown*,) \
    ICOM_METHOD2(HRESULT,CreateViewport,LPDIRECT3DVIEWPORT*,, IUnknown*,) \
    ICOM_METHOD2(HRESULT,FindDevice,    LPD3DFINDDEVICESEARCH,, LPD3DFINDDEVICERESULT,)
#define IDirect3D_IMETHODS \
    IUnknown_IMETHODS \
    IDirect3D_METHODS
ICOM_DEFINE(IDirect3D,IUnknown)
#undef ICOM_INTERFACE

#ifdef ICOM_CINTERFACE
// *** IUnknown methods *** //
#define IDirect3D_QueryInterface(p,a,b) ICOM_CALL2(QueryInterface,p,a,b)
#define IDirect3D_AddRef(p)             ICOM_CALL (AddRef,p)
#define IDirect3D_Release(p)            ICOM_CALL (Release,p)
// *** IDirect3D methods *** //
#define IDirect3D_Initialize(p,a)       ICOM_CALL1(Initialize,p,a)
#define IDirect3D_EnumDevices(p,a,b)    ICOM_CALL2(EnumDevice,p,a,b)
#define IDirect3D_CreateLight(p,a,b)    ICOM_CALL2(CreateLight,p,a,b)
#define IDirect3D_CreateMaterial(p,a,b) ICOM_CALL2(CreateMaterial,p,a,b)
#define IDirect3D_CreateViewport(p,a,b) ICOM_CALL2(CreateViewport,p,a,b)
#define IDirect3D_FindDevice(p,a,b)     ICOM_CALL2(FindDevice,p,a,b)
#endif

Comments:

The ICOM_INTERFACE macro is used in the ICOM_METHOD macros to define the type of the 'this' pointer. Defining this macro here saves us the trouble of having to repeat the interface name everywhere. Note however that because of the way macros work, a macro like ICOM_METHOD1 cannot use 'ICOM_INTERFACE##_VTABLE' because this would give 'ICOM_INTERFACE_VTABLE' and not 'IDirect3D_VTABLE'.

ICOM_METHODS defines the methods specific to this interface. It is then aggregated with the inherited methods to form ICOM_IMETHODS.

ICOM_IMETHODS defines the list of methods that are inheritable from this interface. It must be written manually (rather than using a macro to generate the equivalent code) to avoid macro recursion (which compilers don't like).

The ICOM_DEFINE finally declares all the structures necessary for the interface. We have to explicitly use the interface name for macro expansion reasons again. Inherited methods are inherited in C by using the IDirect3D_METHODS macro and the parent's Xxx_IMETHODS macro. In C++ we need only use the IDirect3D_METHODS since method inheritance is taken care of by the language.

In C++ the ICOM_METHOD macros generate a function prototype and a call to a function pointer method. This means using once 't1 p1, t2 p2, ...' and once 'p1, p2' without the types. The only way I found to handle this is to have one ICOM_METHOD macro per number of parameters and to have it take only the type information (with const if necessary) as parameters. The 'undef ICOM_INTERFACE' is here to remind you that using ICOM_INTERFACE in the following macros will not work. This time it's because the ICOM_CALL macro expansion is done only once the 'IDirect3D_Xxx' macro is expanded. And by that time ICOM_INTERFACE will be long gone anyway.

You may have noticed the double commas after each parameter type. This allows you to put the name of that parameter which I think is good for documentation. It is not required and since I did not know what to put there for this example (I could only find doc about IDirect3D2), I left them blank.

Finally the set of 'IDirect3D_Xxx' macros is a standard set of macros defined to ease access to the interface methods in C. Unfortunately I don't see any way to avoid having to duplicate the inherited method definitions there. This time I could have used a trick to use only one macro whatever the number of parameters but I preferred to have it work the same way as above.

You probably have noticed that we don't define the fields we need to actually implement this interface: reference count, pointer to other resources and miscellaneous fields. That's because these interfaces are just that: interfaces. They may be implemented more than once, in different contexts and sometimes not even in Wine. Thus it would not make sense to impose that the interface contains some specific fields.

Bindings in C

In C this gives:

typedef struct IDirect3DVtbl IDirect3DVtbl;
struct IDirect3D {
    IDirect3DVtbl* lpVtbl;
};
struct IDirect3DVtbl {
    HRESULT (*fnQueryInterface)(IDirect3D* me, REFIID riid, LPVOID* ppvObj);
    ULONG (*fnAddRef)(IDirect3D* me);
    ULONG (*fnRelease)(IDirect3D* me);
    HRESULT (*fnInitialize)(IDirect3D* me, REFIID a);
    HRESULT (*fnEnumDevices)(IDirect3D* me, LPD3DENUMDEVICESCALLBACK a, LPVOID b);
    HRESULT (*fnCreateLight)(IDirect3D* me, LPDIRECT3DLIGHT* a, IUnknown* b);
    HRESULT (*fnCreateMaterial)(IDirect3D* me, LPDIRECT3DMATERIAL* a, IUnknown* b);
    HRESULT (*fnCreateViewport)(IDirect3D* me, LPDIRECT3DVIEWPORT* a, IUnknown* b);
    HRESULT (*fnFindDevice)(IDirect3D* me, LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b);
}; 

#ifdef ICOM_CINTERFACE
// *** IUnknown methods *** //
#define IDirect3D_QueryInterface(p,a,b) (p)->lpVtbl->fnQueryInterface(p,a,b)
#define IDirect3D_AddRef(p)             (p)->lpVtbl->fnAddRef(p)
#define IDirect3D_Release(p)            (p)->lpVtbl->fnRelease(p)
// *** IDirect3D methods *** //
#define IDirect3D_Initialize(p,a)       (p)->lpVtbl->fnInitialize(p,a)
#define IDirect3D_EnumDevices(p,a,b)    (p)->lpVtbl->fnEnumDevice(p,a,b)
#define IDirect3D_CreateLight(p,a,b)    (p)->lpVtbl->fnCreateLight(p,a,b)
#define IDirect3D_CreateMaterial(p,a,b) (p)->lpVtbl->fnCreateMaterial(p,a,b)
#define IDirect3D_CreateViewport(p,a,b) (p)->lpVtbl->fnCreateViewport(p,a,b)
#define IDirect3D_FindDevice(p,a,b)     (p)->lpVtbl->fnFindDevice(p,a,b)
#endif

Comments:

IDirect3D only contains a pointer to the IDirect3D virtual/jump table. This is the only thing the user needs to know to use the interface. Of course the structure we will define to implement this interface will have more fields but the first one will match this pointer.

The code generated by ICOM_DEFINE defines both the structure representing the interface and the structure for the jump table. ICOM_DEFINE uses the parent's Xxx_IMETHODS macro to automatically repeat the prototypes of all the inherited methods and then uses IDirect3D_METHODS to define the IDirect3D methods.

Each method is declared as a pointer to function field in the jump table. The implementation will fill this jump table with appropriate values, probably using a static variable, and initialize the lpVtbl field to point to this variable.

The IDirect3D_Xxx macros then just dereference the lpVtbl pointer and use the function pointer corresponding to the macro name. This emulates the behavior of a virtual table and should be just as fast.

This C code should be quite compatible with the Windows headers both for code that uses COM interfaces and for code implementing a COM interface.

Bindings in C++

And in C++ (with gcc's g++):

typedef struct IDirect3D: public IUnknown {
    private: HRESULT (*fnInitialize)(IDirect3D* me, REFIID a);
    public: inline HRESULT Initialize(REFIID a) { return ((IDirect3D*)t.lpVtbl)->fnInitialize(this,a); };
    private: HRESULT (*fnEnumDevices)(IDirect3D* me, LPD3DENUMDEVICESCALLBACK a, LPVOID b);
    public: inline HRESULT EnumDevices(LPD3DENUMDEVICESCALLBACK a, LPVOID b)
        { return ((IDirect3D*)t.lpVtbl)->fnEnumDevices(this,a,b); };
    private: HRESULT (*fnCreateLight)(IDirect3D* me, LPDIRECT3DLIGHT* a, IUnknown* b);
    public: inline HRESULT CreateLight(LPDIRECT3DLIGHT* a, IUnknown* b)
        { return ((IDirect3D*)t.lpVtbl)->fnCreateLight(this,a,b); };
    private: HRESULT (*fnCreateMaterial)(IDirect3D* me, LPDIRECT3DMATERIAL* a, IUnknown* b);
    public: inline HRESULT CreateMaterial(LPDIRECT3DMATERIAL* a, IUnknown* b)
        { return ((IDirect3D*)t.lpVtbl)->fnCreateMaterial(this,a,b); };
    private: HRESULT (*fnCreateViewport)(IDirect3D* me, LPDIRECT3DVIEWPORT* a, IUnknown* b);
    public: inline HRESULT CreateViewport(LPDIRECT3DVIEWPORT* a, IUnknown* b)
        { return ((IDirect3D*)t.lpVtbl)->fnCreateViewport(this,a,b); };
    private:  HRESULT (*fnFindDevice)(IDirect3D* me, LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b);
    public: inline HRESULT FindDevice(LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b)
        { return ((IDirect3D*)t.lpVtbl)->fnFindDevice(this,a,b); };
};

Comments:

In C++ IDirect3D does double duty as both the virtual/jump table and as the interface definition. The reason for this is to avoid having to duplicate the method definitions: once to have the function pointers in the jump table and once to have the methods in the interface class. Here one macro can generate both. This means though that the first pointer, t.lpVtbl defined in IUnknown, must be interpreted as the jump table pointer if we interpret the structure as the interface class, and as the function pointer to the QueryInterface method, t.fnQueryInterface, if we interpret the structure as the jump table. Fortunately this gymnastic is entirely taken care of in the header of IUnknown.

Of course in C++ we use inheritance so that we don't have to duplicate the method definitions.

Since IDirect3D does double duty, each ICOM_METHOD macro defines both a function pointer and a non-virtual inline method which dereferences it and calls it. This way this method behaves just like a virtual method but does not create a true C++ virtual table which would break the structure layout. If you look at the implementation of these methods you'll notice that they would not work for void functions. We have to return something and fortunately this seems to be what all the COM methods do (otherwise we would need another set of macros).

Note how the ICOM_METHOD generates both function prototypes mixing types and formal parameter names and the method invocation using only the formal parameter name. This is the reason why we need different macros to handle different numbers of parameters.

Finally there is no IDirect3D_Xxx macro. These are not needed in C++ unless the CINTERFACE macro is defined in which case we would not be here.

This C++ code works well for code that just uses COM interfaces. But it will not work with C++ code implement a COM interface. That's because such code assumes the interface methods are declared as virtual C++ methods which is not the case here.

Implementing a COM interface.

This continues the above example. This example assumes that the implementation is in C.

typedef struct _IDirect3D {
    void* lpVtbl;
    // ...
 } _IDirect3D;

static ICOM_VTABLE(IDirect3D) d3dvt;

// implement the IDirect3D methods here

int IDirect3D_fnQueryInterface(IDirect3D* me)
{
    ICOM_THIS(IDirect3D,me);
    // ...
}

// ...

static ICOM_VTABLE(IDirect3D) d3dvt = {
    ICOM_MSVTABLE_COMPAT_DummyRTTIVALUE
    IDirect3D_fnQueryInterface,
    IDirect3D_fnAdd,
    IDirect3D_fnAdd2,
    IDirect3D_fnInitialize,
    IDirect3D_fnSetWidth
};

Comments:

We first define what the interface really contains. This is the _IDirect3D structure. The first field must of course be the virtual table pointer. Everything else is free.

Then we predeclare our static virtual table variable, we will need its address in some methods to initialize the virtual table pointer of the returned interface objects.

Then we implement the interface methods. To match what has been declared in the header file they must take a pointer to a IDirect3D structure and we must cast it to an _IDirect3D so that we can manipulate the fields. This is performed by the ICOM_THIS macro.

Finally we initialize the virtual table.

Header files

The needed header files to build OpenGL support in Wine are :

The latter file (glext.h) is, as of now, not necessary to build Wine. But as this file can be easily obtained from SGI ( http://oss.sgi.com/projects/ogl-sample/ABI/glext.h), and that all OpenGL should provide one, I decided to keep it here.

OpenGL library thread-safety

After that, the script checks if the OpenGL library relies or not on the pthread library to provide thread safety (most 'modern' OpenGL libraries do).

If the OpenGL library explicitly links in libpthread (you can check it with a ldd libGL.so), you need to force OpenGL support by starting configure with the --enable-opengl flag.

The reason to this is that Wine contains some hacks done by Ove to cohabit with pthread that are known to work well in most of the cases (glibc 2.1.x). On the other hand, we never got Wine to work with glibc 2.0.6. Thus, I deemed preferable to play it safe : by default, I suppose that the hack won't work and that it's the user's responsibility to enable it.

Anyway, it should be pretty safe to build with --enable-opengl.

OpenGL library itself

To check for the presence of 'libGL' on the system, the script checks if it defines the glXCreateContext function. There should be no problem here.

glXGetProcAddressARB function

The core of Wine's OpenGL implementation (at least for all extensions) is the glXGetProcAddressARB function. Your OpenGL library needs to have this function defined for Wine to be able to support OpenGL.

If your library does not provide it, you are out of luck.

this is not completely true as one could rewrite a glXGetProcAddressARB replacement using dlopen and friends, but well, telling people to upgrade is easier :-).

The Windowing system integration

This integration is done at two levels :

1. At GDI level for all pixel format selection routines (ie choosing if one wants a depth / alpha buffer, the size of these buffers, ...) and to do the 'page flipping' in double buffer mode. This is implemented in graphics/x11drv/opengl.c (all these functions are part of Wine's graphic driver function pointer table and thus could be reimplemented if ever Wine works on another Windowing system than X).

2. In the OpenGL32.DLL itself for all other functionalities (context creation / deletion, querying of extension functions, ...). This is done in dlls/opengl32/wgl.c.

The thunks

The thunks are the Wine code that does the calling convention translation and they are auto-generated by a Perl script. In Wine's CVS tree, these thunks are already generated for you. Now, if you want to do it yourself, there is how it all works....

The script is located in dlls/opengl32 and is called make_opengl. It requires Perl5 to work and takes two arguments :

1. The first is the path to the OpenGL registry. Now, you will all ask 'but what is the OpenGL registry ?' :-) Well, it's part of the OpenGL sample implementation source tree from SGI (more informations at this URL : http://oss.sgi.com/projects/ogl-sample/.

   To summarize, these files contain human-readable but easily parsed information on ALL OpenGL core functions and ALL registered extensions (for example the prototype, the OpenGL version, ...).

2. the second is the OpenGL version to 'simulate'. This fixes the list of functions that the Windows application can link directly to without having to query them from the OpenGL driver. Windows is based, for now, on OpenGL 1.1, but the thunks that are in the CVS tree are generated for OpenGL 1.2.

   This option can have three values: 1.0, 1.1 and 1.2.

This script generates three files :

1. opengl32.spec gives Wine's linker the signature of all function in the OpenGL32.DLL library so that the application can link them. Only 'core' functions are listed here.

2. opengl_norm.c contains all the thunks for the 'core' functions. Your OpenGL library must provide ALL the function used in this file as these are not queried at run time.

3. opengl_ext.c contains all the functions that are not part of the 'core' functions. Contrary to the thunks in opengl_norm.c, these functions do not depend at all on what your libGL provides.

   In fact, before using one of these thunks, the Windows program first needs to 'query' the function pointer. At this point, the corresponding thunk is useless. But as we first query the same function in libGL and store the returned function pointer in the thunk, the latter becomes functional.

Missing GLU32.DLL

GLU is a library that is layered upon OpenGL. There is a 100% correspondence between the libGLU.so that is used on Linux and GLU32.DLL.

As for the moment, I did not create a set of thunks to support this library natively in Wine (it would easy to do, but I am waiting for a better solution than adding another autogenerated thunk file), you can always download anywhere on the net (it's free) a GLU32.DLL file (by browsing, for example, http://www.dll-files.com/dllindex/index.shtml).

OpenGL not detected at configure time

See section (I) for a detailed explanation of the configure requirements.

When running an OpenGL application, the screen flickers

See section (II) for how to create the context double-buffered and thus preventing this flicker effect.

Wine gives me the following error message :

Extension defined in the OpenGL library but NOT in opengl_ext.c...
Please report (lionel.ulmer@free.fr) !
        

This means that the extension requested by the application is found in the libGL used by Linux (ie the call to glXGetProcAddressARB returns a non-NULL pointer) but that this string was NOT found in Wine's extension registry.

This can come from two causes :

1. The opengl_ext.c file is too old and needs to be generated again.

2. Use of obsolete extensions that are not supported anymore by SGI or of 'private' extensions that are not registered. An example of the former are glMTexCoord2fSGIS and glSelectTextureSGIS as used by Quake 2 (and apparently also by old versions of Half Life). If documentation can be found on these functions, they can be added to Wine's extension set.

If you have this, run with --debugmsg +opengl and send me <lionel.ulmer@free.fr> the TRACE.

libopengl32.so is built but it is still not working

This may be caused by some missing functions required by opengl_norm.c but that your Linux OpenGL library does not provide.

To check for this, do the following steps :

1. create a dummy .c file :

   int main(void) { return 0; }

2. try to compile it by linking both libwine and libopengl32 (this command line supposes that you installed the Wine libraries in /usr/local/lib, YMMV) :

   gcc dummy.c -L/usr/local/lib -lwine -lopengl32

3. if it works, the problem is somewhere else (and you can send me an email). If not, you could re-generate the thunk files for OpenGL 1.1 for example (and send me your OpenGL version so that this problem can be detected at configure time).

(Wave form) Audio

MMSYSTEM and WINMM call the real low level audio driver using the wodMessage/widMessage which handles the different requests.

MIDI

MMSYSTEM and WINMM call the low level driver functions using the midMessage and the modMessage functions.

Mixer

MMSYSTEM and WINMM call the low level driver functions using the mxdMessage function.

Aux

The AUX low level driver is the predecessor of the mixer driver (introduced in Win 95).

Wine OSS

All the OSS dependent functions are stored into the WineOSS DLL. It still lack a correct installation scheme (as any multimedia device under Windows), so that all the correct keys are created in the registry. This requires an advanced model since, for example, the number of wave out devices can only be known on the destination system (depends on the sound card driven by the OSS interface). A solution would be to install all the multimedia drivers through the SETUPX DLL; this is not doable yet (the multimedia extension to SETUPX isn't written yet).

Joystick

The API consists of the joy* functions found in dlls/winmm/joystick/joystick.c. The implementation currently uses the Linux joystick device driver API. It is lacking support for enhanced joysticks and has not been extensively tested.

TODO:

• better support of enhanced joysticks (Linux 2.2 interface is available)

• support more joystick drivers (like the XInput extension)

• should load joystick DLL as any other driver (instead of hardcoding) the driver's name, and load it as any low lever driver.

Wave mapper (msacm.drv)

The Wave mapper device allows to load on-demand codecs in order to perform software conversion for the types the actual low level driver (hardware). Those codecs are provided through the standard ACM drivers.

MIDI mapper

Midi mapper allows to map each one of 16 MIDI channels to a specific instrument on an installed sound card. This allows for example to support different MIDI instrument definition (XM, GM...). It also permits to output on a per channel basis to different MIDI renderers.

CDAUDIO

MCIWAVE

MCISEQ (MIDI sequencer)

MCIANIM

MCIAVI

MCI skeleton

Implementation of what is needed to load/unload MCI drivers, and to pass correct information to them. This is implemented in dlls/winmm/mci.c. The mciSendString function uses command strings, which are translated into normal MCI commands as used by mciSendCommand with the help of command tables. The API can be found in dlls/winmm/mmsystem.c and dlls/winmm/mci.c. The functions there (mciOpen,mciSysInfo) handle mid level driver allocation and calls. The implementation is not complete.

MCI drivers are seen as regular Wine modules, and can be loaded (with a correct load order between builtin, native), as any other DLL. Please note, that MCI drivers module names must bear the .drv extension to be correctly understood.

The list of available MCI drivers is obtained as follows: 1. key 'mci' in [option] section from .winerc (or wineconf) mci=CDAUDIO:SEQUENCER gives the list of MCI drivers (names, in uppercase only) to be used in Wine. 2. This list, when defined, supersedes the mci key in c:\windows\system.ini

Note that native VIDEODISC crashes when the module is loaded, which occurs when the MCI procedures are initialized. Make sure that this is not in the list from above. Try adding: mci=CDAUDIO:SEQUENCER:WAVEAUDIO:AVIVIDEO:MPEGVIDEO to the [options] section of the wine config file.

TODO:

• correctly handle the MCI_ALL_DEVICE_ID in functions.

• finish mapping 16 <=> 32 of MCI structures and commands

• MCI_SOUND is not handled correctly (should not be sent to MCI driver => same behavior as MCI_BREAK)

• implement auto-open feature (ie, when a string command is issued for a not yet opened device, MCI automatically opens it)

MCI multi-tasking

Multi-tasking capabilities used for the MCI drivers are provided in dlls/winmm/mmsystem.c.

TODO:

• mmTaskXXX functions are currently broken because the 16 loader does not support binary command lines => provide Wine's own mmtask.tsk not using binary command line.

Timers

It currently uses a service thread, run in the context of the calling process, which should correctly mimic Windows behavior.

TODO:

• Check if minimal time is satisfactory for most programs.

• current implementation may let a timer tick (once) after it has been destroyed

MMIO

The API consists of the mmio* functions found in dlls/winmm/mmio.c. Seems to work ok in most of the cases. There's some linear/segmented issues with 16 bit code. There are also some bugs when writing MMIO files.

sndPlayXXX functions

Seem to work correctly.

Drivers

Since all multimedia drivers (MCI, low level ones, ACM drivers, mappers) are, at first, drivers they need to appear in the [mci] or [mci32] section of the system.ini file. Since all drivers are, at first, DLLs, you can choose to load their Wine's (built-in) or Windows (native) version.

MCI

A default [mci] section (in system.ini) looks like (see the note above on videodisc):

   [mci]
   cdaudio=mcicda.drv
   sequencer=mciseq.drv
   waveaudio=mciwave.drv
   avivideo=mciavi.drv
   videodisc=mcipionr.drv
   vcr=mcivisca.drv
   MPEGVideo=mciqtz.drv
	

By default, the list of loadable MCI drivers will be made of those drivers (in the [mci] section).

The list of loadable (recognized) MCI drivers can be altered in the [option] section of the wine config file, like: mci=CDAUDIO:SEQUENCER:WAVEAUDIO:AVIVIDEO:MPEGVIDEO

TODO:

• use a default registry setting to bypass this (ugly) configuration model

• we need also a generic tool to let the end user pick up his/her driver depending on the hardware present on the machine. model

Low level drivers

Configuration of low level drivers is done with the Wine configuration file. Default keys are provided in winedefault.reg.

The registry keys used here differ from the Windows' one. Using the Windows' one would require implementing something equivalent to a (real) driver installation. Even if this would be necessary in a few cases (mainly using MS native multimedia) modules, there's no real need so far (or it hasn't been run into yet).

See the configuration part of the User's Guide for more details.

Midi mapper

The Midi mapper configuration is the same as on Windows 9x. Under the key

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Multimedia\MIDIMap
	  

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Schemes\%name_of_scheme%
	  

To provide enhanced configuration and mapping capabilities, each driver can define under the key

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Ports\%driver_name%
	  

ACM

To be done (use the same mechanism as MCI drivers configuration).

VIDC

To be done (use the same mechanism as MCI drivers configuration).

Windows 9x multimedia architecture

             |
Kernel space |                    Client applications
             |
             |           | |         ^ ^       | |          | |
             |        16>| |<32   16>| |<32 16>| |<32    16>| |<32
             |           | v         | |       | v          | v
             |      +----|-----------|---------|------------|-------+
             |      |    |           |         |            |       |  WinMM.dll
             |      |    |           |         |            |       |   32 bit
             |      +----|-----------|---------|------------|-------+
             |           | |         | ^       | |          |
             |  +------+ | |<16      | |       | |<16       |
             |  |   16>| | |         | |       | |          |
             |  |      v v v         | |       v v          v
             |  |   +---------------+---+-------------+-------------+
             |  |   | waveInXXX     |   | mciXXX      | *playSound* |
             |  |   | waveOutXXX    |   |             | mmioXXX     |
             |  |   | midiInXXX     |   |             | timeXXX     |
             |  |   | midiOutXXX    |   |             | driverXXX   |
             |  |   | midiStreamXXX |   |             |             |  MMSystem.dll
             |  |   | mixerXXX      |   |             |             |     16 bit
 +--------+  |  |   | auxXXX    +---+   +---+ mmThread|             |
 |MMDEVLDR|<------->| joyXXX    | Call back | mmTask  |             |
 +--------+  |  |   +-----------+-----------+---------+-------------+
     ^       |  |          |       ^    ^     | ^
     |       |  |       16>|       |<16>|  16>| |<16
     v       |  |          v       |    |     v |
 +--------+  |  |   +-------------+    +----------+
 |  VxD   |<------->|    *.drv    |    | mci*.drv |
 +--------+  |  |   +--------------+   +-----------+
             |  |    |  msacm.drv  |    | mciwave  |
             |  |    +--------------+   +-----------+
             |  |     | midimap.drv |    | mcimidi  |
             |  |     +-------------+    +-----------+
             |  |    Low-level drivers    |    ...   | MCI drivers
             |  |                         +----------+
             |  |                               |
             |  |                               |<16
             |  +-------------------------------+
             |
	

The important points to notice are:

• all drivers (and most of the core code) is 16 bit

• all hardware (or most of it) dependent code reside in the kernel space (which is not surprising)

Wine multimedia architecture

             |
Kernel space |                    Client applications
             |
             |           | |         ^ ^       | |          | |
             |        16>| |<32   16>| |<32 16>| |<32    16>| |<32
             |           | |         | |       | |          | |
             |  +------+ | |         | |       | |          | |
             |  |32/16>| | |         | |       | |          | |
             |  |      v v v         | |       v v          v v
             |  |   +---------------+---+-------------+-------------+
             |  |   | waveInXXX     |   | mciXXX      | *playSound* |
             |  |   | waveOutXXX    |   |             | mmioXXX     | WinMM.dll
             |  |   | midiInXXX     |   |             | timeXXX     |   32 bit
             |  |   | midiOutXXX    |   |             | driverXXX   |
             |  |   | midiStreamXXX |   |             |             | MMSystem.dll
             |  |   | mixerXXX      |   |             |             |   16 bit
             |  |   | auxXXX    +---+   +---+ mmThread|             |
             |  |   | joyXXX    | Call back | mmTask  |             |
             |  |   +-----------+-----------+---------+-------------+
             |  |         ||      ^    ^     ||    ^^
             |  |      16>||<32   |<16>|  16>||<32>||<16
             |  |         vv      |<32>|     vv    ||
+---------+  |  |   +-------------+    +----------+
|HW driver|<------->|    *.drv    |    | mci*.drv |
+---------+  |  |   +--------------+   +-----------+
             |  |    |  msacm.drv  |    | mciwave  |
             |  |    +--------------+   +-----------+
             |  |     | midimap.drv |    | mcimidi  |
             |  |     +-------------+    +-----------+
             |  |    Low-level drivers    |    ...   | MCI drivers
             |  |                         +----------+
             |  |                               |
             |  |                               |<32/16
             |  +-------------------------------+
             |
	

From the previous drawings, the most noticeable differences are:

• low-level drivers can either be 16 or 32 bit

• MCI drivers can either be 16 or 32 bit

• MMSystem and WinMM will be hosted in a single elfglue library

• no link between the MMSystem/WinMM pair on kernel space shall exist. For example, there will be a low level driver to talk to a UNIX OSS (Open Sound System) driver

• all built-in drivers (low-level and MCI) will be written as 32 bit drivers

• all native drivers will be 16 bits drivers

Contents

tbd

Status

tbd

Caching

The MSACM/MSACM32 keeps some data cached for all known ACM drivers. Under the key

		  Software\Microsoft\AudioCompressionManager\DriverCache\<driver
		  name>
	  

• aFormatTagCache which contains an array of DWORD. There are two DWORDs per cFormatTags entry. The first DWORD contains a format tag value, and the second the associated maximum size for a WAVEFORMATEX structure. (Fields dwFormatTag and cbFormatSize from ACMFORMATDETAILS)

• cFilterTags contains the number of tags supported by the driver for filtering.

• cFormatTags contains the number of tags support by the driver for conversions.

• fdwSupport (the same as the one returned from acmDriverDetails).

The cFilterTags, cFormatTags, fdwSupport are the same values as the ones returned from acmDriverDetails function.

Why #ifdef MyOS is probably a mistake.

Operating systems change. Maybe yours doesn't have the foo.h header, but maybe a future version will have it. If you want to #include <foo.h>, it doesn't matter what operating system you are using; it only matters whether foo.h is there.

Furthermore, operating systems change names or "fork" into several ones. An #ifdef MyOs will break over time.

If you use the feature of autoconf -- the Gnu auto-configuration utility -- wisely, you will help future porters automatically because your changes will test for features, not names of operating systems. A feature can be many things:

• existence of a header file

• existence of a library function

• existence of libraries

• bugs in header files, library functions, the compiler, ...

You will need Gnu Autoconf, which you can get from your friendly Gnu mirror. This program takes Wine's configure.ac file and produces a configure shell script that users use to configure Wine to their system.

There are exceptions to the "avoid #ifdef MyOS" rule. Wine, for example, needs the internals of the signal stack -- that cannot easily be described in terms of features. Moreover, you can not use autoconf's HAVE_* symbols in Wine's headers, as these may be used by Winelib users who may not be using a configure script.

Let's now turn to specific porting problems and how to solve them.

MyOS doesn't have the foo.h header!

This first step is to make autoconf check for this header. In configure.in you add a segment like this in the section that checks for header files (search for "header files"):

AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
        

If your operating system supports a header file with the same contents but a different name, say bar.h, add a check for that also.

Now you can change

#include <foo.h>
        

to

#ifdef HAVE_FOO_H
#include <foo.h>
#elif defined (HAVE_BAR_H)
#include <bar.h>
#endif
        

If your system doesn't have a corresponding header file even though it has the library functions being used, you might have to add an #else section to the conditional. Avoid this if you can.

You will also need to add #undef HAVE_FOO_H (etc.) to include/config.h.in

Finish up with make configure and ./configure.

MyOS doesn't have the bar function!

A typical example of this is the memmove function. To solve this problem you would add memmove to the list of functions that autoconf checks for. In configure.in you search for AC_CHECK_FUNCS and add memmove. (You will notice that someone already did this for this particular function.)

Secondly, you will also need to add #undef HAVE_BAR to include/config.h.in

The next step depends on the nature of the missing function.

Finish up with make configure and ./configure.