Pilot's Logbook

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…)

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!

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 …

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…