PicBasic Pro Compiler Ver. 2.42 README.TXT
Copyright 2002 microEngineering Labs, Inc.

This software and accompanying documentation is copyright (c)
microEngineering Labs, Inc. and may only be used by owners of the
microEngineering Labs, Inc. PicBasic Pro Compiler.  Please contact
microEngineering Labs, Inc. to license this software.  Contact
information is listed at the end of this file.

The files on this disk should include:

        BS1DEFS.BAS             BS1 RAM and pin definitions
        BS2DEFS.BAS             BS2 RAM and pin definitions
        ICDDEFS*.BAS            ICD memory allocation
        MODEDEFS.BAS            Serial, Shift and X-10 mode definitions
        MP.EXE                  Mpasm launcher
        MPLAB.TXT               MPLAB installation/simulation instructions
        NEW.TXT                 New compiler features
        PBP.EXE                 PicBasic Pro Compiler
        PBPW.EXE                PicBasic Pro Compiler, 32-bit Windows executable
        PBP*.LIB                PBP library files
        PBP*.MAC                PBP macro files
        PBP*.RAM                PBP library RAM files
        PM.EXE                  PM Assembler
        PM.TXT                  PM Assembler instruction file
        README.TXT              This file
        *EXT.BAS                External register definitions
        *.BAS                   PBP BASIC include file for each device
        *.INC                   PBP include file for each device
        \INC\M*.INC             PM include file for each device
        \SAMPLES\*.BAS          PBP sample programs
        \USB\*.*                USB files



Version Information

Version 2.4 of the PicBasic Pro Compiler adds support for the PIC18Fxxx
devices and limited support for the 12-bit core PICmicro MCU devices.  See
the NEW.TXT file for specific new feature information.



PIC18Xxxx Information

The 16-bit core 18Xxxx PICmicro MCUs may now be used with the PicBasic Pro
Compiler.  MPASM or MPASMWIN must be used as the assembler as PM does not
support the PIC18Xxxx devices.  Simply specify the assembler and device type
on the command line using the -a and -p options:

        PBP -ampasm -p18c452 filename

Early PIC18Xxxx devices do not include the LFSR assembler op-code.  By
default, PBP will not use the LFSR op-code but will use a longer method
instead.  If the PIC18Xxxx device does have the LFSR op-code, a Define may
be added to the BASIC program to tell PBP to use it:

        Define USE_LFSR 1



PIC17Cxxx Information

The 16-bit core 17Cxxx PICmicro MCUs may now be used with the PicBasic Pro
Compiler.  Simply specify the device type on the command line using the
-p option:

        PBP -p17c752 filename

There is no data direction (TRIS) register for PORTA.  Therefore, commands
that rely on the TRIS register for their operation, such as I2CRead and
I2CWrite, may not be used on PORTA.

Hserin and Hserout work with the first USART only.  On devices that have
two USARTs, use the register names to directly access the second USART.

The default Defines for the LCD are:

        Define LCD_DREG PORTB	' LCD data pin port
        Define LCD_DBIT 0	' LCD data pin bit
        Define LCD_RSREG PORTB  ' LCD register select pin port
        Define LCD_RSBIT 4      ' LCD register select pin bit
        Define LCD_EREG PORTB	' LCD enable pin port
        Define LCD_EBIT 5	' LCD enable pin bit
        Define LCD_BITS 4	' LCD number of data bits
        Define LCD_LINES 2      ' LCD number of lines



PIC12C5xx Information

On the PIC12C5xx and 12CE5xx devices, pin GPIO.2 is forced to an input
regardless of the setting of the TRIS register.  To allow this pin to be
used as a standard I/O pin, add the following line to the beginning of
the program:

	OPTION_REG.5 = 0



Files Information

FILES should be set to at least 75 in your CONFIG.SYS file.  It is
also a good idea to set BUFFERS to at least 75.



Out of Memory Errors

Compiling large PicBasic Pro source code files can tax the memory of
the PC running the compiler.  If an Out of Memory error is issued and
the FILES and BUFFERS are set as above, an alternate version of PBP
can be used.  PBPW.EXE has been compiled to make use of all of the
memory available to Windows 95, 98, ME, NT, 2000 and XP.  You must, of
course, be running in a DOS shell from one of those Windows environments
or within Microchip's MPLAB or other Windows IDE.  To execute the Windows
version from the DOS command line, simply substitute PBPW for PBP.

        PBPW options filename



OPTION Register

The actual name of the OPTION register for use by PicBasic Pro is
OPTION_REG.  This is the Microchip compatible name so that it can be
used within MPLAB.  The names of the registers that PicBasic Pro can
use may be found in the files PIC12EXT.BAS, PIC14EXT.BAS, PIC17EXT.BAS
and PIC18EXT.BAS.



GPIO, TRISIO Registers

The actual name of the port and TRIS register for use by PicBasic Pro for
the PIC12C5xx and 12C67x parts is GPIO and TRISIO.  These are the Microchip
compatible names so that they can be used within MPLAB.  The names of the
registers that PicBasic Pro can use may be found in the files PIC12EXT.BAS,
PIC14EXT.BAS, PIC17EXT.BAS and PIC18EXT.BAS.



Aliases

The PicBasic Pro Compiler allows multiple variable names to point to the
same RAM locations.  These are generally called aliases.  Aliases should
only be applied to the originally created variable.  There should be no
aliases to an alias.



Loader Define

A Define tells the compiler that a boot loader, like the melabs Loader,
is going to be used to put the program into the PICmicro MCU.  This Define
moves the compiler's library code out of the first 4 locations.

        Define LOADER_USED 1



OSCCAL Defines

Some PICmicro MCUs, notably the PIC12C671, 672, 12CE673 and 674, have
on-chip RC oscillators.  These devices contain an oscillator calibration
factor in the last location of code space.  The on-chip oscillator may
be fine-tuned by acquiring the data from this location and moving it into
the OSCCAL register.  Two Defines have been created to perform this task
automatically each time the program starts.

        Define OSCCAL_1K 1      ' Set OSCCAL for 1K device
        Define OSCCAL_2K 1      ' Set OSCCAL for 2K device

Add one of these 2 Defines near the beginning of the PicBasic Pro program
to perform the setting of OSCCAL.  These Defines are only for the PIC12C67x
devices.  The PIC12C5xx devices set the OSSCAL without using a Define.

If a UV erasable device has been erased, the value cannot be read from
memory.  If one of these Defines is used on an erased part, it will cause
the program to loop endlessly.  To set the OSCCAL register on an erased part,
near the beginning of the program, add the line:

        OSCCAL = $a0            ' Set OSCCAL register to $a0

The $a0 is merely an example.  The part would need to be read before it
is erased to obtain the actual OSCCAL value for that particular device.

Please see the Microchip data sheets for more information on OSCCAL.



Additional Case Sensitivity Information

As the PicBasic Pro manual points out, the PicBasic Pro Compiler
itself is not case sensitive.  This means, for example, LOOP: would
be the same label as loop: or even LoOp:.

The assemblers that are launched by PBP, on the other hand, are of
varying degrees of case sensitivity.  The PM Assembler, is also case
insensitive.

MPASM defaults to case sensitive.  Normally this will have no
noticable effect on programs, unless in-line assembly code
is used.  PBP Defines like OSC and the LCD definitions must be in
all upper-case as shown in the examples in the manual.



Additional MPASM Information

MPASM may be used with PBP in two ways.  If the command line option
"-ampasm" is used, MPASM will be launched following compilation to
complete the process.  MPASM will display its own screen with its
progress.

Alternatively, the command line option "-amp" will launch MPASM in
quiet mode and only display any errors.  However, the launcher consumes
additional memory that is therefore not available to MPASM.

For maximum memory availability to MPASM, the command line option
"-ampasm" or "-ampasmwin" should be used.

In any case, MPASM is not included with PBP and must be obtained from
Microchip.



Additional PM Information

PicBasic Pro now uses PM Assembler version 4.00 or later to work with
the 16-bit core PICmicro MCUs.  Do not use an earlier version of PM with
version 2.2 or later of PBP.



Additional Interrupt Information

Interrupts in Pro may be accomplished in two manners: the On Interrupt
BASIC instruction and by using an assembler interrupt routine.  The
On Interrupt instruction may be used with any PICmicro MCU but can add a
fair bit of overhead and potential latency.

Interrupts in assembler need to be treated differently depending on
whether the device has more than 2K of code space or not.  If the device
has 2K of code space or less, registers the interrupt handler uses may be
save and restored in the handler and the interrupt handler may appear
anywhere in the program.

If the device has more than 2K of code space, however, PCLATH must be
set before jumping to the interrupt handler.  This is because PCLATH
may be pointing to a different code page than the interrupt handler is
in, when an interrupt occurs.  Before the PCLATH register can be changed,
its current value, along with the current value of the W and STATUS
registers must be saved. Once this has been accomplished, the interrupt
handler may appear anywhere in the program, as above.

There is a stub in the file PBPPIC14.LIB that will automatically set up
PCLATH before the interrupt handler is jumped to.  However, it needs memory
allocated in the BASIC source file for storing the saved values.  The
following code fragment will allocate this memory.  While the stub
saves these values, your interrupt handler will need to restore them
before exiting.  The stub to save the registers is automatically inserted
for devices with more that 2K of code space.  If the device has 2K or less
of code space, the interrupt handler will need to save, as well as,
restore the registers.

wsave   var     byte $20 system
'wsave1  var     byte $a0 system ' Necessary for devices with RAM in bank1
'wsave2  var     byte $120 system ' Necessary for devices with RAM in bank2
'wsave3  var     byte $1a0 system ' Necessary for devices with RAM in bank3
ssave   var     byte bank0 system
psave   var     byte bank0 system

The interrupt section in the manual has more information on interrupts
in assembler and BASIC.



Reserved Words

As stated in the manual, all of the PicBasic Pro commands are reserved
and may not be used as a program variable or label.  Count is an
example of this.  Since Count is a PicBasic Pro command, it may not be
used as a variable or label.  Additionally, the names of the PICmicro MCU
registers listed in the file PIC1*EXT.BAS are also predefined and
may not be defined again as something else.  Also reserved are the
system variables listed in PBPPIC1*.RAM.  On and Off are also reserved
and may not be used as program variables or labels.  If BS1DEFS.BAS,
BS2DEFS.BAS or MODEDEFS.BAS are included in the program, all of
their contents are now defined and cannot be redefined.



PicStic Information

Micromint PicStic users must tell PBP which PicStic is the target so
that it can include the proper library.  The command line option "-p"
should be followed by the name of the PicStic:

        pbp -pps1 filename
        pbp -pps2 filename
        pbp -pps3 filename
        pbp -pps4 filename

These files specify PIC16F84A as the device.  A particular PicStic
may contain either a PIC16C84, PIC16F84 or PIC16F84A.

        pbp -pps1_2k filename
        pbp -pps2_2k filename
        pbp -pps3_2k filename
        pbp -pps4_2k filename

These PicStic 2k files specify PIC16F628 as the device.

        pbp -pps5 filename

This PicStic file specifies PIC16F876 as the device.

The PicStic libraries only work with 14-bit core parts, not 12-bit core or
16-bit core PIC17Cxxx and PIC18Xxxx devices.



Temporary Variables

PBP creates temporary variables to store intermediate results of
expressions.  These temporaries are always words and are only created
when necessay.  They can cause unexpected RAM usage.  To see what
variables are used, see the .ASM file created by PBP.

Math operations are generally 16-bit integer operations.  You can
usually mix 8- and 16-bit operands with no ill effects.  PBP will
sort things out and usually give you the result you are looking for.
However, certain situations can create problems.

As an example, consider the following two code fragments:

Listing 1:
addr    var     byte

        addr = 10
        I2CWrite 0,1,$a0,addr,[addr * 2]


Listing 2:
addr    var     byte
store   var     byte

        addr = 10
        store = addr * 2
        I2CWrite 0,1,$a0,addr,[store]


These two listing seem as if they should yield the same result.
But because of the 16-bit expression handling and word-sized temporary
variables, they will do two different things.

The program in Listing 2 will write the byte store (which is address * 2
or 20) to I2C address 10.

The program in Listing 1 looks like it will do the same thing but in
reality, it won't.  Instead of writing a single byte 20 to I2C address 10,
it will write a word 20 (two consecutive bytes, 0 then 20).  This is
because the result of the mathematical expression is a word.

This problem does not affect very many commands, but it is safer
to create your own intermediate variables of the desired size as in
Listing 2, rather than to let PBP make all the decisions for you.



Current PICmicro MCU support:

12C508(A), 12C509(A), 12CE518, 12CE519: Limited support.

12C671, 12C672, 12CE673, 12CE674, 12F629, 12F675: Supported.

14C000: Supported.

16C432, 16C433: Supported.

16C505, 16C54(AC), 16C55(A), 16C56(A), 16C57(C), 16C58(B), 16HV540: Limited
support.

16C554, 16C558, 16C61, 16C62(AB), 16C620(A), 16C621(A), 16C622(A), 16C63(A),
16C64(A), 16C642, 16C65(AB), 16C66, 16C662, 16C67, 16C71, 16C710, 16C711,
16C712, 16C715, 16C716, 16C717, 16C72(A), 16C73(AB), 16C74(AB), 16C745,
16C76, 16C765, 16C77, 16C770, 16C771, 16C773, 16C774, 16C781, 16C782, 16C84,
16C923, 16C924, 16C925, 16C926, 16CE623, 16CE624, 16CE625, 16F627, 16F628,
16F72, 16F73, 16F74, 16F76, 16F77, 16F83, 16F84(A), 16F870, 16F871, 16F872,
16F873(A), 16F874(A), 16F876(A), 16F877(A): Supported.

17C42A, 17C43, 17C44, 17C752, 17C756(A), 17C762, 17C766: Supported.

18C242, 18C442, 18C252, 18C452, 18C601, 18C658, 18C801, 18C858, 18F242,
18F248, 18F252, 18F258, 18F442, 18F448, 18F452, 18F458, 18F6620, 18F6720,
18F8620, 18F8720:
Supported.

PicStic1, PicStic2, PicStic3, PicStic4, PicStic5, PicStic1 2k, PicStic2 2k,
PicStic3 2k, PicStic4 2k: Supported.


microEngineering Labs, Inc.
Box 60039
Colorado Springs CO 80960-0039
USA
(719) 520-5323
(719) 520-1867 fax
http://www.melabs.com
email:support@melabs.com
