Next: , Previous: Native Mode, Up: Top


14 Debugging

14.1 dbprintf

You can use the dbprintf() function to print debug messages. dbprintf uses the builtin sprintf function to format the message, and then calls db_puts to print it. How these messages are printed depends on which version of pinmame you are using. At present, there is no way to see these messages when you are running on real hardware.

If you are running Linux, and you obtain the patches to xpinmame, each character is written to a new hardware register, the debugger port. It acts like a serial port and can be used to communicate between the game program and a separate debug console. The program wpcdebug is the console. Run this at the same time as pinmame and you will see the debug messages printed out. The two programs use a local socket to send data back and forth.

The console also accepts keyboard input and passes it back to the running program. See common/db.c for more information.

Under an unpatched emulator, such as on Windows, debug messages are sent to the WPC parallel port. pinmame writes the printer output to a file in the memcard directory. Under Windows, these files cannot be read while the program is still running.

In either case, the code to drive the serial/parallel port is only enough to keep the emulator happy; none of it would work on real hardware.

14.2 gdb

In native mode only, you can use gdb as you would on any other program. Because native mode uses ncurses, however, it is best to run the debugger in a separate window from the program itself.

Start FreeWPC as usual, then from another window, run make attach. (See the Makefile to see what this does; you really don't need to be in the source tree to do it.) gdb starts, searches for the PID of the program, and attaches to it. The program will stop, and you can then control it from the gdb prompt.

There are some special gdb macros provided in gdbmacros. All of the usual breakpoints, stepping, and variable evaluation commands work as you would expect.

14.3 exec09

exec09 is the 6809 emulator that is provided with GCC6809. exec09 supports a subset of the WPC architecture and can be used as a replacement for PinMAME. It is mostly good for debugging straight CPU code that does not access hardware. It provides a command-line monitor with breakpoints, single-step, and symbolic debugging which is sometimes more useful than PinMAME or gdb.

exec09 can measure the length of time a function takes, including interrupt handlers, which is good for determining performance.

14.4 Breakpoints

FreeWPC now supports breaking into the game program when the compile-time flag CONFIG_BPT is turned on. This works both in emulators and on real hardware. When enabled, this feature overrides the normal use of the Escape coin door button. Pressing Escape now halts the system; press Escape again to resume.

While halted, you can use the Up and Down buttons to view memory.

If a fatal error occurs when the debugger is compiled in, the machine will fall into the debugger instead of rebooting. This will show you what error occurred and which task was last running.

When halted, only normal task scheduling and periodic functions cease to run. Interrupt handlers/realtime functions cannot be halted, and thus, if they fail, the system will behave erratically. (Smoke alert.)

You can also dynamically enable and disable breakpoints at various places within the code, so that the debugger will start when the program hits that location, without having to press Escape.

14.5 Switch Stress Test

The switch stress test is used to test switch handling over a long period of time. When enabled, this adjustment causes the game to pretend that switch closures are occurring randomly. No balls are actually put into play, but the machine is fooled into thinking so.

Stress test also exercises ball devices correctly, and simulates 'enter' events instead of individual device switches. Ball locks, trough serves, and multiballs can all be tested.

You can force end-of-ball by pressing the Start Button several seconds after the start of the ball (the delay allows you to still add players to test multiplayer games). If in multiball play, pressing Start simulates the drain of exactly one ball at a time.

Closures are simulated randomly at a rate of about 10 per second. This test has been used to uncover some hard to find bugs in the game logic after extended play.

Naturally, this feature is disabled by default.