~drache/dusk-debug

#Dusk symbols for GDB

This repository contains a few scripts which generate an ELF file suitable for debugging DuskOS with GDB.

#Retrieving word information

The project requires a list of words next to their address. To do so, define the function mwords inside of Dusk as described in mwords.fs, then run it.

~~Then clean all the lines before ---DEBUG WORD LIST---, this one included.~~

You should have a file which looks like the following:

...
---DEBUG WORD LIST---
...
*, 80083b68
^, 80083b34
|, 80083b00
&, 80083acc
swap-, 80083a98
...

Name it syms.log for the Makefile to work seamlessly.

#Printing to a logfile for QEMU

Here is an example for the riscv target on how to output all the lines displayed by DuskOS to a syms.log file.

# ...

emul: $(TARGETS)
	qemu-system-riscv32 -M virt -bios none -display none \
		-chardev stdio,id=char0,logfile=syms.log,signal=on \
		-serial chardev:char0 \
		-device loader,addr=0x80000000,file=riscvkernel.img \
			-device loader,addr=0x83000000,file=riscvfat.img

#Building and running

Everything needed to build the project is a C compiler and the <elf.h> header. This project should normally be ANSI compliant, it is made for C90 support.
The GNU linker ld is also needed to generate the ELF file from the linker script. If another linker support those linker scripts it should work as well.

Once you have those dependencies and your syms.log file, simply run

make all

Once the syms.debug file created, you can run GDB and add the symbols:

add-symbol-file syms.debug

Note that some symbols have unusual names (as it is allowed in Forth), don't forget to wrap their name in single quotes when needed.

break '*'

#Configuration

There are a few defined constants which can act as basic configuration:

OFFSET: the global offset used for all functions, by default at 0x80000000
REPLACEMENT_CHAR: with which character we replace " for the linker script
MAXIMUM_SIZE: at which point we consider the symbol too big to be a function
DEFAULT_SIZE: the default size of a symbol (if too big or too small)
CUSTOM_SIZE_PATH: the path of the file to look for custom sizes

The OFFSET can technically always be 0 and nothing bad should happen.

If the UNWRAPPED environment variable is set, then the program will not search for a ---DEBUG WORD LIST--- header and will assume there are only valid lines in the input file.

#Custom sizes for symbols

You can define a list of custom sizes for symbols in the file named CUSTOM_SIZE_PATH ("sizes" by default). This list will then override the naive sizes when building the .debug target.

Note that it must be of format <addr> <size> where addr is in base 16 and size in base 10. For example:

80083acc 44

#Improvements

There is no guarantee that I will ever implement those:

[x] Automate the ---DEBUG WORD LIST--- part
[ ] Replace back the \`` character with "`
[ ] Write an elf.h shim
[x] Make it possible to specify some symbol sizes manually
[ ] Add 32bit support

refs