The Debug Console

AGT provides a full printf implementation which gets piped to all enabled text devices. There are currently 4 different devices.

First, ensure your Makefile is configured to produce 'testing' (or 'debug') builds and not 'release' builds. This ensures that message print code is not suppressed, otherwise you'll see nothing. Testing builds are optimised like release builds, but retain important debug features & logging support.

'USE_CFG=testing'

TOS/Bconout

This is where message prints get routed by default - until the point where the display becomes owned by AGT. From this point onwards (at least until shutdown/restore/exit) no further output will go to the TOS console. This device is mainly used for basic startup messages but is otherwise of limited use.

AGT Console

AGT has a built-in console device which displays up to 6 lines of text in the lower border of the screen. Since the display is low-resolution, the amount of information displayable here is limited. However it is useful when testing on real hardware, when no other output is convenient.

This can be enabled with 'AGT_CONFIG_DEBUG_CONSOLE' passed via the Makefile.

The console is accessed via keys, so the input device must be configured with...

#!c++
        AGT_InstallInputService();

...just after the call to 'machinestate.claim();'

To view the console, hold down TAB. To toggle the console, hit SHIFT+TAB.

Note: There is a hack you can use to toggle the console without keys - however functions will be added soon to do this properly.

#!c++

// add at top of sourcefile
extern "C" char* console_base;
extern "C" char* show_console;

    // to enable console
    show_console = console_base;

    // to disable console
    show_console = 0;

If the 'xassert(expr)' macro is used within the code to test expressions for true/false, any failed test (i.e. =false) will halt the program and open the console automatically, showing the line number where the fault occurred.

Note that toggling the console just toggles the displaying of the console buffer. If the console is enabled via Makefile, the buffer is updated on every print event - irrespective of whether it toggled for viewing or not.

Steem Boiler Log

Output to the Steem Boiler logfile can be enabled by passing 'AGT_CONFIG_STEEM_DEBUG'.

CAUTION: The Steem Boiler log uses a reserved hardware register address, and causes BUSERR on real STs, or on plain versions of Steem. It is therefore wise to enable this switch only when needed, and then turn it off again before you send your builds to other to try!

Hatari NatFeats Log

Enabling the Hatari logging functionality requires some extra code and initialisation, and an extra switch on Hatari itself.

The AGT side is enabled by setting 'USE_HATARI_NATFEATS=yes' in the Makefile. This is required to ensure the Makefile can link the additional object files required.

Hatari should be started with '--natfeats=yes' on the commandline.

Other devices

It's possible other devices will be added if there is demand - e.g. serial output. However until someone asks, only the current 4 are likely to be provided.