=================================================
       README file for the CC8E C compiler, DEMO edition
       =================================================

Welcome to the CC8E C compiler. The DEMO edition can generate up to
1024 words of code in a single module. External linker support is
not available on the DEMO edition.

The alternative TEST edition allows a large program to be compiled
using CC8E. However, NO hex file is generated and the assembly file
is NOT complete.


RESTRICTIONS
------------

  The DEMO edition can be used to generate code for all prototype
  and non-commercial systems without restrictions. NO permission is
  given to use the generated code in commercial systems.

  No restriction applies to source code written by the user.


COPYRIGHT NOTICE
----------------

  Copyright (c) B Knudsen Data, Trondheim, Norway, 2001 - 2006.

  www.bknd.com         Fax: (+47) 73 96 51 84

  The CC8E compiler is protected by Norwegian copyright laws and
  thus by corresponding copyright laws agreed internationally by
  mutual consent. Modification of the compiler is strongly
  prohibited. All rights reserved.

  B Knudsen Data assumes no responsibility for errors or defects in
  the compiler or in the other supplied files. This also applies to
  problems caused by such errors.

  Permission is required to distribute the DEMO edition.


SPECIAL ISSUES
--------------

  1. The new EXTENDED instruction set available on PIC18 devices
     released after May 2004 is NOT yet supported by CC8E. The
     extended instruction set is enabled or disabled by the XINST
     bit of config address 0x30006. The extended instruction set
     allows reentrant code and add 8 extra instructions: ADDFSR,
     ADDULNK, CALLW, MOVSF, MOVSS, PUSHL, SUBFSR, SUBULNK.

     a) By not enabling the extended instruction the access bank
        address 0 - 0x5F can be used as normal by the compiler.

     b) If the extended instruction is enabled, then the access bank
        address 0 - 0x5F MUST NOT be used for direct variable access
        by the compiler (not in inline assembly either). It can be
        used for indirect access (INDFx, ..).


  2. Computed goto using an 8 bit offset does not update PCLATU, and
     must therefore not cross a 64k address boundary. This condition
     is checked automatically when using the built in single module
     linker. For relocatable assembly on devices with over 64k code,
     this condition must be ensured manually. This is best done by
     using separate code SECTIONs of 64k byte each. Computed goto is
     generated when using skip(), skipL(), skipM() and also for
     leanslice tasks.


  3. The maximum call level must be restricted manually when using
     NESTED interrupts. This can be done by setting the maximum
     stack level allowed:

       #pragma stackLevels 28   // reserve three levels (31 is max)

     This statement must be put after the chip definition, and 2
     extra levels must be reserved when using ICD2 debugging. The
     extra levels for ICD2 debugging are normally reserved
     automatically in the header file.


SUPPLIED FILES
--------------

  cc8e.exe      : CC8E compiler, DEMO edition

  install.txt   : installation guide and MPLAB setup
  inline.txt    : information on inline assembly syntax
  chip.txt      : how to make new chip definitions
  cdata.txt     : info on the #pragma cdata statement
  config.txt    : the chip configuration bits
  linker.txt    : using MPLINK to link several modules (C or asm)
  math.txt      : math library support
  errata.txt    : silicon errata issues

  int18xxx.h    : interrupt header file

  hexcodes.h    : direct coded instructions

  cc8e.mtc      : MPLAB configuration file
  tlcc8e.ini    : MPLAB configuration file

  op.inc        : compiler options in a file
  reloc.inc     : options for generating object modules for linking

  demo.c        : sample syntax including interrupt
  demo-var.c    : defining RAM variables
  demo-mat.c    : integer math operations
  demo-fpm.c    : floating point math
  demo-fxm.c    : fixed point math
  demo-rom.c    : const data and DW
  demo-ptr.c    : indexed tables and pointers
  demo-ins.c    : generating single instructions using C code

  18C242.H, ..  : header files for specific chip support

  math16.h      : 8-16 bit math library, signed and unsigned
  math24.h      : 8-24 bit math library, signed and unsigned
  math32.h   (1): 8-32 bit math library, signed and unsigned
  math16x.h     : 16 bit fixed point library
  math24x.h     : 24 bit fixed point library
  math32x.h  (1): 32 bit fixed point library
  math16f.h  (1): 16 bit floating point library
  math24f.h     : 24 bit floating point library
  math32f.h     : 32 bit floating point library
  math24lb.h    : 24 bit floating point math functions (log,sqrt,cos,..)
  math32lb.h    : 32 bit floating point math functions (log,sqrt,cos,..)

  (1) : Not available on the DEMO and STANDARD edition

  news.txt      : recent added features
  readme.txt    : this file


SUPPORTED DEVICES
-----------------

  The compiler supports the PIC18 devices from Microchip. Take a
  look in chip.txt for details on how to generate code for a
  particular device.


PROGRAMMING RECOMMENDATIONS THAT ENABLES COMPACT CODE
-----------------------------------------------------

  1. If you are going to use multiplication and division, take a
     look at 'math.txt'.

  2. CC8E will update the bank bits automatically, but variables
     have to be placed on the different RAM banks by using pragma
     statements or bank type modifiers. It therefore recommended to
     locate all global variables belonging to the same RAM bank
     together (in header files).

        #pragma rambank 0
         char a;  // variables to be located in bank 0
        #pragma rambank 1
         // variables to be located in bank 1
         ..

     Some notes when locating variables:
     a) Access RAM and bank 0 is the most valuable RAM area. Use
        this with care.
     b) Locate most local variables in access RAM (move arrays
        to bank 1, 2 etc. if not enough space)
     c) Locate global arrays in banked memory (bank1, 2, etc.)
     d) Use option -V to generate the *.var file. This contains
        the number of access in each variable (#AC). Move variables
        with few accesses to bank 1, 2, etc.
     e) Locate variables which are close related to each other in
        the same bank.
     f) Locate all variables accessed in the same function in the
        same bank if possible.
     g) Use as few banks as possible


  3. It is most efficient to put all local variables in access RAM.
     This is easiest done by moving all global variables to the
     beginning of the program (or to header files). Then change the
     rambank to mapped RAM before compiling the functions:

         // all global variables
         #pragma rambank -    // access RAM
         // all functions


  4. It is recommended to define all functions before they are
     called. That is, make sure that the function code is compiled
     before the first function call is made. This allows better
     optimization of the bank selection bits (BSR).


  5. Computed goto is very efficient for implementing a multi-
     selection (instead of using the switch or multiple if
     statements). Many examples of how to do this is found in
     'Application Notes' in the User's Manual.


  6. The smallest possible variables should be used. Variables of 1
     and 8 bit are efficient. Also, some operations on signed
     variables requires more code compared to using unsigned
     variables.


SOME REGISTER ARE VOLATILE
--------------------------

  Note that RAM and special purpose registers are treated different.
  Most special purpose registers are volatile. That is, the compiler
  assumes that the contents may have changed between each register
  access. Optimization will therefore be different.



SOME CODE GENERATION NOTES:
---------------------------

  The compiler has some powerful features which may be confusing
  when the assembly file is examined:

    1) Peephole optimization: can be switched off with the '-u'
       command line option

    2) Extended call level: CALL's are replaced by GOTO's in some
       cases.

    3) Overlapping local variables: The compiler calculates a
       safe mapping to global addresses based on the variable
       scope, global optimized.

    4) Global optimization when updating the bank selection bits.
       The contents of these bits can be difficult to trace because
       the compiler removes nearly all unnessesary updating.

    5) The switch test constants will be different from the
       constants in the source file because the W register is
       modified through a series of XORLW instructions.

  If the code looks wrong, think twice. The advanced optimization
  is sometimes difficult to understand.



PROGRAMMING PRECAUTIONS:
------------------------

  1. The bank selection bits (BSR) are checked and updated by the
     compiler. Attempts to set or clear these bits in the source
     code are removed by the optimizer. This process may be switched
     off, local or global.

  2. Note that global variabeles are NOT initialized. The function
     clearRAM() can be used to clear ALL RAM locations (at startup).



MAIN COMPILER VERSIONS:
-----------------------

  February 2002 :  Version 1.0 released
  January  2004 :  Version 1.1 released



WRITING CODE THAT CAN BE COMPILED BY CC8E
-----------------------------------------

  CC8E is not a full C compiler. There are restrictions to be aware
  of. The main problem is that CC8E has limited ability to allocate
  temporary variables. Because of this, complex statements often
  have to be rewritten using simpler statements. This is most
  notisable when using variables of 16 bit or larger. There is an
  advantage of such rewriting. Often the generated hex code gets
  more compact.


  MODIFIED SAMPLE:

    uns16 array[10], temp, temp2;
    char j, k;

    //if(array[j] > array[j+1])
    //{
    //    temp = array[j];
    //    array[j] = array[j+1];
    //    array[j+1] = temp;
    //}

    temp = array[j];
    k = j+1;
    temp2 = array[k];
    if(temp > temp2)
    {
        array[j] = temp2;
        array[k] = temp;
    }


  MODIFIED SAMPLE:

    #include "math32f.h"
    #include "math32lb.h"

    void main( void)
    {
        double X, input;
        #define Const 22.94

        //X = exp( ( Const / input ) + ( Const * log(input) ) );
        X = log(input) * Const;
        X = exp( Const/input + X );
    }


  MODIFIED SAMPLE:
    //if (x++ < 20) { /* .. */ }
    if (x < 20) { x++;  /* .. */ }
    if (++x < 20) { /* .. */ }  // ok


  MODIFIED SAMPLE:

    unsigned long checksum;
    unsigned char c;
    unsigned long calc(unsigned long c);
    //checksum = calc(c^checksum) ^ (checksum/256);
    unsigned long tmp = calc(c^checksum);
    checksum /= 256;
    checksum ^= tmp;


  MODIFIED SAMPLE:

    //rx_str[ptr2] = rx_str[ptr1];
    char tmp = rx_str[ptr1];
    rx_str[ptr2] = tmp;


  MODIFIED SAMPLE:

    // if (c = TestOptions(0x00c6)) { /* .. */ }
    c = TestOptions(0x00c6);
    if (c) { /* .. */ }


  MODIFIED SAMPLE:

    //if (!((1<<(rx_str[ptr1]-1))&option)) { /* .. */ }
    unsigned char xtmp = rx_str[ptr1] - 1;
    unsigned long tmp = (unsigned long)1 << xtmp;
    tmp &= option;
    if (!tmp) { /* .. */ }


  MODIFIED SAMPLE:

    unsigned long packet;
    //packet = rx_str[2]*256 + rx_str[3];
    packet.high8 = rx_str[2];
    packet.low8 = rx_str[3];


  MODIFIED SAMPLE:

    unsigned long length;
    //length = 0x45 + 0x88 + 0x40 + 127 + addr1 + addr3 + str[1] + str[3];
    length = (unsigned long) 0x45 + 0x88 + 0x40 + 127 + addr1;
    length += addr3;
    length += str[1];
    length += str[3];

    //length = (length & 255) + packet / 256;
    length &= 255;
    length += packet.high8;