Snork: New Tracing Tool for AmigaOS 4

Hi all! I’d like to introduce Snork, a tool I worked on alongside the DumbPad editor last week.

What is Snork?

Snork is a utility for monitoring and logging function calls to system libraries on AOS4.
It’s designed for developers and advanced users who need to debug applications or analyze system behavior.

Years ago, on AmigaOS 3, I loved using Gerson Kurz’s Snoopy from 1994 (over 30 years ago!), and I appreciated
its script-driven approach, which let me create specific scripts for each debugging task, combining functions
from different libraries as needed, etc. However, the original Snoopy was written in 68k assembly, using SetFunction
to patch jump tables, and isn’t compatible with AmigaOS 4 of course. So, I created Snork, which adopts a similar
script-driven approach but is written in C, using IExec->SetMethod to patch modern library interfaces. It’s not a
direct clone of course, but it borrows the idea of script-based control while being built from scratch for AmigaOS 4.

While AmigaOS 4 has tools like glSnoop by Capehill (focused on ogles2.library and warp3dnova.library) and Snoopy
by Colin Wenzel (focused on dos.library with a GUI), these are limited to specific libraries. Snork, on the other
hand, monitors function calls to system libraries like dos.library, intuition.library, exec.library, and others,
with plans to support most system libraries in future versions. In its first version, Snork supports only dos.library
and intuition.library and does not handle functions with variable arguments (e.g., tags or ...), support of which and
additional libraries is planned for the next version.

Download it here: https://kas1e.mikendezign.com/aos4/debug/snork/snork_v01.lha


How Snork Works


Snork reads a configuration script called main.snork to determine which libraries and functions to monitor. Here’s how it operates:

Reads the Script: Parses main.snork to identify libraries (via base= lines) and functions to intercept (via watch= lines),along with logging templates.
Patches Functions: Replaces function pointers in library interfaces with wrappers that log parameters before calling the original functions.
Logs Parameters: Outputs logs to the serial port using IExec->DebugPrintF. You’ll need a terminal or a tool like Sashimi to view them.
Handles Events: Runs in the background, responding to Ctrl+C to stop and clean up resources.

(click open in new tab for fullsize):



This screenshot shows a main.snork script example, the log output, demonstrating how it monitors function calls and part of Snork's guide.

Configuring Snork

Snork is controlled through the main.snork script, where you define libraries and functions to monitor. The scripts directory
includes pre-written templates for all supported functions in dos.library and intuition.library. You can copy specific lines
into main.snork and edit them as needed.

NOTE: Using all templates at once may slow things down due to heavy serial output, so select only what you need. For fun,
you could include everything and watch the serial port get flooded with output!

The script uses two commands at moment:

1. base

Specifies a library and its alias.

Syntax: base=<alias>,<library_name>

alias mean short name (e.g., dos) and library_name mean full name (e.g., dos.library).

Example: base=dos,dos.library



2. watch

Defines a function to monitor and its logging template.

Syntax: watch=<base>,<function>,<template>

base mean library alias, function mean function name (e.g., Write) and template mean Parameter list, e.g., fh=%lp,buf=%lp,len=%ld.

Example: watch=dos,Write,fh=%lp,buf=%lp,len=%ld


Parameter Formats:

%lp: Pointer (hex).
%ld: Long (decimal).
%s: String.
-: Ignore parameter (e.g., fh=-,buf=%lp,len=%ld skips fh).

How to use

After creating a main.snork script (or using the prebuilt default one for initial tests), run Snork in the shell. You’ll see output like this:



As long as you don’t press Ctrl+C, your serial port will show the debug output you specified.

The archive includes a guide with detailed instructions, so check it out for more information.

Feedback and Future Plans

This is the first beta, and there’s room for improvement. Please share your ideas, findings, and suggestions.
What needs to change? What features should be added? Which libraries should come next?
(I’m thinking about exec.library, utility.library, and graphics.library.)

Snork has been tested on real hardware (X5000, Pegasos2) and emulated QEMU/Pegasos2, but bugs are possible, of course.
If you find issues or have ideas about , report it all plz.

Thanks!

Just test it a bit and working fine on SAM460ex.

Just when you CTRL+C Snork just show a simple "Snork ended" on Shell/CLI (and maybe to serial outoput too).

@kas1e

Sounds like a cool tool (love the name!). I like that you can decide which parameters of each function to snoop on, rather than having to see them all, whether you're interested in them or not.

Quote:
It would be nice to be able to see the return value from the patched calls, though that will be a bit more complex as you need to report twice, once before the call and once after.

It would also be nice if it showed the name of the program making the call like OS4 Snoopy does, so you can see which calls are made by the program being debugged (and once you can do that, the option to snoop only on a specified program would help filter out clutter from other programs).

A good deal of caution should be employed when displaying a string parameter. Since one of the uses of the program is debugging, you have to consider that in some cases string pointers may not be valid (illegal values other than NULL or -1), or may not point at a real NUL-terminated string.

Somewhere down the road a standalone GUI tool -- something like MPlayer-GUI -- could be created to build the script files and send them to Snork for processing. But that can wait until all the basics are working.

Quote:
Those would be my choices.

@msteed
Quote:Using a IExec->TypeOfMem() check could partially help: If it returns 0 it's not a virtual address mapped by the kernel, and accessing it will very likely cause a DSI exception.

Quote:Checking that isn't that easy, but possible as well.
Requires using such checks for each MMU page, if it's mapped or not. On most, or maybe all, OS4 systems the MMU page size is 4KB.