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 koreader-base/luajit-2.0/src inside the directory where you built KOReader. Start gdb-multiarch:

gdb-multiarch luajit

In the (gdb) prompt, inform the architecture and connect to your device:

set architecture arm
target remote 192.168.15.244:2345

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