Preparing ARM Enabled Projects for the Gopher2600 Debugger - JetSetIlly/Gopher2600-Docs GitHub Wiki

In order to debug ARM enabled Atari 2600 ROMs most effectively, the ARM code must be compiled with DWARF debugging enabled.

This page explains the how to prepare your project for effective debugging. It is assumed that you already have a project that produces a working ROM file. It also assumes that you are using the GCC compiler. Other compilers should work so long as they produce standard DWARF data (version 2 or version 4).

For a full list of GCC compiler options targeting the ARM see gcc.gnu.org

ELF projects have the most straightforward structure of all ARM enabled Atari 2600 ROMs. As such, they are the easiest to prepare for the debugger.

For example, to build a project, mygame, the following command line will suffice:

arm-none-eabi-gcc -r -mlong-calls -fno-exceptions -march=armv7-m *.c -omygame.bin -O2 -Wall -g3 -gdwarf-4 -gstrict-dwarf

The key arguments on this command line are -g3 -gdwarf-4 -gstrict-dwarf and should always be present in addition to whatever other arguments your project requires.

The binary file can be loaded directly into Gopher2600 either to play or to debug. The same binary will also run on a PlusCart or UnoCart, but for distribution purposes you should strip the debugging data.

arm-none-eabi-strip mygame.bin -d -R.comment -R.ARM-attributes

Preparation of CDFJ projects follow the same principles for ELF projects. The arguments that you must give to your compiler are:

-g3 -gdwarf-4 -gstrict-dwarf

For example, using Spiceware's "Collect3" project as a reference the, "C Compiler flags" section of the Makefile should be changed to:

OPTIMIZATION = -Os 
CFLAGS = -mcpu=arm7tdmi -march=armv4t -mthumb # -mthumb-interwork
CFLAGS += -g3 -gdwarf-4 -gstrict-dwarf
CFLAGS += -Wall -ffunction-sections # -save-temps #-mlong-calls 
CFLAGS += $(OPTIMIZATION) $(INCLUDES)
CFLAGS += -Wl,--build-id=none

(The only change here is the addition of the third line)

In the case of the "Collect3" project, this change causes the intermediate ELF file to be built with debugging data.

DPC+ projects are very similar to CDFJ projects. Again, the important compiler arguments are:

-g3 -gdwarf-4 -gstrict-dwarf

Using Spiceware's "Collect2" project as a reference, the "C Compiler flags" section of the Makefile should be changed to:

OPTIMIZATION = -Os 
CFLAGS = -mcpu=arm7tdmi -march=armv4t -mthumb # -mthumb-interwork
CFLAGS += -g3 -gdwarf-4 -gstrict-dwarf
CFLAGS += -Wall -ffunction-sections -save-temps -g -Wa,-a,-ad,-alhms=$(<:%.c=$(BIN)/%.lst) # -mlong-calls -save-temps 
CFLAGS += $(OPTIMIZATION) $(INCLUDES)

(The only change here is the addition of the third line)

As in the case of CDFJ project, this causes the intermediate ELF file to be built with debugging data.

ACE projects are very specialised projects and to a certain extent have been superseded by the more flexible ELF project type. None-the-less, ACE projects can also be built with DWARF data using the same principles as the project types described above. That is, invoke the C compiler with the -g3 -gdwarf-4 -gstrict-dwarf arguments.

Once your project has been prepared for the production of DWARF debugging data, the Atari 2600 ROM file can be loaded into Gopher2600 as normal.

In the case of ELF projects, so long as you have not stripped the binary, the debugging data will be automatically loaded.

In the case of CDFJ and DPC+ projects, the debugging data is held in the intermediary ELF file. If your project is structured like Spiceware's example "Collect" projects, then Gopher2600 will find this ELF file and load the debugging data automatically

In fact, Gopher2600 will look in a few places for the debugging data, so you project doesn't have to be structured exactly like the "Collect" projects.

• The intermediary ELF file must be named either:
  • armcode.elf
  • custom2.elf
  • main.elf
• The file must be located either:
  • In the same directory as the ROM file
  • Or in a sub-directory named:
    • main
    • main/bin (or main\bin for Windows users)
    • custom/bin (custom\bin for Windows users)
    • arm

In exceptional cases, you can specify the ELF file on the command line with the -elf argument.

gopher2600 debug -elf myCDFJproject.elf myCDFJfinalgame.bin

DWARF data does not embed the source code of your project in either the final or intermediary ELF file. It does however contain the location information (or path information) for the source code.

This means that if you move a project's location, either to another place on your computer or if you download an example project, it should be completely recompiled in order for the debugging data to be as fresh as possible.

It is sometimes useful to view the DWARF information without resorting to emulation. To create a dump of the DWARF data use the readelf tool from the toolchain you used to create the binary.

arm-none-eabi-readelf --debug-dump <elf file>

Similarly, to create a dump of the assembled instructions use the objdump tool from the same toolchain.

arm-none-eabi-objdump -Sdrl <elf file>

More specialist uses of objdump allow you to view the location list and frame information. It's unlikely you'll need to inspect this information but it was useful to me during development of the emulator.

arm-none-eabi-objdump --dwarf=loc <elf file>

arm-none-eabi-objdump --dwarf=frames <elf file>