GCBASIC documentation
Compiler Directives

Syntax:

    #chip model, frequency

    #chip model, frequency / numeric constant

Explanation:

The #chip directive is used to specify the chip model and frequency that GCBASIC will use.

The model is the specific microcontroller - an example is "16F819".

The frequency is the frequency of the chip in MHz, and is required for the delay and PWM routines. The following constants simplify setting specific frequencies: 31k, 32.768K, 125k, 250k, or 500k. Any of these constants can be used, as shown in the example below.

If frequency is not present, the compiler will select a default frequency that should work for the microcontroller.

If numeric constant is specified, then the compiler will complete a simple maths calculation to determine the frequency. The only supported maths operation is divide.

When using an AVR:

When using an LGT:

Examples:

    #chip 12F509, 4
    #chip 18F4550, 48
    #chip 16F88, 0.125
    #chip tiny2313, 1
    #chip mega8, 16
    #chip 12f1840, 31k
    #chip 12f1840, 500k
    #chip 12f1840, 250k
    #chip 12f1840, 125k

    #chip lgt8x328p, 4
    #chip tiny3127, 16 / 48

    'Select the internal low frequency oscillator. The microcontroller must have a low frequency oscillator option.  The internal oscillator is automatically selected on PIC.
    #chip 16f18326, 31k

    'Select the external SOSC clock source.
    #chip 16f18855, 32.768k
    #config osc=SOSC

Setting Other Clock Frequencies: Some alternative compilers allow the value of the clock frequency to be set with a numerical value in Hertz (i.e. 24576000). This can be useful when using clock frequencies other than the standard frequencies.

GCBASIC requires clock frequencies to be specified in MHz, but will accept decimal points. For example, if you wanted to run a 16F1827 at 24576000 Hz, you would write the following:

    #chip 16F1827, 24.576

GCBASIC support for microcontrollers:

Each microcontroller has a microcontroller data file. This file is located in the \GCBasic\chipdata\ folder when installed.

An example is 12F1840.dat.

There are two sections in the microcontroller data file that control the "chip frequency": they are

*[ChipData]* and *[ConfigOps]*

ChipData section

The ChipData section for the 12F1840 microcontroller. The 12F1840 is used as an example.

    [ChipData]
    Prog=4096
    EEPROM=256
    RAM=256
    I/O=6
    ADC=4
    MaxMHz=32
    IntOsc=32, 16, 8, 4, 2, 1, 0.5, 0.25, 0.125
    31kSupport=INTOSC,OSCCON,2
    Pins=8
    Family=15
    ConfigWords=2
    PSP=0
    MaxAddress=4095

The IntOsc line specifies the supported internal clock frequencies - the 12F1840 microcontroller supports nine internal frequencies (ChipMHz). #chip is used as follows: The 31kSupport line specifies that the chip supports 31k as an internal clock frequency.

    #chip 12F1840, 32

A ChipMHz of 32 does two things.

If you set ChipMHz to something other than the valid options in the [ChipData] IntOsc section of the microcontroller-specific dat file, then the compiler assumes that you are using an external oscillator and will calculate the delays according to the value you use. The wait times will be incorrect if you are not using an external oscillator at the same frequency as ChipMHz.

    Example:  #chip 12F1840, 12

Since "12" is not a valid internal oscillator frequency, the microcontroller FOSC will default to 8 MHz, because there is no external crystal installed. However, the wait times will be incorrect, as they will be calculated by the compiler based upon a 12 MHz clock.

ConfigOps section

The [ConfigOps] section of 12F1840.dat is towards the end of the chip data file. For the 12F1840 it looks like this:

    [ConfigOps]
    OSC=LP,XT,HS,EXTRC,INTOSC,ECL,ECM,ECH
    WDTE=OFF,SWDTEN,NSLEEP,ON
    PWRTE=ON,OFF
    MCLRE=OFF,ON
    CP=ON,OFF
    CPD=ON,OFF
    BOREN=OFF,SBODEN,NSLEEP,ON
    CLKOUTEN=ON,OFF
    IESO=OFF,ON
    FCMEN=OFF,ON
    WRT=ALL,HALF,BOOT,OFF
    PLLEN=OFF,ON
    STVREN=OFF,ON
    BORV=HI,LO,19
    LVP=OFF,ON

OSC specifies which oscillator options are available for the specific microcontroller. INTOSC is the internal oscillator. All others are some form of external clock source. PLLEN sets the internal Phase Lock Loop either on or off. With this chip the default clock frequency is 8 MHz. The PLL multiplies this by 4. So to get 32 MHz the basic internal oscillator will be 8 MHz, then multiplied by 4. For 16 MHz it will be 4 MHz, multiplied by 4.

GCB sets the PLL automatically, so this option should generally be left alone. If PLLEN is set to ON, then GCB may not be able to set the correct frequency of the internal oscillator. Only set PLL = ON if you know what you are doing.

It is good practice to set the oscillator source in #config at the beginning of your code when you are not using the internal oscillator. This prevents potential errors. Example:

    #Chip 12F1840, 16
    #Config OSC = INTOSC   'This is normally not required as the internal oscillator is the default oscillator.

In the example above, GCBASIC will automatically set the necessary OSC bits for the microcontroller. Frequency bits will be set to 4 MHz, and the PLL will be turned on, and wait times will be calculated on an FOSC of 16 MHz.

You can set the clock to other frequencies, but you have to put the PIC into EC, or External Clock, mode and then supply that specific clock frequency to the OSC1 pin.

There are three EC modes on the PIC12F1840:

    ECL - 0 MHz - 0.5 MHz
    ECM - 0.5 MHz - 4 MHz
    ECH = 4 MHz - 32MHz

Example: For a 2.1 MHz clock, you would need to set the #config and the clock frequency, and provide the OSC1 pin with a 2.1 MHz signal.

    #chip 12f1840,2.1
    #config OSC = ECM

Notes

When "#config osc=" is not specified in the source code, most microcontrollers will default to an external oscillator source. This means that at runtime the chip is expecting an external clock signal. If the external clock signal is not present, the chip detects a "failure" of the external clock and falls back to the default internal oscillator setting.

The PLLEN bit defaults to OFF. The PLL is enabled depending upon the ChipMHz in #chip xxxxxx, ChipMHz.

The GCBASIC defaults - this is how the bits are set if there is no #config in the source code; GCBASIC does set certain bits. To examine what bits are set on a particular chip, you can omit #config in the source code, then compile the code and use "Open ASM" in the GCBASIC IDE. The bits that are set will be in the config section. All other bits (those not specifically set with #Config) will be at the POR setting as described below. The POR settings are shown in the datasheet for each microcontroller.

Currently, GCBASIC sets the LVP bit OFF by default on many chips. This does not affect normal HV programming, like with a PicKit3. The default of LVP = OFF will prevent the microcontroller from being programmed with a Low Voltage Programmer. This means that if a PIC microcontroller has previously been programmed with LVP = OFF, then it must be erased or reprogrammed with LVP = ON, using an HVP programmer, prior to using certain programming devices, e.g. Curiosity development boards, or "NS" programmers, as these require LVP = ON.

When LVP = ON, the MCLR pin is automatically set to EXTERNAL MCLR. This means that the MCLRE pin CANNOT be used for general purpose I/O functions.

The native POR (Power On Reset) defaults are the state of the config bits after power-on if the ASM code has no configuration entries, or on a blank factory chip. The only way to power up in this state with GCB code is to use #option NoConfig in the GCBASIC source code.

See Also: