Outline:

tutorials/tutor0

You can build this example with:

> make clean; make

This tutorial will describe a minimal skeleton program which links AGT library code and uses it to detect the machine type, while highlighting a few minimum requirements to build/link a valid program.

Skeleton program:

The first program 'tutor0' is really just a skeleton program that builds and prints a message when run. It doesn't really use AGT except to configure() itself and report the machine type. It does however contain some basic stuff that's more or less the same for any AGT program (at least, for the samples provided).

Headers:

AGT requires certain headers to be included to configure and use features. Some are mandatory in the main sourcefile.

#include "agtsys/common_cpp.h"

This one covers some C/C++ language support, common [types], helper functions and other useful stuff.

#include "agtsys/ealloc.h"

This provides access to memory allocation functions. Special versions of malloc/free which track activity.

#include "agtsys/system.h"

This provides access to system services including machine state save/restore, machine detection, natfeats debugging and (debug) raster timing macros.

#include "agtsys/spritesheet.h" #include "agtsys/slabsheet.h" #include "agtsys/entity.h"

These are not used in tutor0 but currently required anyway. They are needed by any realistic AGT program.

IMPORTANT: The following details are accurate for the 'default' source control branch. Pending versions use a new method to set up supervisor/stack and program entrypoint which looks a little different. Docs will be updated to reflect the changes as they are introduced to 'default'.

Definitions:

A few things must be defined for AGT to produce a valid program.

machine machinestate;

The 'machine' class provides an interface to detecting, self-configuring, saving/restoring the machine state before any other hardware features are used. The object 'machinestate' is an instance of that interface which will be used by the program.

entity_t *g_pe_viewport = NULL;

This defines a global pointer to the 'viewport' entity. Some AGT engine components depend on it. Since we're not using viewports (or entities) yet, its NULL.

Next is the stack definition and standard entrypoint AGT_MAIN:

S_SUPER_SSP(AGT_CONFIG_STACK);

AGT_MAIN;

If LINK_MINIMAL=no was specified in the makefile, the program must define and set its own supervisor stack. This line implements the stack storage buffer. It dissolves away to nothing if LINK_MINIMAL=yes, which is our default.

The Code:

The program begins with...

int AGT_EntryPoint()
{

Next we configure AGT according to the hardware it is running on. This detects the machine type and helps set up other components before use. It does not modify the hardware state itself - just checks & configures.

machinestate.configure();

Once this is done, we can use the detected machine flags to print a message.

    if (bSTE)
    {   
        printf("machine: STE\n"); 
    }

The program ends with a return value:

    pprintf("terminate...\n");

    return 0;
}

That's all there is to tutor0. Not very exciting, but it'll help when looking at the next, more interesting sample...