libtrace – a library function tracer for FS-UAE

Posted on by

During development traces are a really helpful source of information when doing debugging or if you simply want to understand how a system works. When developing for the classic Amiga platform you learn a lot about the inner workings of applications if you could see what library functions they call and what parameters they pass in and get out. You can observe its behavior without having the source code and all that almost live…

Here libtrace comes into play: Its a debugging extension I have written for the famous FS-UAE Amiga emulator that allows you to take this look behind the scenes of the system: You can trace any library and any function set and you will see what function was called by printing its name, the arguments and the values passed in an out…

How does it work?

Build FS-UAE with libtrace

First you need to build a new FS-UAE from source with the libtrace feature. Use my libtrace branch on GitHub for this.

Configure Tracing

You need to write a small config text file that defines the trace profile, i.e. what libraries you want to see and what functions.

Name the file e.g. libtrace.cfg with the following contents:

dos.library
fd/dos_lib.fd
+*
!Open
#
exec.library
fd/exec_lib.fd
InitResident
#

Here we will trace dos.library and exec.library. In dos we want to see all functions (*) but not the Open() call. In exec only the InitResident() function is traced. The .fd files need to reside on your host in the given directory (here in the fd folder of the current directory). Take them from the AmigaOS NDK.

See the libtrace documentation for more details on the config file

Enable Tracing

Now run FS-UAE and enter the debugger with F11+d.

In the Debugger load the config file and enable tracing:

Lc 'libtrace.cfg'
Le 1
x

Exit the debugger and reset your Amiga to activate the trace (F11+r).

With the new Amiga startup you should see the traces popping in on your console.

It looks like this:

@00f81014 0000f8c8:Initial CLI exec InitResident(resident[a1]=00fbf080, segList[d1]=00000000)
@00fbf100 0000f8c8:Initial CLI dos CreateProc(name[d1]=00fbf09a, pri[d2]=00000000, segList[d3]=003efcdb, stackSize[d4]=00000800)
@00fbf100 0000f8c8:Initial CLI dos CreateProc -> d0=0001bd44
@00f81014 0000f8c8:Initial CLI exec InitResident -> d0=000160e0
@00fb85f0 0001c620:CON dos WaitPkt()
@00fb85f0 0001c620:CON dos WaitPkt -> d0=0001c5f0
@00fb85f0 0001c620:CON dos [DosPkt: Type=00000000 Args=00005883,00000000,0000084b,00000000 Res=00000000,00000000]
@00fb8490 0001c620:CON dos StrToLong(string[d1]=0001e06c, value[d2]=0001d0b8)
@00fb8490 0001c620:CON dos StrToLong -> d0=ffffffff

You’ll see the PC calling the function, the exec task with name, the lib and finally the function with all argument names and values. A second line reports the return of the function and prints the result value.

You can filter the trace and focus on a single task if you give its name in the debugger with the Lt option. Furthermore, you can write the traces to a file instead of the console with the Lo command.

Lt 'CON'
Lo 'out.txt'

That’s it… Read the libtrace doc for more details and a technical description of the inner workings of this feature.

Have Fun and Happy Amiga Coding!

Leave a Reply