Man Linux: Main Page and Category List


       pgmspace - .TH "pgmspace" 3 "Thu Aug 12 2010" "Version 1.6.8" "avr-


       pgmspace - .SH "Introduction"

       So you have some constant data and you're running out of room to store
       it? Many AVRs have limited amount of RAM in which to store data, but
       may have more Flash space available. The AVR is a Harvard architecture
       processor, where Flash is used for the program, RAM is used for data,
       and they each have separate address spaces. It is a challenge to get
       constant data to be stored in the Program Space, and to retrieve that
       data to use it in the AVR application.

       The problem is exacerbated by the fact that the C Language was not
       designed for Harvard architectures, it was designed for Von Neumann
       architectures where code and data exist in the same address space. This
       means that any compiler for a Harvard architecture processor, like the
       AVR, has to use other means to operate with separate address spaces.

       Some compilers use non-standard C language keywords, or they extend the
       standard syntax in ways that are non-standard. The AVR toolset takes a
       different approach.

       GCC has a special keyword, __attribute__ that is used to attach
       different attributes to things such as function declarations,
       variables, and types. This keyword is followed by an attribute
       specification in double parentheses. In AVR GCC, there is a special
       attribute called progmem. This attribute is use on data declarations,
       and tells the compiler to place the data in the Program Memory (Flash).

       AVR-Libc provides a simple macro PROGMEM that is defined as the
       attribute syntax of GCC with the progmem attribute. This macro was
       created as a convenience to the end user, as we will see below. The
       PROGMEM macro is defined in the <avr/pgmspace.h> system header file.

       It is difficult to modify GCC to create new extensions to the C
       language syntax, so instead, avr-libc has created macros to retrieve
       the data from the Program Space. These macros are also found in the
       <avr/pgmspace.h> system header file.

A Note On const

       Many users bring up the idea of using C's keyword const as a means of
       declaring data to be in Program Space. Doing this would be an abuse of
       the intended meaning of the const keyword.

       const is used to tell the compiler that the data is to be 'read-only'.
       It is used to help make it easier for the compiler to make certain
       transformations, or to help the compiler check for incorrect usage of
       those variables.

       For example, the const keyword is commonly used in many functions as a
       modifier on the parameter type. This tells the compiler that the
       function will only use the parameter as read-only and will not modify
       the contents of the parameter variable.

       const was intended for uses such as this, not as a means to identify
       where the data should be stored. If it were used as a means to define
       data storage, then it loses its correct meaning (changes its semantics)
       in other situations such as in the function parameter example.

Storing and Retrieving Data in the Program Space

       Let's say you have some global data:

       unsigned char mydata[11][10] =

       and later in your code you access this data in a function and store a
       single byte into a variable like so:

       byte = mydata[i][j];

       Now you want to store your data in Program Memory. Use the PROGMEM
       macro found in <avr/pgmspace.h> and put it after the declaration of the
       variable, but before the initializer, like so:

       #include <avr/pgmspace.h>
       unsigned char mydata[11][10] PROGMEM =

       That's it! Now your data is in the Program Space. You can compile,
       link, and check the map file to verify that mydata is placed in the
       correct section.

       Now that your data resides in the Program Space, your code to access
       (read) the data will no longer work. The code that gets generated will
       retrieve the data that is located at the address of the mydata array,
       plus offsets indexed by the i and j variables. However, the final
       address that is calculated where to the retrieve the data points to the
       Data Space! Not the Program Space where the data is actually located.
       It is likely that you will be retrieving some garbage. The problem is
       that AVR GCC does not intrinsically know that the data resides in the
       Program Space.

       The solution is fairly simple. The 'rule of thumb' for accessing data
       stored in the Program Space is to access the data as you normally would
       (as if the variable is stored in Data Space), like so:

       byte = mydata[i][j];

       then take the address of the data:

       byte = &(mydata[i][j]);

       then use the appropriate pgm_read_* macro, and the address of your data
       becomes the parameter to that macro:

       byte = pgm_read_byte(&(mydata[i][j]));

       The pgm_read_* macros take an address that points to the Program Space,
       and retrieves the data that is stored at that address. This is why you
       take the address of the offset into the array. This address becomes the
       parameter to the macro so it can generate the correct code to retrieve
       the data from the Program Space. There are different pgm_read_* macros
       to read different sizes of data at the address given.

Storing and Retrieving Strings in the Program Space

       Now that you can successfully store and retrieve simple data from
       Program Space you want to store and retrive strings from Program Space.
       And specifically you want to store and array of strings to Program
       Space. So you start off with your array, like so:

       char *string_table[] =
           'String 1',
           'String 2',
           'String 3',
           'String 4',
           'String 5'

       and then you add your PROGMEM macro to the end of the declaration:

       char *string_table[] PROGMEM =
           'String 1',
           'String 2',
           'String 3',
           'String 4',
           'String 5'

       Right? WRONG!

       Unfortunately, with GCC attributes, they affect only the declaration
       that they are attached to. So in this case, we successfully put the
       string_table variable, the array itself, in the Program Space. This
       DOES NOT put the actual strings themselves into Program Space. At this
       point, the strings are still in the Data Space, which is probably not
       what you want.

       In order to put the strings in Program Space, you have to have explicit
       declarations for each string, and put each string in Program Space:

       char string_1[] PROGMEM = 'String 1';
       char string_2[] PROGMEM = 'String 2';
       char string_3[] PROGMEM = 'String 3';
       char string_4[] PROGMEM = 'String 4';
       char string_5[] PROGMEM = 'String 5';

       Then use the new symbols in your table, like so:

       PGM_P string_table[] PROGMEM =

       Now this has the effect of putting string_table in Program Space, where
       string_table is an array of pointers to characters (strings), where
       each pointer is a pointer to the Program Space, where each string is
       also stored.

       The PGM_P type above is also a macro that defined as a pointer to a
       character in the Program Space.

       Retrieving the strings are a different matter. You probably don't want
       to pull the string out of Program Space, byte by byte, using the
       pgm_read_byte() macro. There are other functions declared in the
       <avr/pgmspace.h> header file that work with strings that are stored in
       the Program Space.

       For example if you want to copy the string from Program Space to a
       buffer in RAM (like an automatic variable inside a function, that is
       allocated on the stack), you can do this:

       void foo(void)
           char buffer[10];

           for (unsigned char i = 0; i < 5; i++)
               strcpy_P(buffer, (PGM_P)pgm_read_word(&(string_table[i])));

               // Display buffer on LCD.

       Here, the string_table array is stored in Program Space, so we access
       it normally, as if were stored in Data Space, then take the address of
       the location we want to access, and use the address as a parameter to
       pgm_read_word. We use the pgm_read_word macro to read the string
       pointer out of the string_table array. Remember that a pointer is
       16-bits, or word size. The pgm_read_word macro will return a 16-bit
       unsigned integer. We then have to typecast it as a true pointer to
       program memory, PGM_P. This pointer is an address in Program Space
       pointing to the string that we want to copy. This pointer is then used
       as a parameter to the function strcpy_P. The function strcpy_P is just
       like the regular strcpy function, except that it copies a string from
       Program Space (the second parameter) to a buffer in the Data Space (the
       first parameter).

       There are many string functions available that work with strings
       located in Program Space. All of these special string functions have a
       suffix of _P in the function name, and are declared in the
       <avr/pgmspace.h> header file.


       The macros and functions used to retrieve data from the Program Space
       have to generate some extra code in order to actually load the data
       from the Program Space. This incurs some extra overhead in terms of
       code space (extra opcodes) and execution time. Usually, both the space
       and time overhead is minimal compared to the space savings of putting
       data in Program Space. But you should be aware of this so you can
       minimize the number of calls within a single function that gets the
       same piece of data from Program Space. It is always instructive to look
       at the resulting disassembly from the compiler.