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

The cdata statement stores 14 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 EEPROM data,
or 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. 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: 0x0000 - 0x1FFF, 0x2100 - 0x21FF

  VXS : < VALUE | EXPRESSION | STRING>
  VALUE: 0 .. 0x3FFF
  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:   \xHH  or  \xH  : hexadecimal number
        \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

Strings are stored as 7 bit ASCII characters (14 bit core devices).
The least significant 7 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:

    #define _NOP 0x0000
    #pragma cdata[0] = _NOP
    #pragma resetVector 1    // goto main at address 1


2. Restoring calibration values:

    #define ResetAddress  0x3FF   // 16C509(A)
    #define _MOVLW 0x3000
    #pragma cdata[ResetAddress]= _MOVLW + CalValue


3. Storing EEPROM data

    Note that EEPROM data must be put in an assembly module when
    using MPLINK.

    #define CDATA_START  0x2100
    #pragma cdata[CDATA_START]  // start of cdata block
    #pragma cdata[] = 0x3F, 10, 20, 'a'
    #pragma cdata[] = "a\0b\0c\0"
      // '\0' must be added in strings due to 14 bit compression
    #pragma cdata[] = 'a', 'b', 'c'


4. Storing packed strings and other data in flash devices (16F87X)

    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[] = 0x3FFF, 0x2000, 0x1000
    #pragma cdata[] = 0x100, (10<<4) + 3456,\
                      10, 456, 10000

    #define D7(l,h)  l + h*128
    #define D28(x)  x%0x4000, x/0x4000
    #pragma cdata[] = D7(10,20), D28(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);


The cdata statements should normally be stored after the program
code. 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
    #pragma origin CDATA_END
    .. C functions at addresses higher than CDATA_END

If the address defined by CDATA_START overlaps with function code,
then an error will occur when #pragma origin CDATA_START is used.

Statement #pragma origin CDATA_END checks that no invalid program
code addresses is used.

It is recommended to specify the address only at the beginning of a
continuous cdata block (as shown).

Preprocessor statements can be used for checking size during
compilation:

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