Debugging the BOINC Windows Client

From Unofficial BOINC Wiki

Contents 1 General 2 Symbol Files 3 Crashes 4 Callstacks 4.1 Extracting Callstacks 5 Command-Line Options 6 Logging and Error Output

[edit] General

This page contains the basics that will allow you to Debug the BOINC Client Software.

[edit] Symbol Files

Symbol files are used by various Windows debugging engines to match up memory addresses to symbol names. Symbol names are names of variables, functions, and subroutines that a developer has named a piece of code before the compilation process.

The Symbol Files for the BOINC Client Software are used to "fix" the problem occurrence to a specific location in the source code.

The files generally start out like boinc_xxx_pdb.zip where the xxx is the Version Number of the BOINC Client Software you are running.

The uncompressed files should be stored in the same directory as the BOINC Client Software.

[edit] Crashes

If either BOINC Daemon or the BOINC Manager crash, (they unexpectedly stop running or disappear), there should be some diagnostic information recorded in stderrdae.txt for BOINC Daemon and stderrgui.txt for the BOINC Manager.

The diagnostic information we are looking for is called a callstack which is described below.

[edit] Callstacks

Callstacks help us identify where the problem is by telling us which file and what line number in the source code the error occurred in.

Here is an example of a good callstack:

***UNHANDLED EXCEPTION****
Reason: Access Violation (0xc0000005) at address 0x00411A87 write attempt to address 0x00000000

1: 06/08/05 15:07:01
1: c:\boincsrc\main\boinc\client\cs_benchmark.c(310) +8 bytes (CLIENT_STATE::cpu_benchmarks_poll)
1: c:\boincsrc\main\boinc\client\client_state.c(431) +0 bytes (CLIENT_STATE::do_something)

Here is an example of a bad callstack:

***UNHANDLED EXCEPTION****
Reason: Access Violation (0xc0000005) at address 0x7C34FEDC read attempt to address 0x05595D90

1: 06/08/05 00:36:54
1: SymGetLineFromAddr(): GetLastError = 126
1: SymGetLineFromAddr(): GetLastError = 126
1: SymGetLineFromAddr(): GetLastError = 126
1: SymGetLineFromAddr(): GetLastError = 126

[edit] Extracting Callstacks

If we need a callstack to help solve a problem that doesn't manifest itself as a crash you can still extract a callstack from a running program using some freeware tools Microsoft publishes called Debugging Tools for Windows.

The Debugging Tools for Windows can be found here: Debugging Tools for Windows

Once these tools are installed on your machine and the symbol files are extracted to the BOINC Client Software installation directory you can run 'WinDBG.exe' and attach to the 'BOINC.exe' process through the file menu to begin your debugging session. Once 'WinDBG.exe' has attached itself to 'BOINC.exe' you can view the callstack by typing 'kb' in the command window and then hitting enter.

Here is an example of the output 'WinDBG.exe' displays when it dumps a callstack:

ChildEBP RetAddr  Args to Child              
0012fafc 7c821364 77e42439 00000000 0012fb40 ntdll!KiFastSystemCallRet
0012fb00 77e42439 00000000 0012fb40 ffffff4a ntdll!NtDelayExecution+0xc
0012fb68 77e424b7 00000064 00000000 0012fee0 kernel32!SleepEx+0x68
*** WARNING: Unable to verify checksum for C:\Program Files\BOINC\boinc.exe
0012fb78 00430206 00000064 00424b3c 9999999a kernel32!Sleep+0xf
0012fb80 00424b3c 9999999a 3fb99999 00000002 boinc!boinc_sleep+0x16 [c:\boincsrc\main\boinc_public\lib\util.c @ 251]
0012fee0 00424f87 0012fefc 9999999a 3fb99999 boinc!NET_XFER_SET::do_select+0x26c [c:\boincsrc\main\boinc_public\client\net_xfer.c @ 319]
0012fef4 00407a2d 00000000 00000000 7c34f6f4 boinc!NET_XFER_SET::net_sleep+0x17 [c:\boincsrc\main\boinc_public\client\net_xfer.c @ 245]
0012ff18 004225dd 9999999a 3fb99999 00000000 boinc!CLIENT_STATE::net_sleep+0x7d  [c:\boincsrc\main\boinc_public\client\client_state.c @ 369]
0012ff38 0042276f 7ffdf000 00000000 00000000 boinc!boinc_main_loop+0x7d [c:\boincsrc\main\boinc_public\client\main.c @ 331]
0012ff60 00431c0d 00000002 017acfc0 016def68 boinc!main+0x11f [c:\boincsrc\main\boinc_public\client\main.c @ 412]
0012ffc0 77e523cd 00000000 00000000 7ffdf000 boinc!mainCRTStartup+0x143 [f:\vs70builds\3077\vc\crtbld\crt\src\crtexe.c @ 398]
0012fff0 00000000 00431aca 00000000 78746341 kernel32!BaseProcessStart+0x23

Warning: You may need to add the BOINC directory to 'WinDBG.exe' symbol search path from the File menu in order to get a valid callstack.

[edit] Command-Line Options

Some command-line options intended for debugging:

• -exit_when_idle

Exit when we're not working on anything and a Scheduling Server gives a 'no work' return.

• -no_time_test

Don't run performance Benchmarks; used fixed numbers instead.

• -exit_after N

Exit after about N seconds

• -giveup_after N

Give up on file transfers after N seconds (default is 2 weeks)

• -limit_transfer_rate N

Limit total network traffic to N bytes/sec.

• -min

Put BOINC Client Software in the background after starting up

[edit] Logging and Error Output

The BOINC Client Software writes error messages to several Log Files. These Log Files are uniquely named and allows you to know which part of the BOINC Client Software output the information. The Log Files include:

• From the BOINC Daemon:
  • stdoutdae.txt
  • stderrdae.txt
• From the BOINC Manager:
  • stdoutgui.txt
  • stdouterr.txt

The BOINC Client Software writes error messages to stderr. This mechanism is reserved for serious problems, i.e. those that reflect bugs in the core client program or conditions that require user intervention.

In addition, the BOINC Client Software can write a variety of 'logging' information to stdout. The logging options are read from a file log_flags.xml. This file has the following format:

<log_flags>
    [ flags ]
</log_flags>

The flags are as follows:

• <task/>

Log the start, restart and completion of computational tasks.

• <file_xfer/>

Log the start, restart and completion of file transfers.

• <sched_ops/>

Log connections with scheduling servers.

• <state_debug/>

Log changes to the 'client state' data structures.

• <task_debug/>

Log debugging information about task execution.

• <file_xfer_debug/>

Log debugging information about file transfers.

• <sched_op_debug/>

Log the request and reply messages of exchanges with scheduling servers.

• <http_debug/>

Log debugging information about HTTP operations.

• <proxy_debug/>

Log debugging information about Proxy usage.

• <time_debug/>

Log the passage of time.

• <net_xfer_debug/>

Log debugging information about network communication.

• <measurement_debug/>

Log debugging information about measurements of CPU speed, platform, disk space, etc.

• <poll_debug/>

Log debugging information about polling operations.

• <guirpc_debug/>

Log debugging information about the GUI RPC interface.

• <sched_cpu_debug/>

Log debugging information about the CPU scheduler.

• <scrsave_debug/>

Log debugging information about the screen saver.

• <dont_check_file_sizes/>

Unknown usage ...

If the log flag is not recognized, the Error Message: LOG_FLAGS::parse: unrecognized: '(data)' will be output on the Messages Tab and in the Log Files.

Note:

This error message only appears to be written to the Messages Tab and not the Log Files.