cdata.txt

FreeRTOS 是一个源码公开的免费的嵌入式实时操作系统

THE CDATA STATEMENT
-------------------

The cdata statement stores 16 bit data in program memory.

NOTE 1: cdata[] can currently not be used with relocatable assembly. When
using MPLINK, such data statements can be put in an assembly module.

NOTE 2: Constant data should normally be stored using the 'const'
type modifier. However, cdata[] is useful for storing data and
instructions at fixed addresses.

NOTE 3: There is no check on validity of the inserted data. However,
it is NOT possible to overwrite program code and other cdata
sections (except config, ID and EEPROM data). The data is added at
the end of the assembly and hex file in the same order as it is
defined.



SYNTAX
  #pragma cdata[ADDRESS]   = <VXS>, .., <VXS>
  #pragma cdata[]          = <VXS>, .., <VXS>
  #pragma cdata.IDENTIFIER = <VXS>, .., <VXS>

  ADDRESS: 24 bit byte address

  VXS : < VALUE | EXPRESSION | STRING>
  VALUE: 0 .. 0xFFFF
  EXPRESSION: any valid C constant expression (i.e. 0x1000 | (3*1234))
  STRING: "Valid C String\r\n\0\x24\x8\xe\xFF\xff\\\""

  String translation:   
        \0 => 0   \1 => 1    \2 => 2    \3 => 3    \4 => 4
        \5 => 5   \6 => 6    \7 => 7    \a => 7    \b => 8
        \t => 9   \n => 10   \f => 12   \v => 11   \r => 13
        \\ => the backslash character itself (0x5C)
        \" => '"' (0x22)
        \xHH  or  \xH  : hexadecimal number
        "\x1Conflict"  is better written as  "\x1" "Conflict"


Strings are stored as 8 bit ASCII characters. The least significant
8 bits of each code word are filled first.

Strings are aligned on word addresses for each <VXS>. However,
alignment does not occur when writing  "abc" "def".

IDENTIFIER: any undefined identifier. It is converted to a macro
identifier and set to the current cdata word address. The purpose is
to provide an automatic way to find the address of stored items.

Empty cdata statements can be used to set or read the current
cdata address.
    #pragma cdata[ADDRESS]    // set current cdata address
    #pragma cdata.IDENTIFIER  // "get" current cdata address

Only cdata within the valid code space is counted when calculating
the total number of code words.


TYPICAL USAGE OF THE CDATA STATEMENT:

1. Defining special startup sequences:

    #include "hexcodes.h"
    #pragma cdata[0] = __NOP
    #pragma resetVector 2    // goto main at byte address 2


2. Storing EEPROM data

   EEPROM data can be put into the HEX file at addresses 0xF00000
   and forward for transfer to the internal EEPROM during
   programming of a device. Note that each cdata item is 16 bit
   wide, and will thus define 2 EEPROM locations. The low 8 bit
   will be stored first (even addresses) then the high 8 bit (odd
   addresses). The compiler does not know how much EEPROM space a
   device has.

    #define EEPROM_START  0xF00000
    #pragma cdata[EEPROM_START]      // start of cdata block
    #pragma cdata[] = 0xFFFF, 1000   // 4 bytes EEPROM data

    #define D8(l,h)  (((l)&0xFF) + ((h)&0xFF)*256)
    #pragma cdata[] = D8( 10, 20), D8( 0, 2+5)  // 4 bytes

   Strings will be stored as a number of 2*8 bits when using cdata.

    #pragma cdata[] = "Hello world!\0"


3. Storing packed strings and other data

    The cdata definitions should be put in a separate file and
    included in the beginning of the program. This enables
    identifiers to be used in the program and checking to be
    performed.


    #define CDATA_START  0x80
    #pragma cdata[CDATA_START]  // start of cdata block
    #pragma cdata[] = 0xFFFF, 0x2000, 0x1000
    #pragma cdata[] = 0x100, (10<<4) + 3456,\
                      10, 456, 10000

    #define D8(l,h)  (((l)&0xFF) + ((h)&0xFF)*256)
    #define D32(x)  x%0x10000, x/0x10000
    #pragma cdata[] = D8(10,20), D32(10234543)

    #pragma cdata.ID0 = 0x10, 200+3000
    #pragma cdata.ID1 = "Hello world\0"
    #pragma cdata.ID2 = "Another string\r\n" "merged"

    #pragma cdata.ID_TABLE = ID0, ID1, ID2  // store addresses

    #pragma cdata.CDATA_END    // end of cdata block

    ..

    #pragma origin CDATA_END  // program code follow here

    void write(uns16 strID);
    ..
    write(ID1);
    write(ID2);


All cdata start addresses have to be decided manually. The setup
could be as follows:

    .. cdata definitions
    .. C functions at addresses lower than CDATA_START
    // #pragma origin CDATA_START  // optional
    #pragma origin CDATA_END
    .. C functions at addresses higher than CDATA_END

The #pragma origin CDATA_START is not required, because data
overlapping is detected automatically. However, the compiler tells
how many instructions are skipped for each origin statement. The
cdata words are not counted at this printout.

Statement #pragma origin CDATA_END allows functions to be stored
right after the cdata area. This origin statement is not required if
all cdata are located at the end of the code space.

Preprocessor statements can be used for checking size during
compilation:

    #if CDATA_END - CDATA_START > 20
     #error This is too much
    #endif