Chapter 1. Debugging Wine

1.1. Introduction

1.1.1. 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 thread, 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 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, are indirections to system objects (in this case processes or threads). 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).

1.1.2. 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 first part of the debugging APIs (in KERNEL32.DLL) allows a W-process, called the debugger, to control the execution of another W-process, the debuggee. To control means stopping/resuming execution, enabling/disabling single stepping, setting breakpoints, reading/writing debuggee memory... Another part of the debugging APIs resides in DBGHELP.DLL (and its ancestor IMAGEHLP.DLL) and lets a debugger look into symbols and types from any module (if the module has been compiled with the proper options).

winedbg is a Winelib application making use of these APIs (KERNEL32.DLL debugging API and class="libraryfile"DBGHELP.DLL) to allow debugging both any Wine or Winelib application as well as Wine itself (kernel and all DLLs).