How to debug an IOC running on MSWindows using windbg

[<Paul.gibbons@diamond.ac.uk>]

 

The following is a list of instructions to allow debugging of an EPICS IOC on Windows using the Microsoft Windows Debugger (WinDbg).

I have little development experience of EPICS but medium experience of windbg. On hearing that people were experiencing problems debugging iocs on Windows I

decided to check it out.

 

 

Brief Introduction to Windows Debugger and comparison with Visual Studio

------------------------------------------------------------------------

WinDbg provides a user interface to the underlying debugging engine called Windows Debugger which is implemented in dbgeng.dll. Other interfaces to this engine exist which collectively are called Windows Debuggers. Note that the Visual Studio debugger is completely different to the Windows debugger; however it is possible to integrate use of the Windows Debugger within Visual Studio in Windows 7 and later.

For more information see the documentation in the Windows SDK.

 

Brief Introduction to winDbg

----------------------------

Microsoft Windows Debugger (WinDbg) is a powerful Windows-based debugger that is capable of both user-mode and kernel-mode debugging. WinDbg provides debugging for the Windows kernel, kernel-mode drivers, and system services, as well as user-mode applications and drivers.

 

WinDbg uses the Visual Studio debug symbol formats for source-level debugging. It can access any symbol or variable from a module that has PDB symbol files, and can access any public function's name that is exposed by modules that were compiled with COFF symbol files (such as Windows .dbg files). WinDbg can view source code, set breakpoints, view variables (including C++ objects), stack traces, and memory. Its Debugger Command window allows the user to issue a wide variety of commands. For kernel-mode debugging, WinDbg typically requires two computers (the host computer and the target computer). WinDbg also supports various remote debugging options for both user-mode and kernel-mode targets.

 

WinDbg is a graphical-interface counterpart to CDB/NTSD and to KD/NTKD.

 

Building EPICS base, an IOC and symbol files

--------------------------------------------

1. Download and build EPICS base.

Simply follow the existing instructions on the ANL EPICS Windows page( http://www.aps.anl.gov/epics/base/win32.php), including the additional instructions

posted by Carsten Winkler.(http://www.aps.anl.gov/epics/tech-talk/2010/msg00595.php)

 

I choose to use:

Visual C++ 2010 Express

7zip

ActivePerl

GnuWin 3.8.1

 

Note that I set EPICS_HOST_ARCH=win32-x86 although the OS is Windows 64bit.

 

 

2. Build the example ioc

a)Follow the instructions in the Application Developer Guide section 2.2.2 (http://windbg.info/download/doc/pdf/WinDbg_A_to_Z_color.pdf)

mkdir c:\ioc1

cd c:\ioc1

c:\base-3.14.12\bin\win32-x86\makeBaseApp.pl -t example myexample

c:\base-3.14.12\bin\win32-x86\makeBaseApp.pl -i -t example myexample

 

b) Add compiler and linker flags to build a PDB symbol file.

I added the following statements in <top>\configure\CONFIG. e.g. c:\ioc1\configure\CONFIG

USR_CFLAGS += -DDEBUG  /Zi /O2

 

USR_CPPFLAGS += -DDEBUG /Zi /O2

 

USR_LDFLAGS += /INCREMENTAL:NO /DEBUG /OPT:REF /OPT:ICF

 

I expect someone with better knowledge of the EPICS build system could suggest a better method to add these flags.

 

c) Compile and link

cd c:\ioc1

make

 

Start the IOC

-------------

Just follow the instructions in Application Developer Guide section 2.2.7

e.g.

c:\ioc1>cd iocBoot\iocmyexample

c:\ioc1\iocBoot\iocmyexample>..\..\bin\win32-x86\myexample.exe st.cmd

epics> dbl   (note that name of the machine is paulgibbonsHost, this will be replaced by the name of your machine )

paulgibbonsHost:ai1

paulgibbonsHost:ai2

paulgibbonsHost:ai3

paulgibbonsHost:aiExample

paulgibbonsHost:aiExample1

paulgibbonsHost:aiExample2

paulgibbonsHost:aiExample3

paulgibbonsHost:aSubExample

paulgibbonsHost:calc1

paulgibbonsHost:calc2

paulgibbonsHost:calc3

paulgibbonsHost:calcExample

paulgibbonsHost:calcExample1

paulgibbonsHost:calcExample2

paulgibbonsHost:calcExample3

paulgibbonsHost:compressExample

paulgibbonsHost:subExample

paulgibbonsHost:xxxExample

epics>

 

Test the ioc

C:\Users\paul gibbons>caget paulgibbonsHost:ai1

paulgibbonsHost:ai1            5

 

 

Install and start Windbg

------------------------

Download and install the Windows SDK. Note that you only need the Debugging Tools.

Start windbg from the newly created Windows Kits in the Start menu.

 

Attaching windbg to a process and stepping through code

-------------------------------------------------------

Use File | Attach to a Process.. and select the ioc process. In the example above the process is called myexample.exe

Note that the process is interrupted by this action. To continue execution use menu Debug | Go.

 

To control the debugger first interrupted execution of the process using command Debug | Break.

To view the loaded modules (exe, dll) use the command lm

To load the symbol file for a module for which the loading of symbols is shown as deferred enter the command >ld <module> e.g. >ld myexampleSupport

To view all the symbols of the module myexampleSupport enter the command >x myexampleSupport!*

 

If the function on which you wish to set a break point is viewable by the x command then you can set a breakpoint using the command>bpx <address>

 

In this example we will set a breakpoint on the function process defined in C:\ioc1\myexampleApp\src\xxxRecord.c which is built into the module myexampleSupport.dll

>bp myexampleSupport!process

 

Now continue execution of the ioc using Debug | Go.

 

xxxRecord defines the record type xxx, of which the PV paulgibbonsHost:xxxExample is an instance. So to cause the breakpoint to be fired we simple do a caput on this record

>caput paulgibbonsHost:xxxExample 1

 

On detection of the breakpoint windbg will open the relevant source file at which point you can view variables and step through code.

 

Note that we have not had to tell windbg where to find the symbol file (pdb) or source code as it is in the position recorded in the executable module. You can however tell

windebg where to find these using the commands:

File | Symbol File Path to specify the path in which to search for symbol files. In this example C:\ioc1\myexampleApp\src\O.win32-x86

File | Source File Path to specify the path in which to search for source files. In this example C:\ioc1\myexampleApp\src

 

 

 

 

 

-- 

This e-mail and any attachments may contain confidential, copyright and or privileged material, and are for the use of the intended addressee only. If you are not the intended addressee or an authorised recipient of the addressee please notify us of receipt by returning the e-mail and do not use, copy, retain, distribute or disclose the information in or attached to the e-mail.
Any opinions expressed within this e-mail are those of the individual and not necessarily of Diamond Light Source Ltd.
Diamond Light Source Ltd. cannot guarantee that this e-mail or any attachments are free from viruses and we cannot accept liability for any damage which you may sustain as a result of software viruses which may be transmitted in or with the message.
Diamond Light Source Limited (company no. 4375679). Registered in England and Wales with its registered office at Diamond House, Harwell Science and Innovation Campus, Didcot, Oxfordshire, OX11 0DE, United Kingdom