29. February 2008 by pilot.

So we understand now what we don’t know (see The Stack … so misunderstood, part 1). We know how to set a minimum limit for the Stack size. We know how to verify how much space the linker has allocated for a project. We DON’T know how much Stack space our project is actually using!

If we have the luxury of being able to simulate the entire application in a complete and realistic scenario, nothing beats the power of MPLAB SIM. We can open the Watch window and keep an eye on WRGE15 and SPLIM. Opening the Stack window we can watch the stack grow and see each function parameters as they are passed along.

But as the complexity of a project grows, full simulations became less likely… and we want to find a way to identify Stack issues at run time when debugging in circuit.

Quite empirically, if a program is not crashing (as in experiencing inexplicable resets) chances are we have not reached the stack limit (yet). But what if we do experience those resets… in a complex application things can go wrong in many ways … it would be nice to be able to pin-point the issue and make a clear determination when we fail because of the stack.
Here is an example project with a (perverse) recursive function (call()) that will exercise the stack available for as many nested calls as the parameter passed: stack.c

Make the parameter large enough or allocate a large enough Heap (8,000?) and sooner rather than later it will produce a Stack Error trap.

By replacing the default trap handler for the _StackError vector, we could perhaps place a function (with an infinite loop) in there to capture and retain control of the application when things go wrong. Placing a breakpoint inside our custom handler we would be immediately alerted as soon as our program reaches the top of the stack space. Here is an example: stack2.c

Unfortunately the new handler, as any C function, is going to need to use the stack itself. Even if we declare it with the no_auto_psv attribute (to avoid saving and restoring the PSV registers values) and even if we don’t use any local variable.

It seems like a catch 22 condition. We cannot write a handler for a Stack Error condition in C because by definition each C function uses at least a small amount of Stack space.

We might be tempted to artificially lower the stack limit (SPLIM) to allow for some extra room for the handler function so to “break the loop”. But this is just an illusion… We cannot know before hand by how much the stack will be exceeded when the trap occurs. In other words, think of a case where the stack is almost all used up, the stack pointer is just one word below the limit and then a function call is made to a routine that allocates 100 bytes for local variables… To get away with it, we should really lower the stack limit for the worst possible case (the function that allocates the largest amount of stack space) but this is exactly the type of complex and manual analysis of a project we were determined NOT to have to go through in the first place (besides a possible big waste of space).

Fortunately to our rescue comes one powerful option of the MPLAB C30 compiler, that allows us to insert custom code before the prologue of an interrupt handler, that is before the stack is touched! It is called the interrupt preprologue. Here is an example of how we would use it, combined with one instruction of inline assembly to achieve a blocking interrupt handler that does not rely on the stack: stack3.c

void __attribute__((no_auto_psv, interrupt( preprologue(”1: bra 1b”))))

where the “1: bra 1b” is a single instruction infinite loop that we insert before the handler prologue.

But by the time we do this and we try to set a breakpoint on the line, we realize that we have gone full circle. This is not C code anymore… and to set the breakpoint we need to switch to the disassembly window…

If we surrender to the evidence, we get a cleaner, less cryptic and overall more elegant solution by using the original code stack.c and including in our project a simple (three lines long) assembly source code:

.global __StackError
__StackError:
bra __StackError

(Note the double underscore before the label StackError)

Save it as stackhandler.s and add it to the project.

Now we can set a breakpoint inside the new handler and we can have our real time debugger to halt and notify us whenever a Stack Error trap is triggered at run time!

Perhaps we learned a good lesson today. Certain things are just meant to be done in assembly! …although there are not that many left anymore!

Posted in Tips and Tricks | No Comments »

28. February 2008 by pilot.

The stack is such a key element of every C program that too often we take it for granted and we don’t spend enough time to make sure we have it set properly. Most often we resolve to look into it only by the time we notice the code is mis-behaving and by trial and error, among many other things, we finally decide to make some more room for it and see if things improve… There has to be a better way to check and debug our stack allocation strategy.
To start with you need to understand how the linker allocates space for it (where and how much) and how we can control the process.

Considering only the PIC24F architecture (the dsPIC and PIC24H will add a few twists to what follows) the stack is defined by the linker as the largest (and last) block of RAM allocated after everything else has been taken care of…

In the simplest possible situation, starting from the lowest RAM addresses (right after the interrupt vectors tables) you will see the linker placing all your programs (global) variables and those required by the libraries you used. Then you will see the Heap (if any size>0 is defined) and last the stack, using up ALL the memory that remained available. A picture is worth a million words, here is what an example for a simple project using the PIC24FJ128GA010 would look like:

Since the stack of the PIC24 grows toward higher addresses as you use it, the stack pointer (WREG15) is initially set at the bottom of the stack area (__SP) by the C startup code. The stack limit register (SPLIM) is also set at this time to be an address just 8 bytes below the physical end of the memory space. The function of SPLIM is that of triggering a trap when our application reaches the upper limit and runs out of stack space.

The trap mechanism is very similar to an interrupt (of the highest possible priority) that calls a specific vector (_StackError) where we can place a handler routine. The MPLAB C30 compiler places a default handler (just a reset instruction) in each trap and each empty interrupt vector unless otherwise instructed. We can of course define a custom trap handler, but first let’s look at how we can control the amount of space reserved for the stack.

The project Build Options dialog box (select Project>Build Options>Project or click on the Build Options button ) is the obvious place where to look and in particular the MPLAB LINK30 pane:

Here the Heap size and Min. Stack size parameters can be passed to the linker.

Notice that I marked in bold the word Min here, because it is way too easy to simply ignore this detail. In fact while we get full control on the size of the Heap, for the Stack we are given only the option to specify a “threshold” below which the linker will be required to “notify us”. The parameter we select here is NOT the value that will be used by the linker to set the initial stack pointer (__SP or WREG15) and/or to decide where the stack limit (SPLIM) is to be set! As we said above, the linker will first allocate all the other memory “objects” and then assign the largest remaining block of memory to the stack. So in other words, the true stack space size is defined sort of by default, as a result of the combination of all the other project parameters.

When all is said and done, the linker finally looks back and verifies that the size it came up with is larger than the Min Stack Size parameter we set. If it is not we get a compile time error right away. But if there is no error, the stack size could be actually much larger than the minimum amount we asked for.

Note that, probably because of my assembly programming background, this behavior is almost the opposite of the way I used to picture it to be. In my mind the stack size was the one deliberately assigned (just like I used to assign manually my stack pointer in the good old assembly days) and the Heap was supposed to be taking the left overs!

As a side effect of this allocation strategy, and mixing it with my (wrong) initial assumptions, I would like to illustrate a scenario that lead me in the past to considerable trouble and had me quite puzzled for a while.

In my application using both large global arrays and dynamic memory allocation (malloc()) I had the Min. Stack parameter set to 512 bytes and the Heap parameter set to 4,192. The application would run normally under these conditions, but the need for more dynamic memory and a few back of the envelope calculations induced me to think that I could really afford to allocate more space for the Heap (according to my estimates I was using only 1,512 bytes of RAM for my global variables) while keeping the stack safely to the present size. So I did increase the Heap size to 6k bytes, the linker did not complain about any issue with the stack, but the application started immediately behaving erratically producing inexplicable occasional resets.

What was going on?

To my surprise, after a lot of head scratching, I realized that my application was really using almost 1Kbytes of stack space. When the Heap was originally set to 4K bytes the Stack had been allocated as much as 2.5K bytes (8K-4K-1.5K=2.5K). A number larger than the minimum I was requesting.
When I increased the Heap size to 6K, the Stack got squeezed to 512 bytes (8K-6K-1.5K=.5K) still ok according to my request to the linker (notify me if less than 512…) but definitely not enough for the appetite of my application.

It is easy to fall in this trap (pun intended) and assume that since your Build Options are specifying X amount of bytes for the Stack, and your application is not crashing, your stack usage is X bytes or less. The actual amount of stack your application has been allocated and might be currently using could be much larger than the minimum specified. Finding out exactly how much could be quite tricky!

One quick reality check can be easily performed though, courtesy of the MPLAB C30 compiler (default options), you can inspect the build report in the output window Build pane:

Circled in red is the actual stack size that, as you can see in the example, is lager (192) than the amount specified in the project build options (64, see previous picture).

But once more, don’t fall in a “new” trap, the reported “allocated” stack space is not telling us how much of it is actually used by the application!

(to be continued…)

Posted in Tips and Tricks | No Comments »

6. February 2008 by pilot.

MPLAB has become such a large application, or I should better say “group” of applications, and it keeps evolving so fast that one can hardly keep up with the pace of monthly (when it is not weekly) updates. Typically before rushing to install a new version I scan quickly through the readme files to see if there is anything new that I could use immediately, otherwise I tend to postpone the update to let it … settle a bit, if you know what I mean.

With MPLAB 8.00 things were different. The PIC32 had just been announced and this was the first new version of MPLAB to openly support it. I was too curious to pass the opportunity and I did the install without paying much attention to what other features had been added.  Turns out, I made a mistake because I failed to notice a powerful update to the Watch window capabilities!

Now you can inspect/watch:

• Aspecific element of an array: ar[12]
• An object pointed to by a pointer: *ptr
• An element of a structure/union: str.mbr
• An element of a structure/union via a pointer: p->mbr
• Perform simple math: vrbl-1
• Use constants defined in the program in all of the above: ar[M_SIZE-1]

Just type these simple expressions directly in the watch window in the Symbol Name column

it will work seamlessly allowing you to get a better picture of your… bugs!

Posted in Tips and Tricks, MPLAB 8.00 | No Comments »

5. February 2008 by pilot.

I am sure you won’t be surprised to learn that most (if not all) of the code presented in the book is derived from my past experimentations on the PIC18 and PIC16 over a few years… In particular the FileIO project started on the PIC18F8720 and was, back then, associated to a different set of low level routines (for Compact Flash FLASH memory cards).

Also during debugging of the PIC24 version, I used static memory allocation (it made inspecting data structures with MPLAB so much easier), so when recently one of my readers asked about the possibility to modify the code to allow for static allocation of the I/O buffers and MEDIA data structures, it was easy for me to provide an “alternative”…

In fact this is nothing but a quick debugging fix, though it could be just your ticket. Below you will find two simple functions designed to replace malloc() and free() that can be inserted at the top of the fileio.c code (and enabled when the macro DBG is defined):

#ifdef DBG
//----------------------------------------------------------------------
// debugging malloc and free
#define F_MAX 2 // max number of files open
MFILE F[F_MAX];
MEDIA disk;
unsigned char B[F_MAX][512];
int Fcount=0, Bcount=0;

void * malloc( unsigned size)
{
if ( size == 512)
{
if ( Bcount<F_MAX)
return (void *)B[Bcount++];
else
return NULL;
}
else if ( size == sizeof( MFILE))
{
if ( Fcount<F_MAX)
return (void *)&F[Fcount++];
else
return NULL;
}
else if ( size == sizeof( MEDIA))
{
return &disk;
}
else
return NULL;
} // malloc

void free( void *p)
{
if (( p == B[0])||( p == B[1]))
Bcount–;
else
Fcount–;
} // free
#endif

NOTE: Should you try to port the code (back) to the C18 compiler, keep in mind that you will need to be very careful to modify the linker script as well to allow for the large buffers requiring more than 256 bytes each … Check the C18 compiler manual for help on how to allocate objects that are larger than 256bytes …

Posted in Chapter 14, Tips and Tricks | No Comments »

4. February 2008 by pilot.

There is one table I have been looking for many times among the PIC24 documentation and could never find… it’s a pin-out table, nothing fancy, but a complete one that would help me figure out quickly how to tell if and where a given I/O is used/shared/multiplexed with what…

Table 1.2 in the PIC24fj128GA010 datasheet  (DS39747C) for example list all the functions but it ends up also listing the same pin many times.  For example pin 44 (in the 100 pin package) is listed as AN15 and CN12 on page 11 and two pages later as RB15. This is very logical and convenient from an editorial point of view, as it allows for a single table to concisely include ALL the information (for all packages), but it makes it very hard for me, when looking for an available I/O to use, to discover if the pin is already in use or it could conflict with the operation of a given peripheral.

An option is to inspect the pin out diagrams (figures  from page 2 to page 4 of the datasheet)  but those are not as “complete”, and require quite some head turning (try and find OC5 in the 100pin diagram for example…)

In other words it would take a re-sorting of table 2.1 by pin#, times three, to provide one new table per package.

The solution I found to work best for my needs was to create an Excel spreadsheet that I could easily sort and re-sort on different columns.
So, here it is:  PIC24 Pinout (Missing) Table

The table can be re-sorted as needed by different package columns (64, 80 100-pin), by function or by peripheral (a little  familiarity with Excel might be required here: Select All, then Data>Sort> choose the column …)

As an added bonus it was easy to include the information about the pin usage by the Explore16 board and the various PICTail boards available (including the AV16 of course).

P.S. Should you find any error or omission, please make sure to report it to me…

Posted in Tips and Tricks | 1 Comment »

1. February 2008 by pilot.

The exercises assigned in Chapter 5 are actually quite advanced and are mostly meant to give you ideas of the kind of powerful things you can do in C using interrupts (and simple state machines). The following chapters, in particular in the third part of the book, will cover several such examples. The NTSC composite video generator (Exercise 5.3) is well described in Chapter 12, but you will be able to find the solution to the other two exercises in other (perhaps unexpected) places.

Excercise 5.2 is perhaps my favourite as you will find an example of (interrupt based) radio receiving routines (for a very special protocol) in the code attached to application note AN745, available for download as part of the vast collection of application notes available on Microchip’s web site.

Check the “rxi.c” module in particular. The code was written to be compatible with the HiTech C  compiler and the CCS compiler for the PIC16  architecture, but you should find it easy to port for the PIC24 and compile it with MPLAB C30.

The solution to Exercise 5.1 is not going to be very dissimilar…

Posted in Chapter 5 | No Comments »