

THE PRAGMA STATEMENT


Available #pragma statements:

  #pragma asm2var 1
  #pragma assert /e text passed to the debugger
  #pragma assume *px in rambank 2
  #pragma bit ready @ STATUS.7
  #pragma cdata[1] = 0, 0x2000
  #pragma char varX @ 7
  #pragma chip PIC16C55
  #pragma codepage 0
  #pragma computedGoto 0
  #pragma config WDTE=off, FOSC=HS
  #pragma library 1  // on
  #pragma location 2
  #pragma optimize 0    // ALL off
  #pragma origin 0x200
  #pragma rambank 1
  #pragma rambase 48     /* bank 1 */
  #pragma ramdef 0x190 : 0x19F
  #pragma resetVector 0  // at location 0
  #pragma return[] = "Hello" 0 1 'H'
  #pragma stackLevels 4  // max 64
  #pragma update_FSR 1   /* ON */
  #pragma update_IRP 0   /* OFF */
  #pragma update_PAGE 0  /* OFF */
  #pragma update_RP 0    /* OFF */
  #pragma wideConstData 50


#pragma asm2var 1

  Enable equ to variable transformation.
  Defined in file 'inline.txt'.



#pragma assert [/] <type> <text field>

  Assert statements allows messages to be passed to the simulator,
  emulator, etc.

  [/] : optional character

  <type> : a = user defined assert
           e = user defined emulator command
           f = user defined printf
           l = user defined log command

  <text field> : any text string, valid to the end of the line.
                 The line can be extended by a '\' character like
                 other preprocessor statements.

  #pragma assert /e text passed to the debugger
  #pragma assert e text passed to the debugger

  #pragma assert ; this assert command is ignored

  NOTE 1: comments in the <text field> will not be removed, but
  passed to the debugger.

  NOTE 2: Only ASCII characters are allowed in the assert text
  field. However, a backslash allows some 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

  Macro's can be used inside assert statements with some
  limitations. The macro should cover the whole text field AND the
  <type> identifier (or none of them). Macro's limited to a part of
  the text field are not translated. Macro's can be used to switch
  on and off a group of assert statements or to define similar
  assert statements.

  #define COMMON_ASSERT a text field
  #define AA /
  ..
  #pragma assert COMMON_ASSERT
  #pragma assert AA a text field

  #define XX /a  /* this will NOT work */
  #pragma assert XX causes an error message

  Macro AA can then be used to disable a group of assert statements.

  #define AA ;



#pragma assume *<pointer> in rambank <n>

  The #pragma assume statement tells the compiler that a pointer
  operates in a limited address range.

  12 bit core: enables optimal updating of the bank selection bits.
  The assume statement is not required for devices with one RAM bank
  only (address up to 31).

  14 bit core: enables updating of the IRP bit. The assume statement
  is ONLY required when more than 2 banks are used, i.e. the upper
  address is above 255. Note that rambank 0 and 1 are equivalent
  (the same RAM half), and also bank 2 and 3. A missing assume
  statement force the compiler to assume that the pointer access a
  location in the same RAM half that the pointer itself resides.

  A warning is printed if a pointer is loaded with an address
  outside the assumed address range.



#pragma bit <name> @ <N.B or variable[.B]>

    Defines the global bit variable <name>. Useful
    for assigning a bit variable to a certain
    address. Only valid addresses are allowed.

    Ex.:    #pragma bit bitxx @ 0x20.7
            #pragma bit ready @ STATUS.7
            #pragma bit ready @ PA2


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

  The cdata statement can store 14 bit data in program memory at
  fixed addresses. It can also be used to store data in EEPROM
  memory. Refer to file 'cdata.txt' for details.

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

    ADDRESS: 0 .. 0x7FFE

    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\\\""


#pragma char <name> @ <constant or variable>

    Defines the global variable <name>. Useful for
    assigning a variable to a certain address. Only
    valid addresses are allowed.

    Ex.:    #pragma char i @ 0x20
            #pragma char PORTX @ PORTC



#pragma chip [=] <device>

  Defines the chip type. This allows the compiler to select the
  right boundaries for code and memory size, variable names, etc.
  Note that the chip type can also be defined as a command line
  option.

    #pragma chip PIC16C55

  This statement have to proceed any normal C statements, but some
  preprocessor statements, like #if and #define, can be compiled
  first.

  The supported devices are known internally (16C54,55,56,57,58, 61,
  64,65, 71,73,74, 84, 620,621,622) or defined in a PICmicro header
  file (i.e.16F877.h). It is also possible to make new header files.
  Refer to 'chip.txt' for details.


#pragma codepage [=] <0,1,2,3>

       // 12 bit core      14 bit core
    0  // 0x000 - 0x1FF    0x0000 - 0x07FF
    1  // 0x200 - 0x3FF    0x0800 - 0x0FFF
    2  // 0x400 - 0x5FF    0x1000 - 0x17FF
    3  // 0x600 - 0x7FF    0x1800 - 0x1FFF

  Defines the codepage to be used. Code is located at the start of
  the active codepage, or from the current active location on that
  page. The codepage can not be changed inside a function.

    #pragma codepage 3
    // following functions are located on codepage 3

  NOTE that non-existing pages for a specific controller are
  mapped into existing ones.


#pragma computedGoto [=] <0,1,2>

  This statement can be used when constructing complicated computed
  goto's. Refer to file 'c-goto.txt' for more details.

     #pragma computedGoto  1  // start region
     #pragma computedGoto  0  // end of region
     #pragma computedGoto  2  // start big region


#pragma config <id> = <state> [, .. , <id> = <state>]

  Refer to file 'config.txt' for details.


#pragma config_def [=] <value>

  Refer to file 'chip.txt' for details.


#pragma library <0/1>

  CC5X will automatically delete unused (library) functions.

    #pragma library 1
     // functions that are deleted if unused
     // applies to prototypes and function definitions
    #pragma library 0


#pragma location [=] <0,1,2,3,->

  The purpose of this statement is to locate the functions in the
  different codepages available. The statement is similar to the
  '#pragma codepage' statement, with some exceptions:

  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 optimize [=] [N:] <0,1>

  This statement enables optimization to be switched ON or OFF in a
  local region. A specific type of optimization can also be switched
  on or off. The default setting is on.

   1 : redirect goto to goto
   2 : remove superfluous gotos
   3 : replace goto by skip instructions
   4 : remove instructions that affects the zero-
       flag only.
   5 : replace INCF and DECF by INCFSZ and DECFSZ
   6 : remove superfluous updating of PA0 and PA1
   7 : remove other superfluous instructions
   8 : remove superfluous loading of W

  Examples:
        #pragma optimize 0    /* ALL off */
        #pragma optimize 1    /* ALL on */
        #pragma optimize 2:1  /* type 2 on */
        #pragma optimize 1:0  /* type 1 off */
        /* combinations are also possible */
        #pragma optimize 3:0, 4:0, 5:1
        #pragma optimize 1, 1:0, 2:0, 3:0

  NOTE: The command line option '-u' will switch optimization
        off globally and cause all settings in the C source code
        to be ignored.



#pragma origin [=] <n>

  Valid address region : 0x0000 - 0x1FFF

  Defines the address (and codepage) of the following code.
  Overlapping code produces an error message. The current active
  location on a codepage can not be moved backwards, even if there
  is no code in that area. Origin can not be changed inside a
  function.

  Examples:
    #pragma origin 4  // interrupt start address
    #pragma origin 0x700


#pragma rambank [=] <0,1,2,3,->

    14 bit core:
    -   =>  mapped space: (chip specific)
    0   =>  bank 0:    0 (0x000) -  127 (0x07F)
    1   =>  bank 1:  128 (0x080) -  255 (0x0FF)
    2   =>  bank 2:  256 (0x100) -  383 (0x17F)
    3   =>  bank 3:  384 (0x180) -  511 (0x1FF)

    12 bit core:
    -   =>  mapped space:    8  -  15 (0x0F)
    0   =>  bank 0:   16 (0x10) -  31 (0x1F)
    1   =>  bank 1:   48 (0x30) -  63 (0x3F)
    2   =>  bank 2:   80 (0x50) -  95 (0x5F)
    3   =>  bank 3:  112 (0x70) - 127 (0x7F)

  '#pragma rambank' defines the region(s) where the compiler will
  allocate variable space. The compiler gives an error message when
  all locations in the current bank are allocated.

  RAM banks are only valid for some of the controllers. Non-existing
  banks for the other controllers are mapped into defined RAM space.



#pragma rambase [=] <n>

  Defines the start address when declaring global variables. This
  statement is included for backward compatibility reasons only. The
  use of rambank and rambase are very similar. The address have to
  be within the RAM address range of the chip used.

  12 bit core note: The locations from address 0 to 31 are treated
  as a unit. Using start address 7 means that locations in the
  mapped register space and bank 0 are allocated. Using start
  address 32 implies that locations in the mapped register space are
  allocated.

  NOTE: The start address is not valid for local variables, but
  'rambase' can be used to select a specific RAM-bank.



#pragma ramdef <ra> : <rb> [SPECIAL_MAPPING]

  This statement is normally used in PICmicro header files.
  Refer to 'chip.txt' for details.


#pragma resetVector <n>

  Some chips have an unusual startup vector location (like the
  PIC16C508/9). The reset-vector then have to be specified.

  NOTE: this statement is normally NOT required, because the
  compiler normally use the default location, which is the first (14
  bit core) or the last location (12 bit core).

      #pragma resetVector 0x1FF // at last code location
      #pragma resetVector 0     // at location 0
      #pragma resetVector 10    // at location 10 (leave 0 - 9 unused)
      #pragma resetVector -     // NO reset-vector at all


#pragma return[<n>] = <strings or constants>

  Allows multiple return statements to be inserted. This statement
  should be proceeded by a statement like 'PCL=PCL+W;'. The compiler
  may otherwise remove all superfluous returns. The constant <n> is
  optional, but it allows the compiler to print a warning when the
  number of constants is not equal to <n>. The compiler also
  generates a page check. Refer to 'Computed Goto' for more details.

  Examples:
    PCL += W;
    #define  NoH  11
    #pragma return[NoH] = "Hello world"
    #pragma return[5] = 1, 4, 5, 6, 7
    #pragma return[] = 0 1 2 3 44 'H' \
                       "Hello" 2 3 4 0x44
    #pragma return[]= 'H' 'e' 'l' 'l' 'o'
    #pragma return[3] = 0b010110 \
                        0b111    0x10
    #pragma return[9] = "a  \" \r\n\0"
    #pragma return[] /* page check only */


#pragma stackLevels <n>

  The number of call levels can be defined (normally not required):

      #pragma stackLevels 4   // max 64

  12 bit core use by default 2 levels
  14 bit core use by default 8 levels


#pragma update_FSR [=] <0,1>

  Allows the automatic updating of the bank selection bits FSR.5 and
  FSR.6 to be switched on and off locally. This can be useful in
  some cases when INDF is used directly in the user code. The
  statement works for core 12 devices with more than one RAM bank.
  It is ignored for the other devices.

    #pragma update_FSR 0   /* OFF */
    #pragma update_FSR 1   /* ON */

  These statements can be inserted anywhere, but they should
  surround a region as small as possible.



#pragma update_IRP [=] <0,1>

  Allows the automatic updating of the indirect bank selection bit
  IRP to be switched on and off locally. The statement is ignored
  when using the 12 bit core.

    #pragma update_IRP 0   /* OFF */
    #pragma update_IRP 1   /* ON */

  These statements can be inserted anywhere.


#pragma update_PAGE [=] <0,1>

  Allows the automatic updating of the page selection bits to be
  switched on and off locally. This is not recommended except in
  special cases. The page bits resides in the STATUS register for
  core 12 devices, and in PCLATH for core 14.

    #pragma update_PAGE 0   /* OFF */
    #pragma update_PAGE 1   /* ON */


#pragma update_RP [=] <0,1>

  Allows the automatic updating of the bank selection bits RP0
  and RP1 to be switched on and off locally. The statement is
  ignored when using the 16C5X family.

    #pragma update_RP 0   /* OFF */
    #pragma update_RP 1   /* ON */

  These statements can be inserted anywhere, but they should
  surround a region as small as possible.



#pragma wideConstData [<N>]

  Enable storing of 14 bit data for 14 bit core devices. Details is
  found in file 'const.txt'.



