Getting Started

Optional Stuff

Structure of a task

Although not absolutely necessary, a task typically is a routine with an entry, some initialization and then an endless loop.  The endless loop typically involves blocking, or waiting, on a semaphore.  That might be explicitly as in the case of AvrXWaitSemaphore, or it might be implicit in the case of AvrXWaitTimer or AvrXWaitMessage.  These last two items actually bock on a semaphore embedded in the timer or message data structure.

There are some data structures that need to be defined along with the code.  Most of the work can be avoided by using handy macros defined in AvrX.inc or AvrX.h, depending upon the version being used.

Below is a simple example of a task that simply blocks on a timer and signals a semaphore.  This is code for AvrX 2.5, the GCC compiler.

Mutex Timeout;

AVRX_TASKDEF(myTask, 10, 3)
{
    TimerControlBlock MyTimer;

    while (1)
    {
        AvrXDelay(&MyTimer, 10); // 10ms delay
        AvrXSetSemaphore(&Timeout);
    }
}

The macro, AVRX_TASKDEF, takes three arguments: the task (procedure) name, the additional stack required above the 35 bytes used for the standard context, and the priority.  It builds all required AvrX data structures and declares the C task procedure.  Please refer to the file AvrX.h for details.

Structure of an Interrupt Handler

Interrupt handlers have to have a specific name associated with them for the GCC compiler to set the appropriate interrupt vector name.  Look at the avr-gcc file sig-avr.h for a list of possible vectors.  AvrX completely handles the saving and restoring of the interrupted context so you DON'T want to use the GCC procedure qualifiers SIGNAL or INTERRUPT.  Instead use the following:

AVRX_SIGINT(SIG_OVERFLOW0)
{
    IntProlog();             // Switch to kernel stack/context
    EndCriticalSection();    // Re-enable interrupts
    outp(TCNT0_INIT, TCNT0); // Reset timer overflow count
    AvrXTimerHandler();      // Call Time queue manager
    Epilog();                // Return to tasks
}

IntProlog() does not re-enable the interrupts in an interrupt handler (this is different from AvrX 2.3) so if you want to be able to nest interrupts you need to explicitly enable them in your handler.  Also, beware, some sources of interrupts are not cleared by servicing the interrupt handler, so you need to clear them BEFORE enabling interrupts or you will endlessly re-enter your code and blow your stack.  The serial UART handlers are a good example of this.  Check the serial I/O files to see how this is handled.

AvrX 2.3 enables interrupts by default in IntProlog(), so you need to clear any pending interrupts BEFORE calling IntProlog().

Structure of your main() code:

The main() code simply initializes hardware and any tasks and then jumps to Epilog().  Here is the main() for the sample file "messages.c"   (Please refer to the actual sample as coding styles have changed since this was originally written)

void main(void)                // Main runs under the AvrX Stack
{
    outp((1<<SE) , MCUCR);     // Enable "Sleep" instruction for idle loop

    outp(TCNT0_INIT, TCNT0);   // TCNT0_INIT defined in "hardware.h"
    outp(TMC8_CK256 , TCCR0);  // Set up Timer0 for CLK/256 rate
    outp((1<<TOIE0), TIMSK);   // Enable0 Timer overflow interrupt

    outp(-1, LED-1);           // Make PORTB output and 
    outp(-1, LED);             // drive high (LEDs off)

    AvrXRunTask(TCB(task1));
    AvrXRunTask(TCB(task2));
    AvrXRunTask(TCB(Monitor));

    InitSerialIO(UBRR_INIT);    // Initialize USART baud rate generator

    Epilog();                   // Switch from AvrX Stack to first task
}

Determining the size of various stacks

For AvrX 2.6 the task stack needs to be 35 bytes + any additional stack needed by the task code.  The C compiler makes pretty heavy use of the stack when calling procedures.  It just depends upon how many automatic variables are used in each procedure.  The best way to determine proper stack sizing is to allocate lots of stack (say, 70 bytes) and run your application for a while to see how deep the stack gets.  Since GCC zeros all memory during startup it is pretty easy to tell. However, to be safe, use the emulator or debug monitor to write a few words of 0xFFFF near the perceived end of the stack to verify exactly how deep it gets.  Then, allocate a couple more bytes (at least one or two words) extra to insure you don't run over onto another stack or data structure.

Determining the kernel stack size is a little easier.  AvrX doesn't consume much stack in it's normal operation.  Perhaps 4-6  bytes at the most.  However, the kernel is re-entrant and will stack a full context for each interrupt that is nested.  So, you need to multiply the total number of interrupt sources (assuming they are all active at all times) by 35 and add any additional stack used by the interrupt code + 4-6 bytes used by AvrX to get a rough idea of the total stack needed.  Of, course, if your application has an interrupt that doesn't use AvrX (e.g. no IntProlog()/Epilog()) then it only stacks whatever it uses onto the kernel stack or the user stack.  In either case, use the above procedure to determine the exact size: allocate extra space, run your application for a while (exercising the interrupt sources) and see just how deep the stack gets.  You might have to deduce the maximum possible depth as some interrupt sources might not happen often enough to cover all possible cases.  For high speed stuff (e.g. serial link dumping lots of data, basic timer for the clock) usually all possible combinations will be covered within a short while.