
HELP FILE FOR THE CC5X C COMPILER
---------------------------------


CONTENTS:

1  INTRODUCTION

2  VARIABLES
2.1  Defining Variables
2.2  Local Variables
2.3  Using RAM Banks
2.4  RAM Bank Selection Bits
2.5  Arrays and Pointers
2.6  Temporary Variables
2.7  Structures and Unions

3  SYNTAX
3.1  CC5X Constructions
3.2  Type Cast
3.3  Direct bit Access
3.4  C Extensions
3.5  Predefined Symbols

4  PREPROCESSOR DIRECTIVES

5  COMMAND LINE OPTIONS

6  PROGRAM CODE
6.1  Program Code Pages
6.2  Subroutine Calls
6.3  Interrupts
6.4  Startup and Termination Code
6.5  Inline Assembly
6.6  Library Support


7  OUTPUT FILES
7.1  Assembly Output File
7.2  Variable List File
7.3  List File
7.4  Function Call Structure



TOPIC:  1  INTRODUCTION

An introduction to the compiler is provided in 'INTRO.TXT'.

File 'INSTALL.TXT' describes how to install and use the
compiler.



TOPIC:  2  VARIABLES

The compiler prints information on the screen when compiling. Most
important are error messages, and how much RAM and PROGRAM space the
program requires. The same information is written to *.occ. This can
look like:

  projects\delay.c:
   Chip = 16C74
   File 'delay.ml1'
   RAM: 00h : -------- -------- -------- --------
   RAM: 20h : ==.***** ******** ******** ********
   RAM: 40h : ******** ******** ******** ********
   RAM: 60h : ******** ******** ******** ********
   RAM: 80h : -------- -------- -------- --------
   RAM: A0h : ******** ******** ******** ********
   RAM: C0h : ******** ******** ******** ********
   RAM: E0h : ******** ******** ******** ********
   File 'delay.var'
   File 'delay.ml2'
   Optimizing - removed 11 instructions (-14 %)
   File 'delay.ml3'
   File 'delay.asm'
   Codepage 0 has   68 word(s) :   3 %
   Codepage 1 has    0 word(s) :   0 %
   File 'delay.obj'
  Total of 68 instructions (1 %)


RAM allocation: The compiler prints information on RAM allocation.
This map is useful to check out which RAM locations are still free.
The map for the 16C57 chip may look like this:

    Mapped RAM: 00h : -------- .7.-****
    Bank 0 RAM: 10h : ====4==* ********
    Bank 1 RAM: 30h : ..6***** ********
    Bank 2 RAM: 50h : ******** ********
    Bank 3 RAM: 70h : -7****** ********

Symbols:
    *  :  free location
    -  :  predefined or pragma variable
    =  :  local variable(s)
    .  :  global variable
    7  :  7 free bits in this location

16C71 map:
    RAM: 00h : -------- ----==== ==3.7... ********
    RAM: 20h : ******** ********




TOPIC:  2.1  DEFINING VARIABLES

CC5X supports integer, fixed and floating point variables. The
variable sizes are 1, 8, 16, 24 and 32 bit. The default int size is
8 bit, and long is 16 bit. Char variables are unsigned by default
and thus range from 0 to 255. Note that 24 and 32 bit variables are
not supported by all CC5X editions.

Information on floating and fixed point variables, including math
libraries is found in MATH.TXT.

CC5X uses (stores) LOW ORDER FIRST. This means that the least
significant byte of a variable is assigned to the lowest address.
All variables are allocated from low RAM addresses and upwards. Each
RAM location can contain 8 bit variables. Address regions used for
special purpose registers are not available for normal allocation.
An error message is produced when there is no space left.

Special purpose registers are either predefined or defined in chip-
specific header files. This applies to W, INDF, TMR0, PCL, STATUS,
FSR, Carry, PD, TO, etc.

    unsigned a8;          //  8 bit unsigned
    char a8;              //  8 bit unsigned
    unsigned long i16;    // 16 bit unsigned

    char varX;
    char counter, L_byte, H_byte;
    bit ready;  // 0 or 1
    bit flag, stop, semafor;

    int i;          //  8 bit signed
    signed char sc; //  8 bit signed
    long i16;       // 16 bit signed

    uns8  u8;  //  8 bit unsigned
    uns16 u16; // 16 bit unsigned
    uns24 u24; // 24 bit unsigned
    uns32 u32; // 32 bit unsigned

    int8  s8;  //  8 bit signed
    int16 s16; // 16 bit signed
    int24 s24; // 24 bit signed
    int32 s32; // 32 bit signed

The bitfield syntax can also be used:

    unsigned x : 24;   // 24 bit unsigned
    int y : 16;        // 16 bit signed

The value range of the variables are:

     TYPE   SIZE            MIN          MAX
     ----   ----            ---          ---
     int8      1           -128          127
    int16      2         -32768        32767
    int24      3       -8388608      8388607
    int32      4    -2147483648   2147483647

     uns8      1              0          255
    uns16      2              0        65535
    uns24      3              0     16777215
    uns32      4              0   4294967295


Assigning variables directly to RAM addresses

All variables, including structures and arrays can be assigned to
fixed address locations. This is useful for assigning names to port
pins. It is also possible to assign overlapping variables (similar
to union). The syntax is:

    <type> <varName> @ <address>;
    <type> <varName> @ <varName2>;
    bit <bitName> @ <address>.<bit>;
    bit <bitName> @ <varName>.<bit>;

    Examples:
    char th @ 0x25;
    //bit th1 @ 0x25.1;  // warning on this
    bit th1 @ th.1;      // no warning

    char tty;
    bit b0;
    char io @ tty;
    bit bx0 @ b0;
    bit bx2b @ tty.7;
    //char tui @ b0;   // size exceeded
    //long r @ tty;   // size exceeded

    char tab[5];
    long tr @ tab;
    struct  {
        long tiM;
        long uu;
    } ham @ tab;

Pragma statements can also be used:

    #pragma char varX @ 0x23
    #pragma char port @ PORTC
    #pragma bit IOpin @ PORTA.1
    #pragma bit ready @ 0x20.2
    #pragma bit ready @ PA2

If the compiler detects double assignments to the same RAM location,
this will cause a warning to be printed. The warning can be avoided
if the second assignment use the variable name from the first
assignment instead of the address ('#pragma char var2 @ var1').

An alternative is to use the '#define' statement:

    #define  PORTX  PORTC
    #define  ready  PA2

Priority when allocating variables:
    1. Variables permanently assigned to a location
    2. Local variables allocated by the compiler
    3. Global variables allocated by the compiler


Supported type modifiers:

    static char a;  /* a global variable; known in the current
                       module only, or having the same name scope as
                       local variables when used in a local block */

    extern char a;  // global variable (in another module)

    auto char a;  // local variable 
                  // 'auto' is normally not used

    register char a; // ignored type modifier

    const char a;  /* 'const' tells that compiler that the data is
                      not modified. This allows global data to be
                      put in program memory. */

    volatile char a; /* ignored type modifier. Note that CC5X use
                        the address to automatically decide that
                        most of the special purpose registers are
                        volatile */

    page0 void fx(void);  // fx() resides in codepage 0
    // page0,page1,page2,page3

    bank0 char a;  // variable 'a' resides in RAM bank 0
    // bank0,bank1,bank2,bank3
    // shrBank : unbanked locations, if available

    size2 char *px;  // pointer px is 16 bit wide
    // size1,size2


TOPIC:  2.2  LOCAL VARIABLES

Local variables are supported. The compiler performs a safe
compression by checking the scope of the variables and reusing the
locations when possible. The limited RAM space in therefore used
efficiently. This feature is very useful, because deciding which
variables can safely overlap is time consuming, especially during
program redesign. Function parameters are located together with
local variables.

Variables should be defined in the innermost block, because this
allows best reuse of RAM locations. It is also possible to add inner
blocks just to reduce the scope of the variables as shown in the
following example:

    void main(void)
    {
        char i;  /* no reuse is possible at the
                    outermost level of 'main' */
        i = 9;
        {  // an inner block is added
            char a;
            for (a = 0; a < 10; a++)
                i += fx(PORTB,0);
        }
        sub(i);
        { // local variables can be assigned immediate:
            char b = s + 1; 
            int i1 = -1, i2 = 0;
            // more code
        }
    }

In some rare situations, global variables can be more efficient than
local variables. However, this will require hard work.

NOTE: local variables may have the same name. However, the compiler
adds an extension to produce an unique name in the assembly, list
and COD file.

NOTE: When a function is not called (defined but not in use), then
all parameters and local variables are truncated to the same
(unused) location.



TOPIC:  2.3  USING RAM BANKS

Using more than one RAM bank is done by setting the active rambank:

    /* variables proceeding the first rambank statement are placed
       in mapped RAM and bank 0. This is also valid for local
       variables and parameters */

    #pragma rambank 2

    char a,b,c; /* a,b and c are put into bank 2 */
    /* parameters and local variables in functions placed here are
       also located in bank 2 ! */

    #pragma rambank 0

    char d;     /* located in bank 0 */

NOTE: Local variables and function parameters also have to be
located. It may be necessary to use '#pragma rambank' between some
of the functions and even INSIDE a function. The recommended
strategy is to locate local variables and function parameters in
mapped RAM or bank 0. Mapped RAM is selected by:

    #pragma rambank -

It is also possible to use the bank type modifier to select the RAM
bank.

    bank0..bank3, shrBank : can replace #pragma rambank
    // shrBank is the unbanked locations, if available

    bank1 char tx[3];  // tx[] is located in bank 1

The bank type modifier defines the RAM bank to locate the variable.
It can locate global variables, function parameters and local
variables. The bank type modifier applies to the variable itself,
but not to the data accessed. This difference is important for
pointers.

NOTE 1: The bank type modifier have higher priority than #pragma
rambank.

NOTE 2: Using 'extern' makes it possible to state the variable
definition several times. However, the first definition defines the
rambank, and later definitions must use the same bank.

NOTE 3: When defining a function prototype, this will normally not
locate the function parameters. However, when adding a bank type
modifier to a function parameter in a prototype, this will define
the bank to be used for this variable.

If variables are located in non-existing RAM banks for a device,
these variables are mapped into existing RAM banks (bank 0). This
applies to the bank type modifiers and the #pragma rambank
statement.

Using RAM banks requires some planning. The optimal placement
requires least code to update the bank selection bits. Some advise
when locating variables:

1. Locate variables which are close related to each other in the
   same bank.
2. Locate all variables accessed in the same function in the
   same bank if possible.
3. Switching between bank 0 and 3, or bank 1 and 2 require more
   instructions than the other combinations.
4. Use as few banks as possible. Fill bank 0 first, then bank 1,
   etc.
5. Remember that local variables and function parameters also may
   require updating of the bank selection bits.



TOPIC:  2.4  RAM BANK SELECTION BITS

RAM and special purpose registers can be located in up to 4 banks.
The 12 bit core uses bit 5 and 6 in FSR to select the right bank. In
the 14 bit core, RP0 and RP1 in the STATUS register are used for this
purpose.

The bank selection bits are automatically checked and updated by the
compiler, and attempts to set or clear these bits in the source code
are removed by the compiler. This feature can be switched off which
means that correct updating has to be done in the C source code.

The compiler uses global optimizing techniques to minimize the extra
code needed to update the bank selection bits. Removing all
unnecessary updating is difficult. However, there should be few
redundant instructions.

The compiler inserts the following instructions:

    BCF 04h,FSR_5    // 12 bit core (16C57,58,..)
    BSF 04h,FSR_5    // 12 bit core (16C57,58,..)
    BCF 04h,FSR_6    // 12 bit core (16C57,58,..)
    BSF 04h,FSR_6    // 12 bit core (16C57,58,..)
    CLRF FSR         // 12 bit core (16C57,58,..)

    BCF 03h,RP0      // 14 bit core
    BSF 03h,RP0      // 14 bit core
    BCF 03h,RP1      // 14 bit core
    BSF 03h,RP1      // 14 bit core

NOTE: The compiler REMOVES all bank updating done by the user.
Actually all of the above stated instructions are removed. It is
therefore possible to switch between manual and automatic updating
by setting or removing the '-b' command line option.

The automatic updating can be switched off locally. This is done by
pragma statements:

    #pragma update_FSR 0   /* OFF, 12 bit core (16C57,58,..) */
    #pragma update_FSR 1   /* ON,  12 bit core (16C57,58,..) */

    #pragma update_RP 0    /* OFF, 14 bit core */
    #pragma update_RP 1    /* ON,  14 bit core  */

These statements can be inserted anywhere, but they should surround
a smallest possible region. Please check the generated assembly code
to ensure that the desired results is achieved.

NOTE: The safest coding is to not assume any specific contents of
the bank selection bits when a local update region is started. The
compiler uses complex rules to update the bank selection bits
outside the local regions. Also, all updating inside a local update
region is traced to enable optimal updating when the region ends.




TOPIC:  2.5  ARRAYS AND POINTERS

One dimensional arrays and single level pointers is implemented.
Note that pointer and indexed arithmetic is currently limited to 8
bit. Assignment is allowed for 8, 16, 24 and 32 bit.

    char t[10], i, index, *p, x, temp;
    uns16 tx[3];

    tx[i] = 10000;

    t[1] = t[i] * 20;  // ok
    t[i] = t[x] * 20;  // not allowed

    temp = t[x] * 20;
    t[i] = temp;

    p = &t[1];
    *p = 100;
    p[2] ++;

The equivalent of a (small) multidimensional array can be
constructed by using a structure. However, only one index can be a
variable.

    struct  {
       char e[4];
       char i;
    } multi[5];

    multi[x].e[3] = 4;
    multi[2].e[i+1] += temp;



Arrays and Pointers on the 12 bit Core:

Indirect RAM access on the 16C57/58/12C509 requires some care
because the RAM bank selection bits resides in the FSR register (bit
5,6). The compiler can do most of the checking. Error messages are
generated when the stated limitations are exceeded.

NOTE: Automatic bankbit updating can be switched off globally
(-b command line option), or locally (#pragma update_FSR 0). Most of
the checking described is performed only if the automatic bankbit
updating in ON.

Reading and writing arrays is straight forward:

    #pragma rambank 2
    char a, e, t[3], s[3];

    a = t[i];
    s[i] = e;
    s[i+3] = e;

The last three statements requires that variable e is located in
mapped RAM (below 0x10) or in the same bank as array 's[]'.
Otherwise an error message is printed to indicate that the compiler
can not update the bank selection bits.

Pointers may need a '#pragma assume' statement:

    #pragma rambank 3
    char *px, r;
    #define LTAB 5
    char tab[ LTAB];
    #pragma assume *px in rambank 3

    px = &tab[0];

    *px = r;

    if (++px == &tab[LTAB])
        px = &tab[0];

A pointer may access more than one bank. The #pragma assume
statement should NOT be used in such cases. The only difference is
that the compiler will know the contents of the FSR.5,6 when a
variable in a specific bank is accessed. Therefore, a statement
like:

    *pointer_to_any_rambank = e;

requires that 'e' in located in mapped RAM (address less than 0x10).

Note that the #pragma assume statement works for single pointers
(and pointers in arrays), but not for pointers located in structures.

Arrays are often more efficient than pointers:

    i = 0;
    // ..
    tab[i] = r;
    if (++i == LTAB)
        i = 0;

Direct use of INDF and FSR is still possible:

    FSR = px;
    INDF = i;

Variable i have to reside in mapped RAM. The compiler performs the
checking when INDF is accessed. The compiler does not try to trace
the contents of FSR when it is loaded directly. Therefore, a
statement like '*px = r;' is normally preferred.

Using #pragma assume '*px' in rambank 3 also makes loading of px more
restrictive. An error message is printed if px is loaded with an
address in another bank. The following cases are checked:

    px = tab;      // same as &tab[0]
    px = &tab[0];
    px = &tab[i];
    px = pxx;      // pxx is another pointer
    px = &pxx[i];

A statement like 'px = &tab[i];' may fool the compiler if the value
of i is too large.

If the above syntax is too restrictive, then a local update region
is the solution. All rambank updating then have to be done with C
statements. Normally, local update regions requires inspection of
the generated assembly file to avoid problems.

    /* these statements clears the buffer */
     i = LTAB;
    #pragma update_FSR 0   /* OFF */
     FSR = &tab[0];
     do  {
         INDF = 0;
         FSR ++;
     } while (--i > 0);
    #pragma update_FSR 1   /* ON */

Without a local update region:

     i = LTAB;
     do
         tab[i-1] = 0;
     while (--i > 0);

In this example, the local update region only has a speed advantage.
The same amount of instructions are generated. Note that although no
rambank updating is required inside the above local region, the
compiler does not know the contents of FSR.5,6 at the end of the
region, and will therefore update these bits afterwards.


Arrays and Pointers and the IRP bit:

For some 14 bit core chips, rambank 2 and 3 is in use. This means
that register bit IRP have to be updated in user code when working
with arrays and tables.

    #pragma rambank 2
     char array[50];
     char x;

     FSR = &array % 256 + x;   // LSB of  &array[x]
     IRP = &array / 256;       // MSB

NOTE: IRP is NOT updated by the compiler before access to INDF in
the user code. Using 'array[x] instead of INDF enables automatic
update of the IRP bit.

It is simplest to locate all arrays in rambank 0/1 or rambank 2/3.
Then IRP can be set to 0 or 1 permanently. Otherwise it has to be
updated according to the actual rambank used.

The compiler will trace all loading of pointers to decide how the
IRP bit should be updated. This applies to both 8 and 16 bit
pointers.

It is also possible to use #pragma assume to state the bank
directly:

    #pragma rambank 1
    char t[3];
    #pragma rambank 3
    char i, *pi,
    char *pit;
    #pragma assume *pi in rambank 3   // or rambank 2
    #pragma assume *pit in rambank 1  // or rambank 0

    pi = &i;
    pit = &t[2];

An error message is printed if a pointer is loaded with an address
from the wrong RAM half. Note that rambank 0 and 1 are grouped
together (the lower RAM half, 0 - 0xFF). Rambank 2 and 3 are the
upper RAM half (0x100 - 0x1FF).

Updating of IRP can be switched off locally. Currently, the compiler
does not remove superfluous updating of the IRP register. This means
that IRP is updated for each pointer or table access.

An efficient strategy may be to locate (most of) the tables in upper
or lower RAM (above or below address 0x100), and do all updating of
IRP in the user code. A few updates is normally sufficient.

    #pragma update_IRP 0   /* off */
    ..
    IRP = 1;  // updated by user code
    ..
    #pragma update_IRP 1   /* on (if required) */



TOPIC:  2.6  TEMPORARY VARIABLES

Operations like multiplication, division, modulo division and shifts
often require temporary variables. The advantage is that the
compiler needs NO PERMANENT SPACE for temporary variables.

The temporary variables are allocated the same way as local
variables, but with a narrow scope. This means that the RAM
locations can be reused in other parts of the program. This is an
efficient strategy and often no extra space is required in
application programs. Note that small test examples may show
different results.



TOPIC:  2.7  STRUCTURES AND UNIONS

Normal C structures can be defined, also nested types. Unions are
allowed.

    struct hh  {
        long a;
        char b;
    } vx1;

    union  {
        struct  {
            char a;
            int16 i;
        } pp;
        char x[4];
        uns32 l;
    } uni;

    vx1.a = -10000;
    uni.x[3] = vx1.b - 10;


Bitfields:

Bitfields in structures are allowed. The size have to be 1, 8, 16,
24 or 32 bit.

    struct bitfield {
        unsigned a : 1;
        unsigned b : 1;
        bit      c;
        unsigned d : 32;
        char     aa;
    } zz;

The CC5X compiler also allows the bitfield syntax to be used outside
structures as a general way of defining variable size:

    int x : 24;  // a 24 bit signed variable


Typedef:

    typedef struct hh HH;

    typedef unsigned ux : 16;  // equal to uns16
    ux  r, a, b;




TOPIC:  3  SYNTAX

TOPIC:  3.1  CC5X CONSTRUCTIONS

Statement:
    { statement; .. statement; }
    if, switch, for, while, do, break, continue, return, goto,
    assignment, function calls


The 'if' statement:

    if (<condition>)
        <statement>;
    else if (<condition>)
        <statement>;
    else
        <statement>;

    The 'else if' and 'else' parts are optional.


The 'while' statement:

   while (<condition>)
       <statement>;

   while (1) {..}    // infinite loop


The 'for' statement:

   for (<initialization>; <condition>; <increment>)
       <statement>;

   initialization:  all legal assignments or empty
   condition:       all legal conditions or empty
   increment:       incrementing or decrementing a
                    variable or empty

   Example 1:  for (v = 0; v < 10; v++)
   Example 2:  for (; v < 10; v++)
   Example 3:  for (v = 0; ; v--)


The 'do' statement:

    do
        <statement>;
    while (<condition>);


The 'switch' statement:

    switch (<variable>)  {
      case <constant1>:
        <statement>; .. <statement>;
        break;
      case <constant2>:
        <statement>; .. <statement>;
        break;
      case <constant3>:
        <statement>; .. <statement>;
        break;
      ..
      default:
        <statement>; .. <statement>;
        break;
    }

    <variable>: all 8 bit variables including W
    break:      optional
    default:    optional, can be put in the
                middle of the switch statement


The 'break' statement:

    Used inside loop statements (for, while, do) to terminate the
    loop. Also used in 'switch' statements.

    Example:
        while (1)  {
            ..
            if (var == 5)
                break;
            ..
        }


The 'continue' statement:

    Used inside loop statements (for, while, do) to force the next
    iteration of the loop to be executed, skipping any code in
    between. In 'while' and 'do-while' loops, the loop condition is
    executed next. In 'for' loops, the increment is processed before
    the loop condition.

    Example:
        for (i = 0; i < 10; i++)  {
            ..
            if (i == 7)
                continue;
            ..
        }


The return statement:

    return <value>; /* exits the current function */

    Examples:
        return;     /* no return value */
        return 12;  /* return constant */


The goto statement:

    goto <label>;

    Jumps to a location, forward or backward.

    Example:
        goto XYZ;
        ..
       XYZ:
        ..


Assignment:

    <variable> = <value> <operation> <value>;
    <variable> <operation> = <value>;
    <variable> ++;
    <variable> --;

    variable:   of type 'bit' or 'char'
    operation:  +  -  &  |  ^  *  /  %  >>  <<
    value:      <variable>  or  <constant>
    constant:   34  0xFF  'A'  0b01101111

    var1 = x + y;
    W = W & 0x1F;
    i = x - 100;

    y ^= 'A';   /* y = y ^ 'A'; */
    W |= 3;     /* W = W | 3; */

    flag = 1;  /* bit variable */

    i++;    /* increment:  i = i + 1; */
    i--;    /* decrement:  i = i - 1; */

Special syntax examples:

    #define mx !a
    if (!mx) ..

    W = W - 3;  // ADDLW 256-3
    b = fx() - 3;

    //Post- and pre-incrementing of pointers
    char *cp;
    t = *--cp;
    t |= *++cp;
    *cp-- = t;
    t = *cp++ + 10;

    // extended pre-incrementing of variables
    t = ++b | 3;
    sum( --b, 10);
    t = tab[ --b];

Condition:

    [ ++ | -- ] <variable> <cond-oper>  <value>
                                [ && condition]
                                [ || condition]

    cond-oper :  ==   !=   >   >=   <   <=

    if (x == 7) ..
    if (Carry == 1  &&  a1 < a2) ..
    if (y > 44 ||  Carry  ||  x != z) ..
    if (--index > 0) ..
    if (bx == 1  ||  ++i < max) ..
    if (sub_1() != 0)  ..


Bit variables:

    bit a, b, c, d;
    char i, j, k;

    bit bitfun(void)  // bit return type (using Carry bit)
    {
        return 0;     // Clear Carry, return
        return 1;     // Set Carry, return
        nop();
        return Carry; // return
        return b;     // Carry=b; return
        return !i;
        return b & PORTA.3;
    }
    ..
    b = bitfun2(bitfun(), 1);
    if (bitfun()) ..
    if (!bitfun()) ..
    if (bitfun() == 0) ..

    b = !charfun();
    b = charfun() > 0;
    b = !bitfun();
    Carry = bitfun();
    b &= bitfun();

    if (bitfun() == b)  ..
    if (bitfun() == PORTA.1) ..

    i += b;   // conditional increment
    i -= b;   // conditional decrement
    i = k+Carry;
    i = k-Carry;
    b = !b;  // Toggle bit  (or b=b==0;)
    b = !c;  // assign inverted bit
    PORTA.0 = !Carry;
    a &= PORTA.0;
    PORTA.1 |= a;
    PORTA.2 &= a;

    // assign condition using 8 bit char variables
    b = !i;
    b = !W;
    b = j == 0;
    b = k != 0;
    b = i > 0;

    // assign bit conditions
    b = c&d; //also &&, |, ||, +, ^ , ==, !=, <, >, >=, <=

    // conditions using bit variables
    if (b == c) ..  // also  !=, >, <, >=, <=

    // initialized local bit variables
    bit bx = cx == '+';
    bit by = fx() != 0xFF;


Precedence of C operators:

    ()                        Highest:
    ++  --
    *  /  %
    +  -
    <<  >>
    <  <=  >  >=
    ==  !=
    &
    ^
    |
    &&
    ||
    =  +=  -=  *=  /=  etc.   Lowest:


Constants:

    x = 34;            /* decimal */
    x = 0x22;          /* hexadecimal */
    x = 'A';           /* ASCII */
    x = 0b010101;      /* binary */

    x = 0x1234 / 256;  /* 0x12 : MSB */
    x = 0x1234 % 256;  /* 0x34 : LSB */

    x = 3 + 4;         /* 7 */
    x = 3 - 4;         /* 255 */
    x = 3 * 4;         /* 12 */
    x = 33 / 4;        /* 8 */
    x = 33 % 4;        /* 1 */
    x = 0xF & 0xF3;    /* 3 */
    x = 0x2 | 0x8;     /* 10 */
    x = 0x2 ^ 0xF;     /* 13 */
    x = 0b10 << 2;     /* 8 */
    x = 0xF >> 2;      /* 3 */

    x = r1 + (3 * 8 - 2);         /* 22 */
    x = r1 + (3 + 99 + 67 - 2);   /* 167 */
    x = ((0xF & 0xF3) + 1) * 4;   /* 16 */

    Please note that parentheses are required in some cases.


Constant Expressions:

The size of integers is by default 8 bits for this compiler (other
compilers use typically 16 or 32 bits depending on the CPU
capabilities). An error is printed if the constant expression loses
significant bits because of value range limitations.

    char a;
    a = (10 * 100) / 256;         // an error is printed
    a = (10L * 100) / 256;        // no error
    a = ((uns16) 10 * 100) / 256; // no error
    a = (uns16) (10 * 100) / 256; // error again

    a = (10 * 200) / 256;  // no error, 200 is a long int by default

    Adding a L means conversion to long (16 bit).

The command line option -cu force 32 bit evaluation of constants
(upward compatibility) so that no significant bits are lost.

The constant type is by default the shortest signed integer. Adding
an U behind a constant means that it is treated as unsigned. Note
that constants above 0x7FFFFFFF are unsigned by default (with or
without an U).


Enumeration:

    An enumeration is a set of named integer constants. It can often
    replace a number of #define's. The numbering normally starts
    with 0, but this can be changed.

    enum { A1, A2, A3, A4 };
    enum { alfa = 8, beta= 0, zeta = -4, eps };


Function definitions can look as follows: 

    void subroutine2(char p) { /* C statements */}
    bit function1(void) { }
    long function2(char W) { }
    void main(void) { }

The compiler need to know the definition of a function before it is
called to enable type checking. A prototype is a function definition
without statements. Prototypes are useful when the function is
called before it is defined. The parameter name is optional in
prototypes:

    char function3(char);
    void subroutine1(void);

Function calls:

    subroutine1();
    subroutine2(24);
    bitX = function1();
    x = function2(W);
    y = fx1(fx3(x));

Parameters in function calls:

There are no fixed limit on the number of parameters allowed in
function calls. Space for parameters are allocated in the same way
as local variables which allows efficient reuse. The bit type is
also allowed. Note that if W is used, this has to be the LAST
parameter.

    char func(char a, uns16 b, bit ob, char W);


Function return values:

Functions can return values up to 4 bytes wide. Return values can be
assigned to a variable or discarded. Handling and using return
values is automated by the compiler.

The least significant byte is always placed in W when using 14 bit
core devices. Signed variables and variables larger than 8 bits also
use temporary variables on the computed stack. The 12 bit core use
the W register when returning 8 bit constants. All other return
values are placed in return variables on the computed stack.
 
A function can return any value type. The W register is used for 8
bit return value if possible. The Carry flag is used for bit return
values. The compiler will automatically allocate a temporary
variable for other return types. A function with no return value is
of type void.


Internal functions:

The internal functions provides direct access to certain inline code:

    btsc(Carry);  // void btsc(char);   - BTFSC f,b
    btss(bit2);   // void btss(char);   - BTFSS f,b
    clrwdt();     // void clrwdt(void); - CLRWDT
    clearRAM();   // void clearRAM(void); clears all RAM
    i = decsz(i); // char decsz(char);  - DECFSZ f,d
    W = incsz(i); // char incsz(char);  - INCFSZ f,d
    nop();        // void nop(void);    - NOP
    nop2();       // void nop2(void);   - GOTO next address
    retint();     // void retint(void); - RETFIE
    W = rl(i);    // char rl(char);     - RLF i,d
    i = rr(i);    // char rr(char);     - RRF i,d
    sleep();      // void sleep(void);  - SLEEP
    skip(i);      // void skip(char);   - computed goto
    k = swap(k);  // char swap(char);   - SWAPF k,d

The internal rotate functions are also available for the larger
variable sizes:

    a16 = rl(a16);   // 16 bit left rotation
    a32 = rr(a32);   // 32 bit right rotation

The inline function nop2() is implemented by a GOTO to the next
address. Thus, nop2() can replace two nop() to get more compact
code. The main use of nop() and nop2() is to design exact delays in
timing critical parts of the application.


Multiplication, division and modulo:

    multiplication :   a16 = b16 * c16;  // 16 * 16 bit

A general multiplication algorithm is implemented, allowing most
combinations of variable sizes. Including a math library allows
library calls to be generated instead of inline code. The algorithm
makes shortcuts when possible, for instance when multiplying by 2.
This is treated as a left shift.

    division       :   a16 = b16 / c8;   // 16 / 8 bit
    modulo         :   a32 = b32 % c16;  // 32 % 16 bit

The division algorithm also allows most combinations of variable
sizes. Shortcuts are made when dividing by 2 (or 2*2*..). These are
treated as right shifts.

Mixed variable sizes are allowed

    a32 = (uns32) b24 * c8;  // 24 * 8 bit, result 32 bit
    a16 = a16 + b8;          // 16 + 8 bit, result 16 bit

Most combinations of variables are allowed, the compiler performs
sign extension is required. Multiple operations in the same
expression are allowed when using 8 bit variables.

    a8 = b8 + c8 + d8 + 10;


TOPIC:  3.2  TYPE CAST

Constants and variables of different types can be mixed in
expressions. The compiler converts them automatically to the same
type according to the stated rules. For example,  the expression:

    a = b + c;

consists of 2 separate operations. The first is the plus operation
and the second is the assignment. The type conversion rules are
first applied to b+c. The result of the plus operation and a are
treated last.

The CC5X compiler use 8 bit int size and contains significantly many
data types (integers, fixed and floating point). The type cast rules
have been set up to provide best possible compatibility with
standard C compilers (which typically use 16 or 32 bit int size).

The type conversion rules implemented are:
1. if one operand is double -> the other is converted to double
2. if one operand is float -> the other is converted to float
3. if one operand is 32 bit -> the other is converted to 32 bit
4. if one operand is 24 bit -> the other is converted to 24 bit
5. if one operand is long -> the other is converted to long
6. if one operand is unsigned -> the other is converted to unsigned

NOTES: The sign is extended before the operand is converted to
unsigned. Assignment is also an operation. Constants are SIGNED,
except if U is added. The bit type is converted to unsigned char.
The fixed point types are handled as subtypes of float.

Type conversion in C is difficult. The compiler generates a warning
if a typecast is required to make the intention clear:

    uns16 a16;
    char b8, c8;
    a16 = b8 * c8;           // warning (8 bit result)
    a16 = (uns16) (b8 * c8); // warning (8 bit result)
    a16 = (uns16) b8 * c8;   // no warning (16 bit result)
    a16 = (uns8) (b8 * c8);  // no warning (8 bit result)


TOPIC:  3.3  DIRECT BIT ACCESS

    Each bit in a variable can be accessed directly:

    uns32 a;
    a.7 = 1;   // set bit 7 of variable a to 1
    if (a.31 == 0)   // test bit 31 of variable a
        t[i].4 = 0;   // bit 4 of the i'th element

    Bit 0: least significant bit
    Bit 7: most significant bit of a 8 bit variable
    Bit 15: most significant bit of a 16 bit variable
    Bit 23: most significant bit of a 24 bit variable
    Bit 31: most significant bit of a 32 bit variable

Also, parts of a variable can be accessed directly:

    uns16 a;
    uns32 b;

    a.low8 = 100; // set the least significant 8 bits
    a = b.high16; // load the most significant 16 bits

    low8 : least significant byte
    high8 : most significant byte

    mid8  : second byte
    midL8 : second byte
    midH8 : third byte

    low16 : least significant 16 bit
    mid16 : middle 16 bit
    high16 : most significant 16 bit

    low24 : least significant 24 bit
    high24 : most significant 24 bit

The table shows which bits are accessed depending on the variable
size in bytes (1,2,3,4) and the sub-index used. The * indicates
normal use of the sub-index:

               1        2        3         4
            ------   ------   -------   -------
    low8      0-7    * 0-7    * 0-7     * 0-7
    high8     0-7    * 8-15   * 16-23   * 24-31
    mid8      0-7      8-15   * 8-15      8-15
    midL8     0-7      8-15     8-15    * 8-15
    midH8     0-7      8-15     16-23   * 16-23
    low16     0-7      0-15   * 0-15    * 0-15
    mid16     0-7      0-15     8-23    * 8-23
    high16    0-7      0-15   * 8-23    * 16-31
    low24     0-7      0-15     0-23    * 0-23
    high24    0-7      0-15     0-23    * 8-31




TOPIC:  3.4  C EXTENSIONS

CC5X adds some extensions to the standard C syntax:

1. The bit variable type

2. The interrupt function type

3. C++ style comments are allowed :
   // a comment, valid to the end of the line

4. Local variables can be declared between statements as in C++.
   Standard C requires local variables to be defined in the
   beginning of a block.

5. Binary constants : 0bxxxxxx or bin(xxxxxx)
   The individual bits can be separated by the '.':
   0b0100
   bin(0100)
   bin(0001.0100)
   0b.0.000.1.01.00000

6. Preprocessor statements can be put into macros. Such preprocessor
   statements are not extended to multiple lines. The inserted
   preprocessor statements are evaluated when the macro is expanded,
   and not when it is defined.

    #define  MAX      \
    {                 \
      a = 0;          \
     #if AAA == 0 && BBB == 0 \
      b = 0;          \
     #endif           \
    }

7.  Several of the type modifiers are not standard in C (page0,
    ..page3, bank0,..bank3, shrBank, size1,size2)


More C extensions are allowed by the #pragma statement.



TOPIC:  3.5  PREDEFINED SYMBOLS

The basic PICmicro registers are predefined (header files defines
the rest):

    W, INDF, PCL, STATUS, FSR, PORTA, Carry, etc.

The following names are defined as internal functions, and are
translated into special instructions or instruction sequences.

    btsc, btss, clearRAM, clrwdt, decfsz, incfsz, nop, nop2, retint,
    rl, rr, sleep, skip, swap

Extensions to the standard C keywords:

    bank0, bank1, bank2, bank3, bit, fixed8_8, .. fixed24_8,
    float16, float24, float32, int8, int16, int24, int32, interrupt,
    page0, page1, page2, page3, shrBank, size1, size2, uns8, uns16,
    uns24, uns32

Standard C keywords used:

    auto, break, case, char, const, continue, default, double, enum,
    extern, do, else, float, for, goto, if, int, long, return,
    short, signed, sizeof, static, struct, switch, typedef, union,
    unsigned, void, while,

    define, elif, ifdef, ifndef, include, endif, error, pragma,
    undef

The remaining standard C keywords are detected and compiled. One is
ignored (register), and the rest cause a warning to be printed
(volatile, line).

The following symbols are automatically defined when using the CC5X
compiler:

    __CodePages__ := equal to 1..4, depending on the
                     number of code pages on the actual chip

    __CC5X__  := Integer version number: 3002 means 3.0B

    __CoreSet__ := 1200: 12 bit core, 1400: 14 bit core

    __IRP_SFR__ := 1 if IRP is active when accessing 
               special function registers using INDF, 0 
               otherwise. Note that '#pragma update_IRP 0'
               will set this macro to 0 until 
               '#pragma update_IRP 1' is processed.

    __IRP_RAM__ := 1 if IRP is active when accessing RAM
               registers using INDF, 0 otherwise. Using  
               '#pragma update_IRP 0' will set this macro 
               to 0 until '#pragma update_IRP 1'.

    _16CXX     :=  always defined (12 and 14 bit cores)
    _16C5X     :=  when the 12 bit core is selected
    _16C54     :=  when the 16C54 is selected, similar for 
                   the other devices


TOPIC:  4  PREPROCESSOR DIRECTIVES

The preprocessor recognises the following keywords:

    #define, #undef, #include
    #if, #ifdef, #ifndef, #elif, #else, #endif
    #error, #pragma

A preprocessor line can be extended by putting a '\' at the end of
the line (no spaces behind).


#define

    #define  counter   v1
    #define  MAX       145
    #define  echo(x)   v2 = x
    #define  mix()     echo(1)   /* nested macro */

    Note that all #define's are global, even if they are put inside
    a function. Preprocessor directives can be put into the #define
    statement.


#include

    #include "test.h"
    #include <test.h> 

    #include's can be nested. When using #include "test.h" the
    current directory is first searched. If the file is not found
    there, then the library directories are searched, in the same
    order as supplied in the command line option list (-I<dir>). The
    current directory is skipped when using #include <test.h>.


#undef

    #define  MAX       145
    ..
    #undef   MAX   /* removes definition of MAX */

    #undef does the opposite of #define. The #undef statement will
    not produce any error message if the symbol is not defined.


#if

    #if defined ALFA  &&  ALFA == 1
        ..
     /* statements compiled if ALFA is equal to 1 */
     /* conditional compilation may be nested */
    #endif

    An arbitrary complex constant expression can be supplied. The
    expression is evaluated the same way as a normal C conditional
    statement is processed. However, every constant is converted to
    a 32 bit signed constant first.

    1) macro's are automatically expanded
    2) defined(SYMBOL)  and  defined SYMBOL are replaced by 1 if the
       symbol is defined, otherwise 0.
    3) legal constants :  1234  -1  'a' '\\'
    4) legal operations :  + - * / % >> <<
                           == != < <= > >= || &&
                           ! ~  ()


#ifdef

    #ifdef SYMBOL
        ..
     /* Statements compiled if SYMBOL is defined.
        Conditional compilation can be nested. SYMBOL
        should not be a variable or a function name. */
    #endif


#ifndef

    #ifndef SYMBOL
        ..
        /* statements compiled if SYMBOL is
           not defined */
    #endif


#elif

    #ifdef AX
        ..
    #elif  defined BX   ||  defined CX
        /* statements compiled if AX is not
           defined, and BX or CX is defined */
    #endif


#else

    #ifdef SYMBOL
        ..
    #else
        ..
    #endif


#endif

    #ifdef SYMBOL
        ..
    #endif


#error

    #error This is a custom defined error message

    The compiler generates an error message using the text found
    behind #error.


#pragma

    The pragma statement is used for processor specific
    implementations. Defined in 'pragma.txt'.




TOPIC:  5  COMMAND LINE OPTIONS


File OPTIONS.TXT contains information on the CC5X options.



TOPIC:  6  PROGRAM CODE

TOPIC:  6.1  PROGRAM CODE PAGES

Many of the PICmicro devices have more than one code page. A code
page contains 512 words on the 12 bit core and 2048 words on the 14
bit core. Using more than one code page requires #pragma statements.
All functions following a '#pragma codepage' statement are put on
the page specified. Codepage 0 is used as default.

    /* functions proceeding the first codepage
       statement are placed on codepage 0 */

    #pragma codepage 2

    char fx(void)
    { .. }
    /* this function is placed on codepage 2 */

    #pragma codepage 1

    /* following functions are placed on codepage 1 */


When switching between codepages, the compiler will keep track on
the next free location on each codepage.

Use of codepages is just a matter of optimization, as long as the
compiler accepts the selection. The optimal combination requires
least code (or has a speed advantage). The optimizer removes
unnecessary setting and clearing of the page selection bits.

Some of the PICmicro devices have 4 code pages. Note that calls
which requires switching between page 0 and 3, or page 1 and 2
requires more instructions than the other combinations.

The compiler produces an error message when page limits are
exceeded.


Another way of locating functions:

The statement '#pragma location' is capable of locating prototypes
on codepages as well as function definitions. The statement is
useful when locating functions defined in library files, or when
locating functions in large programs. Its normal use is in limited
regions in header files. The rules when using '#pragma location'
are:

  1) A function prototype will locate the function on the
     desired codepage, even if the current active codepage is
     different when the function body is compiled.

  2) '#pragma location' have higher priority than '#pragma
       codepage'.

  3) '#pragma location -' restores the current active codepage
     defined by the last '#pragma codepage' or '#pragma origin'.

 #pragma location 1  // codepage 1
  void f1(void);    // functions f1, f2 and f3 are defined
  void f2(void);    // later, but assigned to codepage 1 now
  void f3(void);
 #pragma location 3  // codepage 3
  void f4(void);
 #pragma location -  // back to the current active codepage
  void f5(void);    // this function prototype is not located


The page type modifiers page0..page3 can replace #pragma location/
codepage.

    page2 void fx(void) { .. }  // in codepage 2
    page1 char f2(char a);      // in codepage 1

The page type modifier defines the codepage to locate the function
in, both for function prototypes and function definitions.

NOTE 1: The page type modifier have higher priority than both #
pragma codepage and #pragma location

NOTE 2: When the codepage have been defined using the page type
modifier or #pragma location, then the location is fixed and can not
be changed in the function definition or by using a second
prototype.

Invalid code pages are mapped to valid ones.


NOTES:
1. The location statements have to be compiled before the function
   definition
2. Functions not located are placed on the current active codepage
3. A warning is printed in case of conflicts

The '#pragma location' statement should only be used if required. An
example is when functions inside a module (file) have to be placed
on different codepages, or if much tuning is required to find the
optimal combination. The '#pragma codepage' statement is normally
sufficient.



Page selection bits:

The page selection bits PA0 and PA1 are automatically updated by the
compiler, and attempts to set or clear these bits in the source code
are removed by the optimizer. This process can be switched off by
the -j command line option.

Core 12 note: assigning a value to the STATUS register may cause the
automatic updating to fail.




TOPIC:  6.2  SUBROUTINE CALLS

Subroutine calls are limited to 2 levels for the 12 bit core and 8
levels for the 14 bit core. The compiler automatically checks that
this limit is not exceeded.

There is one exception to this. The compiler can replace CALL by
GOTO to achieve deeper call levels.

  1. When a function is called once only, the call can be
     replaced by a goto. All corresponding returns are also
     replaced by gotos. Call is NOT replaced by goto when:

       i)   The program counter (PCL) is updated
       ii)  The number of return literal exceeds 10
       iii) The function is called from another codepage and
            the number of returns exceeds 10

  2. Call followed by return is replaced by a single goto.


When subroutines are located on the second half of a codepage, it
can not be called directly when using 12 bit core devices. The
compiler automatically inserts links to such "hidden" subroutines.


Stack level checking when using interrupt:

CC5X will normally assume that an interrupt can occur anywhere in
the main program, also at the deepest call level. An error message
is printed if stack overflow may occur. This is not always true,
because the interrupt enable bits controls when interrupts are
allowed. Sometimes the main program need all 8 stack levels for
making calls.

The -q<N> option force CC5X to assume that interrupt will NOT occur
at the <N> deepest call levels of the main program.

The application writer must then ensure that interrupt will not
occur when executing functions at the deepest <N> call levels,
normally by using the global interrupt enable bit. CC5X will
generate a warning for the critical functions. (The normal error
message is always generated when the application contains more than
8 call levels.)

For example, the -q1 option generates a warning for functions calls
that will put the return address at stack level 8 (no free stack
entry for interrupt). Using -q2 means an additional warning at stack
level 7 if the interrupt routine requires 2 levels, i.e. contains
function calls.

It is NOT recommended to use the -q<N> as a default option.


Recursive functions:

Recursive functions are possible. Please note that the termination
condition have to be defined in the application code, and therefore
the call level checking can not be done by the compiler. Also note
that the compiler does not allow any local variables in recursive
functions. Function parameters and local variables can be handled by
writing code that emulates a stack.

A warning is printed when the compiler detects a function which call
itself directly or through another function. This warning can be
switched off with the '-wr' command line option.




TOPIC:  6.3  INTERRUPTS


The 14 bit core allows interrupts:

    * external interrupt on RB0/INT pin
    * external interrupt on port pins change, RB4:7
    * internal interrupt on TMR0 overflow
    * .. and other controller specific interrupts


The structure of the interrupt service routine is as follows:

    #include "int16CXX.h"
    #pragma origin 4

    interrupt serverX(void)
    {
        // W and STATUS are saved by the next macro.
        // PCLATH is also saved if necessary.
        // The code produced is strongly CPU-dependent.

        int_save_registers    // W, STATUS (and PCLATH)
        //char sv_FSR; sv_FSR = FSR;  // if required

        // handle the interrupt

        //FSR = sv_FSR;               // if required
        int_restore_registers // W, STATUS (and PCLATH)
    }

The keyword interrupt allows the routine to be terminated by a
RETFIE instruction. It is possible to call a function from the
interrupt routine (it have to be defined by a prototype function
definition first).

The interrupt routine requires at least one free stack location
because the return address is pushed on the stack. This is
automatically checked by the compiler, even function calls from the
interrupt routine. However, if the program contains recursive
functions, then the call level can not be checked by the compiler.

The interrupt vector is permanently set to address 4. The interrupt
service routine can only be located at this address if it is the
first function defined in the program. The #pragma origin statement
have to be used in order to skip unused program locations.

Vital registers such as STATUS and W should be saved and restored by
the interrupt routine. However, registers that are not modified by
the interrupt routine do not have to be saved. Saving and restoring
registers is device dependent. The file int16CXX.H contains
recommended program sequences for saving and restoring registers.
FSR should also be saved if the interrupt service routine use it for
accessing RAM arrays. For instance to access data buffers used for
serial communication.

The interrupt routine can also contain local variables. Space is
allocated separately because interrupts can occur anytime.

It is possible to design SPECIAL service routines if the use of
interrupts is limited to certain program regions, for instance in
wait loops or after SLEEP instructions. In such cases registers do
not have to be saved. Be careful with PCLATH and RP0/RP1 anyway.

NOTE: clearing GIE requires special attention on some PICmicro
devices. The recommended procedure is: 'do GIE = 0; while (GIE == 1);'.
Note that this applies only to some of the devices (the first
designed ones). Refer to the documentation from Microchip for more
details.

INTERRUPTS CAN BE VERY DIFFICULT. THE PITFALLS ARE MANY.



TOPIC:  6.4  STARTUP AND TERMINATION CODE

The startup code consists of a jump to 'main' which has to be
located on page zero. No variables are initiated. All initialization
has to be done by user code. This simplifies design when the
watchdog timer or MCLR pin is utilized.

The SLEEP instruction is executed when the processor exit 'main()'.
This stops program execution and the chip enters the low power mode.
Program execution may be restarted by a watchdog timer timeout or a
low state on the MCLR pin.

The 14 bit core also allows restart by interrupt. An extra GOTO is
therefore inserted after the last SLEEP in main. This ensures
repeated execution of the main program. However, no extra GOTO is
added when a sleep() command is inserted anywhere else in the
application program.

Clearing ALL RAM locations:

The internal function 'void clearRAM(void);' will set all RAM
locations to zero. The generated code use the FSR register. The
recommended usage is:

    void main(void)
    {
        if (TO == 1 && PD == 1 /* power up */)  {
          WARM_RESET:
            clearRAM();  // set all RAM to 0
        }
        ..
        if (condition)
            goto WARM_RESET;
        ..
    }


The code size and timing depends on the actual chip. The following
table describes the basic types. Chip devices not found here maps to
one of the described types.

INS  ICYC TOTCYC   4 MHz   RAM  START  LAST  BANKS  PICmicro
  8    6    145   0.15ms    25    7    0x1F    -    16C54
  9    4    202   0.20ms    41    7    0x3F    2    16C509
 13    4    290   0.29ms    72    8    0x7F    4    16C57
  8    7    254   0.25ms    36   12    0x2F    -    16C84
  6    5    482   0.48ms    96   32    0x7F    1    16C620A
 12    5    644   0.64ms   128   32    0xBF    2    12C671
  9    4    770   0.77ms   176   32    0xFF    2    16C642
  9    4    770   0.77ms   192   32    0xFF    2    16C74
 10    4    771   0.77ms   192   32    0xFF    4    16C923
 19    5   1110   1.11ms   224   32   0x14F    4    16C627
 12    4   1058   1.06ms   256   32   0x17F    4    16C773
 15    4   1807   1.81ms   368   32   0x1FF    4    16C77

INS:    number of assembly instructions required
ICYC:   cycles (4*clock) for each RAM location cleared
TOTCYC: total number of cycles (4*clock) required
4MHz:   approx. time in milliseconds required at 4 MHz
RAM:    total number of RAM locations
START:  first RAM address
LAST:   last RAM address
BANKS:  number of RAM banks
PICmicro: chip type described



TOPIC:  6.5  INLINE ASSEMBLY

Inline assembly is described in file 'INLINE.TXT'.

The file 'INLINE.H' describes how to emulate inline assembly using C
code. This allows single instructions to be generated. Intended
usage is mainly for code with critical timing.

The compiler will normally generate single instructions if the C
statements are simple. Remember to inspect the generated assembly
file if the application algorithm depends upon a precisely defined
instruction sequence.


TOPIC:  6.6  LIBRARY SUPPORT

The library support includes standard math and support for user
defined libraries. The library files should be included in the
beginning of the application, but after the interrupt routine for
all libraries located on codepage 0.

// ..interrupt routine
#include "math16.h"   // 16 bit integer math
#include "math24f.h"  // 24 bit floating point
#include "math24lb.h" // 24 bit math functions

CC5X will automatically delete unused library functions. This
feature can also be used to delete unused application functions:

#pragma library 1
// library functions that are deleted if unused
#pragma library 0


Math libraries are described in MATH.TXT.




TOPIC:  7  OUTPUT FILES

The compiler produces a compiler output file and an hex file that
may be used for programming PICmicro devices directly. This hex file
is produced only if no errors are detected during compilation. The
compiler may also produce other files by setting command line
options.



TOPIC:  7.1  ASSEMBLY OUTPUT FILE

The compiler can produce a complete assembly file. Text from the
source file is merged into the assembly file. This makes the code
more readable. User variable names are used throughout.

Local variables may have equal names. The compiler then adds an
extension to the variable name in order to produce an unique name.

There are many command line options which changes the standard
assembly file produced. Please note the difference between the -a
and the -A options. The -a option is needed to produce an assembly
file, while the -A option changes the contents of the assembly and
list files.



TOPIC:  7.2  VARIABLE LIST FILE

The variable list file contains information on the variables
declared. Variables are sorted by address by default, but this can
be changed. The compiler needs the command line option -V to
produce this file. The file name is <src>.var.

The general format is -V[rnuD]. The additional letters allows the
file contents to be adjusted:

    r : only variables which are referenced in the code
    n : sort variables by name
    u : keep the variables unsorted
    D : use decimal numbers


Variable file contents:

    X [b] ADR :REF: name

      X ->  L  : local variable
            G  : global variable
            P  : assigned to certain address
            R  : overlapping, directly assigned
            E  : unused external variable (not allocated)

      b ->  -  : mapped RAM (available in all banks)
            0  : bank 0
            1  : bank 1
            2  : bank 2
            3  : bank 3

      REF -> 12  : number of instructions using the variable

      ADR -> 0Ah   : file address
             0Ch,0 : bit address (file + bit number)


    Examples:

    R [-] 0x006.0  :  1:  in
    R [-] 0x00B    : 10:  alfa
    P [-] 0x00B    : 12:  fixc
    L [-] 0x00D    :  1:  lok
    L [0] 0x012.0  :  6:  b1
    G [0] 0x012.1  : 16:  bx
    G [0] 0x015    : 23:  b

    When a function is not called (unused), all its parameters and
    local variables are truncated to the same location. Example:

    L [-] 0x00F   : 16<> pm_2_




TOPIC:  7.3  LIST FILE

The compiler can also produce a list file. The command line option
is -L. The general format is -L[<col>,<lin>]. The maximum number of
columns per line <col> and lines per page <lin> can be altered. The
default setting is -L80,60. The contents of the list file can be
changed by using the -A option.



TOPIC:  7.4  FUNCTION CALL STRUCTURE

The function call structure can be written to file <src>.fcs.
This is useful for codepage optimization and function restructuring
in case of call level problems. Note that 2 different formats are
produced; the first is a list of functions, the second is a
recursive expansion of the function call structure. The command
line option is '-Q' for both formats.

Format sample:

  F: function1              :#1  : p0 <- p1
      func2                 : #5  : p0 -> p3 **
      delay                 : #2  : p0 -> p2 *
      func3                 : #3  : p0 -> p0

The meaning of the symbols is:

  1.  func2, delay and func3 are called from function1
  2.  #1 : function1 is called once
  3.  #3 : func3 is called 3 times (once from function1)
  4.  p0 <- p1 : function1 resides on page 0
  5.  p0 <- p1 : function1 is called from page 1
  6   p0 -> p3 : call to func2 (resides on page 3)
  7.  * : one pagebit have to be updated before call
  8.  ** : both pagebits have to be updated


The call structure is also expanded recursively:

    L0  main
    L1    function1
    L2      func2
    L2      delay
    L2      func3
    L1    function1 ..

Explanation of symbols used:

    L1 : stack level 1  (max 2 or 8 levels). This is the
         REAL stack level, compensated when CALL's have
         been replaced by GOTO.

    .. : only the first call is fully expanded if more
         that one call to the same function occur inside
         the same function body.

    [CALL->GOTO] : CALL replaced by GOTO in order
                   to get more call levels

    [T-GOTO] : CALL+RETURN is replaced by a single GOTO.
               This saves a call level.

    [RECURSIVE] : recursive function call




