Dennis Lambe
Notes on my fixes to the FreeRTOS PIC18F mcc18 port
Last modified: <2012-04-03 16:40:40>

The MCC18 C compiler for PIC18 has two behaviors which make porting
FreeRTOS less straightforward and require user configuration. The
first is the compiler requirement that memory regions into which the
compiler allocates variables must not span memory banks[1][2], which
makes pvPortMalloc implementation challenging. The second is that the
compiler uses a variable and unpredictable amount of access memory for
the MATH_DATA and .tmpdata sections[3], which must be saved as part of
a task's context.

Both of these issues require the user to modify the linker script and
make corresponding changes to configuration definitions.

HEAP MANAGEMENT

The FreeRTOS memory management code in heap_1.c, heap_2.c, and
heap_3.c cannot be used without modification on PIC18. Instead, a
heap_1-style implementation of pvPortMalloc is provided in
Source/portable/MPLAB/PIC18F/heap_1_pic.c.

The linker script contains a protected memory region named 'heap'
which is reserved for memory allocated by pvPortMalloc. The size of
this region should match exactly the size defined in
configTOTAL_HEAP_SIZE. If you change one, you must change the other.

The 'heap' region is permitted to cross memory bank boundaries because
its contents will only ever be referenced through pointers, which is
safe according to the C18 User's Guide[2].

The regions that were replaced by 'heap' have been left in the linker
script, commented out, to make it easier to reduce the heap size and
restore the original configuration.

COMPILER-MANAGED MEMORY

The compiler-managed MATH_DATA and .tmpdata sections can change size
at any time as your project evolves. Unnoticed changes in size can
cause hard-to-diagnose run-time errors due to incomplete context
saving.

For this reason, FreeRTOS must be configured with the current sizes of
these sections. configCOMPILER_MANAGED_MEMORY_SIZE must be set to the
combined size of MATH_DATA and .tmpdata. These section sizes are
determined by the compiler and can be found in the map file.

Also for this reason, the Demo linker script is configured to fail
with an error whenever either compiler-managed memory section gets
larger. The linker script contains directives which force MATH_DATA
and .tmpdata into a special region named 'cmpmng', which should always
be big enough to hold both of them. If these sections grow larger than
cmpmng, linking will fail with an error like the following:

    Error - section '.tmpdata' has a memory 'cmpmng' which can not fit
    the section. Section '.tmpdata' length=0x00000006.

If this occurs, resize the cmpmng section by taking space from the
accessram section until the project links successfully, and then
change configCOMPILER_MANAGED_MEMORY_SIZE to match the new size of the
cmpmng region.

If MATH_DATA or .tmpdata shrinks your program will continue to behave
correctly because the cmpmng region is protected and won't be used for
any other purpose. However, it can result in a small amount of wasted
memory and context switch times slightly longer than necessary. For
this reason it may be worthwhile to watch out for shrinking in
MATH_DATA or .tmpdata if your application's timing or memory usage
requirements are very strict.

A NOTE ON TASK STACKS

This patch doesn't change the way task stacks are managed on
FreeRTOS. However, for completeness, here is an explanation of what is
required in order for FreeRTOS and MCC18 to cooperate properly to
manage task stacks.

Since task stacks are allocated from the heap, there is no guarantee
that they will reside within a single memory bank. For this reason,
the Multi-bank Stack Model[4] must be specified for all FreeRTOS
projects. This setting can be found in the Project Build Options,
"MPLAB C18" tab, Category "Memory Model", and corresponds to the
compiler switch -Ls.

REFERENCES

[1] MPASM(TM) Assembler, MPLINK(TM) Object Linker, MPLIB(TM) Object Librarian User's Guide, Section 11.4: Linker Script Caveats
[1] MPLAB(R) C18 C Compiler User's Guide, Section 5.2: Application: Creating Large Data Objects and the USART
[3] MPLAB(R) C18 C Compiler User's Guide, Section 3.4: Compiler-Managed Resources
[4] MPLAB(R) C18 C Compiler User's Guide, Section 3.2.4: Managing the Software Stack