1.2 PIC1000 Getting Started Writing C-code for PIC16 and PIC18

Registers are divided into Control (CON), Status (STA) and Data registers with their naming reflecting this. A general purpose control register of a module has the control identifier named CON. If multiple general purpose control registers exist in a module, they have a suffix number identifier. In this case, the control registers will be named CON0, CON1, CON2 and so on. For example, see ADCON0, ADCON1, ADCON2 and ADCON3 registers in Figure 1-3.

When there are multiple instances of the same peripheral in a device, the name of the peripheral control registers will be depicted as the concatenation of the peripheral identifier, the peripheral instance number and the control identifier. Therefore, all the register names of PIC microcontrollers are unique. For example, in Figure 1-4, observe the RC2STA (Receive Status and Control Register) for EUSART peripheral instance 2.

For registers that have a specific function, their name reflects this functionality. For example, BAUD2CON is the Baud Rate Control Register for the second instance of the EUSART peripheral.

Since the PIC data bus width is 8 bits, larger registers are implemented using several 8-bit registers. For a 16-bit register, the high and low bytes are accessed by appending ‘H’ and ‘L’ respectively to the register name. For example, the ADC Result Register is named ADRES and the two bytes are ADRESL and ADRESH.

After the Register Summary section in the device data sheet, each register has a Register Definition section, which fully describes the functionality of each bit and bit field in the register. The Register Definitions section shows one instance of all the register names with an ‘x’ in place of the peripheral instance number. An example is presented in Figure 1-5.

Since the prefix for the peripheral module type is unique, each bit name described in the data sheet is unique.

The device header file offers some register bits a Short Bit Name alternative consisting of only the bit function abbreviation. Since this is defined in the context of a bit union for a specific register, the bit access remains unique. For further details on how to access a bit using the short or long naming convention, refer to 2.1.1 Register Unions.

Each register has a union declared in the header file for the individual bits in that register. This allows access to an individual bit/bit field from the register using the union declaration.

typedef union {
    struct {
        unsigned ADGO                   :1;
        unsigned                        :1;
        unsigned ADFM                   :1;
        unsigned                        :1;
        unsigned ADCS                   :1;
        unsigned                        :1;
        unsigned ADCONT                 :1;
        unsigned ADON                   :1;
    };
    struct {
        unsigned GO                     :1;
        unsigned                        :1;
        unsigned ADFM0                  :1;
    };
} ADCON0bits_t;
extern volatile ADCON0bits_t ADCON0bits __at(0xF5B);

The union declaration of the ADCON0 register is shown in the code listing above. This register can be accessed as a whole using the macro declaration or as an individual bit/bit field from the register using the union declaration. Here is an example:

ADCON0 = 0x01;       /* using macro declaration */
ADCON0bits.GO = 1;   /* using bit unions with short bit name convention */
ADCON0bits.ADGO = 1; /* using bit unions with long bit name convention */

The convention used when accessing a bit or a bit field from a register using the union declaration of register is presented in Figure 2-1.

For further details on unions, consult Microchip Developer - Unions.

Some registers are used in conjunction with other registers to represent 16-bit values. These registers can be accessed as a whole using the register macro or by accessing the low/high bytes using the ‘L’/’H’ suffixes attached to the register macro. For example, the 16-bit ADC Result register has the following declaration in the header file:

#define ADRES ADRES
extern volatile unsigned short          ADRES               __at(0xF5E);
#define ADRESL ADRESL
extern volatile unsigned char           ADRESL              __at(0xF5E);
#define ADRESH ADRESH
extern volatile unsigned char           ADRESH              __at(0xF5F);

The bit masks are predefined in the device header file. For example, the bit mask for the ADPSIS bit is defined as below.

#define _ADCON2_ADPSIS_MASK                                 0x80

The naming convention adopted for the predefined bit masks in the header file is presented in Figure 2-2 with an example for the ADPSIS bit in the ADCON2 register.

Many functions are controlled by a bit field. For example, ADCRS[2:0] and ADMD[2:0] in the ADCON2 register are grouped bits. The value of the bits in a field selects a specific configuration.

When changing bits in a bit field, it is not enough to set the bits for the desired configuration. It is also required to clear the bits from the old configuration before assigning a new value. To facilitate this, a bit field mask is defined.

The field masks are predefined in the device header file. For example, the field mask for the ADMD bit field is defined below.

#define _ADCON2_ADMD_MASK                                   0x7

The naming convention adopted for the predefined bit field masks in the header file is presented in the Figure 2-3 with an example for the ADMD bit field in the ADCON2 register.

The bits from a bit field can be accessed as individual bits. To differentiate between these bits, a suffix (index of each bit in the bit field) is appended to the bit field name. The masks for the bits in a bit field are defined below.

#define _ADCON2_ADMD0_MASK                                  0x1
#define _ADCON2_ADMD1_MASK                                  0x2
#define _ADCON2_ADMD2_MASK                                  0x4

For further details on bit fields, consult Microchip Developer - Bit Fields.

The recommended coding style to set or clear a specific bit in a register is to use the union declaration of the register from the header file.

The example below shows how to set and clear the Enable bit from the ADCON0 register using the recommended coding style.

ADCON0bits.ADON = 1; /* the ADC Enable bit is set */
ADCON0bits.ADON = 0; /* the ADC Enable bit is cleared */

/* wait while the ADGO bit is set */
while(ADCON0bits.ADGO) 
{
    /* wait */
}

The code listing below shows how to read the value of a PORT pin using bit unions and execute a set of instructions if that pin is low.

/* if pin 0 of the PORTA is clear execute a set of instructions */
if(!PORTAbits.RA0)
{
    /* set of instructions */
}

There are alternative ways to set and clear register bits by using bit masks or bit positions.

In order to set a bit from a register using bit masks, the binary OR operator will be applied between the register and the bit mask. Using the binary OR operator will ensure that the other bit settings made inside the register will remain the same and unaffected by this operation.

ADCON0 |= _ADCON0_ADON_MASK; /* the ADC Enable bit is set */

In order to clear a bit from a register using bit masks, the binary AND operator will be applied between the register and the negated value of the bit mask. This operation also keeps the other bit settings unchanged.

ADCON0 &= ~_ADCON0_ADON_MASK; /* the ADC Enable bit is cleared */

The bit mask for the ADC Enable bit (ADON) has the following declaration in the header file.

#define _ADCON0_ADON_MASK                                   0x80

The code listing below shows how to read the value of a PORT pin using bit masks and execute a set of instructions if that pin is low.

if(PORTA & _PORTA_RA0_MASK)
{
    /* set of instructions */
}

In order to set a bit from a register using bit positions, the binary OR operator will be applied between the register and the value resulting from shifting ‘1’ with the value of the bit position. To clear a bit using bit positions the binary AND operator is used with the negated value of the shifting result.

ADCON0 |= (1 << _ADCON0_ADON_POSITION);  /* the ADC Enable bit is set */
ADCON0 &= ~(1 << _ADCON0_ADON_POSITION); /* the ADC Enable bit is cleared */

#define _ADCON0_ADON_POSITION                               0x7

The code listing below shows how to read the value of a PORT pin using bit positions and execute a set of instructions if that pin is low.

if(PORTA & (1<< _PORTA_RA0_POSITION))
{
    /* set of instructions */
}

Register initialization using bit and bit field unions will always need to be done in several lines of code, if configuring more than one bit or bit field.

The example below shows the recommended way of initializing a register, by using the union declaration of the register from the header file.

T0CON0bits.T0EN = 1;      /* Enable TMR0 */
T0CON0bits.T016BIT = 0;   /* Select 8-bit operation mode */
T0CON0bits.T0OUTPS = 0x9; /* Select 1:10 postscaler */

Read-modify-write operations are not needed, when working with bit masks or bit positions, if the reset value of the register is 0x00 and the register configures in a single line.

The example below shows how to achieve the same configuration using bit masks.

T0CON0 = _T0CON0_T0EN_MASK      /* Enable TMR0 */
       | _T0CON0_T0OUTPS0_MASK  /* Select 1:10 postscaler */
       | _T0CON0_T0OUTPS3_MASK; /* 8-bit operation mode selected by default */
             			

/* incorrect initialization of the T0CON0 register */
T0CON0 = _T0CON0_T0EN_MASK;
T0CON0 = _T0CON0_T0OUTPS0_MASK;
T0CON0 = _T0CON0_T0OUTPS3_MASK;

In this example, no mask is used to explicitly configure the timer in the 8-bit mode. This is possible because the reset value of the T016BIT is '0' which corresponds to the 8-bit mode. To emphasize the configuration of this bit as 0, the user could explicitly select the desired 8-bit mode by using a read-modify-write operation. However, this would need to be a separate line of code and would leave the register unchanged:

T0CON0 = _T0CON0_T0EN_MASK       /* Enable TMR0 */
       | _T0CON0_T0OUTPS0_MASK   /* Select 1:10 postscaler */
       | _T0CON0_T0OUTPS3_MASK;  
T0CON0 &= ~_T0CON0_T016BIT_MASK; /* Select 8-bit operation mode explicitly */

Read-modify-write operations are not needed, when working with bit masks or bit positions, if the reset value of the register is '0' and the register configures in a single line.

The code listing below shows how to initialize a register using bit positions.

T0CON0 = (1 << _T0CON0_T0EN_POSITION)      /* Enable TMR0 */
       | (0 << _T0CON0_T016BIT_POSITION)   /* A placeholder to select 16-bit mode*/
       | (1 << _T0CON0_T0OUTPS0_POSITION)
       | (1 << _T0CON0_T0OUTPS3_POSITION); /* Select 1:10 postscaler */

This section covers considerations when updating a register bit field using various header file defines. The following bit field will be used as an example, where an update is needed, compared to the initialization configuration covered in 3.2. Register Initialization section.

The union declaration of the registers offers access to register bits and bit fields without affecting the rest of the register.

/* using a hex value */
T0CON0bits.T0OUTPS = 0x7;     /* Select 1:10 postscaler */
/* using a binary value */
T0CON0bits.T0OUTPS = 0b0111;  /* Select 1:10 postscaler */

This is the recommended way of updating bit field register configurations, which is simpler than the alternative options.

When updating only a bit field in a register, a read-modify-write must be used, to keep the other settings unaffected. Therefore, in order to change the configuration of a register bit field, it is recommended to first clear the bit field and then set a new configuration. However, in order to avoid putting the register in an unintended state between the clear and setting the new configuration, this should be done in a single line of code. For simplicity, the steps are first covered individually.

The bit field masks can be used to clear a bit field before assigning a new configuration. In the example, the T0OUTPS bit field mask is used to clear bit field.

/* The T0OUTPS bit field is cleared (Selecting a postscaler of 1:1 (T0OUTPS = 0)) */
T0CON0 &= ~_T0CON0_T0OUTPS_MASK; 
/* Selecting new configuration (0b0111) of the T0OUTPS bit field */
T0CON0 |= _T0CON0_T0OUTPS2_MASK | _T0CON0_T0OUTPS1_MASK | _T0CON0_T0OUTPS0_MASK;  

The bit field mask for the TMR0 Output Postscaler Select (T0OUTPS) has the following declaration in the header file.

#define _T0CON0_T0OUTPS_MASK                               0xF

These steps must be implemented in a single line to avoid putting the microcontroller in an unintended state.

T0CON0 = (T0CON0 & ~_T0CON0_T0OUTPS_MASK) | _T0CON0_T0OUTPS2_MASK 
                                          | _T0CON0_T0OUTPS1_MASK 
                                          | _T0CON0_T0OUTPS0_MASK;

The example below shows how to update a register bit field using bit positions to set the new configuration. Similar to the process of updating a register configuration using bit masks, the current configuration must be cleared and the new configuration set, in a single line of code.

/* Changing a bit field configuration with bit positions */
T0CON0 = (T0CON0 & ~_T0CON0_T0OUTPS_MASK) | (0 << _T0CON0_T0OUTPS3_POSITION)
                                          | (1 << _T0CON0_T0OUTPS2_POSITION)
                                          | (1 << _T0CON0_T0OUTPS1_POSITION)
                                          | (1 << _T0CON0_T0OUTPS0_POSITION);

T0CON0 = (T0CON0 & ~_T0CON0_T0OUTPS_MASK) | (1 << _T0CON0_T0OUTPS2_POSITION)
                                          | (1 << _T0CON0_T0OUTPS1_POSITION)
                                          | (1 << _T0CON0_T0OUTPS0_POSITION);

To configure the device using MPLAB X Integrated Development Environment (IDE), the user must use configuration pragmas. More information about the compiler and the configuration bits of the desired device can be found by accessing the Compiler Help, the blue question mark from the MPLAB X IDE project dashboard, as presented in the figure below.

Example configurations can be found for specific devices under the Configuration Settings Reference section. An example for the PIC16F18446 is shown below.

The easiest way to complete the pragmas that are required to configure the device is to use the Configuration Bits Window, a feature of MPLAB X IDE.

Follow these steps to get the information to complete the pragmas:

• Open the Configuration Bits Window (Window > Target Memory Views > Configuration Bits or Production > Set Configuration Bits).
• Review every setting in the Configuration Bits Window.
• Generate the pragma derivatives that implement the chosen settings by clicking the Generate Source Code to Output button.
• Copy the generated code from this window to a source file.