device/p18xxxxx.h

The device directory contains an header file for each flavor of PIC18 device. #include one of these files when you need to access a register of the the target device (eg: #include <device/p18f2525.h>). Since version V0.7.0, the device headers contain various definitions that allow to access each bit of registers using a symbolic identifier. These identifiers can be found in Microchip's datasheets.

Each bit (or bit field) can be accessed using the standard syntax (based on structures) or using the explicit bit field syntax (that is specific to cpik). The following example illustrates how the devices' registers are declared.

// ======================================
//         PROCESSOR : p18f2525
// ======================================

// This file has been automatically generated from Microchip's "p18f2525.inc" file.
// with the inc2h-v3 utility.             Please do not edit.
// Do not use with cpik versions < V0.7. Please report problems to the author.
// (C) Alain Gibaud  2012-2013    (alain.gibaud@free.fr)

// Note; All SFRs are reachable via access bank
#pragma firstsfr 0xf80
// ... 
// ...
// ------------------------------
//        T3CON
// ------------------------------
unsigned int T3CON@0xfb1 ;
union
{

struct 
{
  unsigned int 
  TMR3ON : 1 ,
  TMR3CS : 1 ,
  NOT_T3SYNC : 1 ,
  T3CCP1 : 1 ,
  T3CKPS0 : 1 ,
  T3CKPS1 : 1 ,
  T3CCP2 : 1 ,
  RD16 : 1 ;
} ; 

struct 
{
  unsigned int 
  : 2,
  T3SYNC : 1 ;
} ; 

// The following are aliases ..  
struct 
{
  unsigned int 
  : 4,
  _T3CKPS : 2 ;
} ; 

} T3CONbits@0xfb1  ;

#define _TMR3ON 0
#define _TMR3CS 1
#define _NOT_T3SYNC 2
#define _T3CCP1 3
#define _T3CKPS0 4
#define _T3CKPS1 5
#define _T3CCP2 6
#define _RD16 7

#define _T3SYNC 2

// The following are aliases ..  
#define __T3CKPS 4:2

In this example, the T3CON register contains both individual bits, and a group of 2 bits (T3CKPS0 and T3CKPS1), which can be manipulated as a bit field. Thus, the following codes are equivalent because the _T3CKPS member name is an alias for the T3CKPS0/T3CKPS1 group of bits.

T3CONbits.T3CKPS0 = 0 ;  T3CONbits.T3CKPS1 = 1 ; // method 1 : individual bits
T3CONbits._T3CKPS = 0b10 ;                       // method 2 : bit field

Moreover, macros are also provided to use the explicit bit field syntax (see section 10.12.8). These macros have the same name that the classic member names, with a «_» prefix:

T3CON._T3CKPS0 = 0 ;  T3CON._T3CKPS1 = 1 ; // method 1 : individual bits
T3CON.__T3CKPS = 0b10 ;                    // method 2 : bit field

Notice that the names T3CKPS0, T3CKPS1, etc have been choosen to be compatible with the member names used by Microchip, but obviously, they sound like macro names, despite the fact they are not. On the other hand, the identifiers such as _T3CKPS0, etc. correspond to genuine macros.

AG 2013-04-10