Remote debugging with gdbserver

Making a debug build

First of all, you need to make a debug build. If you have already built KOReader, clean your tree:

make clean

disable stripping in koreader-base

Edit koreader-base/Makefile. Find the following lines and comment them as below:

#ifndef EMULATE_READER
#       $(STRIP) --strip-unneeded \
#               $(OUTPUT_DIR)/extr \
#               $(OUTPUT_DIR)/sdcv \
#               $(LUAJIT) \
#               $(OUTPUT_DIR)/libs/*.so*
#endif

koreader-base building settings

Edit koreader-base/Makefile.defs. Look for the following line and comment it as below:

#BASE_CFLAGS:=-O2 -ffast-math -pipe -fomit-frame-pointer

And uncomment the following line:

BASE_CFLAGS:=-O0 -g

luajit building settings

Edit koreader-base/luajit-2.0/src/Makefile. Look for and uncomment the following lines:

CCDEBUG= -g

XCFLAGS+= -DLUAJIT_USE_GDBJIT

XCFLAGS+= -DLUA_USE_APICHECK

XCFLAGS+= -DLUA_USE_ASSERT

The LUA_USE_APICHECK and LUA_USE_ASSERT are not really needed for our purpose (using remote gdb), but they are often useful for debugging koreader-base.

You may also want to enable Valgrind support, although for this to be useful we still would need to build a valgrind package able to run in the Kindle or in the Kobo (currently not done yet).

XCFLAGS+= -DLUAJIT_USE_VALGRIND

Build it

Build KOReader as usual. For the Kindle:

make customupdate

Or for the Kobo:

make TARGET_DEVICE=KOBO koboupdate

Running in your device

The Kindle comes with gdbserver pre-installed, at least on FW 5.x, so you don't need to install any additional software in the device.

Edit the shell script koreader.sh or koreader_kobo.sh present in your device. Look for the line which calls reader.lua:

./reader.lua "$@" 2> crash.log

Prefix the line with gdbserver :2345 ./luajit ./koreader-base . You might also want to remove 2> crash.log if you are launching KOReader from a ssh session. For example:

gdbserver :2345 ./luajit ./koreader-base ./reader.lua "$@"

Now launch KOReader. It will wait for your computer to connect to gdbserver before proceeding.

Debugging from your computer

Suppose the IP address of your device is 192.168.15.244 (which is the default IP address for Kindle with USBNet). Change if your device has another address.

Go to the directory where you built KOReader and do a cd koreader-arm-*/koreader. Start gdb-multiarch. In the (gdb) prompt, inform the architecture, load the symbols, and connect to your device:

set gnutarget elf32-littlearm
file luajit
target remote 192.168.15.244:2345

Now set any breakpoints you might want to set, then issue the continue command to start running.

Workaround for debugging shared libraries

If you need to set any breakpoints in code outside the main luajit executable, a little trick is needed. For some reason, when using this kind of remote debugging, gdb currently only loads symbols from the libraries if you instruct do to it after the program is already running. So, after you issued continue in gdb prompt, interrupt execution (pressing the keys Ctrl+C), and enter the following command:

set solib-search-path libs

Then, symbols from the shared libraries should be loaded.