5.2.4 Configuration Bit Access

The config pragma allows the configuration bits (or fuses) and ID-location registers to be specified in the assembly source file. Configuration bits, or fuses, are used to set up fundamental device operation, such as the oscillator mode, watchdog timer, programming mode and code protection. These bits must be correctly set to ensure your program executes correctly.

The pragma has the following forms:

#pragma config setting = value
#pragma config register = literal_value

Here, setting is a configuration setting descriptor, e.g., WDT, and value can be either a textual description of the desired state, e.g., OFF, or a numerical value. Either the setting or value tokens or the setting = value expression can be surrounded by either double or single quotes to protect them from any macro substitution performed by the preprocessor, for example:

#pragma config "WDT = ON"      // turn on watchdog timer
#pragma config WDTPS = 0x1A    // specify the timer postscale value

Some value tokens that appear to be purely numerical are in fact a textual description of the value, for example in the following:

config WDTPS = 32

the 32 token is a textual description for some devices that indicates a watchdog timer post-scale of 1:32, not the number 32. In such a case, it might not be the number 32 that is programmed into the relevant bits of the configuration register. The assembler will first check if value represents a predefined string, and only if that is not the case, assume it represents a numerical constant, which will then be subject to the same constraints as other numerical constant operands.

You should never assume that the OFF and ON tokens used in configuration macros equate to 0 and 1, respectively, as that is often not the case.

The register field is the name of a configuration or ID-location register, and this must always be used with a value that is a numerical constant, for example:

#pragma config CONFIG1L = 0x8F

The available setting, register and value fields are documented in the chipinfo file relevant to your device (i.e. pic_chipinfo.html and pic18_chipinfo.html) and that are located in the docs directory of your compiler installation. Click the link to your target device and the page will show you the settings and values that are appropriate with this pragma. Configuration registers that are One-Time-Programmable are indicated next to the register's name in these files. Review your device data sheet for more information.

One config pragma can be used to set each configuration setting; alternatively, several comma-separated configuration settings can be specified by the same pragma. The pragma can be used as many times as required to fully configure the device.

The following example shows a configuration register being programmed as a whole and programmed using the individual settings contained within that register.

// PIC18F67K22
// VREG Sleep Enable bit : Enabled
// LF-INTOSC Low-power Enable bit : LF-INTOSC in High-power mode during Sleep
// SOSC Power Selection and mode Configuration bits : High Power SOSC circuit selected
// Extended Instruction Set : Enabled
#pragma config RETEN = ON, INTOSCSEL = HIGH, SOSCSEL = HIGH, XINST = ON

// Alternatively
#pragma config CONFIG1L = 0x5D

// IDLOC @ 0x200000
#pragma config IDLOC0 = 0x15

The config pragmas do not produce executable code and ideally, they should be placed outside function definitions. Avoid placing these pragmas in library archives, as they do not define symbols and hence will not normally be linked into the application. It is recommended that these pragmas be placed in one C source file. Be mindful when merging bootloader and application projects that these pragmas should be defined by only one of these projects.

All the bits in the Configuration Words should be programmed to prevent erratic program behavior. Do not leave them in their default/unprogrammed state. Not all Configuration bits have a default state of logic high; some have a logic low default state. Consult your device data sheet for more information.

If you are using MPLAB X IDE, take advantage of its built-in tools to generate the required pragmas, so that you can copy and paste them into your source code. See the MPLAB® X IDE User’s Guide for a description and use of the Configuration Bits window.