JALv2 PRAGMAs
     __________________________________________________________
     __________________________________________________________

   There are many extra things the compiler either needs to know
   to do its job, or modify its behavior to suit a particular
   need. This information is passed to the compiler with something
   called a PRAGMA. This file describes every PRAGMA the compiler
   understands.

   See the JALv2 documentation for definitions and conventions.
   Any time multiple options are allowed, the default option is
   preceded with a '*'. An {empty} option is interpreted as the
   default option.

   Table of Contents
   1. Chip Configuration

        1.1. TARGET CHIP
        1.2. TARGET CLOCK
        1.3. TARGET FUSES
        1.4. TARGET opt tags

   2. Compiler Configuration

        2.1. BOOTLOADER

              2.1.1. BLOADER
              2.1.2. LOADER18 [ cexpr ]
              2.1.3. LONG_START
              2.1.4. RICKPIC

        2.2. CLEAR
        2.3. EEDATA
        2.4. FUSE
        2.5. IDDATA
        2.6. TASK

   3. Global Configuration

        3.1. ERROR
        3.2. NAME
        3.3. SIZE
        3.4. SPEED

   4. PROCEDURE/FUNCTION Configuration

        4.1. FRAME
        4.2. INLINE
        4.3. INTERRUPT

              4.3.1. * NORMAL
              4.3.2. FAST
              4.3.3. RAW

        4.4. JUMP_TABLE
        4.5. KEEP
        4.6. NOSTACK

   5. Optimization PRAGMAs

        5.1. EXPR_REDUCE
        5.2. CEXPR_REDUCE
        5.3. CONST_DETECT
        5.4. LOAD_REDUCE
        5.5. TEMP_REDUCE
        5.6. VARIABLE_FRAME
        5.7. VARIABLE_REUSE

   6. Warning

        6.1. ALL
        6.2. BACKEND
        6.3. CONVERSION
        6.4. DIRECTIVES
        6.5. MISC
        6.6. RANGE
        6.7. STACK_OVERFLOW
        6.8. TRUNCATE

   7. Chip Specification

        7.1. CODE
        7.2. DATA
        7.3. EEPROM
        7.4. FUSE_DEF
        7.5. ID
        7.6. STACK
        7.7. TARGET CPU
        7.8. TARGET BANK
        7.9. TARGET PAGE

   8. Debugging

        8.1. CODEGEN
        8.2. PCODE
     __________________________________________________________

Chapter 1. Chip Configuration

   Select various attributes of a chip.
     __________________________________________________________

1.1. TARGET CHIP

   Syntax:
        PRAGMA TARGET CHIP chipname

   Analogous to:
        CONST _target_chip = cexpr

   The compiler will look for a constant named `PIC_chipname' and
   assign it to _target_chip. This might be used by some libraries
   to modify their behavior based on the chip in use. The compiler
   itself does not use this information.
     __________________________________________________________

1.2. TARGET CLOCK

   Format:
        PRAGMA TARGET CLOCK cexpr

   Analogous to:
        CONST _target_clock = cexpr

   Set the target clock rate to cexpr in Hz. The compiler only
   needs this if the _usec_delay statement is used.
     __________________________________________________________

1.3. TARGET FUSES

   Format:
        PRAGMA TARGET FUSES [ cexpr0 ] cexpr

   Analogous to:
        CONST _config = cexpr,
        or CONST _config[cexpr0] = cexpr

   cexpr0 is only used when multiple config words exist in which
   case 0 is the first config word, 1 the second, and so on.

   The configuration words define how some parts of the
   destination chip are used. While it is possible to set the
   fuses directly, it is generally better to use the "TARGET opt
   tags" construct below.
     __________________________________________________________

1.4. TARGET opt tags

   Format:
        PRAGMA TARGET opt tags

   This accesses the mneumonic symbols defined with PRAGMA
   FUSE_DEF. This is preferable to setting the fuse values
   directly, because (1) mneumonics are more easily readable than
   numeric values, and (2) the same mneumonic can be setup
   differently on different chips.
     __________________________________________________________

Chapter 2. Compiler Configuration

   Configure compiler code generation policies.
     __________________________________________________________

2.1. BOOTLOADER

   Format:
        PRAGMA BOOTLOADER { BLOADER | LONG_START | LOADER18 [ cexpr ] |
RICKPIC}

   Set the user code preamble as follows:
     __________________________________________________________

2.1.1. BLOADER

   Pre-amble:
          ORG 0x0003
          GOTO _pic_pre_user
     __________________________________________________________

2.1.2. LOADER18 [ cexpr ]

   Pre-amble:
          ORG cexpr -- (or 0x0800 if cexpr is not present)

   The interrupt vector, if used, is put at cexpr + 8
     __________________________________________________________

2.1.3. LONG_START

   Pre-amble:
            ORG 0x0000
            BSF/BCF _pclath, 4
            BSF/BCF _pclath, 3
            GOTO _pic_pre_user
            NOP
     __________________________________________________________

2.1.4. RICKPIC

   Pre-amble:
          ORG  0x0003
          GOTO _pic_pre_user

   nb: if "PRAGMA INTERRUPT RAW" is used, the interrupt routine
   must not exceed one page (minus a few bytes).
     __________________________________________________________

2.2. CLEAR

   Format:
        PRAGMA CLEAR { YES | NO | }

   YES -- Code is generated to set all user-data to 0
   * NO -- No such code is generated

   nb: volatile variables, and variables explicitly placed by the
   user are *not* set to 0
     __________________________________________________________

2.3. EEDATA

   Format:
        PRAGMA EEDATA expr;[','expr;1...]

   Places data into the EEPROM (defined with PRAGMA EEPROM..). The
   first time this statement is executed, the data are placed into
   location 0 of the EEPROM. Each time after the data are placed
   in consecutive locations.
     __________________________________________________________

2.4. FUSE

   Format:
        PRAGMA FUSES { YES | NO | }

   * YES -- The `__config' line is written to the assembly file
   NO -- The `__config' line is not written to the assembly file

   It is often convenient *not* to program the CONFIG word (for
   example, when using a boot loader). This suppresses that
   programming.
     __________________________________________________________

2.5. IDDATA

   Format:
        PRAGMA IDDATA expr;[','expr;1...]

   Places data into the ID area (defined with PRAGMA ID...). The
   first time this statement is executed, the data are placed into
   location 0 of the ID. Each time after the data are placed in
   consecutive locations.
     __________________________________________________________

2.6. TASK

   Format:
        PRAGMA TASK cexpr

   Set the maximum concurrent task count to cexpr. It is generally
   better to set this in your program, instead of doing so with
   the compiler option ("-tasks") as it is unlikely to change.

   nb: When multiple tasks are used, the main task requires one
   task slot.
     __________________________________________________________

Chapter 3. Global Configuration

   These can all be used globally.
     __________________________________________________________

3.1. ERROR

   Format:
        PRAGMA ERROR

   Causes an error to be generated. This has been superceded with
   the "_ERROR" command (see the JALv2 reference guide).
     __________________________________________________________

3.2. NAME

   Format:
        PRAGMA NAME str

   Causes an error to be generated if the current source file name
   (excluding the .jal extension and path) doesn't match str.
     __________________________________________________________

3.3. SIZE

   Format:
        PRAGMA SIZE

   Anything physically following this pragma will be optimized for
   size. See notes under `PRAGMA SPEED'
     __________________________________________________________

3.4. SPEED

   Format:
        PRAGMA SPEED

   Anything physically following this pragma will be optimized for
   speed. Currently this only affects the generation of the shift
   operators -- loops will be unrolled for SPEED, but used for
   SIZE. In the future this could affect other loop unrolling.
     __________________________________________________________

Chapter 4. PROCEDURE/FUNCTION Configuration

   These must be used with a procedure and/or function and are
   only in effect for the procedure/function in which they're
   used.
     __________________________________________________________

4.1. FRAME

   Format:
        PRAGMA FRAME

   Used within a function or procedure, declares that all
   variables in the function or procedure will be allocated into a
   single `frame'. This guarantees that all local variables will
   be allocated in the same data bank, so bank switching to access
   variables will be minimized. This can also result in `out of
   data space' errors due to memory fragmentation when plenty of
   space is otherwise available.

   Normally variables are allocated at the lowest address into
   which they will fit. This makes much better use of the memory,
   but can cause variables in the same function to be allocated in
   separate banks which results in bank switching overhead.

   nb: Any re-entrant function, and any function called through a
   function pointer (aka, pseudo-variable function) will allocate
   per-frame regardless of this setting.
     __________________________________________________________

4.2. INLINE

   Format:
        PRAGMA INLINE

   Used within a function or procedure, declares that this
   function or procedure will not get a seperate body, but rather
   will be copied directly into the calling code.

   nb: If a procedure or function marked `inline' is executed as
   volatile parameter, it will get a body.
     __________________________________________________________

4.3. INTERRUPT

   Format:
        PRAGMA INTERRUPT { FAST | RAW | NORMAL | }

   This must be used within a procedure that takes no parameters.
   It defines the procedure as an interrupt entry point. Such a
   procedure is added to a chain of procedures executed whenever
   an interrupt hits. Once a procedure has been marked interrupt,
   it cannot be called directly by the program.
     __________________________________________________________

4.3.1. * NORMAL

   W, STATUS, PCLATH, FSR, TBLPTR and _picstate are saved on ISR
   entry and restored on exit
     __________________________________________________________

4.3.2. FAST

   _pic_state is *not* saved or restored. In this case, the
   interrupt procedure should be written entirely in assembly to
   avoid corrupting the pic_state area.
     __________________________________________________________

4.3.3. RAW

   *None* of the normal pre-amble or cleanup code is generated.
   The user is entirely responsible for the interrupt. The code is
   guarenteed to placed at the interrupt vector.

   nb: this feature isn't yet available
     __________________________________________________________

4.4. JUMP_TABLE

   Format:
        PRAGMA JUMP_TABLE

   This generates a warning, but does nothing. It's here for
   backward compatability.
     __________________________________________________________

4.5. KEEP

   Format:
        PRAGMA KEEP { BANK | PAGE } [ "," { BANK | PAGE } ... ]

   This guarentees the page and/or bank select bit manipulations
   will not be removed. Normally, they are removed if analysis
   shows them to be unnecessary. This is only useful to guarentee
   certain timings. This effects the entire procedure or function
   in which it is declared (not just from point of declaration).
     __________________________________________________________

4.6. NOSTACK

   Format:
        PRAGMA NOSTACK

   Used within a procedure, the procedure will not be called using
   the normal call/return instructions. Instead, the return
   address will be stored in a procedure-local variable,
   '_return,' and the call will be executed by jumping to the
   start of the procedure. The return will be executed by jumping
   to the first statement after the call.

   The overhead for this is two or three data bytes, four to six
   instructions for the return, and eight to ten instructions for
   the call. Currently re-entrant functions and functions called
   indirectly cannot use this pragma.
     __________________________________________________________

Chapter 5. Optimization PRAGMAs

   These all effect various optimizations done by the compiler.
   These cannot be used to turn on and off optimizations for
   specific parts of the code -- the last one parsed will be the
   one in effect.

   For a complete description of each, including warnings and
   caveats, please refer to the Optimizations chapter of the Jalv2
   Compiler Options document
     __________________________________________________________

5.1. EXPR_REDUCE

   Format:
        PRAGMA OPT EXPR_REDUCE { YES | NO | }

   * YES --expression reduction is performed
   NO -- expression reduction is not performed

   Expression reduction looks for things like `x * 1' and replaces
   with `x'. See `EXPRESSION REDUCTION' in jalopts.txt for
   details.
     __________________________________________________________

5.2. CEXPR_REDUCE

   Format:
          PRAGMA OPT CEXPR_REDUCE { YES | NO | }

   * YES -- constant expression reduction is performed
   NO -- constant expression reduction is no performed

   Constant expression reduction looks for operations on two
   constants that can be evaluated at compile time, saving both
   time and memory.

   nb: disabling this will cause the backend code generators to
   fail, so only do so if `PRAGMA DEBUG CODEGEN OFF' is specified.
     __________________________________________________________

5.3. CONST_DETECT

   Format:
        PRAGMA OPT CONST_DETECT { YES | NO | }

   YES -- enable constant detection
   * NO -- disable constant detection

   Look for variables that are defined but are either only
   assigned once, or are always assigned the same value. When this
   happens, replace all occurances of the variable with the
   constant.

   nb : PRAGMA CLEAR will prevent this option from having any
   effect unless the variable is only assigned the constant 0.
     __________________________________________________________

5.4. LOAD_REDUCE

   Format:
        PRAGMA OPT LOAD_REDUCE { YES | NO | }

   YES -- Perform load reduction
   * NO -- Do not perform load reduction

   Load reduction tracks the value in W and attempts to remove any
   load into W of a value it already holds.

   nb: this is still considered experimental!
     __________________________________________________________

5.5. TEMP_REDUCE

   Format:
        PRAGMA OPT TEMP_REDUCE { YES | NO | }

   YES -- Perform temporary variable reduction
   * NO -- Do not perform temporary variable reduction

   Temporary reduction effects complex instructions. For example,
   without temporary reduction the expression:
        a = b + c * d + e

   will use three temporary variables. With reduction, it will
   only use one.
     __________________________________________________________

5.6. VARIABLE_FRAME

   Format:
        PRAGMA OPT VARIABLE_FRAME { YES | NO | }

   YES -- allocate variables a frame at a time
   * NO -- allocate variables individually

   Normally, variables are allocated individually. This allows
   optimal use of data memory, but means that variables in a given
   procedure might be spread across multiple banks. Enabling this
   option will guarentee that all variables in a procedure will
   reside in a single bank.

   nb: unlike `PRAGMA FRAME' above, this affects the entire file
     __________________________________________________________

5.7. VARIABLE_REUSE

   Format:
        PRAGMA OPT VARIABLE_REDUCE { YES | NO | }

   * YES -- Perform variable reduction
   NO -- Do not perform variable reduction

   Variable reduction looks for variables that are assigned, but
   not used, or used, but not assigned, or neither used nor
   assigned. In these cases normally the variable is removed
   (unless it is volatile). Turning this off leaves the variable
   around.
     __________________________________________________________

Chapter 6. Warning

   Warning pragmas are in effect until changed (they can be turned
   on and off at will).
     __________________________________________________________

6.1. ALL

   Format:
        PRAGMA WARN ALL { YES | NO }

   * YES -- enable all warnings
   NO -- disable all warnings
     __________________________________________________________

6.2. BACKEND

   Format:
        PRAGMA WARN BACKEND { YES | NO }

   * YES -- enable all warnings
   NO -- disable all warnings

   This turns on debugging of the code generator (currently the
   translation from pcode --> PIC).
     __________________________________________________________

6.3. CONVERSION

   Format:
        PRAGMA WARN CONVERSION { YES | NO | }

   * YES -- enable conversion warnings
   NO -- disable conversion warnings

   Conversion warnings occur when assigning unsigned to signed, or
   signed to unsigned.
     __________________________________________________________

6.4. DIRECTIVES

   Format:
        PRAGMA WARN DIRECTIVES { YES | NO | }

   YES -- enable directive warnings
   * NO -- disable directive warnings

   The JAL language has a peculiar feature : the construct:
        IF cexpr THEN ... END IF

   is actually a compiler directive. If cexpr evaluates to 0, the
   compiler stops translating the code until it reaches the
   corresponding END IF. This warning will simply shows where this
   construct is used.
     __________________________________________________________

6.5. MISC

        PRAGMA WARN MISC { YES | NO | }

   * YES -- enable misc. warnings
   NO -- disable misc. warning

   There are some warnings that are not catagorized. This enables
   or disables them.
     __________________________________________________________

6.6. RANGE

   Format:
        PRAGMA WARN RANGE { YES | NO | }

   * YES -- enable out of range warnings
   NO -- disable out of range warnings

   This enables or disabled `value out of range' warnings.
     __________________________________________________________

6.7. STACK_OVERFLOW

   Format:
        PRAGMA WARN STACK_OVERFLOW { YES | NO | }

   YES -- stack overflow results in a warning
   * NO -- stack overflow results in an error
     __________________________________________________________

6.8. TRUNCATE

   Format:
        PRAGMA WARN TRUNCATE { YES | NO | }

   * YES -- enable the truncation warning
   NO -- disable the truncation warning

   Truncation can occur when a larger sized value is assigned to
   smaller one.
     __________________________________________________________

Chapter 7. Chip Specification

   These are used in the chip definition files, not normally by
   the end user.
     __________________________________________________________

7.1. CODE

   Format:
        PRAGMA CODE cexpr

   Defines the code size for a device -- used to detect code too
   large. For the 12 & 14 bit cores, this number is in WORDs, for
   the 16 bit cores, this number is in BYTEs. Blame MicroChip.
     __________________________________________________________

7.2. DATA

   Format:
        PRAGMA [DATA | SHARED] cexpr0['-'cexpr1[',' ...]

   Defines a range allowed when allocating variables. DATA access
   is assumed to require whatever banking method is needed for the
   target, whereas SHARED is assumed to not require these bits.

   Note that automatic variable allocation only uses the area
   denoted by DATA, never the area denoted by SHARED.
     __________________________________________________________

7.3. EEPROM

   Format:
        PRAGMA EEPROM cexpr0 ',' cexpr1

   Defines EEPROM available to the chip. cexpr0 is the ORG used
   when programming the device, size is the EEPROM cexpr1 in
   bytes.
     __________________________________________________________

7.4. FUSE_DEF

   Format:
        PRAGMA FUSE_DEF opt[':'cexpr0] cexprm '{'
          tag '=' cexprb
          ...
        '}'

   Defines symbolic fuse bits so the end user needn't twiddle them
   directly.

   opt -- a string presented to the user
   [:cexpr0] -- which config word stores this entry, starting with
   0
   cexprm -- the fuse word is bit-wise ANDed with this before
   continuing
   tag -- the sub-tag
   cexprb -- which bit to set

   These are used by the end user with the `PRAGMA TARGET opt
   tags' defined above. In this case the result is similar to:
        _config = _config & cexprm | cexprb
     __________________________________________________________

7.5. ID

   Format:
        PRAGMA ID cexpr0 ',' cexpr1

   Defines ID bytes available to the chip. cexpr0 is the ORG used
   when programming the device, size is the EEPROM cexpr1 in
   bytes.
     __________________________________________________________

7.6. STACK

   Format:
        PRAGMA STACK cexpr

   Defines the hardware stack size for a device -- used to detect
   stack overflow.
     __________________________________________________________

7.7. TARGET CPU

   Format:
        PRAGMA TARGET CPU cexpr

   Analagous to:
        CONST _target_cpu = cexpr

   Set the target CPU. cexpr should be one of the constants from
   come from chipdef.jal.
     __________________________________________________________

7.8. TARGET BANK

   Format:
        PRAGMA TARGET BANK cexpr

   Analagous to:
        CONST target_bank_size = cexpr

   Set the target's data bank size. The default is 128 bytes.
     __________________________________________________________

7.9. TARGET PAGE

   Format:
        PRAGMA TARGET PAGE cexpr

   Analgous to:
        CONST _target_page_size = cexpr

   Set the target's code page size. The default is 2048 words.
   This is not used in the 16 bit cores.
     __________________________________________________________

Chapter 8. Debugging

   The following are only useful when debugging compiler errors.
     __________________________________________________________

8.1. CODEGEN

   Format:
        PRAGMA DEBUG CODEGEN { YES | NO | }

   * YES -- Enable the back_end code generation
   NO -- Disable the back_end code generation

   Allow the pcode to be generated without executing the PIC code
   generator.
     __________________________________________________________

8.2. PCODE

   Format:
        PRAGMA DEBUG PCODE { YES | NO | }

   YES -- show the pcode in the asm file
   * NO -- don't show the pcode in the asm file
