px_pgm_P.h : Support for constant data stored in program memory

Description

RAM saving support for architectures that require methods to store and read constant data in program memory.

File(s):

• common/inc/px_pgm_P.h

This utility module attempts to provide a standardised method to store and read constant data in program memory for devices with separate program and data memory spaces, most notably the Microchip AVR architecture.

For a great introduction, read:

• AVR-GCC and the PROGMEM Attribute by Dean Camera.
• avr-libc: Data in Program Space

Constant data that must be stored in program memory is tagged with the PX_ATTR_PGM attribute.

The suffix "_P" convention is used to indicate that the function reads data stored in program memory, e.g. printf_P() vs. printf(). It is also used to indicate that a source file has been optimised to use const data stored in program memory, e.g. "px_cli_P.c" vs. "px_cli.c".

The "PX_PGM_STR()" macro is used for inline declaration of a string in program memory. See <avr/pgmspace.h> from AVR-Libc

For extra convenience, all-capital macros have been provided to call a program memory function AND inline declare a string in program memory:

// Call progmem version of 'printf' and declare string in program memory
printf_P(PSTR("Hello world!\n"));
 
// Use variable argument convenience macro
PX_PRINTF_P("Hello world!\n");

This module also has the ability to revert to normal RAM storage for architectures that do not require it, or if PX_PGM_P_USE_RAM is defined.

Example:

#include "px_pgm_P.h"
 
// Program memory table for the number of days in each month (non leap year)
const uint8_t px_rtc_month_day_table[] PX_ATTR_PGM =
{
    0,  // Invalid month
   31,  // January
   28,  // February
   31,  // March
   30,  // April
   31,  // May
   30,  // June
   31,  // July
   31,  // August
   30,  // September
   31,  // October
   30,  // November
   31   // December
};
 
// String stored in program memory
const char calender_str[] PX_ATTR_PGM = "Gregorian Calender\n";
 
void report_days(uint8_t month)
{
    uint8_t days_in_month = px_pgm_rd_u8(&px_rtc_month_day_table[month]);
 
    printf_P(calender_str);
    PX_PRINTF_P("Days in month = %d\n", days_in_month);
}