PCWH IDE COMPILER - CUSTOM COMPUTER SERVICES

CCS C Compiler Manual

PCB, PCM & PCH

September 2013

Table of Contents

Overview .................................................................................................................................... 1

PCB, PCM and PCH Overview ............................................................................................... 1

Installation .............................................................................................................................. 1

Technical Support .................................................................................................................. 2

Directories .............................................................................................................................. 2

File Formats ........................................................................................................................... 3

Invoking the Command Line Compiler .................................................................................... 4

PCW Overview ....................................................................................................................... 6

Menu ...................................................................................................................................... 7

Editor Tabs ............................................................................................................................. 7

Slide Out Windows ................................................................................................................. 7

Editor ...................................................................................................................................... 7

Debugging Windows ............................................................................................................... 7

Status Bar .............................................................................................................................. 7

Output Messages ................................................................................................................... 7

Program Syntax ......................................................................................................................... 9

Overall Structure .................................................................................................................... 9

Comment ................................................................................................................................ 9

Trigraph Sequences ..............................................................................................................10

Multiple Project Files .............................................................................................................11

Multiple Compilation Units .....................................................................................................11

Example ................................................................................................................................12

Statements ................................................................................................................................13

if ............................................................................................................................................13

while ......................................................................................................................................14

do-while .................................................................................................................................14

for ..........................................................................................................................................14

switch ....................................................................................................................................15

return .....................................................................................................................................15

goto .......................................................................................................................................16

label ......................................................................................................................................16

break .....................................................................................................................................16

continue .................................................................................................................................17

expr .......................................................................................................................................17

; .............................................................................................................................................17

stmt .......................................................................................................................................17

Expressions ..............................................................................................................................18

Operators ..............................................................................................................................18

Operator Precedence ............................................................................................................19

Reference Parameters ..........................................................................................................20

Variable Argument Lists ........................................................................................................20

Default Parameters................................................................................................................21

Overloaded Functions ...........................................................................................................21

Data Definitions .........................................................................................................................23

Basic and Special types ........................................................................................................23

Declarations ..........................................................................................................................26

Non-RAM Data Definitions .....................................................................................................26

Using Program Memory for Data ...........................................................................................28

iii

Function Definition .................................................................................................................30

Functional Overview..................................................................................................................31

I2C ........................................................................................................................................31

ADC ......................................................................................................................................32

Analog Comparator ...............................................................................................................33

CAN Bus ...............................................................................................................................34

CCP1 ....................................................................................................................................36

CCP2, CCP3, CCP4, CCP5, CCP6 .......................................................................................37

Code Profile...........................................................................................................................37

Configuration Memory ...........................................................................................................38

DAC ......................................................................................................................................39

Data Eeprom .........................................................................................................................40

Data Signal Modulator ...........................................................................................................41

External Memory ...................................................................................................................42

General Purpose I/O ..............................................................................................................42

Internal LCD ..........................................................................................................................43

Internal Oscillator ..................................................................................................................44

Interrupts ...............................................................................................................................45

Low Voltage Detect ...............................................................................................................46

PMP/EPMP ...........................................................................................................................47

Power PWM ..........................................................................................................................48

Program Eeprom ...................................................................................................................50

PSP .......................................................................................................................................52

QEI ........................................................................................................................................53

RS232 I/O .............................................................................................................................54

RTOS ....................................................................................................................................56

SPI ........................................................................................................................................58

Timer0 ...................................................................................................................................59

Timer1 ...................................................................................................................................60

Timer2 ...................................................................................................................................61

Timer3 ...................................................................................................................................61

Timer4 ...................................................................................................................................61

Timer5 ...................................................................................................................................62

TimerA ...................................................................................................................................63

TimerB ...................................................................................................................................64

USB .......................................................................................................................................65

Voltage Reference .................................................................................................................68

WDT or Watch Dog Timer .....................................................................................................69

interrupt_enabled() ................................................................................................................70

Stream I/O .............................................................................................................................70

Pre-Processor ...........................................................................................................................73

PRE-PROCESSOR ...............................................................................................................73

_attribute_x ...........................................................................................................................75

#ASM #ENDASM ..................................................................................................................76

#BIT ......................................................................................................................................86

#BUILD ..................................................................................................................................87

#BYTE ...................................................................................................................................88

#CASE ..................................................................................................................................89

_DATE_ .................................................................................................................................89

#DEFINE ...............................................................................................................................90

#DEFINEDINC ......................................................................................................................91

#DEVICE ...............................................................................................................................92

_DEVICE_ .............................................................................................................................94

#ERROR ...............................................................................................................................95

#EXPORT (options) ...............................................................................................................95

__FILENAME__ ....................................................................................................................97

#FILL_ROM ...........................................................................................................................97

#FUSES ................................................................................................................................98

#HEXCOMMENT ..................................................................................................................99

#ID ........................................................................................................................................99

#IF exp #ELSE #ELIF #ENDIF ............................................................................................ 100

#IFDEF #IFNDEF #ELSE #ELIF #ENDIF ............................................................................ 101

#IGNORE_WARNINGS ....................................................................................................... 102

#IMPORT (options).............................................................................................................. 103

#INCLUDE .......................................................................................................................... 104

#INLINE ............................................................................................................................... 105

#INT_xxxx ........................................................................................................................... 105

#INT_DEFAULT .................................................................................................................. 109

#INT_GLOBAL .................................................................................................................... 109

__LINE__ ............................................................................................................................ 110

#LIST .................................................................................................................................. 110

#LINE .................................................................................................................................. 111

#LOCATE ............................................................................................................................ 111

#MODULE ........................................................................................................................... 112

#NOLIST ............................................................................................................................. 113

#OCS .................................................................................................................................. 113

#OPT ................................................................................................................................... 114

#ORG .................................................................................................................................. 114

#PIN_SELECT .................................................................................................................... 116

__PCB__ ............................................................................................................................. 118

__ PCM __ .......................................................................................................................... 119

__ PCH __ ........................................................................................................................... 119

#PRAGMA ........................................................................................................................... 120

#PRIORITY ......................................................................................................................... 120

#PROFILE ........................................................................................................................... 121

#RESERVE ......................................................................................................................... 122

#ROM .................................................................................................................................. 123

#SEPARATE ....................................................................................................................... 124

#SERIALIZE ........................................................................................................................ 125

#TASK ................................................................................................................................. 127

__ TIME __ .......................................................................................................................... 128

#TYPE ................................................................................................................................. 128

#UNDEF .............................................................................................................................. 130

#USE CAPTURE ................................................................................................................. 131

#USE DELAY ...................................................................................................................... 132

#USE DYNAMIC_MEMORY ................................................................................................ 133

#USE FAST_IO ................................................................................................................... 134

#USE FIXED_IO .................................................................................................................. 134

#USE I2C ............................................................................................................................ 135

#USE PROFILE() ................................................................................................................ 136

#USE PWM ......................................................................................................................... 137

#USE RS232 ...................................................................................................................... 138

#USE RTOS ....................................................................................................................... 142

#USE SPI ............................................................................................................................ 143

#USE STANDARD_IO ......................................................................................................... 145

#USE TIMER ....................................................................................................................... 145

#USE TOUCHPAD .............................................................................................................. 147

#WARNING ......................................................................................................................... 148

#WORD ............................................................................................................................... 149

#ZERO_RAM ...................................................................................................................... 150

Built-in Functions .................................................................................................................... 151

BUILT-IN FUNCTIONS ........................................................................................................ 151

abs( ) ................................................................................................................................... 157

sin( ) cos( ) tan( ) asin( ) acos() atan() sinh() cosh() tanh() atan2() ...................................... 157

adc_done( ) ......................................................................................................................... 158

assert( ) ............................................................................................................................... 159

atoe ..................................................................................................................................... 160

atof( ) ................................................................................................................................... 161

pin_select() .......................................................................................................................... 161

atoi( ) atol( ) atoi32( ) ........................................................................................................... 162

bit_clear( ) ........................................................................................................................... 163

bit_set( ) .............................................................................................................................. 164

bit_test( ) ............................................................................................................................. 164

brownout_enable( ).............................................................................................................. 165

bsearch( ) ............................................................................................................................ 165

calloc( ) ................................................................................................................................ 166

ceil( ) ................................................................................................................................... 167

clc1_setup_gate() clc2_setup_gate() clc3_setup_gate() clc4_setup_gate() ......................... 168

clc1_setup_input() clc2_setup_input() clc3_setup_input() clc4_setup_input() ...................... 169

clear_interrupt( ) .................................................................................................................. 170

cwg_status( ) ....................................................................................................................... 170

cwg_restart( ) ...................................................................................................................... 171

dac_write( ) ......................................................................................................................... 171

delay_cycles( ) .................................................................................................................... 172

delay_ms( ) ......................................................................................................................... 173

delay_us( ) .......................................................................................................................... 173

disable_interrupts( ) ............................................................................................................. 175

div( ) ldiv( ) .......................................................................................................................... 176

enable_interrupts( ) ............................................................................................................. 177

erase_eeprom( ) .................................................................................................................. 178

erase_program_eeprom( ) ................................................................................................... 178

exp( ) ................................................................................................................................... 179

ext_int_edge( ) .................................................................................................................... 179

fabs( ) .................................................................................................................................. 180

getc( ) getch( ) getchar( ) fgetc( ) ......................................................................................... 181

gets( ) fgets( ) ...................................................................................................................... 182

floor( ) .................................................................................................................................. 183

fmod( ) ................................................................................................................................. 183

printf( ) fprintf( ) .................................................................................................................... 184

putc( ) putchar( ) fputc( ) ...................................................................................................... 186

puts( ) fputs( ) ...................................................................................................................... 186

free( )................................................................................................................................... 187

frexp( ) ................................................................................................................................. 187

get_capture_event() ............................................................................................................ 188

get_capture_time() .............................................................................................................. 189

get_nco_accumulator( ) ....................................................................................................... 189

get_nco_inc_value( ) ........................................................................................................... 190

get_ticks( ) ........................................................................................................................... 190

get_timerA( )........................................................................................................................ 191

get_timerB( )........................................................................................................................ 191

get_timerx( ) ........................................................................................................................ 192

get_tris_x( ) ......................................................................................................................... 192

getc( ) getch( ) getchar( ) fgetc( ) ......................................................................................... 193

getenv( ) .............................................................................................................................. 194

gets( ) fgets( ) ...................................................................................................................... 198

goto_address( ) ................................................................................................................... 199

high_speed_adc_done( ) ..................................................................................................... 199

i2c_init( ) .............................................................................................................................. 200

i2c_isr_state( ) ..................................................................................................................... 201

i2c_poll( ) ............................................................................................................................. 202

i2c_read( ) ........................................................................................................................... 202

i2c_slaveaddr( ) ................................................................................................................... 203

i2c_speed( )......................................................................................................................... 204

i2c_start( ) ........................................................................................................................... 204

i2c_stop( ) ........................................................................................................................... 205

i2c_write( ) ........................................................................................................................... 206

input( ) ................................................................................................................................. 207

input_change_x( ) ................................................................................................................ 207

input_state( ) ....................................................................................................................... 208

input_x( ) ............................................................................................................................. 209

interrupt_active( ) ................................................................................................................ 209

isalnum(char) isalpha(char) isdigit(char) islower(char) isspace(char) isupper(char)

isxdigit(char) iscntrl(x) isgraph(x) isprint(x) ispunct(x) .......................................................... 210

isamong( ) ........................................................................................................................... 211

itoa( ) ................................................................................................................................... 211

jump_to_isr( ) ...................................................................................................................... 213

kbhit( ) ................................................................................................................................. 213

label_address( ) ................................................................................................................... 214

labs( ) .................................................................................................................................. 215

lcd_contrast( ) ...................................................................................................................... 215

lcd_load( ) ........................................................................................................................... 216

lcd_symbol( ) ....................................................................................................................... 217

ldexp( ) ................................................................................................................................ 217

log( ) .................................................................................................................................... 218

log10( ) ................................................................................................................................ 219

longjmp( ) ............................................................................................................................ 219

make8( ) .............................................................................................................................. 220

make16( ) ............................................................................................................................ 220

make32( ) ............................................................................................................................ 221

malloc( ) .............................................................................................................................. 222

vii

memcpy( ) memmove( ) ...................................................................................................... 222

memset( ) ............................................................................................................................ 223

modf( ) ................................................................................................................................. 224

_mul( ) ................................................................................................................................. 224

nargs( ) ................................................................................................................................ 225

offsetof( ) offsetofbit( ) ......................................................................................................... 226

offsetof( ) offsetofbit( ) ......................................................................................................... 227

output_x( ) ........................................................................................................................... 228

output_bit( ) ......................................................................................................................... 228

output_drive( ) ..................................................................................................................... 229

output_float( ) ...................................................................................................................... 230

output_high( ) ...................................................................................................................... 231

output_low( )........................................................................................................................ 231

output_toggle( ) ................................................................................................................... 232

perror( ) ............................................................................................................................... 233

port_x_pullups ( ) ................................................................................................................. 233

pow( ) pwr( ) ........................................................................................................................ 234

printf( ) fprintf( ) .................................................................................................................... 235

profileout() ........................................................................................................................... 237

psp_output_full( ) psp_input_full( ) psp_overflow( ) ............................................................. 238

putc( ) putchar( ) fputc( ) ...................................................................................................... 238

putc_send( ); ....................................................................................................................... 239

fputc_send( ); ...................................................................................................................... 239

putc( ) putchar( ) fputc( ) ...................................................................................................... 240

puts( ) fputs( ) ...................................................................................................................... 241

pwm_off() ............................................................................................................................ 241

pwm_on() ............................................................................................................................ 242

pwm_set_duty() ................................................................................................................... 242

pwm_set_duty_percent ....................................................................................................... 243

pwm_set_frequency ............................................................................................................ 243

qei_get_count( ) .................................................................................................................. 244

qei_set_count( ) ................................................................................................................... 244

qei_status( )......................................................................................................................... 245

qsort( ) ................................................................................................................................. 245

rand( ).................................................................................................................................. 246

rcv_buffer_bytes( )............................................................................................................... 246

rcv_buffer_full( ) .................................................................................................................. 247

read_adc( ) .......................................................................................................................... 247

read_bank( ) ........................................................................................................................ 249

read_calibration( ) ............................................................................................................... 249

read_configuration_memory( ) ............................................................................................. 250

read_eeprom( ) .................................................................................................................... 251

read_extended_ram( ) ......................................................................................................... 251

read_program_memory( ) .................................................................................................... 252

read_external_memory( ) .................................................................................................... 252

read_high_speed_adc( ) ...................................................................................................... 252

read_program_eeprom( ) .................................................................................................... 254

read_program_memory( ) .................................................................................................... 255

read_external_memory( ) .................................................................................................... 255

realloc( ) .............................................................................................................................. 255

viii

release_io() ......................................................................................................................... 256

reset_cpu( ) ......................................................................................................................... 257

restart_cause( ) ................................................................................................................... 257

restart_wdt( ) ....................................................................................................................... 258

rotate_left( ) ......................................................................................................................... 259

rotate_right( ) ....................................................................................................................... 259

rtc_alarm_read( ) ................................................................................................................. 260

rtc_alarm_write( ) ................................................................................................................ 261

rtc_read( ) ............................................................................................................................ 261

rtc_write( ) ........................................................................................................................... 262

rtos_await( )......................................................................................................................... 262

rtos_disable( ) ...................................................................................................................... 263

rtos_enable( ) ...................................................................................................................... 263

rtos_msg_poll( ) ................................................................................................................... 264

rtos_msg_read( ) ................................................................................................................. 264

rtos_msg_send( ) ................................................................................................................ 265

rtos_overrun( ) ..................................................................................................................... 265

rtos_run( ) ............................................................................................................................ 266

rtos_signal( )........................................................................................................................ 266

rtos_stats( ) ......................................................................................................................... 267

rtos_terminate( ) .................................................................................................................. 268

rtos_wait( ) .......................................................................................................................... 268

rtos_yield( ) ......................................................................................................................... 269

set_adc_channel( ) .............................................................................................................. 269

set_nco_inc_value( ) ........................................................................................................... 270

set_power_pwm_override( ) ................................................................................................ 271

set_power_pwmx_duty( ) .................................................................................................... 271

set_pwm1_duty( ) set_pwm2_duty( ) set_pwm3_duty( ) set_pwm4_duty( )

set_pwm5_duty( ) ................................................................................................................ 272

set_rtcc( ) set_timer0( ) set_timer1( ) set_timer2( ) set_timer3( ) set_timer4( )

set_timer5( ) ........................................................................................................................ 273

set_ticks( ) ........................................................................................................................... 274

set_timerA( ) ........................................................................................................................ 274

set_timerB( ) ........................................................................................................................ 275

set_timerx( ) ........................................................................................................................ 275

set_rtcc( ) set_timer0( ) set_timer1( ) set_timer2( ) set_timer3( ) set_timer4( )

set_timer5( ) ........................................................................................................................ 276

set_tris_x( ) ......................................................................................................................... 277

set_uart_speed( ) ................................................................................................................ 278

setjmp( ) .............................................................................................................................. 278

setup_adc(mode) ................................................................................................................ 279

setup_adc_ports( )............................................................................................................... 279

setup_ccp1( ) setup_ccp2( ) setup_ccp3( ) setup_ccp4( ) setup_ccp5( )

setup_ccp6( ) ....................................................................................................................... 281

setup_clc1() setup_clc2() setup_clc3() setup_clc4() ............................................................ 283

setup_comparator( ) ............................................................................................................ 283

setup_counters( ) ................................................................................................................ 284

setup_cwg( ) ........................................................................................................................ 285

setup_dac( ) ........................................................................................................................ 286

setup_external_memory( ) ................................................................................................... 287

setup_high_speed_adc( ) .................................................................................................... 287

setup_high_speed_adc_pair( ) ............................................................................................ 288

setup_lcd( ) ......................................................................................................................... 289

setup_low_volt_detect( ) ...................................................................................................... 290

setup_nco( ) ........................................................................................................................ 290

setup_opamp1( ) setup_opamp2( ) ...................................................................................... 291

setup_oscillator( ) ................................................................................................................ 292

setup_pmp(option,address_mask) ....................................................................................... 293

setup_power_pwm( ) ........................................................................................................... 293

setup_power_pwm_pins( ) ................................................................................................... 295

setup_psp(option,address_mask) ........................................................................................ 295

setup_pwm1( ) setup_pwm2( ) setup_pwm3( ) setup_pwm4( ) ............................................ 296

setup_qei( ) ......................................................................................................................... 297

setup_rtc( ) .......................................................................................................................... 297

setup_rtc_alarm( ) ............................................................................................................... 298

setup_spi( ) setup_spi2( ) .................................................................................................... 299

setup_timer_A( ) .................................................................................................................. 299

setup_timer_B( ) .................................................................................................................. 300

setup_timer_0( ) .................................................................................................................. 300

setup_timer_1( ) .................................................................................................................. 301

setup_timer_2( ) .................................................................................................................. 302

setup_timer_3( ) .................................................................................................................. 302

setup_timer_4( ) .................................................................................................................. 303

setup_timer_5( ) .................................................................................................................. 304

setup_uart( ) ........................................................................................................................ 304

setup_vref( ) ........................................................................................................................ 305

setup_wdt( )......................................................................................................................... 306

shift_left( ) ........................................................................................................................... 306

shift_right( ) ......................................................................................................................... 307

sleep( ) ................................................................................................................................ 307

sleep_ulpwu( ) ..................................................................................................................... 308

spi_data_is_in( ) spi_data_is_in2( ) ..................................................................................... 309

spi_init() ............................................................................................................................... 309

spi_prewrite(data); ............................................................................................................... 310

spi_read( ) spi_read2( ) ..................................................................................................... 310

spi_read_16() ...................................................................................................................... 311

spi_read2_16() .................................................................................................................... 311

spi_read3_16() .................................................................................................................... 311

spi_read4_16() .................................................................................................................... 311

spi_speed ............................................................................................................................ 312

spi_write( ) spi_write2( ) ...................................................................................................... 312

spi_xfer( ) ............................................................................................................................ 313

SPII_XFER_IN() .................................................................................................................. 314

sprintf( ) ............................................................................................................................... 314

sqrt( ) ................................................................................................................................... 315

srand( ) ................................................................................................................................ 315

STANDARD STRING FUNCTIONS( ) memchr( ) memcmp( ) strcat( ) strchr( )

strcmp( ) strcoll( ) strcspn( ) strerror( ) stricmp( ) strlen( ) strlwr( ) strncat( )

strncmp( ) strncpy( ) strpbrk( ) strrchr( ) strspn( ) strstr( ) strxfrm( ) ...................................... 316

strtod( ) ................................................................................................................................ 317

strtok( ) ................................................................................................................................ 318

strtol( ) ................................................................................................................................. 319

strtoul( ) ............................................................................................................................... 320

swap( ) ................................................................................................................................ 321

tolower( ) toupper( ) ............................................................................................................. 321

touchpad_getc( ) ................................................................................................................. 322

touchpad_hit( ) .................................................................................................................... 323

touchpad_state( ) ................................................................................................................ 323

tx_buffer_bytes() ................................................................................................................. 324

tx_buffer_full( ) .................................................................................................................... 325

va_arg( ) .............................................................................................................................. 325

va_end( ) ............................................................................................................................. 326

va_start ............................................................................................................................... 327

write_bank( )........................................................................................................................ 328

write_configuration_memory( ) ............................................................................................ 328

write_eeprom( ) ................................................................................................................... 329

write_external_memory( ) .................................................................................................... 330

write_extended_ram( ) ......................................................................................................... 331

write_program_eeprom( ) .................................................................................................... 332

write_program_memory( ) ................................................................................................... 333

Standard C Include Files ......................................................................................................... 335

errno.h ................................................................................................................................. 335

float.h .................................................................................................................................. 335

limits.h ................................................................................................................................. 336

locale.h ................................................................................................................................ 336

setjmp.h ............................................................................................................................... 337

stddef.h ............................................................................................................................... 337

stdio.h.................................................................................................................................. 337

stdlib.h ................................................................................................................................. 337

Error Messages ....................................................................................................................... 338

Compiler Error Messages .................................................................................................... 338

Compiler Warning Messages .................................................................................................. 347

Compiler Warning Messages ............................................................................................... 347

Common Questions & Answers .............................................................................................. 350

How are type conversions handled? .................................................................................... 350

How can a constant data table be placed in ROM? ............................................................. 351

How can I use two or more RS-232 ports on one PIC®? ..................................................... 351

How can the RB interrupt be used to detect a button press? ............................................... 352

How do I directly read/write to internal registers? ................................................................ 353

How do I do a printf to a string? ........................................................................................... 353

How do I get getc() to timeout after a specified time? .......................................................... 354

How do I make a pointer to a function? ................................................................................ 354

How do I put a NOP at location 0 for the ICD? ..................................................................... 354

How do I wait only a specified time for a button press? ....................................................... 355

How do I write variables to EEPROM that are not a byte? ................................................... 355

How does one map a variable to an I/O port? ...................................................................... 356

How does the compiler determine TRUE and FALSE on expressions? ............................... 357

How does the PIC® connect to a PC? ................................................................................. 357

How does the PIC® connect to an I2C device? ................................................................... 358

How much time do math operations take? ........................................................................... 358

Instead of 800, the compiler calls 0. Why? .......................................................................... 359

Instead of A0, the compiler is using register 20. Why? ....................................................... 359

What can be done about an OUT OF RAM error? ............................................................... 359

What is an easy way for two or more PICs® to communicate? ............................................ 360

What is an easy way for two or more PICs® to communicate? ............................................ 361

What is the format of floating point numbers? ...................................................................... 362

Why does the .LST file look out of order? ............................................................................ 363

Why does the compiler show less RAM than there really is? ............................................... 363

Why does the compiler use the obsolete TRIS? .................................................................. 364

Why is the RS-232 not working right? .................................................................................. 364

Example Programs ................................................................................................................. 367

EXAMPLE PROGRAMS ...................................................................................................... 367

Software License Agreement .................................................................................................. 391

SOFTWARE LICENSE AGREEMENT................................................................................. 391

OVERVIEW

PCB, PCM and PCH Overview

The PCB, PCM, and PCH are separate compilers. PCB is for 12-bit opcodes, PCM is for 14-bit

opcodes, and PCH is for 16-bit opcode PIC® microcontrollers. Due to many similarities, all three

compilers are covered in this reference manual. Features and limitations that apply to only

specific microcontrollers are indicated within. These compilers are specifically designed to meet

the unique needs of the PIC® microcontroller. This allows developers to quickly design

applications software in a more readable, high-level language.

IDE Compilers (PCW, PCWH and PCWHD) have the exclusive C Aware integrated

development environment for compiling, analyzing and debugging in real-time. Other features

and integrated tools can be viewed here.

When compared to a more traditional C compiler, PCB, PCM, and PCH have some limitations.

As an example of the limitations, function recursion is not allowed. This is due to the fact that

the PIC® has no stack to push variables onto, and also because of the way the compilers

optimize the code. The compilers can efficiently implement normal C constructs, input/output

operations, and bit twiddling operations. All normal C data types are supported along with

pointers to constant arrays, fixed point decimal, and arrays of bits.

Installation

Insert the CD ROM, select each of the programs you wish to install and follow the on-screen

instructions.

If the CD does not auto start run the setup program in the root directory.

For help answering the version questions see the "Directories" Help topic.

Key Questions that may come up:

Keep Settings- Unless you are having trouble select this

Link Compiler Extensions- If you select this the file extensions like .c will start

the compiler IDE when you double click on files with that extension. .hex files start

the CCSLOAD program. This selection can be change in the IDE.

Install MP LAB Plug In- If you plan to use MPLAB and you don't select this you

will need to download and manually install the Plug-In.

Install ICD2, ICD3...drivers-select if you use these microchip ICD units.

Delete Demo Files- Always a good idea

Install WIN8 APP- Allows you to start the IDE from the WIN8 Start Menu.

Technical Support

Compiler, software, and driver updates are available to download at:

http://www.ccsinfo.com/download

Compilers come with 30 or 60 days of download rights with the initial purchase. One year

maintenance plans may be purchased for access to updates as released.

The intent of new releases is to provide up-to-date support with greater ease of use and

minimal, if any, transition difficulty.

To ensure any problem that may occur is corrected quickly and diligently, it is recommended to

send an email to: support@ccsinfo.com or use the Technical Support Wizard in PCW. Include

the version of the compiler, an outline of the problem and attach any files with the email request.

CCS strives to answer technical support timely and thoroughly.

Technical Support is available by phone during business hours for urgent needs or if email

responses are not adequate. Please call 262-522-6500 x32.

Directories

The compiler will search the following directories for Include files.

 Directories listed on the command line

 Directories specified in the .CCSPJT file

 The same directory as the source.directories in the ccsc.ini file

By default, the compiler files are put in C:\Program Files\PICC and the example

programs are in \PICC\EXAMPLES. The include files are in PICC\drivers. The

device header files are in PICC\devices.

The compiler itself is a DLL file. The DLL files are in a DLL directory by default in \PICC\DLL.

It is sometimes helpful to maintain multiple compiler versions. For example, a project was

tested with a specific version, but newer projects use a newer version. When installing the

compiler you are prompted for what version to keep on the PC. IDE users can change versions

using Help>about and clicking "other versions." Command Line users use start>all

programs>PIC-C>compiler version.

Two directories are used outside the PICC tree. Both can be reached with start>all

programs>PIC-C.

1.) A project directory as a default location for your projects. By default put in "My

Documents." This is a good place for VISTA and up.

2.) User configuration settings and PCWH loaded files are kept in %APPDATA%\PICC

File Formats

This is the source file containing user C source code.

These are standard or custom header files used to define pins, register, register bits,

functions and preprocessor directives.

.pjt

This is the older pre- Version 5 project file which contains information related to the

project.

.ccspjt

This is the project file which contains information related to the project.

.lst

This is the listing file which shows each C source line and the associated assembly

code generated for that line.

The elements in the .LST file may be selected in PCW under Options>Project>Output

Files

CCS Basic

Standard assembly instructions

with Opcodes

Includes the HEX opcode for each instruction

Old Standard

Symbolic

Shows variable names instead of addresses

.sym

This is the symbol map which shows each register location and what program variables

are stored in each location.

.sta

The statistics file shows the RAM, ROM, and STACK usage. It provides information on

the source codes structural and textual complexities using Halstead and McCabe

metrics.

.tre

The tree file shows the call tree. It details each function and what functions it calls

along with the ROM and RAM usage for each function.

.hex

The compiler generates standard HEX files that are compatible with all programmers.

The compiler can output 8-bet hex, 16-bit hex, and binary files.

.cof

This is a binary containing machine code and debugging information.

The debug files may be output as Microchip .COD file for MPLAB 1-5, Advanced

Transdata .MAP file, expanded .COD file for CCS debugging or MPLAB 6 and up .xx

.COF file. All file formats and extensions may be selected via Options File Associations

option in Windows IDE.

.cod

This is a binary file containing debug information.

.rtf

The output of the Documentation Generator is exported in a Rich Text File format

which can be viewed using the RTF editor or Wordpad.

.rvf

The Rich View Format is used by the RTF Editor within the IDE to view the Rich Text

File.

.dgr

The .DGR file is the output of the flowchart maker.

.esym

.xsym

These files are generated for the IDE users. The file contains Identifiers and Comment

information. This data can be used for automatic documentation generation and for the

IDE helpers.

Relocatable object file

.osym

This file is generated when the compiler is set to export a relocatable object file. This

file is a .sym file for just the one unit.

.err

Compiler error file

.ccsloa

used to link Windows 8 apps to CCSLoad

.ccssio

used to link Windows 8 apps to Serial Port Monitor

Invoking the Command Line Compiler

The command line compiler is invoked with the following command:

CCSC [options] [cfilename]

Valid options:

+FB

Select PCB (12 bit)

-D

Do not create debug file

+FM

Select PCM (14 bit)

+DS

Standard .COD format debug file

+FH

Select PCH (PIC18XXX)

+DM

.MAP format debug file

+Yx

Optimization level x (0-9)

+DC

Expanded .COD format debug file

+DF

Enables the output of an COFF

debug file.

+FS

Select SXC (SX)

+EO

Old error file format

+ES

Standard error file

-T

Do not generate a tree file

Create call tree (.TRE)

-A

Do not create stats file (.STA)

Create stats file (.STA)

-EW

Suppress warnings (use with +EA)

+EW

Show warning messages

-E

Only show first error

+EA

Show all error messages and all

warnings

+EX

Error/warning message format uses

GCC's "brief format" (compatible with

GCC editor environments)

The xxx in the following are optional. If included it sets the file extension:

+LNxxx

Normal list file

+O8xxx

8-bit Intel HEX output file

+LSxxx

MPASM format list file

+OWxxx

16-bit Intel HEX output file

+LOxxx

Old MPASM list file

+OBxxx

Binary output file

+LYxxx

Symbolic list file

-O

Do not create object file

-L

Do not create list file

Keep compile status window up after compile

+Pxx

Keep status window up for xx seconds after compile

+PN

Keep status window up only if there are no errors

+PE

Keep status window up only if there are errors

Keep scratch files on disk after compile

+DF

COFF Debug file

I+="..."

Same as I="..." Except the path list is appended to the current list

I="..."

Set include directory search path, for example:

I="c:\picc\examples;c:\picc\myincludes"

If no I= appears on the command line the .PJT file will be used to supply the

include file paths.

-P

Close compile window after compile is complete

Generate a symbol file (.SYM)

-M

Do not create symbol file

Create a project file (.PJT)

-J

Do not create PJT file

+ICD

Compile for use with an ICD

#xxx="yyy"

Set a global #define for id xxx with a value of yyy, example:

#debug="true"

+Gxxx="yyy"

Same as #xxx="yyy"

Brings up a help file

Same as +?

+STDOUT

Outputs errors to STDOUT (for use with third party editors)

+SETUP

Install CCSC into MPLAB (no compile is done)

sourceline=

Allows a source line to be injected at the start of the source file.

Example: CCSC +FM myfile.c sourceline=“#include <16F887.h>”

Show compiler version (no compile is done)

Show all valid devices in database (no compile is done)

A / character may be used in place of a + character. The default options are as follows:

+FM +ES +J +DC +Y9 -T -A +M +LNlst +O8hex -P -Z

If @filename appears on the CCSC command line, command line options will be read from the

specified file. Parameters may appear on multiple lines in the file.

If the file CCSC.INI exists in the same directory as CCSC.EXE, then command line parameters

are read from that file before they are processed on the command line.

Examples:

CCSC +FM C:\PICSTUFF\TEST.C

CCSC +FM +P +T TEST.C

PCW Overview

The PCW IDE provides the user an easy to use editor and environment for

developing microcontroller applications. The IDE comprises of many components,

which are summarized below. For more information and details, use the Help>PCW

in the compiler..

Many of these windows can be re-arranged and docked into different positions.

All of the IDE's functions are on the main menu. The main menu

is divided into separate sections, click on a section title ('Edit',

'Search', etc) to change the section. Double clicking on the

section, or clicking on the chevron on the right, will cause the

menu to minimize and take less space.

Editor Tabs

All of the open files are listed here. The active file, which is the file

currently being edited, is given a different highlight than the other

files. Clicking on the X on the right closes the active file. Right

clicking on a tab gives a menu of useful actions for that file.

Slide Out Windows

'Files' shows all the active files in the current project. 'Projects'

shows all the recent projects worked on. 'Identifiers' shows all the

variables, definitions, prototypes and identifiers in your current

project.

Editor

The editor is the main work area of the IDE and the place where

the user enters and edits source code. Right clicking in this area

gives a menu of useful actions for the code being edited.

Debugging Windows

Debugger control is done in the debugging windows. These

windows allow you set breakpoints, single step, watch variables

and more.

Status Bar

The status bar gives the user helpful information like the cursor

position, project open and file being edited.

Output Messages

Output messages are displayed here. This includes messages

from the compiler during a build, messages from the programmer

tool during programming or the results from find and searching.

PROGRAM SYNTAX

Overall Structure

A program is made up of the following four elements in a file:

Comment

Pre-Processor Directive

Data Definition

Function Definition

Every C program must contain a main function which is the starting point of the program

execution. The program can be split into multiple functions according to the their purpose and

the functions could be called from main or the sub-functions. In a large project functions can

also be placed in different C files or header files that can be included in the main C file to group

the related functions by their category. CCS C also requires to include the appropriate device

file using #include directive to include the device specific functionality. There are also some

preprocessor directives like #fuses to specify the fuses for the chip and #use delay to specify

the clock speed. The functions contain the data declarations,definitions,statements and

expressions. The compiler also provides a large number of standard C libraries as well as other

device drivers that can be included and used in the programs. CCS also provides a large

number of built-in functions to access the various peripherals included in the PIC

microcontroller.

Comment

Comments – Standard Comments

A comment may appear anywhere within a file except within a quoted string. Characters

between /* and */ are ignored. Characters after a // up to the end of the line are ignored.

Comments for Documentation Generator

The compiler recognizes comments in the source code based on certain markups. The compiler

recognizes these special types of comments that can be later exported for use in the

documentation generator. The documentation generator utility uses a user selectable template

to export these comments and create a formatted output document in Rich Text File Format.

This utility is only available in the IDE version of the compiler. The source code markups are as

follows.

Global Comments

These are named comments that appear at the top of your source code. The comment names

are case sensitive and they must match the case used in the documentation template.

For example:

//*PURPOSE This program implements a Bootloader.

//*AUTHOR John Doe

A '//' followed by an * will tell the compiler that the keyword which follows it will be the named

comment. The actual comment that follows it will be exported as a paragraph to the

documentation generator.

Program Syntax

Multiple line comments can be specified by adding a : after the *, so the compiler will not

concatenate the comments that follow. For example:

/**:CHANGES

05/16/06 Added PWM loop

05/27.06 Fixed Flashing problem

Variable Comments

A variable comment is a comment that appears immediately after a variable declaration. For

example:

int seconds; // Number of seconds since last entry

long day, // Current day of the month, /* Current Month */

long year; // Year

Function Comments

A function comment is a comment that appears just before a function declaration. For example:

// The following function initializes outputs

void function_foo()

{ init_outputs();

}

Function Named Comments

The named comments can be used for functions in a similar manner to the Global Comments.

These comments appear before the function, and the names are exported as-is to the

documentation generator.

For example:

//*PURPOSE This function displays data in BCD format

void display_BCD( byte n)

{ display_routine();

}

Trigraph Sequences

The compiler accepts three character sequences instead of some special

characters not available on all keyboards as follows:

Sequence

Same as

??=

??(

[

??/

??)

]

??'

??<

{

Program Syntax

??!

??>

}

??-

Multiple Project Files

When there are multiple files in a project they can all be included using the

#include in the main file or the sub-files to use the automatic linker included in the

compiler. All the header files, standard libraries and driver files can be included

using this method to automatically link them.

For example: if you have main.c, x.c, x.h, y.c,y.h and z.c and z.h files in your

project, you can say in:

main.c

#include <device header file>

#include<x.c>

#include<y.c>

#include <z.c>

x.c

#include <x.h>

y.c

#include <y.h>

z.c

#include <z.h>

In this example there are 8 files and one compilation unit. Main.c is the only file compiled.

Note that the #module directive can be used in any include file to limit the visibility of the symbol

in that file.

To separately compile your files see the section "multiple compilation units".

Multiple Compilation Units

Traditionally, the CCS C compiler used only one compilation unit and multiple files

were implemented with #include files. When using multiple compilation units, care

must be given that pre-processor commands that control the compilation are

compatible across all units. It is recommended that directives such as #FUSES,

#USE and the device header file all put in an include file included by all units. When

a unit is compiled it will output a relocatable object file (*.o) and symbol file (*.osym).

There are several ways to accomplish this with the CCS C Compiler. All of these

methods and example projects are included in the MCU.zip in the examples

directory of the compiler.

Program Syntax

Example

Here is a sample program with explanation using CCS C to read adc samples over rs232:

///////////////////////////////////////////////////////

/// This program displays the min and max of 30, ///

/// comments that explains what the program does, ///

/// and A/D samples over the RS-232 interface. ///

///////////////////////////////////////////////////////

#include <16F887.h> // preprocessor directive that selects the chip

PIC16F887

#fuses NOPROTECT // Code protection turned off

#use delay(crystal=20mhz) // preprocessor directive that specifies the clock

type and speed

#use rs232(baud=9600, xmit=PIN_C6, rcv=PIN_C7) // preprocessor directive that

includes the

// rs232 libraries

void main() { // main function

int i, value, min, max; // local variable declaration

printf("Sampling:"); // printf function included in

the RS232 library

setup_port_a( ALL_ANALOG ); // A/D setup functions- built-

setup_adc( ADC_CLOCK_INTERNAL ); // Internal clock always works

set_adc_channel( 0 ); // Set channel to AN0

do { // do forever statement

min=255;

max=0;

for(i=0; i<=30; ++i) { // Take 30 samples

delay_ms(100); // Wait for a tenth of a

second

value = Read_ADC(); // A/D read functions- built-

if(value<min) // Find smallest sample

min=value;

if(value>max) // Find largest sample

max=value;

}

printf("\n\rMin: %2X Max: %2X\n\r",min,max);

} while (TRUE);

}

STATEMENTS

if-else

The if-else statement is used to make decisions.

The syntax is:

if (expr)

stmt-1;

[else

stmt-2;]

The expression is evaluated; if it is true stmt-1 is done. If it is false then stmt-2 is done.

else-if

This is used to make multi-way decisions.

The syntax is:

if (expr)

stmt;

[else if (expr)

stmt;]

...

[else

stmt;]

The expressions are evaluated in order; if any expression is true, the statement associated with

it is executed and it terminates the chain. If none of the conditions are satisfied the last else part

is executed.

Example:

if (x==25)

x=1;

else

x=x+1;

Also See: Statements

Statements

while

While is used as a loop/iteration statement.

The syntax is:

while (expr)

statement

The expression is evaluated and the statement is executed until it becomes false in which case

the execution continues after the statement.

Example:

while (get_rtcc()!=0)

putc('n');

Also See: Statements

do-while

do-while: Differs from while and for loop in that the termination

condition is checked at the bottom of the loop rather than at the

top and so the body of the loop is always executed at least once.

The syntax is:

statement

while (expr);

The statement is executed; the expr is evaluated. If true, the

same is repeated and when it becomes false the loop terminates.

Also See: Statements , While

for

For is also used as a loop/iteration statement.

The syntax is:

for (expr1;expr2;expr3)

statement

The expressions are loop control statements. expr1 is the

initialization, expr2 is the termination check and expr3 is re-

initialization. Any of them can be omitted.

Example:

for (i=1;i<=10;++i)

printf("%u\r\n",i);

Also See: Statements

Statements

switch

Switch is also a special multi-way decision maker.

The syntax is

switch (expr) {

case const1: stmt sequence;

break;

...

[default:stmt]

}

This tests whether the expression matches one of the constant values and branches

accordingly.

If none of the cases are satisfied the default case is executed. The break causes an immediate

exit, otherwise control falls through to the next case.

Example:

switch (cmd) {

case 0:printf("cmd 0");

break;

case 1:printf("cmd 1");

break;

default:printf("bad cmd");

break; }

Also See: Statements

return

A return statement allows an immediate exit from a switch or a loop or function and also

returns a value.

The syntax is:

return(expr);

Example:

return (5);

Also See: Statements

Statements

goto

The goto statement cause an unconditional branch to the label.

The syntax is:

goto label;

A label has the same form as a variable name, and is followed by a colon. The goto's

are used sparingly, if at all.

Example:

goto loop;

Also See: Statements

label

The label a goto jumps to.

The syntax is:

label: stmnt;

Example:

loop: i++;

Also See: Statements

break

break.

The break statement is used to exit out of a control loop. It provides an early exit

from while, for ,do and switch.

The syntax is

break;

It causes the innermost enclosing loop (or switch) to be exited immediately.

Example:

break;

Also See: Statements

Statements

continue

The continue statement causes the next iteration of the enclosing loop(While, For,

Do) to begin.

The syntax is:

continue;

It causes the test part to be executed immediately in case of do and while and the

control passes the

re-initialization step in case of for.

Example:

continue;

Also See: Statements

expr

The syntax is:

expr;

Example:

i=1;

Also See: Statements

;

Statement: ;

Example:

;

Also See: Statements

stmt

Zero or more semi-colon separated.

The syntax is:

{[stmt]}

Example:

{a=1;

b=1;}

Also See: Statements

EXPRESSIONS

Operators

Addition Operator

Addition assignment operator, x+=y, is the same as x=x+y

Bitwise and assignment operator, x&=y, is the same as

x=x&y

Address operator

Bitwise and operator

Bitwise exclusive or assignment operator, x^=y, is the same

as x=x^y

Bitwise exclusive or operator

Bitwise inclusive or assignment operator, xl=y, is the same

as x=xly

Bitwise inclusive or operator

Conditional Expression operator

- -

Decrement

Division assignment operator, x/=y, is the same as x=x/y

Division operator

Equality

Greater than operator

Greater than or equal to operator

Increment

Indirection operator

Inequality

<<=

Left shift assignment operator, x<<=y, is the same as

x=x<<y

Less than operator

Left Shift operator

Less than or equal to operator

Logical AND operator

Logical negation operator

Logical OR operator

Modules assignment operator x%=y, is the same as x=x%y

Modules operator

Multiplication assignment operator, x*=y, is the same as

x=x*y

Expressions

Multiplication operator

One's complement operator

>>=

Right shift assignment, x>>=y, is the same as x=x>>y

Right shift operator

Structure Pointer operation

Subtraction assignment operator, x-=y, is the same as x=x-

Subtraction operator

sizeof

Determines size in bytes of operand

Operator Precedence

PIN DESCENDING PRECEDENCE

(expr)

++expr

expr++

- -expr

expr - -

!expr

~expr

+expr

-expr

(type)expr

*expr

&value

sizeof(type)

expr*expr

expr/expr

expr%expr

expr+expr

expr-expr

expr<<expr

expr>>expr

expr<expr

expr<=expr

expr>expr

expr>=expr

expr==expr

expr!=expr

expr&expr

expr^expr

expr | expr

expr&& expr

expr || expr

expr ? expr: expr

lvalue = expr

lvalue+=expr

lvalue-=expr

lvalue*=expr

lvalue/=expr

lvalue%=expr

lvalue>>=expr

lvalue<<=expr

lvalue&=expr

lvalue^=expr

lvalue|=expr

expr, expr

(Operators on the same line are equal in precedence)

Expressions

Reference Parameters

The compiler has limited support for reference parameters. This increases the readability of

code and the efficiency of some inline procedures. The following two procedures are the

same. The one with reference parameters will be implemented with greater efficiency when it is

inline.

funct_a(int*x,int*y){

/*Traditional*/

if(*x!=5)

*y=*x+3;

}

funct_a(&a,&b);

funct_b(int&x,int&y){

/*Reference params*/

if(x!=5)

y=x+3;

}

funct_b(a,b);

Variable Argument Lists

The compiler supports a variable number of parameters. This works like the ANSI requirements

except that it does not require at least one fixed parameter as ANSI does. The function can be

passed any number of variables and any data types. The access functions are VA_START,

VA_ARG, and VA_END. To view the number of arguments passed, the NARGS function can be

used.

stdarg.h holds the macros and va_list data type needed for variable

number of parameters.

#include <stdarg.h>

A function with variable number of parameters requires two things. First, it requires the ellipsis

(...), which must be the last parameter of the function. The ellipsis represents the variable

argument list. Second, it requires one more variable before the ellipsis (...). Usually you will use

this variable as a method for determining how many variables have been pushed onto the

ellipsis.

Expressions

Here is a function that calculates and returns the sum of all variables:

int Sum(int count, ...)

{

//a pointer to the argument list

va_list al;

int x, sum=0;

//start the argument list

//count is the first variable before the ellipsis

va_start(al, count);

while(count--) {

//get an int from the list

x = var_arg(al, int);

sum += x;

}

//stop using the list

va_end(al);

return(sum);

}

Some examples of using this new function:

x=Sum(5, 10, 20, 30, 40, 50);

y=Sum(3, a, b, c);

Default Parameters

Default parameters allows a function to have default values if nothing is passed to it when

called. int mygetc(char *c, int n=100){

}

This function waits n milliseconds for a character over RS232. If a character is received, it saves

it to the pointer c and returns TRUE. If there was a timeout it returns FALSE.

//gets a char, waits 100ms for timeout

mygetc(&c);

//gets a char, waits 200ms for a timeout

mygetc(&c, 200);

Overloaded Functions

Overloaded functions allow the user to have multiple functions with the same name, but they

must accept different parameters. The return types must remain the same.

Here is an example of function overloading: Two functions have the same name but differ in the

types of parameters. The compiler determines which data type is being passed as a parameter

and calls the proper function.

Expressions

This function finds the square root of a long integer variable.

long FindSquareRoot(long n){

}

This function finds the square root of a float variable.

float FindSquareRoot(float n){

}

FindSquareRoot is now called. If variable is of long type, it will call the first FindSquareRoot()

example. If variable is of float type, it will call the second FindSquareRoot() example.

result=FindSquareRoot(variable);

DATA DEFINITIONS

Basic and Special types

This section describes what the basic data types and specifiers

are and how variables can be declared using those types. In C all

the variables should be declared before they are used. They can

be defined inside a function (local) or outside all functions

(global). This will affect the visibility and life of the variables.

Basic Types

Range

Type-Specifier

Size

Unsigned

Signed

Digits

int1

1 bit number

0 to 1

N/A

1/2

int8

8 bit number

0 to 255

-128 to 127

2-3

int16

16 bit number

0 to 65535

-32768 to 32767

4-5

int32

32 bit number

0 to 4294967295

-2147483648 to 2147483647

9-10

int48

48 bit number

0 to

281474976710655

-140737488355328 to

140737488355327

14-15

int64

64 bit number

N/A

-9223372036854775808 to

9223372036854775807

18-19

float32

32 bit float

-1.5 x 1045 to 3.4 x 1038

7-8

C Standard Type

Default Type

short

int1

char

unsigned int8

int

int8

long

int16

long long

int32

float

float32

double

N/A

Type-Qualifier

static

Variable is globally active and initialized to 0. Only accessible from this compilation

unit.

auto

Variable exists only while the procedure is active. This is the default and AUTO need

not be used.

double

Is a reserved word but is not a supported data type.

Data Definitions

extern

External variable used with multiple compilation units. No storage is allocated. Is

used to make otherwise out of scope data accessible. there must be a non-extern

definition at the global level in some compilation unit.

Is allowed as a qualifier however, has no effect.

_ fixed(n)

Creates a fixed point decimal number where n is how many decimal places to

implement.

unsigned

Data is always positive. This is the default data type if not specified.

signed

Data can be negative or positive.

volatile

Tells the compiler optimizer that this variable can be changed at any point during

execution.

const

Data is read-only. Depending on compiler configuration, this qualifier may just make

the data read-only -AND/OR- it may place the data into program memory to save

space. (see #DEVICE const=)

rom

Forces data into program memory. Pointers may be used to this data but they can not

be mixed with RAM pointers.

void

Built-in basic type. Type void is used to indicate no specific type in places where a

type is required.

readonly

Writes to this variable should be dis-allowed

_bif

Used for compiler built in function prototypes on the same line

Special types

enum enumeration type: creates a list of integer constants.

enum

[id]

{ [ id [ = cexpr]] }

One or more comma separated

The id after enum is created as a type large enough to the

largest constant in the list. The ids in the list are each created as

a constant. By default the first id is set to zero and they

increment by one. If a = cexpr follows an id that id will have the

value of the constant expression an d the following list will

increment by one.

Data Definitions

For example:

enum colors{red, green=2, blue}; // red will be 0, green will be 2 and

// blue will be 3

Struct structure type: creates a collection of one or more

variables, possibly of different types, grouped together as a

single unit.

struct[*] [id] {

type-qualifier [*] id

[:bits];

} [id]

One or more,

semi-colon

separated

Zero

or more

For example:

struct data_record {

int a[2];

int b : 2; /*2 bits */

int c : 3; /*3 bits*/

int d;

} data_var; //data_record is a structure type

//data _var is a variable

Union type: holds objects of different types and sizes, with the

compiler keeping track of size and alignment requirements. They

provide a way to manipulate different kinds of data in a single

area of storage.

union[*] [id] {

type-qualifier [*] id

[:bits];

} [id]

One or more,

semi-colon

separated

Zero

or more

For example:

union u_tab {

int ival;

long lval;

float fval;

}; // u_tag is a union type that can hold a float

If typedef is used with any of the basic or special types it creates a

new type name that can be used in declarations. The identifier

Data Definitions

does not allocate space but rather may be used as a type specifier

in other data definitions.

typedef

[type-qualifier] [type-specifier] [declarator];

For example:

typedef int mybyte; // mybyte can be used in

declaration to

// specify the int type

typedef short mybit; // mybyte can be used in

declaration to

// specify the int type

typedef enum {red, green=2,blue}colors; //colors can be used to

declare

//variables of this enum type

__ADDRESS__: A predefined symbol __ADDRESS__ may be

used to indicate a type that must hold a program memory

address.

For example:

___ADDRESS__ testa = 0x1000 //will allocate 16 bits for test a and

//initialize to 0x1000

Declarations

A declaration specifies a type qualifier and a type specifier, and is followed by a list

of one or more variables of that type.

For example:

int a,b,c,d;

mybit e,f;

mybyte g[3][2];

char *h;

colors j;

struct data_record data[10];

static int i;

extern long j;

Variables can also be declared along with the definitions of the special types.

For example:

enum colors{red, green=2,blue}i,j,k; // colors is the enum type and

i,j,k

//are variables of that type

Non-RAM Data Definitions

CCS C compiler also provides a custom qualifier addressmod which can

be used to define a memory region that can be RAM, program eeprom,

data eeprom or external memory. Addressmod replaces the older

typemod (with a different syntax).

Data Definitions

The usage is :

addressmod

(name,read_function,write_function,start_address,end_address,

share);

Where the read_function and write_function should be blank for RAM, or

for other memory should be the following prototype:

// read procedure for reading n bytes from the memory starting at

location addr

void read_function(int32 addr,int8 *ram, int nbytes){

}

//write procedure for writing n bytes to the memory starting at

location addr

void write_function(int32 addr,int8 *ram, int nbytes){

}

For RAM the share argument may be true if unused RAM in this area can be used by the

compiler for standard variables.

Example:

void DataEE_Read(int32 addr, int8 * ram, int bytes) {

int i;

for(i=0;i<bytes;i++,ram++,addr++)

*ram=read_eeprom(addr);

}

void DataEE_Write(int32 addr, int8 * ram, int bytes) {

int i;

for(i=0;i<bytes;i++,ram++,addr++)

write_eeprom(addr,*ram);

}

addressmod (DataEE,DataEE_read,DataEE_write,5,0xff);

// would define a region called DataEE between

// 0x5 and 0xff in the chip data EEprom.

void main (void)

{

int DataEE test;

int x,y;

x=12;

test=x; // writes x to the Data EEPROM

y=test; // Reads the Data EEPROM

}

Note: If the area is defined in RAM then read and write functions are not

required, the variables assigned in the memory region defined by the

addressmod can be treated as a regular variable in all valid expressions.

Any structure or data type can be used with an addressmod. Pointers

can also be made to an addressmod data type. The #type directive can

be used to make this memory region as default for variable allocations.

Data Definitions

The syntax is :

#type default=addressmodname // all the variable declarations

that

// follow will use this memory

region

#type default= // goes back to the default mode

For example:

Type default=emi //emi is the addressmod name

defined

char buffer[8192];

#include <memoryhog.h>

#type default=

Using Program Memory for Data

CCS C Compiler provides a few different ways to use program memory for data. The different

ways are discussed below:

Constant Data:

The const qualifier will place the variables into program memory. If the keyword const is used

before the identifier, the identifier is treated as a constant. Constants should be initialized and

may not be changed at run-time. This is an easy way to create lookup tables.

The rom Qualifier puts data in program memory with 3 bytes per instruction space. The address

used for ROM data is not a physical address but rather a true byte address. The & operator can

be used on ROM variables however the address is logical not physical.

The syntax is:

const type id[cexpr] = {value}

For example:

Placing data into ROM

const int table[16]={0,1,2...15}

Placing a string into ROM

const char cstring[6]={"hello"}

Creating pointers to constants

const char *cptr;

cptr = string;

The #org preprocessor can be used to place the constant to specified address blocks.

For example:

The constant ID will be at 1C00.

#ORG 0x1C00, 0x1C0F

CONST CHAR ID[10]= {"123456789"};

Note: Some extra code will precede the 123456789.

The function label_address can be used to get the address of the constant. The constant

variable can be accessed in the code. This is a great way of storing constant data in large

programs. Variable length constant strings can be stored into program memory.

A special method allows the use of pointers to ROM. This method does not contain extra code

at the start of the structure as does constant.

Data Definitions

For example:

char rom commands[] = {“put|get|status|shutdown”};

The compiler allows a non-standard C feature to implement a constant array of variable length

strings. The syntax is:

const char id[n] [*] = { "string", "string" ...};

Where n is optional and id is the table identifier.

For example:

const char colors[] [*] = {"Red", "Green", "Blue"};

#ROM directive:

Another method is to use #rom to assign data to program memory.

The syntax is:

#rom address = {data, data, … , data}

For example:

Places 1,2,3,4 to ROM addresses starting at 0x1000

#rom 0x1000 = {1, 2, 3, 4}

Places null terminated string in ROM

#rom 0x1000={"hello"}

This method can only be used to initialize the program memory.

Built-in-Functions:

The compiler also provides built-in functions to place data in program memory, they are:

 write_program_eeprom(address,data);

- Writes data to program memory

 write_program_memory(address, dataptr, count);

- Writes count bytes of data from dataptr to address in program memory.

Please refer to the help of these functions to get more details on their usage and limitations

regarding erase procedures. These functions can be used only on chips that allow writes to

program memory. The compiler uses the flash memory erase and write routines to implement

the functionality.

The data placed in program memory using the methods listed above can be read from width the

following functions:

 read_program_memory((address, dataptr, count)

- Reads count bytes from program memory at address to RAM at dataptr.

These functions can be used only on chips that allow reads from program memory. The

compiler uses the flash memory read routines to implement the functionality.

Data Definitions

Function Definition

The format of a function definition is as follows:

[qualifier] id

( [type-specifier id] )

{ [stmt] }

Optional See Below

Zero or more comma

separated.

See Data Types

Zero or more Semi-colon

separated. See

Statements.

The qualifiers for a function are as follows:

 VOID

 type-specifier

 #separate

 #inline

 #int_..

When one of the above are used and the function has a prototype (forward declaration of the

function before it is defined) you must include the qualifier on both the prototype and function

definition.

A (non-standard) feature has been added to the compiler to help get around the problems

created by the fact that pointers cannot be created to constant strings. A function that has one

CHAR parameter will accept a constant string where it is called. The compiler will generate a

loop that will call the function once for each character in the string.

Example:

void lcd_putc(char c ) {

...

}

lcd_putc ("Hi There.");

FUNCTIONAL OVERVIEW

I2C

I2C™ is a popular two-wire communication protocol developed by Phillips. Many PIC

microcontrollers support hardware-based I2C™. CCS offers support for the hardware-based

I2C™ and a software-based master I2C™ device. (For more information on the hardware-based

I2C module, please consult the datasheet for you target device; not all PICs support I2C™.)

Relevant Functions:

i2c_start()

Issues a start command when in the I2C master mode.

i2c_write(data)

Sends a single byte over the I2C interface.

i2c_read()

Reads a byte over the I2C interface.

i2c_stop()

Issues a stop command when in the I2C master mode.

i2c_poll()

Returns a TRUE if the hardware has received a byte in the

buffer.

Relevant Preprocessor:

#USE I2C

Configures the compiler to support I2C™ to your

specifications.

Relevant Interrupts:

#INT_SSP

I2C or SPI activity

#INT_BUSCOL

Bus Collision

#INT_I2C

I2C Interrupt (Only on 14000)

#INT_BUSCOL2

Bus Collision (Only supported on some PIC18's)

#INT_SSP2

I2C or SPI activity (Only supported on some PIC18's)

Relevant Include Files:

None, all functions built-in

Relevant getenv() Parameters:

I2C_SLAVE

Returns a 1 if the device has I2C slave H/W

I2C_MASTER

Returns a 1 if the device has a I2C master H/W

Example Code:

#define Device_SDA PIN_C3

// Pin defines

#define Device_SLC PIN_C4

#use i2c(master,

sda=Device_SDA,

scl=Device_SCL)

// Configure Device as Master

Functional Overview

BYTE data;

// Data to be transmitted

i2c_start();

// Issues a start command when in the I2C master mode.

i2c_write(data);

// Sends a single byte over the I2C interface.

i2c_stop();

// Issues a stop command when in the I2C master mode.

ADC

These options let the user configure and use the analog to digital converter module. They are

only available on devices with the ADC hardware. The options for the functions and directives

vary depending on the chip and are listed in the device header file. On some devices there are

two independent ADC modules, for these chips the second module is configured using

secondary ADC setup functions (Ex. setup_ADC2).

Relevant Functions:

setup_adc(mode)

Sets up the a/d mode like off, the adc clock etc.

setup_adc_ports(value)

Sets the available adc pins to be analog or digital.

set_adc_channel(channel)

Specifies the channel to be use for the a/d call.

read_adc(mode)

Starts the conversion and reads the value. The mode

can also control the functionality.

adc_done()

Returns 1 if the ADC module has finished its conversion.

Relevant Preprocessor:

#DEVICE ADC=xx

Configures the read_adc return size. For example, using

a PIC with a 10 bit A/D you can use 8 or 10 for xx- 8 will

return the most significant byte, 10 will return the full A/D

reading of 10 bits.

Relevant Interrupts:

INT_AD

Interrupt fires when a/d conversion is complete

INT_ADOF

Interrupt fires when a/d conversion has timed out

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

ADC_CHANNELS

Number of A/D channels

ADC_RESOLUTION

Number of bits returned by read_adc

Example Code:

#DEVICE ADC=10

...

Functional Overview

long value;

...

setup_adc(ADC_CLOCK_INTERNAL);

//enables the a/d module

//and sets the clock to internal adc clock

setup_adc_ports(ALL_ANALOG);

//sets all the adc pins to analog

set_adc_channel(0);

//the next read_adc call will read channel 0

delay_us(10);

//a small delay is required after setting the channel

//and before read

value=read_adc();

//starts the conversion and reads the result

//and store it in value

read_adc(ADC_START_ONLY);

//only starts the conversion

value=read_adc(ADC_READ_ONLY);

//reads the result of the last conversion and store it in

//value. Assuming the device hat a 10bit ADC module,

//value will range between 0-3FF. If #DEVICE ADC=8

had //been used instead the result will yield 0-FF. If

#DEVICE //ADC=16 had been used instead the result

will yield 0-//FFC0

Analog Comparator

These functions set up the analog comparator module. Only available in some devices.

Relevant Functions:

setup_comparator(mode)

Enables and sets the analog comparator module. The options

vary depending on the chip. Refer to the header file for

details.

Relevant Preprocessor:

None

Relevant Interrupts:

INT_COMP

Interrupt fires on comparator detect. Some chips have more

than one comparator unit, and thus, more interrupts.

Relevant Include Files:

None, all functions built-in

Relevant getenv() Parameters:

Returns 1 if the device has a

comparator

COMP

Example Code:

setup_comparator(A4_A5_NC_NC);

if(C1OUT)

output_low(PIN_D0);

else

output_high(PIN_D1);

Functional Overview

CAN Bus

These functions allow easy access to the Controller Area Network (CAN) features included with

the MCP2515 CAN interface chip and the PIC18 MCU. These functions will only work with the

MCP2515 CAN interface chip and PIC microcontroller units containing either a CAN or an

ECAN module. Some functions are only available for the ECAN module and are specified by the

work ECAN at the end of the description. The listed interrupts are no available to the MCP2515

interface chip.

Relevant Functions:

can_init(void);

Initializes the CAN module and clears all the filters

and masks so that all messages can be received

from any ID.

can_set_baud(void);

Initializes the baud rate of the CAN bus to125kHz, if

using a 20 MHz clock and the default CAN-BRG

defines, it is called inside the can_init() function so

there is no need to call it.

can_set_mode

(CAN_OP_MODE mode);

Allows the mode of the CAN module to be changed

to configuration mode, listen mode, loop back mode,

disabled mode, or normal mode.

can_set_functional_mode

(CAN_FUN_OP_MODE mode);

Allows the functional mode of ECAN modules to be

changed to legacy mode, enhanced legacy mode,

or first in firstout (fifo) mode. ECAN

can_set_id(int* addr, int32 id, int1 ext);

Can be used to set the filter and mask ID's to the

value specified by addr. It is also used to set the ID

of the message to be sent.

can_get_id(int * addr, int1 ext);

Returns the ID of a received message.

can_putd

(int32 id, int * data, int len,

int priority, int1 ext, int1 rtr);

Constructs a CAN packet using the given

arguments and places it in one of the available

transmit buffers.

can_getd

(int32 & id, int * data, int & len,

struct rx_stat & stat);

Retrieves a received message from one of the CAN

buffers and stores the relevant data in the

referenced function parameters.

can_enable_rtr(PROG_BUFFER b);

Enables the automatic response feature which

automatically sends a user created packet when a

specified ID is received. ECAN

can_disable_rtr(PROG_BUFFER b);

Disables the automatic response feature. ECAN

can_load_rtr

Creates and loads the packet that will automatically

Functional Overview

(PROG_BUFFER b, int * data, int len);

transmitted when the triggering ID is received.

ECAN

can_enable_filter(long filter);

Enables one of the extra filters included in the

ECAN module. ECAN

can_disable_filter(long filter);

Disables one of the extra filters included in the

ECAN module. ECAN

can_associate_filter_to_buffer

(CAN_FILTER_ASSOCIATION_BUFFERS

buffer,CAN_FILTER_ASSOCIATION

filter);

Used to associate a filter to a specific buffer. This

allows only specific buffers to be filtered and is

available in the ECAN module. ECAN

can_associate_filter_to_mask

(CAN_MASK_FILTER_ASSOCIATE

mask,

CAN_FILTER_ASSOCIATION filter);

Used to associate a mask to a specific buffer. This

allows only specific buffer to have this mask applied.

This feature is available in the ECAN module. ECAN

can_fifo_getd(int32 & id,int * data,

int &len,struct rx_stat & stat);

Retrieves the next buffer in the fifo buffer. Only

available in the ECON module while operating in fifo

mode. ECAN

Relevant Preprocessor:

None

Relevant Interrupts:

#int_canirx

This interrupt is triggered when an invalid packet is

received on the CAN.

#int_canwake

This interrupt is triggered when the PIC is woken up

by activity on the CAN.

#int_canerr

This interrupt is triggered when there is an error in

the CAN module.

#int_cantx0

This interrupt is triggered when transmission from

buffer 0 has completed.

#int_cantx1

This interrupt is triggered when transmission from

buffer 1 has completed.

#int_cantx2

This interrupt is triggered when transmission from

buffer 2 has completed.

#int_canrx0

This interrupt is triggered when a message is

received in buffer 0.

#int_canrx1

This interrupt is triggered when a message is

received in buffer 1.

Relevant Include Files:

can-mcp2510.c

Drivers for the MCP2510 and MCP2515 interface

chips

Functional Overview

can-18xxx8.c

Drivers for the built in CAN module

can-18F4580.c

Drivers for the build in ECAN module

Relevant getenv() Parameters:

none

Example Code:

can_init();

// initializes the CAN bus

can_putd(0x300,data,8,3,TRUE,FALSE);

// places a message on the CAN buss with

// ID = 0x300 and eight bytes of data pointed to by

// “data”, the TRUE creates an extended ID, the

// FALSE creates

can_getd(ID,data,len,stat);

// retrieves a message from the CAN bus storing the

// ID in the ID variable, the data at the array pointed

to by

// “data', the number of data bytes in len, and

statistics

// about the data in the stat structure.

CCP1

These options lets to configure and use the CCP module. There might be multiple CCP modules

for a device. These functions are only available on devices with CCP hardware. They operate in

3 modes: capture, compare and PWM. The source in capture/compare mode can be timer1 or

timer3 and in PWM can be timer2 or timer4. The options available are different for different

devices and are listed in the device header file. In capture mode the value of the timer is copied

to the CCP_X register when the input pin event occurs. In compare mode it will trigger an action

when timer and CCP_x values are equal and in PWM mode it will generate a square wave.

Relevant Functions:

setup_ccp1(mode)

Sets the mode to capture, compare or PWM. For capture

set_pwm1_duty(value)

The value is written to the pwm1 to set the duty.

Relevant Preprocessor:

None

Relevant Interrupts :

INT_CCP1

Interrupt fires when capture or compare on CCP1

Relevant Include Files:

None, all functions built-in

Functional Overview

Relevant getenv() parameters:

CCP1

Returns 1 if the device has CCP1

Example Code:

#int_ccp1

void isr()

{

rise = CCP_1;

//CCP_1 is the time the pulse went high

fall = CCP_2;

//CCP_2 is the time the pulse went low

pulse_width = fall - rise;

//pulse width

}

setup_ccp1(CCP_CAPTURE_RE);

// Configure CCP1 to capture rise

setup_ccp2(CCP_CAPTURE_FE);

// Configure CCP2 to capture fall

setup_timer_1(T1_INTERNAL);

// Start timer 1

Some chips also have fuses which allows to multiplex the ccp/pwm on different pins. So check

the fuses to see which pin is set by default. Also fuses to enable/disable pwm outputs.

CCP2, CCP3, CCP4, CCP5, CCP6

Similar to CCP1

Code Profile

Profile a program while it is running. Unlike in-circuit debugging, this tool grabs information

while the program is running and provides statistics, logging and tracing of it's execution. This

is accomplished by using a simple communication method between the processor and the ICD

with minimal side-effects to the timing and execution of the program. Another benefit of code

profile versus in-circuit debugging is that a program written with profile support enabled will run

correctly even if there is no ICD connected.

In order to use Code Profiling, several functions and pre-processor statements need to be

included in the project being compiled and profiled. Doing this adds the proper code profile

run-time support on the microcontroller.

See the help file in the Code Profile tool for more help

and usage examples.

Relevant Functions:

profileout()

Send a user specified message or variable to be displayed or

logged by the code profile tool.

Relevant Pre-Processor:

#use profile()

Global configuration of the code profile run-time on the

microcontroller.

Functional Overview

#profile

Dynamically enable/disable specific elements of the profiler.

Relevant Interrupts:

The profiler can be configured to use a microcontroller's

internal timer for more accurate timing of events over the

clock on the PC. This timer is configured using the #profile

pre-processor command.

Relevant Include Files:

None – all the functions are built into the compiler.

Relevant getenv():

None

Example Code:

#include <18F4520.h>

#use delay(crystal=10MHz, clock=40MHz)

#profile functions, parameters

void main(void)

{

int adc;

setup_adc(ADC_CLOCK_INTERNAL);

set_adc_channel(0);

for(;;)

{

adc = read_adc();

profileout(adc);

delay_ms(250);

}

Configuration Memory

On all PIC18 Family of chips, the configuration memory is readable and writable. This

functionality is not available on the PIC16 Family of devices..

Relevant Functions:

write_configuration_memory

(ramaddress, count)

Writes count bytes, no erase needed

write_configuration_memory

(offset,ramaddress, count)

Writes count bytes, no erase needed starting at byte

address offset

read_configuration_memory

(ramaddress,count)

Read count bytes of configuration memory

Relevant Preprocessor:

None

Functional Overview

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

None

Example Code:

For PIC18f452

int16 data=0xc32;

...

write_configuration_memory(data,2);

//writes 2 bytes to the configuration memory

DAC

These options let the user configure and use the digital to analog converter module. They are

only available on devices with the DAC hardware. The options for the functions and directives

vary depending on the chip and are listed in the device header file.

Relevant Functions:

setup_dac(divisor)

Sets up the DAC e.g. Reference voltages

dac_write(value)

Writes the 8-bit value to the DAC module

Sets up the d/a mode e.g. Right enable, clock divisor

Writes the 16-bit value to the specified channel

Relevant Preprocessor:

#USE DELAY(clock=20M, Aux: crystal=6M, clock=3M)

Relevant Interrupts:

None

Relevant Include Files:

None, all functions built-in

Relevant getenv()

parameters:

None

int8 i=0;

setup_dac

Functional Overview

(DAC_VSS_VDD);

while (TRUE) {

itt;

dac_write(i);

}

Data Eeprom

The data eeprom memory is readable and writable in some chips. These options lets the user

read and write to the data eeprom memory. These functions are only available in flash chips.

Relevant Functions:

(8 bit or 16 bit depending on the

device)

read_eeprom(address)

Reads the data EEPROM memory location

write_eeprom(address, value)

Erases and writes value to data EEPROM location address.

Reads N bytes of data EEPROM starting at memory location

address. The maximum return size is int64.

Reads from EEPROM to fill variable starting at address

Reads N bytes, starting at address, to pointer

Writes value to EEPROM address

Writes N bytes to address from pointer

Relevant Preprocessor:

#ROM address={list}

Can also be used to put data EEPROM memory data into the

hex file.

write_eeprom = noint

Allows interrupts to occur while the write_eeprom() operations

is polling the done bit to check if the write operations has

completed. Can be used as long as no EEPROM operations

are performed during an ISR.

Relevant Interrupts:

INT_EEPROM

Interrupt fires when EEPROM write is complete

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

DATA_EEPROM

Size of data EEPROM memory.

Example Code:

For 18F452

#rom 0xf00000={1,2,3,4,5}

//inserts this data into the hex file. The data eeprom address

//differs for different family of chips. Please refer to the

//programming specs to find the right value for the device

Functional Overview

write_eeprom(0x0,0x12);

//writes 0x12 to data eeprom location 0

value=read_eeprom(0x0);

//reads data eeprom location 0x0 returns 0x12

#ROM 0x007FFC00={1,2,3,4,5}

// Inserts this data into the hex file

// The data EEPROM address differs between PICs

// Please refer to the device editor for device specific values.

write_eeprom(0x10, 0x1337);

// Writes 0x1337 to data EEPROM location 10.

value=read_eeprom(0x0);

// Reads data EEPROM location 10 returns 0x1337.

Data Signal Modulator

The Data Signal Modulator (DSM) allows the user to mix a digital data stream (the “modulator

signal”) with a carrier signal to produce a modulated output. Both the carrier and the modulator

signals are supplied to the DSM module, either internally from the output of a peripheral, or

externally through an input pin. The modulated output signal is generated by performing a

logical AND operation of both the carrier and modulator signals and then it is provided to the

MDOUT pin. Using this method, the DSM can generate the following types of key modulation

schemes:

 Frequency Shift Keying (FSK)

 Phase Shift Keying (PSK)

 On-Off Keying (OOK)

Relevant Functions:

(8 bit or 16 bit depending on the

device)

setup_dsm(mode,source,carrier)

Configures the DSM module and selects the source signal and

carrier signals.

setup_dsm(TRUE)

Enables the DSM module.

setup_dsm(FALSE)

Disables the DSM module.

Relevant Preprocessor:

None

Relevant Interrupts:

None

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

None

Functional Overview

Example Code:

setup_dsm(DSM_ENABLED |

//Enables DSM module with the output enabled and selects

UART1

DSM_OUTPUT_ENABLED,

//as the source signal and VSS as the high carrier signal and OC1's

DSM_SOURCE_UART1,

//PWM output as the low carrier signal.

DSM_CARRIER_HIGH_VSS |

DSM_CARRIER_LOW_OC1);

if(input(PIN_B0))

setup_dsm(FALSE);

Disable DSM module

else

setup_dsm(TRUE);

Enable DSM module

External Memory

Some PIC18 devices have the external memory functionality where the external memory can be

mapped to external memory devices like (Flash, EPROM or RAM). These functions are

available only on devices that support external memory bus.

General Purpose I/O

These options let the user configure and use the I/O pins on the device. These functions will

affect the pins that are listed in the device header file.

Relevant Functions:

output_high(pin)

Sets the given pin to high state.

output_low(pin)

Sets the given pin to the ground state.

output_float(pin)

Sets the specified pin to the output mode. This will allow the pin

to float high to represent a high on an open collector type of

connection.

output_x(value)

Outputs an entire byte to the port.

output_bit(pin,value)

Outputs the specified value (0,1) to the specified I/O pin.

input(pin)

The function returns the state of the indicated pin.

input_state(pin)

This function reads the level of a pin without changing the

direction of the pin as INPUT() does.

set_tris_x(value)

Sets the value of the I/O port direction register. A '1' is an input

and '0' is for output.

input_change_x( )

This function reads the levels of the pins on the port, and

compares them to the last time they were read to see if there was

a change, 1 if there was, 0 if there wasn't.

Relevant Preprocessor:

#USE STANDARD_IO(port)

This compiler will use this directive be default and it will

automatically inserts code for the direction register whenever an

Functional Overview

I/O function like output_high() or input() is used.

#USE FAST_IO(port)

This directive will configure the I/O port to use the fast method of

performing I/O. The user will be responsible for setting the port

direction register using the set_tris_x() function.

#USE FIXED_IO

(port_outputs=;in,pin?)

This directive set particular pins to be used an input or output,

and the compiler will perform this setup every time this pin is

used.

Relevant Interrupts:

None

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

PIN:pb

Returns a 1 if bit b on port p is on this part

Example Code:

#use fast_io(b)

...

Int8 Tris_value= 0x0F;

int1 Pin_value;

...

set_tris_b(Tris_value);

//Sets B0:B3 as input and B4:B7 as output

output_high(PIN_B7);

//Set the pin B7 to High

If(input(PIN_B0)){

//Read the value on pin B0, set B7 to low if pin B0 is high

output_high(PIN_B7);}

Internal LCD

Some families of PIC microcontrollers can drive a glass segment LCD directly, without the need

of an LCD controller. For example, the PIC16C92X, PIC16F91X, and PIC16F193X series of

chips have an internal LCD driver module.

Relevant Functions:

setup_lcd

(mode, prescale, [segments])

Configures the LCD Driver Module to use the specified mode,

timer prescaler, and segments. For more information on valid

modes and settings, see the setup_lcd( ) manual page and the

*.h header file for the PIC micro-controller being used.

lcd_symbol

(symbol, segment_b7 ...

segment_b0)

The specified symbol is placed on the desired segments, where

segment_b7 to segment_b0 represent SEGXX pins on the PIC

micro-controller. For example, if bit 0 of symbol is set, then

segment_b0 is set, and if segment_b0 is 15, then SEG15 would

be set.

Functional Overview

lcd_load(ptr, offset, length)

Writes length bytes of data from pointer directly to the LCD

segment memory, starting with offset.

lcd_contrast (contrast)

Passing a value of 0 – 7 will change the contrast of the LCD

segments, 0 being the minimum, 7 being the maximum.

Relevant Preprocessor:

None

Relevant Interrupts:

#int_lcd

LCD frame is complete, all pixels displayed

Relevant Inlcude Files:

None, all functions built-in to the compiler.

Relevant getenv() Parameters:

LCD

Returns TRUE if the device has an Internal LCD Driver Module.

Example Program:

// How each segment of the LCD is set (on or off) for the ASCII digits 0 to 9.

byte CONST DIGIT_MAP[10] = {0xFC, 0x60, 0xDA, 0xF2, 0x66, 0xB6, 0xBE, 0xE0, 0xFE,

0xE6};

// Define the segment information for the first digit of the LCD

#define DIGIT1 COM1+20, COM1+18, COM2+18, COM3+20, COM2+28, COM1+28,

COM2+20, COM3+18

// Displays the digits 0 to 9 on the first digit of the LCD.

for(i = 0; i <= 9; i++) {

lcd_symbol( DIGIT_MAP[i], DIGIT1 );

delay_ms( 1000 );

}

Internal Oscillator

Many chips have internal oscillator. There are different ways to configure the internal oscillator.

Some chips have a constant 4 Mhz factory calibrated internal oscillator. The value is stored in

some location (mostly the highest program memory) and the compiler moves it to the osccal

be programmed before the oscillator is functioning properly. Some chips have factory calibrated

internal oscillator that offers software selectable frequency range(from 31Kz to 8 Mhz) and they

have a default value and can be switched to a higher/lower value in software. They are also

software tunable. Some chips also provide the PLL option for the internal oscillator.

Relevant Functions:

setup_oscillator(mode,

finetune)

Sets the value of the internal oscillator and also tunes it. The

options vary depending on the chip and are listed in the device

Functional Overview

header files.

Relevant Preprocessor:

None

Relevant Interrupts:

INT_OSC_FAIL or INT_OSCF

Interrupt fires when the system oscillator fails and the processor

switches to the internal oscillator.

Relevant Include Files:

None, all functions built-in

Relevant getenv()

parameters:

None

Example Code:

For PIC18F8722

setup_oscillator(OSC_32MHZ);

//sets the internal oscillator to 32MHz (PLL enabled)

If the internal oscillator fuse option are specified in the #fuses and a valid clock is specified in

the #use delay(clock=xxx) directive the compiler automatically sets up the oscillator. The #use

delay statements should be used to tell the compiler about the oscillator speed.

Interrupts

The following functions allow for the control of the interrupt subsystem of the microcontroller.

With these functions, interrupts can be enabled, disabled, and cleared. With the preprocessor

directives, a default function can be called for any interrupt that does not have an associated

ISR, and a global function can replace the compiler generated interrupt dispatcher.

Relevant Functions:

disable_interrupts()

Disables the specified interrupt.

enable_interrupts()

Enables the specified interrupt.

ext_int_edge()

Enables the edge on which the edge interrupt should trigger. This

can be either rising or falling edge.

clear_interrupt()

This function will clear the specified interrupt flag. This can be

used if a global isr is used, or to prevent an interrupt from being

serviced.

interrupt_active()

This function checks the interrupt flag of specified interrupt and

returns true if flag is set.

interrupt_enabled()

This function checks the interrupt enable flag of the specified

interrupt and returns TRUE if set.

Relevant Preprocessor:

Functional Overview

#DEVICE HIGH_INTS=

This directive tells the compiler to generate code for high priority

interrupts.

#INT_XXX fast

This directive tells the compiler that the specified interrupt should

be treated as a high priority interrupt.

Relevant Interrupts:

#int_default

This directive specifies that the following function should be called

if an interrupt is triggered but no routine is associated with that

interrupt.

#int_global

This directive specifies that the following function should be called

whenever an interrupt is triggered. This function will replace the

compiler generated interrupt dispatcher.

#int_xxx

This directive specifies that the following function should be called

whenever the xxx interrupt is triggered. If the compiler generated

interrupt dispatcher is used, the compiler will take care of clearing

the interrupt flag bits.

Relevant Include Files:

none, all functions built in.

Relevant getenv()

Parameters:

none

Example Code:

#int_timer0

void timer0interrupt()

// #int_timer associates the following function with the

// interrupt service routine that should be called

enable_interrupts(TIMER0);

// enables the timer0 interrupt

disable_interrtups(TIMER0);

// disables the timer0 interrupt

clear_interrupt(TIMER0);

// clears the timer0 interrupt flag

Low Voltage Detect

These functions configure the high/low voltage detect module. Functions available on the chips

that have the low voltage detect hardware.

Relevant Functions:

setup_low_volt_detect(mode)

Sets the voltage trigger levels and also the mode (below or

above in case of the high/low voltage detect module). The

options vary depending on the chip and are listed in the

device header files.

Functional Overview

Relevant Preprocessor:

None

Relevant Interrupts :

INT_LOWVOLT

Interrupt fires on low voltage detect

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

None

Example Code:

For PIC18F8722

setup_low_volt_detect

(LVD_36|LVD_TRIGGER_ABOVE);

//sets the trigger level as 3.6 volts and

// trigger direction as above. The interrupt

//if enabled is fired when the voltage is

//above 3.6 volts.

PMP/EPMP

The Parallel Master Port (PMP)/Enhanced Parallel Master Port (EPMP) is a parallel 8-bit/16-bit

I/O module specifically designed to communicate with a wide variety of parallel devices. Key

features of the PMP module are:

· 8 or 16 Data lines

· Up to 16 or 32 Programmable Address Lines

· Up to 2 Chip Select Lines

· Programmable Strobe option

· Address Auto-Increment/Auto-Decrement

· Programmable Address/Data Multiplexing

· Programmable Polarity on Control Signals

· Legacy Parallel Slave(PSP) Support

· Enhanced Parallel Slave Port Support

· Programmable Wait States

Relevant Functions:

This will setup the PMP/EPMP module for various mode and

specifies which address lines to be used.

setup_psp

(options,address_mask)

This will setup the PSP module for various mode and specifies

which address lines to be used.

setup_pmp_csx(options,[offset])

Sets up the Chip Select X Configuration, Mode and Base

Address registers

setup_psp_es(options)

Sets up the Chip Select X Configuration and Mode registers

Write the data byte to the next buffer location.

Functional Overview

This will write a byte of data to the next buffer location or will

write a byte to the specified buffer location.

Reads a byte of data.

psp_read() will read a byte of data from the next buffer

location and psp_read ( address ) will read the buffer location

address.

Configures the address register of the PMP module with the

destination address during Master mode operation.

This will return the status of the output buffer underflow bit.

This will return the status of the input buffers.

psp_input_full()

This will return the status of the input buffers.

This will return the status of the output buffers.

psp_output_full()

This will return the status of the output buffers.

Relevant Preprocessor:

None

Relevant Interrupts :

#INT_PMP

Interrupt on read or write strobe

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

None

Example Code:

setup_pmp( PAR_ENABLE |

Sets up Master mode with address lines PMA0:PMA7

PAR_MASTER_MODE_1 |

PAR_STOP_IN_IDLE,0x00FF );

If ( pmp_output_full ( ))

{

pmp_write(next_byte);

}

Power PWM

These options lets the user configure the Pulse Width Modulation (PWM) pins. They are only

available on devices equipped with PWM. The options for these functions vary depending on

the chip and are listed in the device header file.

Relevant Functions:

Functional Overview

setup_power_pwm(config)

Sets up the PWM clock, period, dead time etc.

setup_power_pwm_pins(module x)

Configure the pins of the PWM to be in

Complimentary, ON or OFF mode.

set_power_pwmx_duty(duty)

Stores the value of the duty cycle in the PDCXL/H

which the PWM is in active state.

set_power_pwm_override(pwm,override,valu

This function determines whether the OVDCONS

or the PDC registers determine the PWM output .

Relevant Preprocessor:

None

Relevant Interrupts:

#INT_PWMTB

PWM Timebase Interrupt (Only available on

PIC18XX31)

Relevant getenv() Parameters:

None

Example Code:

....

long duty_cycle, period;

...

// Configures PWM pins to be ON,OFF or in Complimentary mode.

setup_power_pwm_pins(PWM_COMPLEMENTARY ,PWM_OFF, PWM_OFF, PWM_OFF);

//Sets up PWM clock , postscale and period. Here period is used to set the

//PWM Frequency as follows:

//Frequency = Fosc / (4 * (period+1) *postscale)

setup_power_pwm(PWM_CLOCK_DIV_4|PWM_FREE_RUN,1,0,period,0,1,0);

set_power_pwm0_duty(duty_cycle));

// Sets the duty cycle of the PWM 0,1 in

//Complementary mode

Functional Overview

Program Eeprom

The Flash program memory is readable and writable in some chips and is just readable in

some. These options lets the user read and write to the Flash program memory. These

functions are only available in flash chips.

Relevant Functions:

read_program_eeprom(address)

Reads the program memory location (16 bit or

32 bit depending on the device).

write_program_eeprom(address, value)

Writes value to program memory location

address.

erase_program_eeprom(address)

Erases FLASH_ERASE_SIZE bytes in program

memory.

write_program_memory(address,dataptr,count)

Writes count bytes to program memory from

dataptr to address. When address is a mutiple

of FLASH_ERASE_SIZE an erase is also

performed.

read_program_memory(address,dataptr,count)

Read count bytes from program memory at

address to dataptr.

Relevant Preprocessor:

#ROM address={list}

Can be used to put program memory data into

the hex file.

#DEVICE(WRITE_EEPROM=ASYNC)

Can be used with #DEVICE to prevent the write

function from hanging. When this is used make

sure the eeprom is not written both inside and

outside the ISR.

Relevant Interrupts:

INT_EEPROM

Interrupt fires when eeprom write is complete.

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters

PROGRAM_MEMORY

Size of program memory

READ_PROGRAM

Returns 1 if program memory can be read

FLASH_WRITE_SIZE

Smallest number of bytes written in flash

FLASH_ERASE_SIZE

Smallest number of bytes erased in flash

Functional Overview

Example Code:

For 18F452 where the write size is 8 bytes and erase size is 64 bytes

#rom 0xa00={1,2,3,4,5}

//inserts this data into the hex file.

erase_program_eeprom(0x1000);

//erases 64 bytes strting at 0x1000

write_program_eeprom(0x1000,0x1234);

//writes 0x1234 to 0x1000

value=read_program_eeprom(0x1000);

//reads 0x1000 returns 0x1234

write_program_memory(0x1000,data,8);

//erases 64 bytes starting at 0x1000 as 0x1000

is a multiple

//of 64 and writes 8 bytes from data to 0x1000

read_program_memory(0x1000,value,8);

//reads 8 bytes to value from 0x1000

erase_program_eeprom(0x1000);

//erases 64 bytes starting at 0x1000

write_program_memory(0x1010,data,8);

//writes 8 bytes from data to 0x1000

read_program_memory(0x1000,value,8);

//reads 8 bytes to value from 0x1000

For chips where getenv("FLASH_ERASE_SIZE") > getenv("FLASH_WRITE_SIZE")

WRITE_PROGRAM_EEPROM -

Writes 2 bytes,does not erase (use

ERASE_PROGRAM_EEPROM)

WRITE_PROGRAM_MEMORY -

Writes any number of bytes,will erase a block

whenever the first (lowest) byte in a block is

written to. If the first address is not the start of a

block that block is not erased.

ERASE_PROGRAM_EEPROM -

Will erase a block. The lowest address bits are

not used.

For chips where getenv("FLASH_ERASE_SIZE") = getenv("FLASH_WRITE_SIZE")

WRITE_PROGRAM_EEPROM -

Writes 2 bytes, no erase is needed.

WRITE_PROGRAM_MEMORY -

Writes any number of bytes, bytes outside the

range of the write block are not changed. No

erase is needed.

ERASE_PROGRAM_EEPROM -

Not available.

Functional Overview

PSP

These options let to configure and use the Parallel Slave Port on the supported devices.

Relevant Functions:

setup_psp(mode)

Enables/disables the psp port on the chip

psp_output_full()

Returns 1 if the output buffer is full(waiting to be read by the

external bus)

psp_input_full()

Returns 1 if the input buffer is full(waiting to read by the cpu)

psp_overflow()

Returns 1 if a write occurred before the previously written byte

was read

Relevant Preprocessor:

None

Relevant Interrupts :

INT_PSP

Interrupt fires when PSP data is in

Relevant Include Files:

None, all functions built-in

Relevant getenv()

parameters:

PSP

Returns 1 if the device has PSP

Example Code:

while(psp_output_full());

//waits till the output buffer is cleared

psp_data=command;

//writes to the port

while(!input_buffer_full());

//waits till input buffer is cleared

if (psp_overflow())

error=true

//if there is an overflow set the error flag

else

data=psp_data;

//if there is no overflow then read the port

Functional Overview

QEI

The Quadrature Encoder Interface (QEI) module provides the interface to incremental encoders

for obtaining mechanical positional data.

Relevant Functions:

setup_qei(options, filter,maxcount)

Configures the QEI module.

qei_status( )

Returns the status of the QUI module.

qei_set_count(value)

Write a 16-bit value to the position counter.

qei_get_count( )

Reads the current 16-bit value of the position counter.

Relevant Preprocessor:

None

Relevant Interrupts :

#INT_QEI

Interrupt on rollover or underflow of the position counter.

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

None

Example Code:

int16 Value;

setup_qei(QEI_MODE_X2 |

Setup the QEI module

QEI_TIMER_INTERNAL,

QEI_FILTER_DIV_2,QEI_FORWARD);

Value = qei_get_count( );

Read the count.

Functional Overview

RS232 I/O

These functions and directives can be used for setting up and using RS232 I/O functionality.

Relevant Functions:

getc() or getch()

getchar() or fgetc()

Gets a character on the receive pin(from the specified stream

in case of fgetc, stdin by default). Use KBHIT to check if the

character is available.

gets() or fgets()

Gets a string on the receive pin(from the specified stream in

case of fgets, STDIN by default). Use getc to receive each

character until return is encountered.

putc() or putchar() or

fputc()

Puts a character over the transmit pin(on the specified stream

in the case of fputc, stdout by default)

puts() or fputs()

Puts a string over the transmit pin(on the specified stream in

the case of fputc, stdout by default). Uses putc to send each

character.

printf() or fprintf()

Prints the formatted string(on the specified stream in the case

of fprintf, stdout by default). Refer to the printf help for details

on format string.

kbhit()

Return true when a character is received in the buffer in case

of hardware RS232 or when the first bit is sent on the RCV pin

in case of software RS232. Useful for polling without waiting in

getc.

setup_uart(baud,[stream])

setup_uart_speed(baud,[stream])

Used to change the baud rate of the hardware UART at run-

time. Specifying stream is optional. Refer to the help for more

advanced options.

assert(condition)

Checks the condition and if false prints the file name and line

to STDERR. Will not generate code if #DEFINE NODEBUG is

used.

perror(message)

Prints the message and the last system error to STDERR.

putc_send() or fputc_send()

When using transmit buffer, used to transmit data from buffer.

See function description for more detail on when needed.

rcv_buffer_bytes()

When using receive buffer, returns the number of bytes in

buffer that still need to be retrieved.

Functional Overview

tx_buffer_bytes()

When using transmit buffer, returns the number of bytes in

buffer that still need to be sent.

tx_buffer_full()

When using transmit buffer, returns TRUE if transmit buffer is

full.

receive_buffer_full()

When using receive buffer, returns TRUE if receive buffer is

full.

Relevant Interrupts:

INT_RDA

Interrupt fires when the receive data available

INT_TBE

Interrupt fires when the transmit data empty

Some chips have more than one hardware uart, and hence more interrupts.

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

UART

Returns the number of UARTs on this PIC

AUART

Returns true if this UART is an advanced UART

UART_RX

Returns the receive pin for the first UART on this PIC (see

PIN_XX)

UART_TX

Returns the transmit pin for the first UART on this PIC

UART2_RX

Returns the receive pin for the second UART on this PIC

UART2_TX

TX – Returns the transmit pin for the second UART on this

PIC

Example Code:

/* configure and enable uart, use first hardware UART on PIC */

#use rs232(uart1, baud=9600)

/* print a string */

printf(“enter a character”);

/* get a character */

if (kbhit())

//check if a character has been received

c = getc();

//read character from UART

Functional Overview

RTOS

These functions control the operation of the CCS Real Time Operating System (RTOS). This

operating system is cooperatively multitasking and allows for tasks to be scheduled to run at

specified time intervals. Because the RTOS does not use interrupts, the user must be careful to

make use of the rtos_yield() function in every task so that no one task is allowed to run forever.

Relevant Functions:

rtos_run()

Begins the operation of the RTOS. All task management

tasks are implemented by this function.

rtos_terminate()

This function terminates the operation of the RTOS and

returns operation to the original program. Works as a

return from the rtos_run()function.

rtos_enable(task)

Enables one of the RTOS tasks. Once a task is enabled,

the rtos_run() function will call the task when its time

occurs. The parameter to this function is the name of task

to be enabled.

rtos_disable(task)

Disables one of the RTOS tasks. Once a task is disabled,

the rtos_run() function will not call this task until it is

enabled using rtos_enable(). The parameter to this

function is the name of the task to be disabled.

rtos_msg_poll()

Returns true if there is data in the task's message queue.

rtos_msg_read()

Returns the next byte of data contained in the task's

message queue.

rtos_msg_send(task,byte)

Sends a byte of data to the specified task. The data is

placed in the receiving task's message queue.

rtos_yield()

Called with in one of the RTOS tasks and returns control

of the program to the rtos_run() function. All tasks should

call this function when finished.

rtos_signal(sem)

Increments a semaphore which is used to broadcast the

availability of a limited resource.

rtos_wait(sem)

Waits for the resource associated with the semaphore to

become available and then decrements to semaphore to

claim the resource.

rtos_await(expre)

Will wait for the given expression to evaluate to true

before allowing the task to continue.

Functional Overview

rtos_overrun(task)

Will return true if the given task over ran its alloted time.

rtos_stats(task,stat)

Returns the specified statistic about the specified task.

The statistics include the minimum and maximum times

for the task to run and the total time the task has spent

running.

Relevant Preprocessor:

#USE RTOS(options)

This directive is used to specify several different RTOS

attributes including the timer to use, the minor cycle time

and whether or not statistics should be enabled.

#TASK(options)

This directive tells the compiler that the following function

is to be an RTOS task.

#TASK

specifies the rate at which the task should be called, the

maximum time the task shall be allowed to run, and how

large it's queue should be

Relevant Interrupts:

none

Relevant Include Files:

none all functions are built in

Relevant getenv() Parameters:

none

Example Code:

#USE

RTOS(timer=0,minor_cycle=20ms)

// RTOS will use timer zero, minor cycle will be 20ms

...

int sem;

...

#TASK(rate=1s,max=20ms,queue=5)

// Task will run at a rate of once per second

void task_name();

// with a maximum running time of 20ms and

// a 5 byte queue

rtos_run();

// begins the RTOS

rtos_terminate();

// ends the RTOS

rtos_enable(task_name);

// enables the previously declared task.

rtos_disable(task_name);

// disables the previously declared task

rtos_msg_send(task_name,5);

// places the value 5 in task_names queue.

rtos_yield();

// yields control to the RTOS

rtos_sigal(sem);

// signals that the resource represented by sem is

available.

For more information on the CCS RTOS please

Functional Overview

SPI

SPI™ is a fluid standard for 3 or 4 wire, full duplex communications named by Motorola. Most

PIC devices support most common SPI™ modes. CCS provides a support library for taking

advantage of both hardware and software based SPI™ functionality. For software support, see

#USE SPI.

Relevant Functions:

setup_spi(mode)

setup_spi2(mode)

setup_spi3 (mode)

setup_spi4 (mode)

Configure the hardware SPI to the specified mode. The mode

configures setup_spi2(mode) thing such as master or slave

mode, clock speed and clock/data trigger configuration.

Note: for devices with dual SPI interfaces a second function, setup_spi2(), is provided to

configure the second interface.

spi_data_is_in()

Returns TRUE if the SPI receive buffer has a byte of data.

spi_data_is_in2()

spi_write(value)

spi_write2(value)

Transmits the value over the SPI interface. This will cause the

data to be clocked out on the SDO pin.

spi_read(value)

spi_read2(value)

Performs an SPI transaction, where the value is clocked out on

the SDO pin and data clocked in on the SDI pin is returned. If

you just want to clock in data then you can use spi_read() without

a parameter.

Relevant Preprocessor:

None

Relevant Interrupts:

#int_ssp

#int_ssp2

Transaction (read or write) has completed on the indicated

peripheral.

Relevant getenv() Parameters:

SPI

Returns TRUE if the device has an SPI peripheral

Example Code:

//configure the device to be a master, data transmitted on H-to-L clock transition

setup_spi(SPI_MASTER | SPI_H_TO_L | SPI_CLK_DIV_16);

spi_write(0x80);

//write 0x80 to SPI device

value=spi_read();

//read a value from the SPI device

value=spi_read(0x80);

//write 0x80 to SPI device the same time you are reading a value.

Functional Overview

Timer0

These options lets the user configure and use timer0. It is available on all devices and is always

enabled. The clock/counter is 8-bit on pic16s and 8 or 16 bit on pic18s. It counts up and also

provides interrupt on overflow. The options available differ and are listed in the device header

file.

Relevant Functions:

setup_timer_0(mode)

Sets the source, prescale etc for timer0

set_timer0(value) or

set_rtcc(value)

Initializes the timer0 clock/counter. Value may be a 8 bit or 16

bit depending on the device.

value=get_timer0

Returns the value of the timer0 clock/counter

Relevant Preprocessor:

None

Relevant Interrupts :

INT_TIMER0 or INT_RTCC

Interrupt fires when timer0 overflows

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

TIMER0

Returns 1 if the device has timer0

Example Code:

For PIC18F452

setup_timer_0(RTCC_INTERNAL

|RTCC_DIV_2|RTCC_8_BIT);

//sets the internal clock as source

//and prescale 2. At 20Mhz timer0

//will increment every 0.4us in this

//setup and overflows every

//102.4us

set_timer0(0);

//this sets timer0 register to 0

time=get_timer0();

//this will read the timer0 register

//value

Functional Overview

Timer1

These options lets the user configure and use timer1. The clock/counter is 16-bit on pic16s and

pic18s. It counts up and also provides interrupt on overflow. The options available differ and are

listed in the device header file.

Relevant Functions:

setup_timer_1(mode)

Disables or sets the source and prescale for

timer1

set_timer1(value)

Initializes the timer1 clock/counter

value=get_timer1

Returns the value of the timer1 clock/counter

Relevant Preprocessor:

None

Relevant Interrupts:

INT_TIMER1

Interrupt fires when timer1 overflows

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

TIMER1

Returns 1 if the device has timer1

Example Code:

For PIC18F452

setup_timer_1(T1_DISABLED);

//disables timer1

setup_timer_1(T1_INTERNAL|T1_DIV_BY_8);

//sets the internal clock as source

//and prescale as 8. At 20Mhz timer1 will

increment

//every 1.6us in this setup and overflows every

//104.896ms

set_timer1(0);

//this sets timer1 register to 0

time=get_timer1();

//this will read the timer1 register value

Functional Overview

Timer2

These options lets the user configure and use timer2. The clock/counter is 8-bit on pic16s and

pic18s. It counts up and also provides interrupt on overflow. The options available differ and are

listed in the device header file.

Relevant Functions:

setup_timer_2

(mode,period,postscale)

Disables or sets the prescale, period and a postscale for

timer2

set_timer2(value)

Initializes the timer2 clock/counter

value=get_timer2

Returns the value of the timer2 clock/counter

Relevant Preprocessor:

None

Relevant Interrupts:

INT_TIMER2

Interrupt fires when timer2 overflows

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

TIMER2

Returns 1 if the device has timer2

Example Code:

For PIC18F452

setup_timer_2(T2_DISABLED);

//disables timer2

setup_timer_2(T2_DIV_BY_4,0xc0,2);

//sets the prescale as 4, period as 0xc0 and

//postscales as 2.

//At 20Mhz timer2 will increment every .8us in this

//setup overflows every 154.4us and interrupt every

308.2us

set_timer2(0);

//this sets timer2 register to 0

time=get_timer2();

//this will read the timer1 register value

Timer3

Timer3 is very similar to timer1. So please refer to the Timer1 section for more details.

Timer4

Timer4 is very similar to Timer2. So please refer to the Timer2 section for more details.

Functional Overview

Timer5

These options lets the user configure and use timer5. The clock/counter is 16-bit and is

available only on 18Fxx31 devices. It counts up and also provides interrupt on overflow. The

options available differ and are listed in the device header file.

Relevant Functions:

setup_timer_5(mode)

Disables or sets the source and prescale for

imer5

set_timer5(value)

Initializes the timer5 clock/counter

value=get_timer5

Returns the value of the timer51 clock/counter

Relevant Preprocessor:

None

Relevant Interrupts :

INT_TIMER5

Interrupt fires when timer5 overflows

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

TIMER5

Returns 1 if the device has timer5

Example Code:

For PIC18F4431

setup_timer_5(T5_DISABLED)

//disables timer5

setup_timer_5(T5_INTERNAL|T5_DIV_BY_1);

//sets the internal clock as source and

//prescale as 1.

//At 20Mhz timer5 will increment every .2us in

this

//setup and overflows every 13.1072ms

set_timer5(0);

//this sets timer5 register to 0

time=get_timer5();

//this will read the timer5 register value

Functional Overview

TimerA

These options lets the user configure and use timerA. It is available on devices with Timer A

hardware. The clock/counter is 8 bit. It counts up and also provides interrupt on overflow. The

options available are listed in the device's header file.

Relevant Functions:

setup_timer_A(mode)

Disable or sets the source and prescale for timerA

set_timerA(value)

Initializes the timerA clock/counter

value=get_timerA()

Returns the value of the timerA clock/counter

Relevant Preprocessor:

None

Relevant Interrupts :

INT_TIMERA

Interrupt fires when timerA overflows

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

TIMERA

Returns 1 if the device has timerA

Example Code:

setup_timer_A(TA_OFF);

//disable timerA

setup_timer_A

//sets the internal clock as source

(TA_INTERNAL | TA_DIV_8);

//and prescale as 8. At 20MHz timerA will increment

//every 1.6us in this setup and overflows every

//409.6us

set_timerA(0);

//this sets timerA register to 0

time=get_timerA();

//this will read the timerA register value

Functional Overview

TimerB

These options lets the user configure and use timerB. It is available on devices with TimerB

hardware. The clock/counter is 8 bit. It counts up and also provides interrupt on overflow. The

options available are listed in the device's header file.

Relevant Functions:

setup_timer_B(mode)

Disable or sets the source and prescale for timerB

set_timerB(value)

Initializes the timerB clock/counter

value=get_timerB()

Returns the value of the timerB clock/counter

Relevant Preprocessor:

None

Relevant Interrupts :

INT_TIMERB

Interrupt fires when timerB overflows

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

TIMERB

Returns 1 if the device has timerB

Example Code:

setup_timer_B(TB_OFF);

//disable timerB

setup_timer_B

//sets the internal clock as source

(TB_INTERNAL | TB_DIV_8);

//and prescale as 8. At 20MHz timerB will increment

//every 1.6us in this setup and overflows every

//409.6us

set_timerB(0);

//this sets timerB register to 0

time=get_timerB();

//this will read the timerB register value

Functional Overview

USB

Universal Serial Bus, or USB, is used as a method for peripheral devices to connect to and talk

to a personal computer. CCS provides libraries for interfacing a PIC to PC using USB by using

a PIC with an internal USB peripheral (like the PIC16C765 or the PIC18F4550 family) or by

using any PIC with an external USB peripheral (the National USBN9603 family).

Relevant Functions:

usb_init()

Initializes the USB hardware. Will then wait in an infinite loop for the

USB peripheral to be connected to bus (but that doesn't mean it has

been enumerated by the PC). Will enable and use the USB interrupt.

usb_init_cs()

The same as usb_init(), but does not wait for the device to be

connected to the bus. This is useful if your device is not bus powered

and can operate without a USB connection.

usb_task()

If you use connection sense, and the usb_init_cs() for initialization, then

you must periodically call this function to keep an eye on the connection

sense pin. When the PIC is connected to the BUS, this function will then

perpare the USB peripheral. When the PIC is disconnected from the

BUS, it will reset the USB stack and peripheral. Will enable and use the

USB interrupt.

Note: In your application you must define USB_CON_SENSE_PIN to the connection sense pin.

usb_detach()

Removes the PIC from the bus. Will be called automatically by

usb_task() if connection is lost, but can be called manually by the user.

usb_attach()

Attaches the PIC to the bus. Will be called automatically by usb_task()

if connection is made, but can be called manually by the user.

usb_attached()

If using connection sense pin (USB_CON_SENSE_PIN), returns TRUE

if that pin is high. Else will always return TRUE.

usb_enumerated()

Returns TRUE if the device has been enumerated by the PC. If the

device has been enumerated by the PC, that means it is in normal

operation mode and you can send/receive packets.

usb_put_packet

(endpoint, data, len, tgl)

Places the packet of data into the specified endpoint buffer. Returns

TRUE if success, FALSE if the buffer is still full with the last packet.

usb_puts

(endpoint, data, len,

timeout)

Sends the following data to the specified endpoint. usb_puts() differs

from usb_put_packet() in that it will send multi packet messages if the

data will not fit into one packet.

usb_kbhit(endpoint)

Returns TRUE if the specified endpoint has data in it's receive buffer

usb_get_packet

Reads up to max bytes from the specified endpoint buffer and saves it

Functional Overview

(endpoint, ptr, max)

to the pointer ptr. Returns the number of bytes saved to ptr.

usb_gets(endpoint, ptr,

max, timeout)

Reads a message from the specified endpoint. The difference

usb_get_packet() and usb_gets() is that usb_gets() will wait until a full

message has received, which a message may contain more than one

packet. Returns the number of bytes received.

Relevant CDC Functions:

A CDC USB device will emulate an RS-232 device, and will appear on your PC as a COM port.

The follow functions provide you this virtual RS-232/serial interface

Note: When using the CDC library, you can use the same functions above, but do not use the

packet related function such as

usb_kbhit(), usb_get_packet(), etc.

usb_cdc_kbhit()

The same as kbhit(), returns TRUE if there is 1 or more character in the

receive buffer.

usb_cdc_getc()

The same as getc(), reads and returns a character from the receive

buffer. If there is no data in the receive buffer it will wait indefinitely until

there a character has been received.

usb_cdc_putc(c)

The same as putc(), sends a character. It actually puts a character into

the transmit buffer, and if the transmit buffer is full will wait indefinitely

until there is space for the character.

usb_cdc_putc_fast(c)

The same as usb_cdc_putc(), but will not wait indefinitely until there is

space for the character in the transmit buffer. In that situation the

character is lost.

usb_cdc_puts(*str)

Sends a character string (null terminated) to the USB CDC port. Will

return FALSE if the buffer is busy, TRUE if buffer is string was put into

buffer for sending. Entire string must fit into endpoint, if string is longer

than endpoint buffer then excess characters will be ignored.

usb_cdc_putready()

Returns TRUE if there is space in the transmit buffer for another

character.

Relevant Preporcessor:

None

Relevant Interrupts:

#int_usb

A USB event has happened, and requires application intervention. The

USB library that CCS provides handles this interrupt automatically.

Functional Overview

Relevant Include files:

pic_usb.h

Hardware layer driver for the PIC16C765 family PICmicro controllers

with an internal USB peripheral.

pic18_usb.h

Hardware layer driver for the PIC18F4550 family PICmicro controllers

with an internal USB peripheral.

usbn960x.h

Hardware layer driver for the National USBN9603/USBN9604 external

USB peripheral. You can use this external peripheral to add USB to any

microcontroller.

usb.h

Common definitions and prototypes used by the USB driver

usb.c

The USB stack, which handles the USB interrupt and USB Setup

Requests on Endpoint 0.

usb_cdc.h

A driver that takes the previous include files to make a CDC USB

device, which emulates an RS232 legacy device and shows up as a

COM port in the MS Windows device manager.

Relevant getenv() Parameters:

USB

Returns TRUE if the PICmicro controller has an integrated internal USB

peripheral.

Example Code:

Due to the complexity of USB example code will not fit here. But you can find the following

examples installed with your CCS C Compiler:

ex_usb_hid.c

A simple HID device

ex_usb_mouse.c

A HID Mouse, when connected to your PC the mouse cursor will go in

circles.

ex_usb_kbmouse.c

An example of how to create a USB device with multiple interfaces by

creating a keyboard and mouse in one device.

ex_usb_kbmouse2.c

An example of how to use multiple HID report Ids to transmit more than

one type of HID packet, as demonstrated by a keyboard and mouse on

one device.

ex_usb_scope.c

A vendor-specific class using bulk transfers is demonstrated.

ex_usb_serial.c

The CDC virtual RS232 library is demonstrated with this RS232 < - >

USB example.

ex_usb_serial2.c

Another CDC virtual RS232 library example, this time a port of the

ex_intee.c example to use USB instead of RS232.

Functional Overview

Voltage Reference

These functions configure the votlage reference module. These are available only in the

supported chips.

Relevant Functions:

setup_vref(mode | value)

Enables and sets up the internal voltage reference value.

Constants are defined in the device's .h file.

Relevant Preprocesser:

none

Relevant Interrupts:

none

Relevant Include Files:

none, all functions built-in

Relevant getenv() parameters:

VREF

Returns 1 if the device has VREF

Example code:

for PIC12F675

#INT_COMP //comparator interrupt handler

void isr() {

safe_conditions = FALSE;

printf("WARNING!!!! Voltage level is above

3.6V. \r\n");

}

setup_comparator(A1_VR_OUT_ON_A2)//sets 2

comparators(A1 and VR and A2 as output)

{

setup_vref(VREF_HIGH | 15);//sets 3.6(vdd *

value/32 + vdd/4) if vdd is 5.0V

enable_interrupts(INT_COMP); // enable the

comparator interrupt

enable_interrupts(GLOBAL); //enable global

interrupts

}

Functional Overview

WDT or Watch Dog Timer

Different chips provide different options to enable/disable or configure the WDT.

Relevant Functions:

setup_wdt()

Enables/disables the wdt or sets the prescalar.

restart_wdt()

Restarts the wdt, if wdt is enables this must be periodically called

to prevent a timeout reset.

For PCB/PCM chips it is enabled/disabled using WDT or NOWDT fuses whereas on PCH

device it is done using the setup_wdt function.

The timeout time for PCB/PCM chips are set using the setup_wdt function and on PCH using

fuses like WDT16, WDT256 etc.

RESTART_WDT when specified in #USE DELAY, #USE I2C and #USE RS232 statements like

this #USE DELAY(clock=20000000, restart_wdt) will cause the wdt to restart if it times out

during the delay or I2C_READ or GETC.

Relevant Preprocessor:

#FUSES WDT/NOWDT

Enabled/Disables wdt in PCB/PCM devices

#FUSES WDT16

Sets ups the timeout time in PCH devices

Relevant Interrupts:

None

Relevant Include Files:

None, all functions built-in

Relevant getenv() parameters:

None

Example Code:

For PIC16F877

#fuses wdt

setup_wdt(WDT_2304MS);

while(true){

restart_wdt();

perform_activity();

}

For PIC18F452

#fuse WDT1

setup_wdt(WDT_ON);

while(true){

restart_wdt();

perform_activity();

}

Some of the PCB chips are share the WDT prescalar bits with timer0 so the WDT prescalar

constants can be used with setup_counters or setup_timer0 or setup_wdt functions.

Functional Overview

interrupt_enabled()

This function checks the interrupt enabled flag for the specified interrupt and returns

TRUE if set.

Syntax

interrupt_enabled(interrupt);

Parameters

interrupt- constant specifying the interrupt

Returns

Boolean value

Function

The function checks the interrupt enable flag of the specified

interrupt and returns TRUE when set.

Availability

Devices with interrupts

Requires

Interrupt constants defined in the device's .h file.

Examples

if(interrupt_enabled(INT_RDA))

disable_interrupt(INT_RDA);

Example Files

None

Also see

DISABLE_INTERRUPTS(), , Interrupts Overview,

CLEAR_INTERRUPT(),

ENABLE_INTERRUPTS(),,INTERRUPT_ACTIVE()

Stream I/O

Syntax:

#include <ios.h> is required to use any of the ios identifiers.

Output:

output:

stream << variable_or_constant_or_manipulator ;

________________________________

one or more repeats

stream may be the name specified in the #use RS232 stream= option

or for the default stream use cout.

stream may also be the name of a char array. In this case the data is

written to the array with a 0 terminator.

stream may also be the name of a function that accepts a single char

parameter. In this case the function is called for each character to be output.

variables/constants: May be any integer, char, float or fixed type. Char arrays are

output as strings and all other types are output as an address of the variable.

manipulators:

hex -Hex format numbers

dec- Decimal format numbers (default)

setprecision(x) -Set number of places after the decimal point

setw(x) -Set total number of characters output for numbers

boolalpha- Output int1 as true and false

noboolalpha -Output int1 as 1 and 0 (default)

fixed Floats- in decimal format (default)

Functional Overview

scientific Floats- use E notation

iosdefault- All manipulators to default settings

endl -Output CR/LF

ends- Outputs a null ('\000')

Examples:

cout << "Value is " << hex << data << endl;

cout << "Price is $" << setw(4) << setprecision(2) << cost << endl;

lcdputc << '\f' << setw(3) << count << " " << min << " " << max;

string1 << setprecision(1) << sum / count;

string2 << x << ',' << y;

Input:

stream >> variable_or_constant_or_manipulator ;

________________________________

one or more repeats

stream may be the name specified in the #use RS232 stream= option

or for the default stream use cin.

stream may also be the name of a char array. In this case the data is

read from the array up to the 0 terminator.

stream may also be the name of a function that returns a single char and has

no parameters. In this case the function is called for each character to be input.

Make sure the function returns a \r to terminate the input statement.

variables/constants: May be any integer, char, float or fixed type. Char arrays are

input as strings. Floats may use the E format.

Reading of each item terminates with any character not valid for the type. Usually

items are separated by spaces. The termination character is discarded. At the end

of any stream input statement characters are read until a return (\r) is read. No

termination character is read for a single char input.

manipulators:

hex -Hex format numbers

dec- Decimal format numbers (default)

noecho- Suppress echoing

strspace- Allow spaces to be input into strings

nostrspace- Spaces terminate string entry (default)

iosdefault -All manipulators to default settings

Examples:

cout << "Enter number: ";

cin >> value;

cout << "Enter title: ";

cin >> strspace >> title;

cin >> data[i].recordid >> data[i].xpos >> data[i].ypos >> data[i].sample ;

string1 >> data;

lcdputc << "\fEnter count";

lcdputc << keypadgetc >> count; // read from keypad, echo to lcd

// This syntax only works with

// user defined functions.

Functional Overview

PRE-PROCESSOR

Pre-processor directives all begin with a # and are followed by a specific command. Syntax is

dependent on the command. Many commands do not allow other syntactical elements on the

remainder of the line. A table of commands and a description is listed on the previous page.

Several of the pre-processor directives are extensions to standard C. C provides a pre-

processor directive that compilers will accept and ignore or act upon the following data. This

implementation will allow any pre-processor directives to begin with #PRAGMA. To be

compatible with other compilers, this may be used before non-standard features.

Examples:

Both of the following are valid

#INLINE

#PRAGMA INLINE

Standard C

#IF expr

#DEFINE id string

#LIST

#IFDEF id

#UNDEF id

#NOLIST

#IFNDEF

#INCLUDE FILENAME

#PRAGMA cmd

#ELSE

#WARNING

#ERROR

#ELIF

#ENDIF

#DEFINEDINC

Function

Qualifier

#INLINE

#INT_GLOBAL

#SEPARATE

#INT_DEFAULT

Pre-Defined

Identifier

_ _DATE_ _

_LINE_ _

_ _PCH_ _

_ _DEVICE_ _

_FILENAME_ _

_ _PCM_ _

_FILE_ _

_TIME_

_PCB_ _

RTOS

#TASK

#USE RTOS

Device

Specification

#DEVICE chip

#ID "filename"

#HEXCOMMENT

#FUSES options

#ID number

#ID CHECKSUM

#SERIALIZE

#PIN_SELECT

Built-in

LIbraries

#USE DELAY

#USE FIXED_IO

#USE RS232

#USE FAST_IO

#USE I2C

#USE STANDARD_IO

#USE SPI

#USE TOUCHPAD

#USE TIMER

Pre-Processor

#USE CAPTURE

Memory

Control

#ASM

#ENDASM

#ROM

#BIT id=id.const

#FILL_ROM

#TYPE

#BIT id=const.const

#LOCATE id=const

#ZERO_RAM

#BYTE id=const

#ORG

#WORD

#BYTE id=id

#RESERVE

#LINE

#USE DYNAMIC_MEMORY

Compiler

Control

#CASE

#IMPORT

#PRIORITY

#EXPORT

#OPT

#OCS

#IGNORE_WARNINGS

#MODULE

Linker

#IMPORT

#EXPORT

#BUILD

Pre-Processor

_attribute_x

Syntax:

_attribute_x

Elements:

x is the attribute you want to apply. Valid values for x are as follows:

packed

By default each element in a struct or union are padded to be evenly

spaced by the size of 'int'. This is to prevent an address violation when

accessing an element of struct. See the following example:

struct

{

int8 a;

int8 b;

} test;

On architectures where 'int' is 16bit (such as dsPIC or PIC24

PICmicrocontrollers), 'test' would take 4 bytes even though it is

comprised of two 8-bit elements. By applying the 'packed' attribute to

this struct then it would take 2 bytes as originally intended:

struct __attribute__(packed)

{

int8 a;

int8 b;

} test;

Care should be taken by the user when accessing individual elements

of a packed struct – creating a pointer to 'b' in 'test' and attempting to

dereference that pointer would cause an access violation. Any

attempts to read/write 'b' should be done in context of 'test' so the

compiler knows it is packed:

test.b = 5;

aligned(y)

By default the compiler will alocate a variable in the first free memory

location. The aligned attribute will force the compiler to allocate a

location for the specified variable at a location that is modulus of the y

parameter. For example:

int8 array[256] __attribute__(aligned(0x1000));

This will tell the compiler to try to place 'array' at either 0x0, 0x1000,

0x2000, 0x3000, 0x4000, etc.

Purpose

To alter some specifics as to how the compiler operates

Examples:

struct attribute__(packed__)

{

int8 a;

int8 b;

} test;

int8 array[256] __attribute__(aligned(0x1000));

Example Files:

None

Pre-Processor

#ASM #ENDASM

Syntax:

#ASM or #ASM ASIS code #ENDASM

Elements:

code is a list of assembly language instructions

Examples:

int_ffind_parity(int data){int count;, result,datal; data1=data; asm MOV

#0x08, MOV WF, count CLRF result Loop: MOVF data1,w XORWF

result, F RRCF data1,F DECFSZ count,F BRA LOOP MOVLW 0x01

ANDWF resutt, F #end asm

retturn (result)';

}

Example Files:

ex_glint.c

Also See:

None

ADD

Wa,Wb,Wd

Wd = Wa+Wb

ADD

f,W

W0 = f+Wd

ADD

lit10,Wd

Wd = lit10+Wd

ADD

Wa,lit5,Wd

Wd = lit5+Wa

ADD

f,F

f = f+Wd

ADD

acc

Acc = AccA+AccB

ADD

Wd,{lit4},acc

Acc = Acc+(Wa shifted slit4)

ADD.B

lit10,Wd

Wd = lit10+Wd (byte)

ADD

Wd,{lit4},acc

Acc = Acc+(Wa shifted slit4)

ADD.B

lit10,Wd

Wd = lit10+Wd (byte)

ADD.B

f,F

f = f+Wd (byte)

ADD.B

Wa,Wb,Wd

Wd = Wa+Wb (byte)

ADD.B

Wa,lit5,Wd

Wd = lit5+Wa (byte)

ADD.B

f,W

W0 = f+Wd (byte)

ADDC

f,W

Wd = f+Wa+C

ADDC

lit10,Wd

Wd = lit10+Wd+C

ADDC

Wa,lit5,Wd

Wd = lit5+Wa+C

ADDC

f,F

Wd = f+Wa+C

ADDC

Wa,Wb,Wd

Wd = Wa+Wb+C

ADDC.B

lit10,Wd

Wd = lit10+Wd+C(byte)

ADDC.B

Wa,Wb,Wd

Wd = Wa+Wb+C(byte)

ADDC.B

Wa,lit5,Wd

Wd = lit5+Wa+C(byte)

ADDC.B

f,W

Wd = f+Wa+C(byte)

ADDC.B

f,F

Wd = f+Wa+C(byte)

AND

Wa,Wb,Wd

Wd = Wa.&.Wb

Pre-Processor

AND

lit10,Wd

Wd = lit10.&.Wd

AND

f,W

W0 = f.&.Wa

AND

f,F

f = f.&.Wa

AND

Wa,lit5,Wd

Wd = lit5.&.Wa

AND.B

f,W

W0 = f.&.Wa (byte)

AND.B

Wa,Wb,Wd

Wd = Wa.&.Wb (byte)

AND.B

lit10,Wd

Wd = lit10.&.Wd (byte)

AND.B

f,F

f = f.&.Wa (byte)

AND.B

Wa,lit5,Wd

Wd = lit5.&.Wa (byte)

ASR

f,W

W0 = f >> 1arithmetic

ASR

f,F

f = f >> 1arithmetic

ASR

Wa,Wd

Wd = Wa >> 1arithmetic

ASR

Wa,lit4,Wd

Wd = Wa >> lit4arithmetic

ASR

Wa,Wb,Wd

Wd = Wa >> Wbarithmetic

ASR.B

f,F

f = f >> 1arithmetic (byte)

ASR.B

f,W

W0 = f >> 1arithmetic (byte)

ASR.B

Wa,Wd

Wd = Wa >> 1arithmetic (byte)

BCLR

f,B

f.bit = 0

BCLR

Wd,B

Wa.bit = 0

BCLR.B

Wd,B

Wa.bit = 0 (byte)

BRA

Branch unconditionally

BRA

Branch PC+Wa

BRA BZ

Branch if Zero

BRA C

Branch if Carry (no borrow)

BRA GE

Branch if greater than or equal

BRA GEU

Branch if unsigned greater than or equal

BRA GT

Branch if greater than

BRA GTU

Branch if unsigned greater than

BRA LE

Branch if less than or equal

BRA LEU

Branch if unsigned less than or equal

BRA LT

Branch if less than

BRA LTU

Branch if unsigned less than

BRA N

Branch if negative

BRA NC

Branch if not carry (Borrow)

BRA NN

Branch if not negative

BRA NOV

Branch if not Overflow

BRA NZ

Branch if not Zero

BRA OA

Branch if Accumulator A overflow

BRA OB

Branch if Accumulator B overflow

BRA OV

Branch if Overflow

BRA SA

Branch if Accumulator A Saturate

Pre-Processor

BRA SB

Branch if Accumulator B Saturate

BRA Z

Branch if Zero

BREAK

ICD Break

BSET

Wd,B

Wa.bit = 1

BSET

f,B

f.bit = 1

BSET.B

Wd,B

Wa.bit = 1 (byte)

BSW.C

Wa,Wd

Wa.Wb = C

BSW.Z

Wa,Wd

Wa.Wb = Z

BTG

Wd,B

Wa.bit = ~Wa.bit

BTG

f,B

f.bit = ~f.bit

BTG.B

Wd,B

Wa.bit = ~Wa.bit (byte)

BTSC

f,B

Skip if f.bit = 0

BTSC

Wd,B

Skip if Wa.bit4 = 0

BTSS

f,B

Skip if f.bit = 1

BTSS

Wd,B

Skip if Wa.bit = 1

BTST

f,B

Z = f.bit

BTST.C

Wa,Wd

C = Wa.Wb

BTST.C

Wd,B

C = Wa.bit

BTST.Z

Wd,B

Z = Wa.bit

BTST.Z

Wa,Wd

Z = Wa.Wb

BTSTS

f,B

Z = f.bit; f.bit = 1

BTSTS.C

Wd,B

C = Wa.bit; Wa.bit = 1

BTSTS.Z

Wd,B

Z = Wa.bit; Wa.bit = 1

CALL

Call subroutine

CALL

Call [Wa]

CLR

f,F

f = 0

CLR

acc,da,dc,pi

Acc = 0; prefetch=0

CLR

f,W

W0 = 0

CLR

Wd = 0

CLR.B

f,W

W0 = 0 (byte)

CLR.B

Wd = 0 (byte)

CLR.B

f,F

f = 0 (byte)

CLRWDT

Clear WDT

COM

f,F

f = ~f

COM

f,W

W0 = ~f

COM

Wa,Wd

Wd = ~Wa

COM.B

f,W

W0 = ~f(byte)

COM.B

Wa,Wd

Wd = ~Wa (byte)

COM.B

f,F

f = ~f(byte)

W,f

Status set for f - W0

Wa,Wd

Status set for Wb â€“ Wa

Pre-Processor

Wd,lit5

Status set for Wa â€“ lit5

CP.B

W,f

Status set for f - W0 (byte)

CP.B

Wa,Wd

Status set for Wb â€“ Wa (byte)

CP.B

Wd,lit5

Status set for Wa â€“ lit5 (byte)

CP0

Status set for Wa â€“ 0

CP0

W,f

Status set for f â€“ 0

CP0.B

Status set for Wa â€“ 0 (byte)

CP0.B

W,f

Status set for f â€“ 0 (byte)

CPB

Wd,lit5

Status set for Wa â€“ lit5 â€“ C

CPB

Wa,Wd

Status set for Wb â€“ Wa â€“ C

CPB

W,f

Status set for f â€“ W0 - C

CPB.B

Wa,Wd

Status set for Wb â€“ Wa â€“ C (byte)

CPB.B

Wd,lit5

Status set for Wa â€“ lit5 â€“ C(byte)

CPB.B

W,f

Status set for f â€“ W0 - C (byte)

CPSEQ

Wa,Wd

Skip if Wa = Wb

CPSEQ.B

Wa,Wd

Skip if Wa = Wb (byte)

CPSGT

Wa,Wd

Skip if Wa > Wb

CPSGT.B

Wa,Wd

Skip if Wa > Wb (byte)

CPSLT

Wa,Wd

Skip if Wa < Wb

CPSLT.B

Wa,Wd

Skip if Wa < Wb (byte)

CPSNE

Wa,Wd

Skip if Wa != Wb

CPSNE.B

Wa,Wd

Skip if Wa != Wb (byte)

DAW.B

Wa = decimal adjust Wa

DEC

Wa,Wd

Wd = Wa â€“ 1

DEC

f,W

W0 = f â€“ 1

DEC

f,F

f = f â€“ 1

DEC.B

f,F

f = f â€“ 1 (byte)

DEC.B

f,W

W0 = f â€“ 1 (byte)

DEC.B

Wa,Wd

Wd = Wa â€“ 1 (byte)

DEC2

Wa,Wd

Wd = Wa â€“ 2

DEC2

f,W

W0 = f â€“ 2

DEC2

f,F

f = f â€“ 2

DEC2.B

Wa,Wd

Wd = Wa â€“ 2(byte)

DEC2.B

f,W

W0 = f â€“ 2 (byte)

DEC2.B

f,F

f = f â€“ 2 (byte)

DISI

lit14

Disable Interrupts lit14 cycles

DIV.S

Wa,Wd

Signed 16/16-bit integer divide

DIV.SD

Wa,Wd

Signed 16/16-bit integer divide (dword)

DIV.U

Wa,Wd

UnSigned 16/16-bit integer divide

DIV.UD

Wa,Wd

UnSigned 16/16-bit integer divide (dword)

DIVF

Wa,Wd

Signed 16/16-bit fractional divide

Pre-Processor

lit14,a

Do block lit14 times

Wd,a

Do block Wa times

Wd*Wd,acc,da,db

Euclidean Distance (No Accumulate)

EDAC

Wd*Wd,acc,da,db

Euclidean Distance

EXCH

Wa,Wd

Swap Wa and Wb

FBCL

Wa,Wd

Find bit change from left (Msb) side

FEX

ICD Execute

FF1L

Wa,Wd

Find first one from left (Msb) side

FF1R

Wa,Wd

Find first one from right (Lsb) side

GOTO

GoTo

GOTO

GoTo [Wa]

INC

f,W

W0 = f + 1

INC

Wa,Wd

Wd = Wa + 1

INC

f,F

f = f + 1

INC.B

Wa,Wd

Wd = Wa + 1 (byte)

INC.B

f,F

f = f + 1 (byte)

INC.B

f,W

W0 = f + 1 (byte)

INC2

f,W

W0 = f + 2

INC2

Wa,Wd

Wd = Wa + 2

INC2

f,F

f = f + 2

INC2.B

f,W

W0 = f + 2 (byte)

INC2.B

f,F

f = f + 2 (byte)

INC2.B

Wa,Wd

Wd = Wa + 2 (byte)

IOR

lit10,Wd

Wd = lit10 | Wd

IOR

f,F

f = f | Wa

IOR

f,W

W0 = f | Wa

IOR

Wa,lit5,Wd

Wd = Wa.|.lit5

IOR

Wa,Wb,Wd

Wd = Wa.|.Wb

IOR.B

Wa,Wb,Wd

Wd = Wa.|.Wb (byte)

IOR.B

f,W

W0 = f | Wa (byte)

IOR.B

lit10,Wd

Wd = lit10 | Wd (byte)

IOR.B

Wa,lit5,Wd

Wd = Wa.|.lit5 (byte)

IOR.B

f,F

f = f | Wa (byte)

LAC

Wd,{lit4},acc

Acc = Wa shifted slit4

LNK

lit14

Allocate Stack Frame

LSR

f,W

W0 = f >> 1

LSR

Wa,lit4,Wd

Wd = Wa >> lit4

LSR

Wa,Wd

Wd = Wa >> 1

LSR

f,F

f = f >> 1

LSR

Wa,Wb,Wd

Wd = Wb >> Wa

LSR.B

f,W

W0 = f >> 1 (byte)

Pre-Processor

LSR.B

f,F

f = f >> 1 (byte)

LSR.B

Wa,Wd

Wd = Wa >> 1 (byte)

MAC

Wd*Wd,acc,da,dc

Acc = Acc + Wa * Wa; {prefetch}

MAC

Wd*Wc,acc,da,dc,

Acc = Acc + Wa * Wb; {[W13] = Acc}; {prefetch}

MOV

W,f

f = Wa

MOV

f,W

W0 = f

MOV

f,F

f = f

MOV

Wd,?

F = Wa

MOV

Wa+lit,Wd

Wd = [Wa +Slit10]

MOV

?,Wd

Wd = f

MOV

lit16,Wd

Wd = lit16

MOV

Wa,Wd

Wd = Wa

MOV

Wa,Wd+lit

[Wd + Slit10] = Wa

MOV.B

lit8,Wd

Wd = lit8(byte)

MOV.B

W,f

f = Wa (byte)

MOV.B

f,W

W0 = f (byte)

MOV.B

f,F

f = f (byte)

MOV.B

Wa+lit,Wd

Wd = [Wa +Slit10] (byte)

MOV.B

Wa,Wd+lit

[Wd + Slit10] = Wa (byte)

MOV.B

Wa,Wd

Wd = Wa (byte)

MOV.D

Wa,Wd

Wd:Wd+1 = Wa:Wa+1

MOV.D

Wa,Wd

Wd:Wd+1 = Wa:Wa+1

MOVSAC

acc,da,dc,pi

Move ? to ? and ? To ?

MPY

Wd*Wc,acc,da,dc

Acc = Wa*Wb

MPY

Wd*Wd,acc,da,dc

Square to Acc

MPY.N

Wd*Wc,acc,da,dc

Acc = -(Wa*Wb)

MSC

Wd*Wc,acc,da,dc,

Acc = Acc â€“ Wa*Wb

MUL

W,f

W3:W2 = f * Wa

MUL.B

W,f

W3:W2 = f * Wa (byte)

MUL.SS

Wa,Wd

{Wd+1,Wd}= sign(Wa) * sign(Wb)

MUL.SU

Wa,Wd

{Wd+1,Wd} = sign(Wa) * unsign(Wb)

MUL.SU

Wa,lit5,Wd

{Wd+1,Wd}= sign(Wa) * unsign(lit5)

MUL.US

Wa,Wd

{Wd+1,Wd} = unsign(Wa) * sign(Wb)

MUL.UU

Wa,Wd

{Wd+1,Wd} = unsign(Wa) * unsign(Wb)

MUL.UU

Wa,lit5,Wd

{Wd+1,Wd} = unsign(Wa) * unsign(lit5)

NEG

f,F

f = - f

PUSH

Push Wa to TOS

PUSH.D

PUSH double Wa:Wa + 1 to TOS

PUSH.S

PUSH shadow registers

PWRSAV

lit1

Enter Power-saving mode lit1

RCALL

Call (relative)

Pre-Processor

RCALL

Call Wa

REPEAT

lit14

Repeat next instruction (lit14 + 1) times

REPEAT

Repeat next instruction (Wa + 1) times

RESET

Reset

RETFIE

Return from interrupt enable

RETLW

lit10,Wd

Return; Wa = lit10

RETLW.B

lit10,Wd

Return; Wa = lit10 (byte)

RETURN

Return

RLC

Wa,Wd

Wd = rotate left through Carry Wa

RLC

f,F

f = rotate left through Carry f

RLC

f,W

W0 = rotate left through Carry f

RLC.B

f,F

f = rotate left through Carry f (byte)

RLC.B

f,W

W0 = rotate left through Carry f (byte)

RLC.B

Wa,Wd

Wd = rotate left through Carry Wa (byte)

RLNC

Wa,Wd

Wd = rotate left (no Carry) Wa

RLNC

f,F

f = rotate left (no Carry) f

RLNC

f,W

W0 = rotate left (no Carry) f

RLNC.B

f,W

W0 = rotate left (no Carry) f (byte)

RLNC.B

Wa,Wd

Wd = rotate left (no Carry) Wa (byte)

RLNC.B

f,F

f = rotate left (no Carry) f (byte)

RRC

f,F

f = rotate right through Carry f

RRC

Wa,Wd

Wd = rotate right through Carry Wa

RRC

f,W

W0 = rotate right through Carry f

RRC.B

f,W

W0 = rotate right through Carry f (byte)

RRC.B

f,F

f = rotate right through Carry f (byte)

RRC.B

Wa,Wd

Wd = rotate right through Carry Wa (byte)

RRNC

f,F

f = rotate right (no Carry) f

RRNC

f,W

W0 = rotate right (no Carry) f

RRNC

Wa,Wd

Wd = rotate right (no Carry) Wa

RRNC.B

f,F

f = rotate right (no Carry) f (byte)

RRNC.B

Wa,Wd

Wd = rotate right (no Carry) Wa (byte)

RRNC.B

f,W

W0 = rotate right (no Carry) f (byte)

SAC

acc,{lit4},Wd

Wd = Acc slit 4

SAC.R

acc,{lit4},Wd

Wd = Acc slit 4 with rounding

Wa,Wd

Wd = sign-extended Wa

SETM

Wd = 0xFFFF

SETM

f,F

W0 = 0xFFFF

SETM.B

Wd = 0xFFFF (byte)

SETM.B

f,W

W0 = 0xFFFF (byte)

SETM.B

f,F

W0 = 0xFFFF (byte)

SFTAC

acc,Wd

Arithmetic shift Acc by (Wa)

Pre-Processor

SFTAC

acc,lit5

Arithmetic shift Acc by Slit6

f,W

W0 = f << 1

Wa,Wb,Wd

Wd = Wa << Wb

Wa,lit4,Wd

Wd = Wa << lit4

Wa,Wd

Wd = Wa << 1

f,F

f = f << 1

SL.B

f,W

W0 = f << 1 (byte)

SL.B

Wa,Wd

Wd = Wa << 1 (byte)

SL.B

f,F

f = f << 1 (byte)

SSTEP

ICD Single Step

SUB

f,F

f = f â€“ W0

SUB

f,W

W0 = f â€“ W0

SUB

Wa,Wb,Wd

Wd = Wa â€“ Wb

SUB

Wa,lit5,Wd

Wd = Wa â€“ lit5

SUB

acc

Acc = AccA â€“ AccB

SUB

lit10,Wd

Wd = Wd â€“ lit10

SUB.B

Wa,lit5,Wd

Wd = Wa â€“ lit5 (byte)

SUB.B

lit10,Wd

Wd = Wd â€“ lit10 (byte)

SUB.B

f,W

W0 = f â€“ W0 (byte)

SUB.B

Wa,Wb,Wd

Wd = Wa â€“ Wb (byte)

SUB.B

f,F

f = f â€“ W0 (byte)

SUBB

f,W

W0 = f â€“ W0 â€“ C

SUBB

Wa,Wb,Wd

Wd = Wa â€“ Wb â€“ C

SUBB

f,F

f = f â€“ W0 â€“ C

SUBB

Wa,lit5,Wd

Wd = Wa â€“ lit5 - C

SUBB

lit10,Wd

Wd = Wd â€“ lit10 â€“ C

SUBB.B

lit10,Wd

Wd = Wd â€“ lit10 â€“ C(byte)

SUBB.B

Wa,Wb,Wd

Wd = Wa â€“ Wb â€“ C(byte)

SUBB.B

f,F

f = f â€“ W0 â€“ C (byte)

SUBB.B

Wa,lit5,Wd

Wd = Wa â€“ lit5 - C(byte)

SUBB.B

f,W

W0 = f â€“ W0 â€“ C (byte)

SUBBR

Wa,lit5,Wd

Wd = lit5 â€“ Wa - C

SUBBR

f,W

W0 = W0 â€“ f â€“ C

SUBBR

f,F

f = W0 â€“ f â€“ C

SUBBR

Wa,Wb,Wd

Wd = Wa â€“ Wb - C

SUBBR.B

f,F

f = W0 â€“ f â€“ C(byte)

SUBBR.B

f,W

W0 = W0 â€“ f â€“ C(byte)

SUBBR.B

Wa,Wb,Wd

Wd = Wa â€“ Wb - C(byte)

SUBBR.B

Wa,lit5,Wd

Wd = lit5 â€“ Wa - C(byte)

SUBR

Wa,lit5,Wd

Wd = lit5 â€“ Wb

SUBR

f,F

f = W0 â€“ f

Pre-Processor

SUBR

Wa,Wb,Wd

Wd = Waâ€“ Wb

SUBR

f,W

W0 = W0 â€“ f

SUBR.B

Wa,Wb,Wd

Wd = Waâ€“ Wb (byte)

SUBR.B

f,F

f = W0 â€“ f(byte)

SUBR.B

Wa,lit5,Wd

Wd = lit5 â€“ Wb(byte)

SUBR.B

f,W

W0 = W0 â€“ f(byte)

SWAP

Wa = byte or nibble swap Wa

SWAP.B

Wa = byte or nibble swap Wa (byte)

TBLRDH

Wa,Wd

Wd = ROM[Wa] for odd ROM

TBLRDH.B

Wa,Wd

Wd = ROM[Wa] for odd ROM (byte)

TBLRDL

Wa,Wd

Wd = ROM[Wa] for even ROM

TBLRDL.B

Wa,Wd

Wd = ROM[Wa] for even ROM (byte)

TBLWTH

Wa,Wd

ROM[Wa] = Wd for odd ROM

TBLWTH.B

Wa,Wd

ROM[Wa] = Wd for odd ROM (byte)

TBLWTL

Wa,Wd

ROM[Wa] = Wd for even ROM

TBLWTL.B

Wa,Wd

ROM[Wa] = Wd for even ROM (byte)

ULNK

Deallocate Stack Frame

URUN

ICD Run

XOR

Wa,Wb,Wd

Wd = Wa ^ Wb

XOR

f,F

f = f ^ W0

XOR

f,W

W0 = f ^ W0

XOR

Wa,lit5,Wd

Wd = Wa ^ lit5

XOR

lit10,Wd

Wd = Wd ^ lit10

XOR.B

lit10,Wd

Wd = Wd ^ lit10 (byte)

XOR.B

f,W

W0 = f ^ W0 (byte)

XOR.B

Wa,lit5,Wd

Wd = Wa ^ lit5 (byte)

XOR.B

Wa,Wb,Wd

Wd = Wa ^ Wb (byte)

XOR.B

f,F

f = f ^ W0 (byte)

Wa,Wd

Wd = Wa & FF

12 Bit and 14 Bit

ADDWF f,d

ANDWF f,d

CLRF f

CLRW

COMF f,d

DECF f,d

DECFSZ f,d

INCF f,d

INCFSZ f,d

IORWF f,d

MOVF f,d

MOVPHW

MOVPLW

MOVWF f

NOP

RLF f,d

RRF f,d

SUBWF f,d

Pre-Processor

SWAPF f,d

XORWF f,d

BCF f,b

BSF f,b

BTFSC f,b

BTFSS f,b

ANDLW k

CALL k

CLRWDT

GOTO k

IORLW k

MOVLW k

RETLW k

SLEEP

XORLW

OPTION

TRIS k

14 Bit

ADDLW k

SUBLW k

RETFIE

RETURN

may be a constant (file number) or a simple variable

may be a constant (0 or 1) or W or F

f,b

may be a file (as above) and a constant (0-7) or it may be just a bit variable

reference.

may be a constant expression

Note that all expressions and comments are in C like syntax.

PIC 18

ADDWF

f,d

ADDWFC

f,d

ANDWF

f,d

CLRF

COMF

f,d

CPFSEQ

CPFSGT

CPFSLT

DECF

f,d

DECFSZ

f,d

DCFSNZ

f,d

INCF

f,d

INFSNZ

f,d

IORWF

f,d

MOVF

f,d

MOVFF

fs,d

MOVWF

MULWF

NEGF

RLCF

f,d

RLNCF

f,d

RRCF

f,d

RRNCF

f,d

SETF

SUBFWB

f,d

SUBWF

f,d

SUBWFB

f,d

SWAPF

f,d

TSTFSZ

XORWF

f,d

BCF

f,b

BSF

f,b

BTFSC

f,b

BTFSS

f,b

BTG

f,d

BNC

BNN

BNOV

BNZ

BOV

BRA

CALL

n,s

CLRWDT

DAW

GOTO

NOP

POP

PUSH

RCALL

RESET

Pre-Processor

RETFIE

RETLW

RETURN

SLEEP

ADDLW

ANDLW

IORLW

LFSR

f,k

MOVLB

MOVLW

MULLW

RETLW

SUBLW

XORLW

TBLRD

TBLWT

The compiler will set the access bit depending on the value of the file register.

If there is just a variable identifier in the #asm block then the

compiler inserts an & before it. And if it is an expression it must be

a valid C expression that evaluates to a constant (no & here). In C

an un-subscripted array name is a pointer and a constant (no need

for &).

#BIT

Syntax:

#BIT id = x.y

Elements:

id is a valid C identifier,

x is a constant or a C variable,

y is a constant 0-7

Purpose:

A new C variable (one bit) is created and is placed in memory at byte x and bit

y. This is useful to gain access in C directly to a bit in the processors special

function register map. It may also be used to easily access a bit of a standard C

variable.

Examples:

#bit T0IF = 0x b.2

...

T1IF = 0; // Clear Timer 0 interrupt flag

int result;

#bit result_odd = result.0

...

if (result_odd)

Example

Files:

ex_glint.c

Also See:

#BYTE, #RESERVE, #LOCATE, #WORD

Pre-Processor

#BUILD

Syntax:

#BUILD(segment = address)

#BUILD(segment = address, segment = address)

#BUILD(segment = start:end)

#BUILD(segment = start: end, segment = start: end)

#BUILD(nosleep)

Elements:

segment is one of the following memory segments which may be assigned a

location: MEMORY, RESET, or INTERRUPT

address is a ROM location memory address. Start and end are used to specify a

range in memory to be used.

start is the first ROM location and end is the last ROM location to be used.

nosleep is used to prevent the compiler from inserting a sleep at the end of main()

Bootload produces a bootloader-friendly hex file (in order, full block size).

NOSLEEP_LOCK is used instead of A sleep at the end of a main A infinite loop.

Purpose:

PIC18XXX devices with external ROM or PIC18XXX devices with no internal ROM

can direct the compiler to utilize the ROM. When linking multiple compilation units,

this directive must appear exactly the same in each compilation unit.

Examples:

#build(memory=0x20000:0x2FFFF) //Assigns memory space

#build(reset=0x200,interrupt=0x208) //Assigns start

//location

//of reset and

//interrupt

//vectors

#build(reset=0x200:0x207, interrupt=0x208:0x2ff)

//Assign limited space

//for reset and

//interrupt vectors.

#build(memory=0x20000:0x2FFFF) //Assigns memory space

Example

Files:

None

Also See:

#LOCATE, #RESERVE, #ROM, #ORG

Pre-Processor

#BYTE

Syntax:

#BYTE id = x

Elements:

id is a valid C identifier,

x is a C variable or a constant

Purpose:

If the id is already known as a C variable then this will locate the variable at address

x. In this case the variable type does not change from the original definition. If the

id is not known a new C variable is created and placed at address x with the type

int (8 bit)

Warning: In both cases memory at x is not exclusive to this variable. Other

variables may be located at the same location. In fact when x is a variable, then id

and x share the same memory location.

Examples:

#byte status = 3

#byte b_port = 6

struct {

short int r_w;

short int c_d;

int unused : 2;

int data : 4 ; } a _port;

#byte a_port = 5

...

a_port.c_d = 1;

Example

Files:

ex_glint.c

Also See:

#BIT, #LOCATE, #RESERVE, #WORD

Pre-Processor

#CASE

Syntax:

#CASE

Elements:

None

Purpose:

Will cause the compiler to be case sensitive. By default the compiler is case

insensitive. When linking multiple compilation units, this directive must appear

exactly the same in each compilation unit.

Warning: Not all the CCS example programs, headers and drivers have been

tested with case sensitivity turned on.

Examples:

#case

int STATUS;

void func() {

int status;

...

STATUS = status; // Copy local status to

//global

}

Example

Files:

ex_cust.c

Also See:

None

_DATE_

Syntax:

__DATE__

Elements:

None

Purpose:

This pre-processor identifier is replaced at compile time with the date of the

compile in the form: "31-JAN-03"

Examples:

printf("Software was compiled on ");

printf(__DATE__);

Example

Files:

None

Also See:

None

Pre-Processor

#DEFINE

Syntax:

#DEFINE id text

#DEFINE id(x,y...) text

Elements:

id is a preprocessor identifier, text is any text, x,y and so on are local preprocessor

identifiers, and in this form there may be one or more identifiers separated by

commas.

Purpose:

Used to provide a simple string replacement of the ID with the given text from this

point of the program and on.

In the second form (a C macro) the local identifiers are matched up with similar

identifiers in the text and they are replaced with text passed to the macro where it is

used.

If the text contains a string of the form #idx then the result upon evaluation will be

the parameter id concatenated with the string x.

If the text contains a string of the form #idx#idy then parameter idx is concatenated

with parameter idy forming a new identifier.

Within the define text two special operators are supported:

#x is the stringize operator resulting in "x"

x##y is the concatination operator resulting in xy

Examples:

#define BITS 8

a=a+BITS; //same as a=a+8;

#define hi(x) (x<<4)

a=hi(a); //same as a=(a<<4);

#define isequal(a,b) (primary_##a[b]==backup_##a[b])

// usage iseaqual(names,5) is the same as

// (primary_names[5]==backup_names[5])

#define str(s) #s

#define part(device) #include str(device##.h)

// usage part(16F887) is the same as

// #include "16F887.h"

Example

Files:

ex_stwt.c, ex_macro.c

Also See:

#UNDEF, #IFDEF, #IFNDEF

Pre-Processor

#DEFINEDINC

Syntax:

value = definedinc( variable );

Parameters:

variable is the name of the variable, function, or type to be checked.

Returns:

A C status for the type of id entered as follows:

0 – not known

1 – typedef or enum

2 – struct or union type

3 – typemod qualifier

4 – defined function

5 – function prototype

6 – compiler built-in function

7 – local variable

8 – global variable

Function:

This function checks the type of the variable or function being passed in and returns a

specific C status based on the type.

Availability:

All devices

Requires:

None.

Examples:

int x, y = 0;

y = definedinc( x ); // y will return 7 – x is a local variable

Example

Files:

None

Also See:

None

Pre-Processor

#DEVICE

Syntax:

#DEVICE chip options

#DEVICE Compilation mode selection

Elements:

Chip Options-

chip is the name of a specific processor (like: PIC16C74 ), To get a current list of

supported devices:

START | RUN | CCSC +Q

Options are qualifiers to the standard operation of the device. Valid options are:

*=5

Use 5 bit pointers (for all parts)

*=8

Use 8 bit pointers (14 and 16 bit parts)

*=16

Use 16 bit pointers (for 14 bit parts)

ADC=x

Where x is the number of bits read_adc() should

return

ICD=TRUE

Generates code compatible with Microchips ICD

debugging hardware.

ICD=n

For chips with multiple ICSP ports specify the port

number being used. The default is 1.

WRITE_EEPROM=ASYNC

Prevents WRITE_EEPROM from hanging while

writing is taking place. When used, do not write to

EEPROM from both ISR and outside ISR.

WRITE_EEPROM = NOINT

Allows interrupts to occur while the

write_eeprom() operations is polling the done bit

to check if the write operations has completed.

Can be used as long as no EEPROM operations

are performed during an ISR.

HIGH_INTS=TRUE

Use this option for high/low priority interrupts on

the PIC® 18.

%f=.

No 0 before a decimal pint on %f numbers less

than 1.

OVERLOAD=KEYWORD

Overloading of functions is now supported.

Requires the use of the keyword for overloading.

OVERLOAD=AUTO

Default mode for overloading.

PASS_STRINGS=IN_RAM

A new way to pass constant strings to a function

by first copying the string to RAM and then

passing a pointer to RAM to the function.

CONST=READ_ONLY

Uses the ANSI keyword CONST definition,

making CONST variables read only, rather than

located in program memory.

CONST=ROM

Uses the CCS compiler traditional keyword

CONST definition, making CONST variables

Pre-Processor

located in program memory.

NESTED_INTERRUPTS=TRUE

Enables interrupt nesting for PIC24, dsPIC30, and

dsPIC33 devices. Allows higher priority interrupts

to interrupt lower priority interrupts.

NORETFIE

ISR functions (preceeded by a #int_xxx) will use a

RETURN opcode instead of the RETFIE opcode.

This is not a commonly used option; used rarely in

cases where the user is writing their own ISR

handler.

Both chip and options are optional, so multiple #DEVICE lines may be used to fully

define the device. Be warned that a #DEVICE with a chip identifier, will clear all

previous #DEVICE and #FUSE settings.

Compilation mode selection-

The #DEVICE directive supports compilation mode selection. The valid keywords are

CCS2, CCS3, CCS4 and ANSI. The default mode is CCS4. For the CCS4 and ANSI

mode, the compiler uses the default fuse settings NOLVP, PUT for chips with these

fuses. The NOWDT fuse is default if no call is made to restart_wdt().

CCS4

This is the default compilation mode. The pointer size in this mode for

PCM and PCH is set to *=16 if the part has RAM over 0FF.

ANSI

Default data type is SIGNED all other modes default is UNSIGNED.

Compilation is case sensitive, all other modes are case insensitive.

Pointer size is set to *=16 if the part has RAM over 0FF.

CCS2

CCS3

var16 = NegConst8 is compiled as: var16 = NegConst8 & 0xff (no sign

extension) Pointer size is set to *=8 for PCM and PCH and *=5 for PCB

. The overload keyword is required.

CCS2

only

The default #DEVICE ADC is set to the resolution of the part, all other

modes default to 8.

onebit = eightbits is compiled as onebit = (eightbits != 0)

All other modes compile as: onebit = (eightbits & 1)

Purpose:

Chip Options -Defines the target processor. Every program must have exactly one

#DEVICE with a chip. When linking multiple compilation units, this directive must

appear exactly the same in each compilation unit.

Compilation mode selection - The compilation mode selection allows existing code

to be compiled without encountering errors created by compiler compliance. As CCS

discovers discrepancies in the way expressions are evaluated according to ANSI, the

change will generally be made only to the ANSI mode and the next major CCS

release.

Pre-Processor

Examples

Chip Options-

#device PIC16C74

#device PIC16C67 *=16

#device *=16 ICD=TRUE

#device PIC16F877 *=16 ADC=10

#device %f=.

printf("%f",.5); //will print .5, without the directive it will print

0.5

Compilation mode selection-

#device CCS2 // This will set the ADC to the resolution of the

part

Example

Files:

ex_mxram.c , ex_icd.c , 16c74.h ,

Also See:

read_adc()

_DEVICE_

Syntax:

__DEVICE__

Elements:

None

Purpose:

This pre-processor identifier is defined by the compiler with the base number of the

current device (from a #DEVICE). The base number is usually the number after the

C in the part number. For example the PIC16C622 has a base number of 622.

Examples:

#if __device__==71

SETUP_ADC_PORTS( ALL_DIGITAL );

#endif

Example

Files:

None

Also See:

#DEVICE

Pre-Processor

#ERROR

Syntax:

#ERROR text

#ERROR / warning text

#ERROR / information text

Elements:

text is optional and may be any text

Purpose:

Forces the compiler to generate an error at the location this directive

appears in the file. The text may include macros that will be expanded for

the display. This may be used to see the macro expansion. The command

may also be used to alert the user to an invalid compile time situation.

Examples:

#if BUFFER_SIZE>16

#error Buffer size is too large

#endif

#error Macro test: min(x,y)

Example

Files:

ex_psp.c

Also See:

#WARNING

#EXPORT (options)

Syntax:

#EXPORT (options)

Elements:

FILE=filname

The filename which will be generated upon compile. If not given, the filname

will be the name of the file you are compiling, with a .o or .hex extension

(depending on output format).

ONLY=symbol+symbol+.....+symbol

Only the listed symbols will be visible to modules that import or link this

relocatable object file. If neither ONLY or EXCEPT is used, all symbols are

exported.

EXCEPT=symbol+symbol+.....+symbol

All symbols except the listed symbols will be visible to modules that import or

link this relocatable object file. If neither ONLY or EXCEPT is used, all

symbols are exported.

RELOCATABLE

CCS relocatable object file format. Must be imported or linked before loading

into a PIC. This is the default format when the #EXPORT is used.

HEX

Intel HEX file format. Ready to be loaded into a PIC. This is the default format

when no #EXPORT is used.

Pre-Processor

RANGE=start:stop

Only addresses in this range are included in the hex file.

OFFSET=address

Hex file address starts at this address (0 by default)

ODD

Only odd bytes place in hex file.

EVEN

Only even bytes placed in hex file.

Purpose:

This directive will tell the compiler to either generate a relocatable object file or

a stand-alone HEX binary. A relocatable object file must be linked into your

application, while a stand-alone HEX binary can be programmed directly into

the PIC.

The command line compiler and the PCW IDE Project Manager can also be

used to compile/link/build modules and/or projects.

Multiple #EXPORT directives may be used to generate multiple hex files. this

may be used for 8722 like devices with external memory.

Examples:

#EXPORT(RELOCATABLE, ONLY=TimerTask)

void TimerFunc1(void) { /* some code */ }

void TimerFunc2(void) { /* some code */ }

void TimerFunc3(void) { /* some code */ }

void TimerTask(void)

{

TimerFunc1();

TimerFunc2();

TimerFunc3();

}

This source will be compiled into a relocatable object, but the

object this is being linked to can only see TimerTask()

Example Files:

None

See Also:

#EXPORT, Invoking the Command Line Compiler, Multiple Compilation Unit

Pre-Processor

113

#NOLIST

Syntax:

#NOLIST

Elements:

None

Purpose:

Stops inserting source lines into the .LST file (until a #LIST)

Examples:

#NOLIST // Don't clutter up the list file

#include <cdriver.h>

#LIST

Example

Files:

16c74.h

Also See:

#LIST

#OCS

Syntax:

#OCS x

Elements:

x is the clock's speed and can be 1 Hz to 100 MHz.

Purpose:

Used instead of the #use delay(clock = x)

Examples:

#include <18F4520.h>

#device ICD=TRUE

#OCS 20 MHz

#use rs232(debugger)

void main(){

-------;

}

Example

Files:

None

Also See:

#USE DELAY

Pre-Processor

114

#OPT

Syntax:

#OPT n

Elements:

All Devices: n is the optimization level 1-11 or by using the word "compress" for

PIC18 and Enhanced PIC16 families.

Purpose:

The optimization level is set with this directive. This setting applies to the entire

program and may appear anywhere in the file. The PCW default is 9 for normal.

When Compress is specified the optimization is set to an extreme level that

causes a very tight rom image, the code is optimized for space, not speed.

Debugging with this level my be more difficult.

Examples:

#opt 5

Example

Files:

None

Also See:

None

#ORG

Syntax:

#ORG start, end

#ORG segment

#ORG start, end { }

#ORG start, end auto=0

#ORG start,end DEFAULT

#ORG DEFAULT

Elements:

start is the first ROM location (word address) to use, end is the last ROM

location, segment is the start ROM location from a previous #ORG

Purpose:

This directive will fix the following function, constant or ROM declaration into

a specific ROM area. End may be omitted if a segment was previously defined

if you only want to add another function to the segment.

Follow the ORG with a { } to only reserve the area with nothing inserted by the

compiler.

The RAM for a ORG'd function may be reset to low memory so the local

variables and scratch variables are placed in low memory. This should only be

used if the ORG'd function will not return to the caller. The RAM used will

overlap the RAM of the main program. Add a AUTO=0 at the end of the

#ORG line.

Pre-Processor

115

If the keyword DEFAULT is used then this address range is used for all

functions user and compiler generated from this point in the file until a #ORG

DEFAULT is encountered (no address range). If a compiler function is called

from the generated code while DEFAULT is in effect the compiler generates a

new version of the function within the specified address range.

#ORG may be used to locate data in ROM. #ORG may be used to locate data in ROM. Because CONSTANT are

implemented as functions the #ORG should proceed the CONSTANT and

needs a start and end address. For a ROM declaration only the start address

should be specified.

When linking multiple compilation units be aware this directive applies to the

final object file. It is an error if any #ORG overlaps between files unless the

#ORG matches exactly.

Examples:

#ORG 0x1E00, 0x1FFF

MyFunc() {

//This function located at 1E00

}

#ORG 0x1E00

Anotherfunc(){

// This will be somewhere 1E00-1F00

}

#ORG 0x800, 0x820 {}

//Nothing will be at 800-820

#ORG 0x1B80

ROM int32 seridl_N0=12345;

#ORG 0x1C00, 0x1C0F

CHAR CONST ID[10}= {"123456789"};

//This ID will be at 1C00

//Note some extra code will

//proceed the 123456789

#ORG 0x1F00, 0x1FF0

Void loader (){

}

Example Files:

loader.c

Also See:

#ROM

Pre-Processor

116

#PIN_SELECT

Syntax:

#PIN_SELECT function=pin_xx

Elements:

function is the Microchip defined pin function name,

such as: U1RX (UART1 receive), INT1 (external

interrupt 1), T2CK (timer 2 clock), IC1 (input capture

1), OC1 (output capture 1).

INT1

External Interrupt 1

INT2

External Interrupt 2

INT3

External Interrupt 3

T0CK

Timer0 External Clock

T3CK

Timer3 External Clock

CCP1

Input Capture 1

CCP2

Input Capture 2

T1G

Timer1 Gate Input

T3G

Timer3 Gate Input

U2RX

EUSART2

Asynchronous

Receive/Synchronous

Receive (also named:

RX2)

U2CK

EUSART2

Asynchronous Clock

Input

SDI2

SPI2 Data Input

SCK2IN

SPI2 Clock Input

SS2IN

SPI2 Slave Select

Input

FLT0

PWM Fault Input

T0CKI

Timer0 External Clock

Input

T3CKI

Timer3 External Clock

Input

RX2

EUSART2

Asynchronous

Transmit/Asynchronous

Clock Output (also

named: TX2)

NULL

C1OUT

Comparator 1 Output

Pre-Processor

117

C2OUT

Comparator 2 Output

U2TX

EUSART2

Asynchronous

Transmit/

Asynchronous Clock

Output (also named:

TX2)

U2DT

EUSART2

Synchronous Transmit

(also named: DT2)

SDO2

SPI2 Data Output

SCK2OUT

SPIC2 Clock Output

SS2OUT

SPI2 Slave Select

Output

ULPOUT

Ultra Low-Power

Wake-Up Event

P1A

ECCP1 Compare or

PWM Output Channel

P1B

ECCP1 Enhanced

PWM Output, Channel

P1C

ECCP1 Enhanced

PWM Output, Channel

P1D

ECCP1 Enhanced

PWM Output, Channel

P2A

ECCP2 Compare or

PWM Output Channel

P2B

ECCP2 Enhanced

PWM Output, Channel

P2C

ECCP2 Enhanced

PWM Output, Channel

P2D

ECCP1 Enhanced

PWM Output, Channel

TX2

EUSART2

Asynchronous

Transmit/Asynchronous

Clock Output (also

named: TX2)

Pre-Processor

118

DT2

EUSART2

Synchronous Transmit

(also named: U2DT)

SCK2

SPI2 Clock Output

SSDMA

SPI DMA Slave Select

pin_xx is the CCS provided pin definition. For

example: PIN_C7, PIN_B0, PIN_D3, etc.

Purpose:

When using PPS chips a #PIN_SELECT must be

appear before these peripherals can be used or

referenced.

Examples:

#pin_select U1TX=PIN_C6

#pin_select U1RX=PIN_C7

#pin_select INT1=PIN_B0

Example

Files:

None

Also See:

None

__PCB__

Syntax:

__PCB__

Elements:

None

Purpose:

The PCB compiler defines this pre-processor identifier. It may be used to

determine if the PCB compiler is doing the compilation.

Examples:

#ifdef __pcb__

#device PIC16c54

#endif

Example

Files:

ex_sqw.c

Also See:

__PCM__, __PCH__

Pre-Processor

119

__ PCM __

Syntax:

__PCM__

Elements:

None

Purpose:

The PCM compiler defines this pre-processor identifier. It may be used to

determine if the PCM compiler is doing the compilation.

Examples:

#ifdef __pcm__

#device PIC16c71

#endif

Example

Files:

ex_sqw.c

Also See:

__PCB__, __PCH__

__ PCH __

Syntax:

__PCH__

Elements:

None

Purpose:

The PCH compiler defines this pre-processor identifier. It may be used to

determine if the PCH compiler is doing the compilation.

Examples:

#ifdef _ _ PCH _ _

#device PIC18C452

#endif

Example

Files:

ex_sqw.c

Also See:

__PCB__, __PCM__

Pre-Processor

120

#PRAGMA

Syntax:

#PRAGMA cmd

Elements:

cmd is any valid preprocessor directive.

Purpose:

This directive is used to maintain compatibility between C compilers. This

compiler will accept this directive before any other pre-processor command. In

no case does this compiler require this directive.

Examples:

#pragma device PIC16C54

Example

Files:

ex_cust.c

Also See:

None

#PRIORITY

Syntax:

#PRIORITY ints

Elements:

ints is a list of one or more interrupts separated by commas.

export makes the functions generated from this directive available to other

compilation units within the link.

Purpose:

The priority directive may be used to set the interrupt priority. The highest

priority items are first in the list. If an interrupt is active it is never interrupted. If

two interrupts occur at around the same time then the higher one in this list will

be serviced first. When linking multiple compilation units be aware only the one

in the last compilation unit is used.

Examples:

#priority rtcc,rb

Example

Files:

None

Also See:

#INT_xxxx

Pre-Processor

121

#PROFILE

Syntax:

#profile options

Element

options may be one of the following:

functions

Profiles the start/end of functions and all profileout() messages.

functions, parameters

Profiles the start/end of functions, parameters sent to functions, and all

profileout() messages.

profileout

Only profile profilout() messages.

paths

Profiles every branch in the code.

off

Disable all code profiling.

Re-enables the code profiling that was previously disabled with a #profile

off command. This will use the last options before disabled with the off

command.

Purpose:

Large programs on the microcontroller may generate lots of profile data, which may

make it difficult to debug or follow. By using #profile the user can dynamically control

which points of the program are being profiled, and limit data to what is relevant to the

user.

Example

#profile off

void BigFunction(void)

{

// BigFunction code goes here.

// Since #profile off was called above,

// no profiling will happen even for other

// functions called by BigFunction().

}

#profile on

Example

Files:

ex_profile.c

Also

See:

#use profile(), profileout(), Code Profile overview

Pre-Processor

122

#RESERVE

Syntax:

#RESERVE address

#RESERVE address, address, address

#RESERVE start:end

Elements:

address is a RAM address, start is the first address and end is the last address

Purpose:

This directive allows RAM locations to be reserved from use by the

compiler. #RESERVE must appear after the #DEVICE otherwise it will have no

effect. When linking multiple compilation units be aware this directive applies to

the final object file.

Examples:

#DEVICE PIC16C74

#RESERVE 0x60:0X6f

Example

Files:

ex_cust.c

Also See:

#ORG

Pre-Processor

123

#ROM

Syntax:

#ROM address = {list}

#ROM type address = {list}

Elements:

address is a ROM word address, list is a list of words separated by commas

Purpose:

Allows the insertion of data into the .HEX file. In particular, this may be used to

program the '84 data EEPROM, as shown in the following example.

Note that if the #ROM address is inside the program memory space, the directive

creates a segment for the data, resulting in an error if a #ORG is over the same

area. The #ROM data will also be counted as used program memory space.

The type option indicates the type of each item, the default is 16 bits. Using char

as the type treats each item as 7 bits packing 2 chars into every pcm 14-bit word.

When linking multiple compilation units be aware this directive applies to the final

object file.

Some special forms of this directive may be used for verifying program memory:

#ROM address = checksum

This will put a value at address such that the entire program memory will sum

to 0x1248

#ROM address = crc16

This will put a value at address that is a crc16 of all the program memory

except the specified address

#ROM address = crc8

This will put a value at address that is a crc16 of all the program memory

except the specified address

Examples:

#rom getnev ("EEPROM_ADDRESS")={1,2,3,4,5,6,7,8}

#rom int8 0x1000={"(c)CCS, 2010"}

Example

Files:

None

Also See:

#ORG

Pre-Processor

124

#SEPARATE

Syntax:

#SEPARATE

Elements:

None

Purpose:

Tells the compiler that the procedure IMMEDIATELY following

the directive is to be implemented SEPARATELY. This is

useful to prevent the compiler from automatically making a

procedure INLINE. This will save ROM space but it does use

more stack space. The compiler will make all procedures

marked SEPARATE, separate, as requested, even if there is

not enough stack space to execute.

Examples:

#separate

swapbyte (int *a, int *b) {

int t;

t=*a;

*a=*b;

*b=t;

}

Example Files:

ex_cust.c

Also See:

#INLINE

Pre-Processor

125

#SERIALIZE

Syntax:

#SERIALIZE(id=xxx, next="x" | file="filename.txt" " |

listfile="filename.txt", "prompt="text", log="filename.txt")

#SERIALIZE(dataee=x, binary=x, next="x" |

file="filename.txt" | listfile="filename.txt", prompt="text",

log="filename.txt")

Elements:

id=xxx - Specify a C CONST identifier, may be int8, int16,

int32 or char array

Use in place of id parameter, when storing serial number to

EEPROM:

dataee=x - The address x is the start address in the data

EEPROM.

binary=x - The integer x is the number of bytes to be written

to address specified. -or-

string=x - The integer x is the number of bytes to be written

to address specified.

Use only one of the next three options:

file="filename.txt" - The file x is used to read the initial serial

number from, and this file is updated by the ICD programmer.

It is assumed this is a one line file with the serial number. The

programmer will increment the serial number.

listfile="filename.txt" - The file x is used to read the initial

serial number from, and this file is updated by the ICD

programmer. It is assumed this is a file one serial number per

line. The programmer will read the first line then delete that

line from the file.

next="x" - The serial number X is used for the first load, then

the hex file is updated to increment x by one.

Other optional parameters:

prompt="text" - If specified the user will be prompted for a

serial number on each load. If used with one of the above

three options then the default value the user may use is

picked according to the above rules.

log=xxx - A file may optionally be specified to keep a log of

the date, time, hex file name and serial number each time the

part is programmed. If no id=xxx is specified then this may be

used as a simple log of all loads of the hex file.

Purpose:

Assists in making serial numbers easier to implement when

working with CCS ICD units. Comments are inserted into the

Pre-Processor

126

hex file that the ICD software interprets.

Examples:

//Prompt user for serial number to be placed

//at address of serialNumA

//Default serial number = 200int8int8 const

serialNumA=100;

#serialize(id=serialNumA,next="200",prompt="Enter

the serial number")

//Adds serial number log in seriallog.txt

#serialize(id=serialNumA,next="200",prompt="Enter

the serial number", log="seriallog.txt")

//Retrieves serial number from serials.txt

#serialize(id=serialNumA,listfile="serials.txt")

//Place serial number at EEPROM address 0,

reserving 1 byte

#serialize(dataee=0,binary=1,next="45",prompt="Put

in Serial number")

//Place string serial number at EEPROM address 0,

reserving 2 bytes

#serialize(dataee=0,

string=2,next="AB",prompt="Put in Serial number")

Example Files:

None

Also See:

None

Pre-Processor

127

#TASK

(The RTOS is only included with the PCW, PCWH, and PCWHD software packages.)

Each RTOS task is specified as a function that has no parameters and no return. The #TASK

directive is needed just before each RTOS task to enable the compiler to tell which functions are

RTOS tasks. An RTOS task cannot be called directly like a regular function can.

Syntax:

#TASK (options)

Elements:

options are separated by comma and may be:

rate=time

Where time is a number followed by s, ms, us, or ns. This specifies how often

the task will execute.

max=time

Where time is a number followed by s, ms, us, or ns. This specifies the

budgeted time for this task.

queue=bytes

Specifies how many bytes to allocate for this task's incoming messages. The

default value is 0.

enabled=value

Specifies whether a task is enabled or disabled by rtos_run( ).

True for enabled, false for disabled. The default value is enabled.

Purpose:

This directive tells the compiler that the following function is an RTOS task.

The rate option is used to specify how often the task should execute. This

must be a multiple of the minor_cycle option if one is specified in the #USE

RTOS directive.

The max option is used to specify how much processor time a task will use in

one execution of the task. The time specified in max must be equal to or less

than the time specified in the minor_cycle option of the #USE RTOS directive

before the project will compile successfully. The compiler does not have a

way to enforce this limit on processor time, so a programmer must be careful

with how much processor time a task uses for execution. This option does

not need to be specified.

The queue option is used to specify the number of bytes to be reserved

for the task to receive messages from other tasks or functions. The default

queue value is 0.

Examples:

#task(rate=1s, max=20ms, queue=5)

Also See:

#USE RTOS

Pre-Processor

128

__ TIME __

Syntax:

__TIME__

Elements:

None

Purpose:

This pre-processor identifier is replaced at compile time with the time of the

compile in the form: "hh:mm:ss"

Examples:

printf("Software was compiled on ");

printf(__TIME__);

Example

Files:

None

Also See:

None

#TYPE

Syntax:

#TYPE standard-type=size

#TYPE default=area

#TYPE unsigned

#TYPE signed

Elements:

standard-type is one of the C keywords short, int, long, or default

size is 1,8,16, or 32

area is a memory region defined before the #TYPE using the addressmod

directive

Purpose:

By default the compiler treats SHORT as one bit , INT as 8 bits, and LONG as 16

bits. The traditional C convention is to have INT defined as the most efficient size

for the target processor. This is why it is 8 bits on the PIC ® . In order to help with

code compatibility a #TYPE directive may be used to allow these types to be

changed. #TYPE can redefine these keywords.

Note that the commas are optional. Since #TYPE may render some sizes

inaccessible (like a one bit int in the above) four keywords representing the four

ints may always be used: INT1, INT8, INT16, and INT32. Be warned CCS

example programs and include files may not work right if you use #TYPE in your

program.

This directive may also be used to change the default RAM area used for variable

storage. This is done by specifying default=area where area is a addressmod

address space.

Pre-Processor

129

When linking multiple compilation units be aware this directive only applies to the

current compilation unit.

The #TYPE directive allows the keywords UNSIGNED and SIGNED to set the

default data type.

Examples:

#TYPE SHORT= 8 , INT= 16 , LONG= 32

#TYPE default=area

addressmod (user_ram_block, 0x100, 0x1FF);

#type default=user_ram_block // all variable declarations

// in this area will be in

// 0x100-0x1FF

#type default= // restores memory allocation

// back to normal

#TYPE SIGNED

...

void main()

{

int variable1; // variable1 can only take values from -128 to 127

...

}

Example

Files:

ex_cust.c

Also See:

None

Pre-Processor

130

#UNDEF

Syntax:

#UNDEF id

Elements:

id is a pre-processor id defined via #DEFINE

Purpose:

The specified pre-processor ID will no longer have meaning to the pre-

processor.

Examples:

#if MAXSIZE<100

#undef MAXSIZE

#define MAXSIZE 100

#endif

Example

Files:

None

Also See:

#DEFINE

Pre-Processor

131

#USE CAPTURE

Syntax:

#USE CAPTURE(options)

Elements:

ICx/CCPx

Which CCP/Input Capture module to us.

INPUT = PIN_xx

Specifies which pin to use. Useful for device with remappable

pins, this will cause compiler to automatically assign pin to

peripheral.

TIMER=x

Specifies the timer to use with capture unit. If not specified

default to timer 1 for PCM and PCH compilers and timer 3 for

PCD compiler.

TICK=x

The tick time to setup the timer to. If not specified it will be set

to fastest as possible or if same timer was already setup by a

previous stream it will be set to that tick time. If using same

timer as previous stream and different tick time an error will be

generated.

FASTEST

Use instead of TICK=x to set tick time to fastest as possible.

SLOWEST

Use instead of TICK=x to set tick time to slowest as possible.

CAPTURE_RISING

Specifies the edge that timer value is captured on. Defaults to

CAPTURE_RISING.

CAPTURE_FALLING

Specifies the edge that timer value is captured on. Defaults to

CAPTURE_RISING.

CAPTURE_BOTH

PCD only. Specifies the edge that timer value is captured on.

Defaults to CAPTURE_RISING.

PRE=x

Specifies number of rising edges before capture event occurs.

Valid options are 1, 4 and 16, default to 1 if not specified.

Options 4 and 16 are only valid when using

CAPTURE_RISING, will generate an error is used with

CAPTURE_FALLING or CAPTURE_BOTH.

ISR=x

STREAM=id

Pre-Processor

132

Associates a stream identifier with the capture module. The

identifier may be used in functions like get_capture_time().

DEFINE=id

Creates a define named id which specifies the number of

capture per second. Default define name if not specified is

CAPTURES_PER_SECOND. Define name must start with an

ASCII letter 'A' to 'Z', an ASCII letter 'a' to 'z' or an ASCII

underscore ('_').

Purpose:

This directive tells the compiler to setup an input capture on the

specified pin using the specified settings. The #USE DELAY

directive must appear before this directive can be used. This

directive enables use of built-in functions such as

get_capture_time() and get_capture_event().

Examples:

#USE CAPTURE(INPUT=PIN_C2,CAPTURE_RISING,TIMER=1,FASTEST)

Example

Files:

None.

Also See:

get_capture_time(), get_capture_event()

#USE DELAY

Syntax:

#USE DELAY (options))

Elements:

Options may be any of the following separated by commas:

clock=speed speed is a constant 1-100000000 (1 hz to 100 mhz).

This number can contains commas. This number also supports the following

denominations: M, MHZ, K, KHZ. This specifies the clock the CPU runs at.

Depending on the PIC this is 2 or 4 times the instruction rate. This directive is not

needed if the following type=speed is used and there is no frequency multiplication

or division.

type=speed type defines what kind of clock you are using, and the following values

are valid: oscillator, osc (same as oscillator), crystal, xtal (same as crystal), internal,

int (same as internal) or rc. The compiler will automatically set the oscillator

configuration bits based upon your defined type. If you specified internal, the

compiler will also automatically set the internal oscillator to the defined speed.

Configuration fuses are modified when this option is used. Speed is the input

frequency.

restart_wdt will restart the watchdog timer on every delay_us() and delay_ms()

use.

clock_out when used with the internal or oscillator types this enables the clockout

pin to output the clock.

fast_start some chips allow the chip to begin execution using an internal clock until

the primary clock is stable.

lock some chips can prevent the oscillator type from being changed at run time by

Pre-Processor

133

the software.

USB or USB_FULL for devices with a built-in USB peripheral. When used with the

type=speed option the compiler will set the correct configuration bits for the USB

peripheral to operate at Full-Speed.

USB_LOW for devices with a built-in USB peripheral. When used with the

type=speed option the compiler will set the correct configuration bits for the USB

peripheral to operate at Low-Speed.

Also See:

delay_ms(), delay_us()

#USE DYNAMIC_MEMORY

Syntax:

#USE DYNAMIC_MEMORY

Elements:

None

Purpose:

This pre-processor directive instructs the compiler to create the

_DYNAMIC_HEAD object. _DYNAMIC_HEAD is the location where the first

free space is allocated.

Examples:

#USE DYNAMIC_MEMORY

void main ( ){

}

Example

Files:

ex_malloc.c

Also See:

None

Pre-Processor

134

#USE FAST_IO

Syntax:

#USE FAST_IO (port)

Elements:

port is A, B, C, D, E, F, G, H, J or ALL

Purpose:

Affects how the compiler will generate code for input and output instructions that

follow. This directive takes effect until another #use xxxx_IO directive is

encountered. The fast method of doing I/O will cause the compiler to perform I/O

without programming of the direction register. The compiler's default operation is

the opposite of this command, the direction I/O will be set/cleared on each I/O

operation. The user must ensure the direction register is set correctly via

set_tris_X(). When linking multiple compilation units be aware this directive only

applies to the current compilation unit.

Examples:

#use fast_io(A)

Example

Files:

ex_cust.c

Also See:

#USE FIXED_IO, #USE STANDARD_IO, set_tris_X() , General Purpose I/O

#USE FIXED_IO

Syntax:

#USE FIXED_IO (port_outputs=pin, pin?)

Elements:

port is A-G, pin is one of the pin constants defined in the devices .h file.

Purpose:

This directive affects how the compiler will generate code for input and output

instructions that follow. This directive takes effect until another #USE XXX_IO

directive is encountered. The fixed method of doing I/O will cause the compiler to

generate code to make an I/O pin either input or output every time it is used. The

pins are programmed according to the information in this directive (not the

operations actually performed). This saves a byte of RAM used in standard I/O.

When linking multiple compilation units be aware this directive only applies to the

current compilation unit.

Examples:

#use fixed_io(a_outputs=PIN_A2, PIN_A3)

Example

Files:

None

Also See:

#USE FAST_IO, #USE STANDARD_IO, General Purpose I/O

Pre-Processor

135

#USE I2C

Syntax:

#USE I2C (options)

Elements:

Options are separated by commas and may be:

MASTER

Sets to the master mode

MULTI_MASTER

Set the multi_master mode

SLAVE

Set the slave mode

SCL=pin

Specifies the SCL pin (pin is a bit address)

SDA=pin

Specifies the SDA pin

ADDRESS=nn

Specifies the slave mode address

FAST

Use the fast I2C specification.

FAST=nnnnnn

Sets the speed to nnnnnn hz

SLOW

Use the slow I2C specification

RESTART_WDT

Restart the WDT while waiting in I2C_READ

FORCE_HW

Use hardware I2C functions.

FORCE_SW

Use software I2C functions.

NOFLOAT_HIGH

Does not allow signals to float high, signals

are driven from low to high

SMBUS

Bus used is not I2C bus, but very similar

STREAM=id

Associates a stream identifier with this I2C

port. The identifier may then be used in

functions like i2c_read or i2c_write.

NO_STRETCH

Do not allow clock streaching

MASK=nn

Set an address mask for parts that support it

I2C1

Instead of SCL= and SDA= this sets the pins

to the first module

I2C2

Instead of SCL= and SDA= this sets the pins

to the second module

NOINIT

No initialization of the I2C peripheral is

performed. Use I2C_INIT() to initialize

peripheral at run time.

Only some chips allow the following:

DATA_HOLD

No ACK is sent until I2C_READ is called for data bytes

(slave only)

ADDRESS_HOLD

No ACK is sent until I2C_read is called for the address

byte (slave only)

SDA_HOLD

Min of 300ns holdtime on SDA a from SCL goes low

Pre-Processor

136

Purpose:

CCS offers support for the hardware-based I2CTM and a software-based master

I2CTM device.(For more information on the hardware-based I2C module, please

consult the datasheet for your target device; not all PICs support I2CTM.

The I2C library contains functions to implement an I2C bus. The #USE I2C

remains in effect for the I2C_START, I2C_STOP, I2C_READ, I2C_WRITE and

I2C_POLL functions until another USE I2C is encountered. Software functions are

generated unless the FORCE_HW is specified. The SLAVE mode should only be

used with the built-in SSP. The functions created with this directive are exported

when using multiple compilation units. To access the correct function use the

stream identifier.

Examples:

#use I2C(master, sda=PIN_B0, scl=PIN_B1)

#use I2C(slave,sda=PIN_C4,scl=PIN_C3

address=0xa0,FORCE_HW)

#use I2C(master, scl=PIN_B0, sda=PIN_B1, fast=450000)

//sets the target speed to 450 KBSP

Example

Files:

ex_extee.c with 16c74.h

Also See:

i2c_poll, i2c_speed, i2c_start, i2c_stop, i2c_slaveaddr, i2c_isr_state,

i2c_write, i2c_read, I2C Overview

#USE PROFILE()

Syntax:

#use profile(options)

Elements:

options may be any of the following, comma separated:

ICD

Default – configures code profiler to use the ICD connection.

TIMER1

Optional. If specified, the code profiler run-time on the microcontroller

will use the Timer1 peripheral as a timestamp for all profile events. If not

specified the code profiler tool will use the PC clock, which may not be

accurate for fast events.

BAUD=x

Optional. If specified, will use a different baud rate between the

microcontroller and the code profiler tool. This may be required on

slow microcontrollers to attempt to use a slower baud rate.

Purpose:

Tell the compiler to add the code profiler run-time in the microcontroller and configure

the link and clock.

Examples

#profile(ICD, TIMER1, baud=9600)

Example

Files:

ex_profile.c

Pre-Processor

137

#USE PWM

Syntax:

#USE PWM(options)

Elements:

Options are separated by commas and may be:

PWMx or CCPx

Selects the CCP to use, x being the module number to use.

OUTPUT=PIN_xx

Selects the PWM pin to use, pin must be one of the CCP pins. If device has

remappable pins compiler will assign specified pin to specified CCP module. If

CCP module not specified it will assign remappable pin to first available module.

TIMER=x

Selects timer to use with PWM module, default if not specified is

timer 2.

FREQUENCY=x

Sets the period of PWM based off specified value, should not be

used if PERIOD is already specified. If frequency can't be

achieved exactly compiler will generate a message specifying the

exact frequency and period of PWM. If neither FREQUENCY or

PERIOD is specified, the period defaults to maximum possible

period with maximum resolution and compiler will generate a

message specifying the frequency and period of PWM, or if using

same timer as previous stream instead of setting to maximum

possible it will be set to the same as previous stream. If using

same timer as previous stream and frequency is different compiler

will generate an error.

PERIOD=x

Sets the period of PWM, should not be used if FREQUENCY is

already specified. If period can't be achieved exactly compiler will

generate a message specifying the exact period and frequency of

PWM. If neither PERIOD or FREQUENCY is specified, the period

defaults to maximum possible period with maximum resolution and

compiler will generate a message specifying the frequency and

period of PWM, or if using same timer as previous stream instead

of setting to maximum possible it will be set to the same as

previous stream. If using same timer as previous stream and

period is different compiler will generate an error.

BITS=x

Sets the resolution of the the duty cycle, if period or frequency is

specified will adjust the period to meet set resolution and will

generate an message specifying the frequency and duty of PWM.

If period or frequency not specified will set period to maximum

possible for specified resolution and compiler will generate a

message specifying the frequency and period of PWM, unless

using same timer as previous then it will generate an error if

resolution is different then previous stream. If not specified then

frequency, period or previous stream using same timer sets the

resolution.

DUTY=x

Selects the duty percentage of PWM, default if not specified is

50%.

STREAM=id

Associates a stream identifier with the PWM signal. The identifier

may be used in functions like pwm_set_duty_percent().

Pre-Processor

138

Purpose:

This directive tells the compiler to setup a PWM on the specified

pin using the specified frequency, period, duty cycle and resolution.

The #USE DELAY directive must appear before this directive can

be used. This directive enables use of built-in functions such as

set_pwm_duty_percent(), set_pwm_frequency(),

set_pwm_period(), pwm_on() and pwm_off().

Example Files

None

Also See:

#USE RS232

Syntax:

#USE RS232 (options)

Elements:

Options are separated by commas and may be:

STREAM=id

Associates a stream identifier with this RS232 port.

The identifier may then be used in functions like

fputc.

BAUD=x

Set baud rate to x

XMIT=pin

Set transmit pin

RCV=pin

Set receive pin

FORCE_SW

Will generate software serial I/O routines even

when the UART pins are specified.

BRGH1OK

Allow bad baud rates on chips that have baud rate

problems.

ENABLE=pin

The specified pin will be high during transmit. This

may be used to enable 485 transmit.

DEBUGGER

Indicates this stream is used to send/receive data

though a CCS ICD unit. The default pin used in

B3, use XMIT= and RCV= to change the pin used.

Both should be the same pin.

RESTART_WDT

Will cause GETC() to clear the WDT as it waits for

a character.

INVERT

Invert the polarity of the serial pins (normally not

needed when level converter, such as the

MAX232). May not be used with the internal UART.

PARITY=X

Where x is N, E, or O.

Pre-Processor

139

BITS =X

Where x is 5-9 (5-7 may not be used with the SCI).

FLOAT_HIGH

The line is not driven high. This is used for open

collector outputs. Bit 6 in RS232_ERRORS is set if

the pin is not high at the end of the bit time.

ERRORS

Used to cause the compiler to keep receive errors

in the variable RS232_ERRORS and to reset

errors when they occur.

SAMPLE_EARLY

A getc() normally samples data in the middle of a

bit time. This option causes the sample to be at the

start of a bit time. May not be used with the UART.

RETURN=pin

For FLOAT_HIGH and MULTI_MASTER this is the

pin used to read the signal back. The default for

FLOAT_HIGH is the XMIT pin and for

MULTI_MASTER the RCV pin.

MULTI_MASTER

Uses the RETURN pin to determine if another

master on the bus is transmitting at the same time.

If a collision is detected bit 6 is set in

RS232_ERRORS and all future PUTC's are

ignored until bit 6 is cleared. The signal is checked

at the start and end of a bit time. May not be used

with the UART.

LONG_DATA

Makes getc() return an int16 and putc accept an

int16. This is for 9 bit data formats.

DISABLE_INTS

Will cause interrupts to be disabled when the

routines get or put a character. This prevents

character distortion for software implemented I/O

and prevents interaction between I/O in interrupt

handlers and the main program when using the

UART.

STOP=X

To set the number of stop bits (default is 1). This

works for both UART and

non-UART ports.

TIMEOUT=X

To set the time getc() waits for a byte in

milliseconds. If no character comes in within this

time the RS232_ERRORS is set to 0 as well as the

return value form getc(). This works for both UART

and non-UART ports.

Pre-Processor

140

SYNC_SLAVE

Makes the RS232 line a synchronous slave,

making the receive pin a clock in, and the data pin

the data in/out.

SYNC_MASTER

Makes the RS232 line a synchronous master,

making the receive pin a clock out, and the data

pin the data in/out.

SYNC_MATER_CONT

Makes the RS232 line a synchronous master mode

in continuous receive mode. The receive pin is set

as a clock out, and the data pin is set as the data

in/out.

UART1

Sets the XMIT= and RCV= to the chips first

hardware UART.

UART2

Sets the XMIT= and RCV= to the chips second

hardware UART.

NOINIT

No initialization of the UART peripheral is

performed. Useful for dynamic control of the UART

baudrate or initializing the peripheral manually at a

later point in the program's run time. If this option is

used, then setup_uart( ) needs to be used to

initialize the peripheral. Using a serial routine (such

as getc( ) or putc( )) before the UART is initialized

will cause undefined behavior.

Serial Buffer Options:

RECEIVE_BUFFER=x

Size in bytes of UART circular receive buffer,

default if not specified is zero. Uses an interrupt to

receive data, supports RDA interrupt or external

interrupts.

TRANSMIT_BUFFER=x

Size in bytes of UART circular transmit buffer,

default if not specified is zero.

TXISR

If TRANSMIT_BUFFER is greater then zero

specifies using TBE interrupt for transmitting data.

Default is NOTXISR if TXISR or NOTXISR is not

specified. TXISR option can only be used when

using hardware UART.

NOTXISR

If TRANSMIT_BUFFER is greater then zero

specifies to not use TBE interrupt for transmitting

data. Default is NOTXISR if TXISR or NOTXISR is

not specified and XMIT_BUFFER is greater then

zero

Flow Control Options:

RTS = PIN_xx

Pin to use for RTS flow control. When using

FLOW_CONTROL_MODE this pin is driven to the

active level when it is ready to receive more data.

Pre-Processor

141

In SIMPLEX_MODE the pin is driven to the active

level when it has data to transmit.

FLOW_CONTROL_MODE can only be use when

using RECEIVE_BUFFER

RTS_LEVEL=x

Specifies the active level of the RTS pin, HIGH is

active high and LOW is active low. Defaults to

LOW if not specified.

CTS = PIN_xx

Pin to use for CTS flow control. In both

FLOW_CONTROL_MODE and SIMPLEX_MODE

this pin is sampled to see if it clear to send data. If

pin is at active level and there is data to send it will

send next data byte.

CTS_LEVEL=x

Specifies the active level of the CTS pin, HIGH is

active high and LOW is active low. Default to LOW

if not specified

FLOW_CONTROL_MODE

Specifies how the RTS pin is used. For

FLOW_CONTROL_MODE the RTS pin is driven to

the active level when ready to receive data.

Defaults to FLOW_CONTROL_MODE when

neither FLOW_CONTROL_MODE or

SIMPLEX_MODE is specified. If RTS pin isn't

specified then this option is not used.

SIMPLEX_MODE

Specifies how the RTS pin is used. For

SIMPLEX_MODE the RTS pin is driven to the

active level when it has data to send. Defaults to

FLOW_CONTROL_MODE when neither

FLOW_CONTROL_MODE or SIMPLEX_MODE is

specified. If RTS pin isn't specified then this option

is not used.

Purpose:

This directive tells the compiler the baud rate and pins used for serial I/O. This

directive takes effect until another RS232 directive is encountered. The #USE

DELAY directive must appear before this directive can be used. This directive

enables use of built-in functions such as GETC, PUTC, and PRINTF. The functions

created with this directive are exported when using multiple compilation units. To

access the correct function use the stream identifier.

When using parts with built-in SCI and the SCI pins are specified, the SCI will be

used. If a baud rate cannot be achieved within 3% of the desired value using the

current clock rate, an error will be generated. The definition of the RS232_ERRORS

is as follows:

No UART:

 Bit 7 is 9th bit for 9 bit data mode (get and put).

 Bit 6 set to one indicates a put failed in float high mode.

With a UART:

 Used only by get:

Pre-Processor

142

 Copy of RCSTA register except:

 Bit 0 is used to indicate a parity error.

Warning:

The PIC UART will shut down on overflow (3 characters received by the hardware

with a GETC() call). The "ERRORS" option prevents the shutdown by detecting the

condition and resetting the UART.

Examples:

#use rs232(baud=9600, xmit=PIN_A2,rcv=PIN_A3)

Example

Files:

ex_cust.c

Also See:

getc(), putc(), printf(), setup_uart( ), RS2332 I/O overview

#USE RTOS

(The RTOS is only included with the PCW and PCWH packages.)

The CCS Real Time Operating System (RTOS) allows a PIC

micro controller to run regularly scheduled tasks without the need

for interrupts. This is accomplished by a function (RTOS_RUN())

that acts as a dispatcher. When a task is scheduled to run, the

dispatch function gives control of the processor to that task.

When the task is done executing or does not need the processor

anymore, control of the processor is returned to the dispatch

function which then will give control of the processor to the next

task that is scheduled to execute at the appropriate time. This

process is called cooperative multi-tasking.

Syntax:

#USE RTOS (options)

Elements:

options are separated by comma and may be:

timer=X

Where x is 0-4 specifying the timer used by the

RTOS.

minor_cycle=time

Where time is a number followed by s, ms, us, ns.

This is the longest time any task will run. Each

task's execution rate must be a multiple of this time.

The compiler can calculate this if it is not specified.

statistics

Maintain min, max, and total time used by each

task.

Purpose:

This directive tells the compiler which timer on the PIC to use for monitoring and

when to grant control to a task. Changes to the specified timer's prescaler will effect

the rate at which tasks are executed.

This directive can also be used to specify the longest time that a task will ever take

to execute with the minor_cycle option. This simply forces all task execution rates to

Pre-Processor

143

be a multiple of the minor_cycle before the project will compile successfully. If the

this option is not specified the compiler will use a minor_cycle value that is the

smallest possible factor of the execution rates of the RTOS tasks.

If the statistics option is specified then the compiler will keep track of the minimum

processor time taken by one execution of each task, the maximum processor time

taken by one execution of each task, and the total processor time used by each task.

When linking multiple compilation units, this directive must appear exactly the same

in each compilation unit.

Examples:

#use rtos(timer=0, minor_cycle=20ms)

Also See:

#TASK

#USE SPI

Syntax:

#USE SPI (options)

Elements:

Options are separated by commas and may be:

MASTER

Set the device as the master. (default)

SLAVE

Set the device as the slave.

BAUD=n

Target bits per second, default is as fast as possible.

CLOCK_HIGH=n

High time of clock in us (not needed if BAUD= is

used). (default=0)

CLOCK_LOW=n

Low time of clock in us (not needed if BAUD= is

used). (default=0)

DI=pin

Optional pin for incoming data.

DO=pin

Optional pin for outgoing data.

CLK=pin

Clock pin.

MODE=n

The mode to put the SPI bus.

ENABLE=pin

Optional pin to be active during data transfer.

LOAD=pin

Optional pin to be pulsed active after data is

transferred.

DIAGNOSTIC=pin

Optional pin to the set high when data is sampled.

SAMPLE_RISE

Sample on rising edge.

SAMPLE_FALL

Sample on falling edge (default).

BITS=n

Max number of bits in a transfer. (default=32)

SAMPLE_COUNT=n

Number of samples to take (uses majority vote).

(default=1

LOAD_ACTIVE=n

Active state for LOAD pin (0, 1).

ENABLE_ACTIVE=n

Active state for ENABLE pin (0, 1). (default=0)

IDLE=n

Inactive state for CLK pin (0, 1). (default=0)

ENABLE_DELAY=n

Time in us to delay after ENABLE is activated.

Pre-Processor

144

(default=0)

DATA_HOLD=n

Time between data change and clock change

LSB_FIRST

LSB is sent first.

MSB_FIRST

MSB is sent first. (default)

STREAM=id

Specify a stream name for this protocol.

SPI1

Use the hardware pins for SPI Port 1

SPI2

Use the hardware pins for SPI Port 2

FORCE_HW

Use the pic hardware SPI.

NOINIT

Don't initialize the hardware SPI Port

Purpose:

The SPI library contains functions to implement an SPI bus. After setting all of the

proper parameters in #USE SPI, the spi_xfer() function can be used to both transfer

and receive data on the SPI bus.

The SPI1 and SPI2 options will use the SPI hardware onboard the PIC. The most

common pins present on hardware SPI are: DI, DO, and CLK. These pins don’t

need to be assigned values through the options; the compiler will automatically

assign hardware-specific values to these pins. Consult your PIC’s data sheet as to

where the pins for hardware SPI are. If hardware SPI is not used, then software SPI

will be used. Software SPI is much slower than hardware SPI, but software SPI can

use any pins to transfer and receive data other than just the pins tied to the PIC’s

hardware SPI pins.

The MODE option is more or less a quick way to specify how the stream is going to

sample data. MODE=0 sets IDLE=0 and SAMPLE_RISE. MODE=1 sets IDLE=0

and SAMPLE_FALL. MODE=2 sets IDLE=1 and SAMPLE_FALL. MODE=3 sets

IDLE=1 and SAMPLE_RISE. There are only these 4 MODEs.

SPI cannot use the same pins for DI and DO. If needed, specify two streams: one to

send data and another to receive data.

The pins must be specified with DI, DO, CLK or SPIx, all other options are defaulted

as indicated above.

Examples:

#use spi(DI=PIN_B1, DO=PIN_B0, CLK=PIN_B2, ENABLE=PIN_B4, BITS=16)

// uses software SPI

#use spi(FORCE_HW, BITS=16, stream=SPI_STREAM)

// uses hardware SPI and gives this stream the name SPI_STREAM

Example

Files:

None

Also See:

spi_xfer()

Pre-Processor

145

#USE STANDARD_IO

Syntax:

#USE STANDARD_IO (port)

Elements:

port is A, B, C, D, E, F, G, H, J or ALL

Purpose:

This directive affects how the compiler will generate code for input and output

instructions that follow. This directive takes effect until another #USE XXX_IO

directive is encountered. The standard method of doing I/O will cause the compiler

to generate code to make an I/O pin either input or output every time it is used. On

the 5X processors this requires one byte of RAM for every port set to standard I/O.

Standard_io is the default I/O method for all ports.

When linking multiple compilation units be aware this directive only applies to the

current compilation unit.

Examples:

#use standard_io(A)

Example

Files:

ex_cust.c

Also See:

#USE FAST_IO, #USE FIXED_IO, General Purpose I/O

#USE TIMER

Syntax:

#USE TIMER (options)

Elements:

TIMER=x

Sets the timer to use as the tick timer. x is a valid timer that the PIC has. Default

value is 1 for Timer 1.

TICK=xx

Sets the desired time for 1 tick. xx can be used with ns(nanoseconds), us

(microseconds), ms (milliseconds), or s (seconds). If the desired tick time can't be

achieved it will set the time to closest achievable time and will generate a warning

specifying the exact tick time. The default value is 1us.

BITS=x

Sets the variable size used by the get_ticks() and set_ticks() functions for returning

and setting the tick time. x can be 8 for 8 bits, 16 for 16 bits or 32 for 32bits. The

default is 32 for 32 bits.

ISR

Uses the timer's interrupt to increment the upper bits of the tick timer. This mode

requires the the global interrupt be enabled in the main program.

NOISR

Pre-Processor

146

The get_ticks() function increments the upper bits of the tick timer. This requires

that the get_ticks() function be called more often then the timer's overflow rate.

NOISR is the default mode of operation.

STREAM=id

Associates a stream identifier with the tick timer. The identifier may be used in

functions like get_ticks().

DEFINE=id

Creates a define named id which specifies the number of ticks that will occur in one

second. Default define name if not specified is TICKS_PER_SECOND. Define

name must start with an ASCII letter 'A' to 'Z', an ASCII letter 'a' to 'z' or an ASCII

underscore ('_').

COUNTER or COUNTER=x

Sets up specified timer as a counter instead of timer. x specifies the prescallar to

setup counter with, default is1 if x is not specified specified. The function get_ticks()

will return the current count and the function set_ticks() can be used to set count to

a specific starting value or to clear counter.

Purpose:

This directive creates a tick timer using one of the PIC's timers. The tick timer is

initialized to zero at program start. This directive also creates the define

TICKS_PER_SECOND as a floating point number, which specifies that number of

ticks that will occur in one second.

Examples:

#USE TIMER(TIMER=1,TICK=1ms,BITS=16,NOISR)

unsigned int16 tick_difference(unsigned int16 current, unsigned

int16 previous) {

return(current - previous);

}

void main(void) {

unsigned int16 current_tick, previous_tick;

current_tick = previous_tick = get_ticks();

while(TRUE) {

current_tick = get_ticks();

if(tick_difference(current_tick, previous_tick) > 1000) {

output_toggle(PIN_B0);

previous_tick = current_tick;

}

Example

Files:

None

Also See:

get_ticks(), set_ticks()

Pre-Processor

147

#USE TOUCHPAD

Syntax:

#USE TOUCHPAD (options)

Elements:

RANGE=x

Sets the oscillator charge/discharge current range. If x is L, current is nominally 0.1

microamps. If x is M, current is nominally 1.2 microamps. If x is H, current is

nominally 18 microamps. Default value is H (18 microamps).

THRESHOLD=x

x is a number between 1-100 and represents the percent reduction in the nominal

frequency that will generate a valid key press in software. Default value is 6%.

SCANTIME=xxMS

xx is the number of milliseconds used by the microprocessor to scan for one key

press. If utilizing multiple touch pads, each pad will use xx milliseconds to scan for

one key press. Default is 32ms.

PIN=char

If a valid key press is determined on “PIN”, the software will return the character

“char” in the function touchpad_getc(). (Example: PIN_B0='A')

SOURCETIME=xxus (CTMU only)

xx is thenumber of microseconds each pin is sampled for by ADC during each scan

time period. Default is 10us.

Purpose:

This directive will tell the compiler to initialize and activate the Capacitive Sensing

Module (CSM)or Charge Time Measurement Unit (CTMU) on the microcontroller.

The compiler requires use of the TIMER0 and TIMER1 modules for CSM and

Timer1 ADC modules for CTMU, and global interrupts must still be activated in the

main program in order for the CSM or CTMU to begin normal operation. For most

applications, a higher RANGE, lower THRESHOLD, and higher SCANTIME will

result better key press detection. Multiple PIN's may be declared in “options”, but

they must be valid pins used by the CSM or CTMU. The user may also generate a

TIMER0 ISR with TIMER0's interrupt occuring every SCANTIME milliseconds. In

this case, the CSM's or CTMU's ISR will be executed first.

Examples:

#USE TOUCHPAD (THRESHOLD=5, PIN_D5='5', PIN_B0='C')

void main(void){

char c;

enable_interrupts(GLOBAL);

while(1){

c = TOUCHPAD_GETC(); //will wait until a pin is detected

} //if PIN_B0 is pressed, c will have 'C'

} //if PIN_D5 is pressed, c will have '5'

Example

Files:

None

Pre-Processor

148

#WARNING

Syntax:

#WARNING text

Elements:

text is optional and may be any text

Purpose:

Forces the compiler to generate a warning at the location this directive appears in

the file. The text may include macros that will be expanded for the display. This may

be used to see the macro expansion. The command may also be used to alert the

user to an invalid compile time situation.

Examples:

#if BUFFER_SIZE < 32

#warning Buffer Overflow may occur

#endif

Example

Files:

ex_psp.c

Also See:

#ERROR

Pre-Processor

149

#WORD

Syntax:

#WORD id = x

Elements:

id is a valid C identifier,

x is a C variable or a constant

Purpose:

If the id is already known as a C variable then this will locate the variable at address

x. In this case the variable type does not change from the original definition. If the id

is not known a new C variable is created and placed at address x with the type

int16

Warning: In both cases memory at x is not exclusive to this variable. Other

variables may be located at the same location. In fact when x is a variable, then id

and x share the same memory location.

Examples:

#word data = 0x0800

struct {

int lowerByte : 8;

int upperByte : 8;

} control_word;

#word control_word = 0x85

...

control_word.upperByte = 0x42;

Example

Files:

None

Also See:

#BIT, #BYTE, #LOCATE, #RESERVE

Pre-Processor

150

#ZERO_RAM

Syntax:

#ZERO_RAM

Elements:

None

Purpose:

This directive zero's out all of the internal registers that may be used to hold

variables before program execution begins.

Examples:

#zero_ram

void main() {

}

Example

Files:

ex_cust.c

Also See:

None

151

BUILT-IN FUNCTIONS

The CCS compiler provides a lot of built-in functions to access and use the PIC microcontroller's

peripherals. This makes it very easy for the users to configure and use the peripherals without

going into in depth details of the registers associated with the functionality. The functions

categorized by the peripherals associated with them are listed on the next page. Click on the

function name to get a complete description and parameter and return value descriptions.