pic ccs c manual

8/6/2019 Pic Ccs c Manual

1/370

C Compiler

Reference Manual

February 2011


2/370


3/370

This manual documents software version 4.Review the readme.txt file in the product directory for changes made since this version.

Copyright 1994, 2011 Custom Computer Services, Inc.All rights reserved worldwide. No part of this work may be reproduced or copied in any form or byany means- electronic, graphic, or mechanical, including photocopying, recording, taping, orinformation retrieval systems without prior permission.


4/370


5/370

v

Table of ContentsOverview ...........................................................................................................................................1

PCB, PCM and PCH Overview .....................................................................................................1Installation ....................................................................................................................................1Technical Support ........................................................................................................................2Directories ....................................................................................................................................2File Formats ..................................................................................................................................3Invoking the Command Line Compiler .......................................................................................5PCW Overview ..............................................................................................................................7

Program Syntax ............................................................................................................................. 17Overall Structure ........................................................................................................................ 17Comment ..................................................................................................................................... 17Trigraph Sequences .......... ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... 19Multiple Project Files .......... .......... ........... .......... ........... .......... ........... .......... ........... .......... ......... 19Multiple Compilation Units ........................................................................................................ 20Example ...................................................................................................................................... 30

Statements ..................................................................................................................................... 31Statements .................................................................................................................................. 31if ................................................................................................................................................... 32while ............................................................................................................................................ 32do ................................................................................................................................................. 33do-while ....................................................................................................................................... 33for ................................................................................................................................................ 33switch .......................................................................................................................................... 34return ........................................................................................................................................... 34goto ............................................................................................................................................. 35label ............................................................................................................................................. 35break ............................................................................................................................................ 35continue ...................................................................................................................................... 36expr.............................................................................................................................................. 36; .................................................................................................................................................... 36stmt.............................................................................................................................................. 36

Expressions ................................................................................................................................... 37Expressions ................................................................................................................................ 37Operators .................................................................................................................................... 38operator precedence ........... .......... ........... .......... ........... .......... ........... .......... ........... .......... ......... 39Reference Parameters ............................................................................................................... 40Variable Argument Lists ............................................................................................................ 40Default Parameters............ ........... .......... ........... .......... .......... ........... .......... ........... .......... ........... 41Overloaded Functions ............................................................................................................... 42

Data Definitions ............................................................................................................................. 43Basic and Special types .......... ........... .......... ........... .......... ........... .......... .......... ........... .......... .... 43Declarations ................................................................................................................................ 46Non-RAM Data Definitions ......................................................................................................... 47Using Program Memory for Data .......... ........... .......... .......... ........... .......... ........... .......... ........... 48Function Definition .......... ........... .......... ........... .......... ........... .......... ........... .......... ........... .......... .. 50

Functional Overviews ........... ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... 51


6/370

CCS C Compiler Reference Manual February 2011

vi

I2C................................................................................................................................................ 51ADC ............................................................................................................................................. 52Analog Comparator ........... ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... 53CAN Bus ...................................................................................................................................... 54CCP1 ............................................................................................................................................ 56CCP2, CCP3, CCP4, CCP5, CCP6.......... ........... .......... .......... ........... .......... ........... .......... ........... 57Configuration Memory ......... ........... ........... .......... ........... .......... .......... ........... .......... ........... ....... 57DAC ............................................................................................................................................. 58

Data Eeprom ............................................................................................................................... 59External Memory ........................................................................................................................ 60General Purpose I/O ................................................................................................................... 61Internal LCD ................................................................................................................................ 62Internal Oscillator ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... .......... .... 63Interrupts .................................................................................................................................... 64Linker .......................................................................................................................................... 65Low Voltage Detect .................................................................................................................... 69PMP ............................................................................................................................................. 69Power PWM ................................................................................................................................. 71Program Eeprom ........................................................................................................................ 72PSP .............................................................................................................................................. 74RS232 I/O .................................................................................................................................... 74RTOS ........................................................................................................................................... 76SPI ............................................................................................................................................... 78Timer0 ......................................................................................................................................... 79Timer1 ......................................................................................................................................... 80Timer2 ......................................................................................................................................... 81Timer3 ......................................................................................................................................... 82Timer4 ......................................................................................................................................... 82Timer5 ......................................................................................................................................... 82USB.............................................................................................................................................. 83Voltage Reference .......... .......... ........... .......... ........... .......... .......... ........... .......... ........... .......... .... 86WDT or Watch Dog Timer .......... .......... ........... .......... ........... .......... ........... .......... ........... .......... .. 87

Pre-Processor Directives .............................................................................................................. 89PRE-PROCESSOR ...................................................................................................................... 89#ASM #ENDASM ......................................................................................................................... 91#BIT ............................................................................................................................................. 94#BUILD ........................................................................................................................................ 95#BYTE .......................................................................................................................................... 96#CASE ......................................................................................................................................... 97_DATE_ ....................................................................................................................................... 97 #DEFINE ...................................................................................................................................... 98#DEVICE ...................................................................................................................................... 99#DEFINEDINC ........................................................................................................................... 101_DEVICE_ .................................................................................................................................. 102 #ERROR .................................................................................................................................... 102#EXPORT (options) .................................................................................................................. 103__FILE__ ................................................................................................................................... 104 __FILENAME__ ......................................................................................................................... 105 #FILL_ROM ............................................................................................................................... 105


7/370

Table Of Contents

vii

#FUSES ..................................................................................................................................... 106#HEXCOMMENT ....................................................................................................................... 107#ID.............................................................................................................................................. 107#IF exp #ELSE #ELIF #ENDIF ........... .......... ........... .......... ........... .......... ........... .......... ........... ... 108#IFDEF #IFNDEF #ELSE #ELIF #ENDIF ........... .......... ........... .......... .......... ........... .......... ......... 109#IGNORE_WARNINGS ............................................................................................................. 110#IMPORT (options) .......... ........... .......... ........... .......... ........... .......... ........... .......... ........... .......... 110#INCLUDE ................................................................................................................................. 111

#INLINE ..................................................................................................................................... 112#INT_xxxx ................................................................................................................................. 113#INT_DEFAULT ......................................................................................................................... 117#INT_GLOBAL .......................................................................................................................... 117__LINE__ ................................................................................................................................... 118 #LIST ......................................................................................................................................... 118#LINE ......................................................................................................................................... 119#LOCATE .................................................................................................................................. 119#MODULE .................................................................................................................................. 120#NOLIST .................................................................................................................................... 120#OPT .......................................................................................................................................... 121#ORG ......................................................................................................................................... 121#OCS ......................................................................................................................................... 123__PCB__ .................................................................................................................................... 123 __ PCM __ ................................................................................................................................. 124 __ PCH __ .................................................................................................................................. 124 #PIN_SELECT ........................................................................................................................... 125#PRAGMA ................................................................................................................................. 126#PRIORITY ................................................................................................................................ 127#RESERVE ................................................................................................................................ 127#ROM ......................................................................................................................................... 128#SEPARATE .............................................................................................................................. 129#SERIALIZE .............................................................................................................................. 129#TASK ....................................................................................................................................... 131__ TIME __ ................................................................................................................................. 132 #TYPE ........................................................................................................................................ 132#UNDEF ..................................................................................................................................... 133#USE DELAY ............................................................................................................................. 134#USE DYNAMIC_MEMORY .......... .......... ........... .......... ........... .......... .......... ........... .......... ......... 135#USE FAST_IO .......................................................................................................................... 136#USE FIXED_IO ........................................................................................................................ 136#USE I2C ................................................................................................................................... 137#USE RS232 ............................................................................................................................. 138#USE RTOS .............................................................................................................................. 142#USE SPI ................................................................................................................................... 143#USE STANDARD_IO .......... .......... ........... .......... ........... .......... ........... .......... ........... .......... ....... 144#USE TIMER .............................................................................................................................. 145#USE TOUCHPAD..................................................................................................................... 146#WARNING ................................................................................................................................ 147#WORD ...................................................................................................................................... 148#ZERO_RAM ............................................................................................................................. 148


8/370


viii

Built-in-Functions ........................................................................................................................ 149BUILT-IN-FUNCTIONS .............................................................................................................. 149abs( ) .......................................................................................................................................... 153adc_done( ) ............................................................................................................................... 154assert( ) ..................................................................................................................................... 155atoe( ) ........................................................................................................................................ 155atof( ) ......................................................................................................................................... 156atoi( ) atol( ) atoi32( ) ........... .......... ........... .......... ........... .......... ........... .......... ........... .......... ....... 156

bit_clear( ) ................................................................................................................................. 157bit_set( ) .................................................................................................................................... 158bit_test( ) ................................................................................................................................... 158brownout_enable( ) .................................................................................................................. 159bsearch( ) .................................................................................................................................. 160calloc( ) ...................................................................................................................................... 161ceil( ) .......................................................................................................................................... 161clear_interrupt( ) ......... ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... ..... 162dac_write( ) ............................................................................................................................... 162delay_cycles( ) .......................................................................................................................... 163delay_ms( ) ............................................................................................................................... 163delay_us( ) ................................................................................................................................ 164disable_interrupts( ) .......... ........... .......... ........... .......... ........... .......... .......... ........... .......... ......... 165div( ) ldiv( ) ................................................................................................................................ 166enable_interrupts( ) ........... ........... .......... ........... .......... ........... .......... .......... ........... .......... ......... 167erase_eeprom ........................................................................................................................... 168erase_program_eeprom( ) ........... .......... ........... .......... ........... .......... .......... ........... .......... ......... 168exp( ) .......................................................................................................................................... 169ext_int_edge( ) ........... .......... ........... .......... .......... ........... .......... ........... .......... ........... .......... ....... 169fabs( ) ........................................................................................................................................ 170floor( ) ........................................................................................................................................ 170fmod( ) ....................................................................................................................................... 171free( ) ......................................................................................................................................... 171frexp( ) ....................................................................................................................................... 172get_timerx( ) .............................................................................................................................. 172get_tris_x( ) ............................................................................................................................... 173get_ticks( ) ................................................................................................................................ 174getc( ) getch( ) getchar( ) fgetc( ) .......... ........... .......... .......... ........... .......... ........... .......... ......... 174getenv( ) .................................................................................................................................... 175gets( ) fgets( ) ........................................................................................................................... 177goto_address( ) ........................................................................................................................ 178high_speed_adc_done( ) ......................................................................................................... 179i2c_isr_state( ) .......................................................................................................................... 180i2c_poll( ) .................................................................................................................................. 181i2c_read( ) ................................................................................................................................. 181i2c_slaveaddr( ) ........................................................................................................................ 182i2c_start( ) ................................................................................................................................. 183i2c_stop( ) ................................................................................................................................. 184i2c_write( ) ................................................................................................................................ 184i2c_speed( ) .............................................................................................................................. 185input( ) ....................................................................................................................................... 186


9/370

Table Of Contents

ix

input_change_x( )........... .......... ........... .......... ........... .......... .......... ........... .......... ........... .......... .. 187input_state( ) ............................................................................................................................. 187input_x( ) ................................................................................................................................... 188interrupt_active( ) ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... .......... .. 189isalnum(char) isalpha(char) isdigit(char) islower(char) isspace(char) isupper(char)isxdigit(char) iscntrl(x) isgraph(x) isprint(x) ispunct(x) ........... .......... ........... .......... ........... ... 189isamong( ) ................................................................................................................................. 190itoa( ) ......................................................................................................................................... 191

jump_to_isr ............................................................................................................................... 192kbhit( ) ....................................................................................................................................... 192label_address( ) .......... ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... ..... 193labs( ) ......................................................................................................................................... 194lcd_load( ) ................................................................................................................................. 194lcd_contrast( ) .......................................................................................................................... 195lcd_symbol( ) ............................................................................................................................ 195ldexp( ) ...................................................................................................................................... 196log( ) .......................................................................................................................................... 197log10( ) ...................................................................................................................................... 198longjmp( ) .................................................................................................................................. 198make8( ) ..................................................................................................................................... 199make16( ) ................................................................................................................................... 199make32( ) ................................................................................................................................... 200malloc( ) .................................................................................................................................... 200memcpy( ) memmove( ) ........... ........... .......... ........... .......... ........... .......... .......... ........... .......... .. 201memset( ) .................................................................................................................................. 202modf( ) ....................................................................................................................................... 202_mul( ) ....................................................................................................................................... 203 nargs( ) ...................................................................................................................................... 203offsetof( ) offsetofbit( ) ............................................................................................................. 204output_x( ) ................................................................................................................................. 205output_bit( ) .............................................................................................................................. 206output_drive( ) .......................................................................................................................... 207output_float( ) .......... .......... ........... .......... ........... .......... .......... ........... .......... ........... .......... ......... 207output_high( ) .......... .......... ........... .......... ........... .......... .......... ........... .......... ........... .......... ......... 208output_low( ) .......... ........... .......... .......... ........... .......... ........... .......... ........... .......... ........... .......... 208output_toggle( ) .......... ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... ..... 209perror( ) ..................................................................................................................................... 210port_x_pullups ( ) ..................................................................................................................... 210pow( ) pwr( ) .............................................................................................................................. 211printf( ) fprintf( ) ........................................................................................................................ 212psp_output_full( ) psp_input_full( ) psp_overflow( ) .......... ........... .......... ........... .......... ......... 213putc( ) putchar( ) fputc( ) .......... ........... .......... ........... .......... ........... .......... .......... ........... .......... .. 214puts( ) fputs( ) .......... .......... ........... .......... ........... .......... .......... ........... .......... ........... .......... ......... 215qsort( ) ....................................................................................................................................... 215rand( ) ........................................................................................................................................ 216read_adc( ) ................................................................................................................................ 217read_bank( ) .............................................................................................................................. 218read_calibration( ) .................................................................................................................... 219read_configuration_memory( ) ............................................................................................... 219


10/370


x

read_eeprom( ) ......................................................................................................................... 220read_high_speed_adc( ) .......................................................................................................... 220read_program_eeprom( ) ........... .......... ........... .......... ........... .......... ........... .......... ........... .......... 222read_program_memory( ) .......... .......... ........... .......... ........... .......... ........... .......... ........... .......... 222read_external_memory( ) ........... .......... ........... .......... ........... .......... ........... .......... ........... .......... 222realloc( ) .................................................................................................................................... 223reset_cpu( ) ............................................................................................................................... 224restart_cause( ) ........................................................................................................................ 224

restart_wdt( ) ............................................................................................................................ 225rotate_left( ) .............................................................................................................................. 226rotate_right( ) ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... .......... ......... 226rtc_alarm_read ......................................................................................................................... 227rtc_alarm_write( ) ..................................................................................................................... 228rtc_read( ) .................................................................................................................................. 228rtc_write( ) ................................................................................................................................. 229rtos_await( ) .............................................................................................................................. 229rtos_disable( ) ........................................................................................................................... 230rtos_enable( ) ............................................................................................................................ 230rtos_msg_poll( ) ....................................................................................................................... 231rtos_msg_read( ) ...................................................................................................................... 231rtos_msg_send( ) ..................................................................................................................... 232rtos_run( ) ................................................................................................................................. 233rtos_signal( ) ............................................................................................................................. 233rtos_stats( ) ............................................................................................................................... 234rtos_terminate( ) ......... ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... ..... 234rtos_wait( ) ................................................................................................................................ 235rtos_yield( ) ............................................................................................................................... 235set_adc_channel( ) .......... ........... .......... ........... .......... ........... .......... ........... .......... ........... .......... 236set_power_pwmx_duty( ) ........................................................................................................ 237set_power_pwm_override( ) ........... ........... .......... ........... .......... ........... .......... .......... ........... ..... 237set_pullup( ) .............................................................................................................................. 238set_pwm1_duty( ) set_pwm2_duty( ) set_pwm3_duty( ) set_pwm4_duty( ) set_pwm5_duty() .................................................................................................................................................. 238set_rtcc( ) set_timer0( ) set_timer1( ) set_timer2( ) set_timer3( ) set_timer4( )set_timer5( ) .............................................................................................................................. 239set_ticks( ) ................................................................................................................................ 240set_timerx( ) .............................................................................................................................. 241set_tris_x( ) ............................................................................................................................... 241set_uart_speed( )...................................................................................................................... 242setjmp( ) .................................................................................................................................... 243setup_adc(mode)...................................................................................................................... 243setup_adc_ports( ) ................................................................................................................... 244setup_ccp1( ) setup_ccp2( ) setup_ccp3( ) setup_ccp4( ) setup_ccp5( ) setup_ccp6( ) .... 244setup_comparator( ) .......... ........... .......... ........... .......... ........... .......... .......... ........... .......... ......... 246setup_counters( ) ..................................................................................................................... 247setup_dac( ) .............................................................................................................................. 248setup_external_memory( ) ........... .......... ........... .......... ........... .......... .......... ........... .......... ......... 248setup_high_speed_adc( ) ........................................................................................................ 249setup_high_speed_adc_pair( ) ........... .......... ........... .......... ........... .......... .......... ........... .......... .. 250


11/370

Table Of Contents

xi

setup_lcd( ) ............................................................................................................................... 251setup_low_volt_detect( ) ......................................................................................................... 252setup_oscillator( ) .................................................................................................................... 252setup_opamp1( ) setup_opamp2( ) ......................................................................................... 253setup_power_pwm( ) ........... .......... ........... .......... ........... .......... ........... .......... ........... .......... ....... 254setup_power_pwm_pins( ) ...................................................................................................... 255setup_pmp(option,address_mask) ......................................................................................... 255setup_psp(option,address_mask) .......................................................................................... 256

setup_qei( ) ............................................................................................................................... 257setup_rtc( ) ................................................................................................................................ 258setup_rtc_alarm( ) .................................................................................................................... 258setup_spi( ) setup_spi2( ) ........................................................................................................ 259setup_timer_0( )........................................................................................................................ 259setup_timer_1( )........................................................................................................................ 260setup_timer_2( )........................................................................................................................ 261setup_timer_3( )........................................................................................................................ 261setup_timer_4( )........................................................................................................................ 262setup_timer_5( )........................................................................................................................ 263setup_uart( ) ............................................................................................................................. 264setup_vref( ) .............................................................................................................................. 265setup_wdt( ) .............................................................................................................................. 266shift_left( ) ................................................................................................................................. 267shift_right( ) .............................................................................................................................. 268sin( ) cos( ) tan( ) asin( ) acos() atan() sinh() cosh() tanh() atan2()........ .......... ........... .......... 269sleep( ) ....................................................................................................................................... 270sleep_ulpwu( ) .......................................................................................................................... 271spi_data_is_in( ) spi_data_is_in2( ) .......... .......... ........... .......... .......... ........... .......... ........... ..... 271spi_read( ) spi_read2( ) .......... ........... .......... ........... .......... ........... .......... ........... .......... ........... ... 272spi_write( ) spi_write2( ) .......... ........... .......... ........... .......... ........... .......... .......... ........... .......... .. 273spi_xfer( ) .................................................................................................................................. 273sprintf( ) ..................................................................................................................................... 274sqrt( ) ......................................................................................................................................... 275srand( ) ...................................................................................................................................... 275STANDARD STRING FUNCTIONS( ) memchr( ) memcmp( ) strcat( ) strchr( ) strcmp( )strcoll( ) strcspn( ) .................................................................................................................... 276strerror( ) stricmp( ) strlen( ) strlwr( ) strncat( ) strncmp( ) strncpy( ) strpbrk( ) strrchr( )strspn( ) strstr( ) strxfrm( ) ........... .......... ........... .......... ........... .......... .......... ........... .......... ......... 276strcpy( ) strcopy( ) .................................................................................................................... 277strtod( ) ...................................................................................................................................... 278strtok( ) ...................................................................................................................................... 278strtol( ) ....................................................................................................................................... 280strtoul( ) ..................................................................................................................................... 280swap( ) ....................................................................................................................................... 281tolower( ) toupper( ) .......... ........... .......... ........... .......... ........... .......... .......... ........... .......... ......... 282touchpad_getc( ) ...................................................................................................................... 282touchpad_hit( ) ......................................................................................................................... 283touchpad_state( ) ..................................................................................................................... 284va_arg( ) .................................................................................................................................... 285va_end( ) ................................................................................................................................... 286


12/370


xii

va_start( ) .................................................................................................................................. 287write_bank( ) ............................................................................................................................. 288write_configuration_memory( ) .......... .......... ........... .......... ........... .......... .......... ........... .......... .. 289write_eeprom( ) ........................................................................................................................ 289write_external_memory( ) .......... .......... ........... .......... ........... .......... ........... .......... ........... .......... 290write_program_eeprom( ) ........................................................................................................ 291write_program_memory( ) ....................................................................................................... 291

Standard C Include Files ............................................................................................................. 293

errno.h ....................................................................................................................................... 293float.h ........................................................................................................................................ 293limits.h ....................................................................................................................................... 294locale.h ...................................................................................................................................... 295setjmp.h .................................................................................................................................... 295stddef.h ..................................................................................................................................... 295stdio.h ....................................................................................................................................... 295stdlib.h ...................................................................................................................................... 296

Error Messages ........... .......... ........... .......... ........... .......... .......... ........... .......... ........... .......... ......... 297Compiler Error Messages ........................................................................................................ 297

Compiler Warning Messages ...................................................................................................... 309Compiler Warning Messages ........... .......... ........... .......... ........... .......... ........... .......... ........... ... 309

COMMON QUESTIONS AND ANSWERS ........... .......... ........... .......... ........... .......... ........... .......... 313How are type conversions handled? ......... ........... .......... ........... .......... ........... .......... ........... ... 313How can a constant data table be placed in ROM? ........... .......... ........... .......... ........... .......... 314How can I use two or more RS-232 ports on one PIC? ....................................................... 315How can the RB interrupt be used to detect a button press? ......... ........... .......... ........... ..... 316How do I do a printf to a string? ......... ........... .......... ........... .......... ........... .......... ........... .......... 316How do I directly read/write to internal registers? .......... ........... .......... .......... ........... .......... .. 317How do I get getc() to timeout after a specified time? .................... .......... ........... .......... ....... 318How do I wait only a specified time for a button press? .......... .......... ........... .......... ........... ... 318How do I make a pointer to a function? ................. .......... .......... ........... .......... ........... .......... .. 319How do I put a NOP at location 0 for the ICD? .......... ........... .......... .......... ........... .......... ......... 319How do I write variables to EEPROM that are not a byte? .......... ........... .......... ........... .......... 320How does one map a variable to an I/O port? ......... ........... .......... ........... .......... ........... .......... 320How does the PIC connect to a PC? ........... .......... ........... .......... ........... .......... ........... .......... 322How does the PIC

connect to an I2C device? .................. .......... ........... .......... ........... .......... 323

How much time do math operations take? .......... .......... ........... .......... ........... .......... ........... ... 324Instead of 800, the compiler calls 0. Why? ................... .......... .......... ........... .......... ........... ..... 325Instead of A0, the compiler is using register 20. Why? .......... .......... ........... .......... ........... ... 325What can be done about an OUT OF RAM error?.............. .......... ........... .......... ........... .......... 326What is an easy way for two or more PICs to communicate? .......... .......... ........... .......... .. 327What is the format of floating point numbers? ........... .......... ........... .......... ........... .......... ....... 328Why does the .LST file look out of order? ........... .......... ........... .......... ........... .......... ........... ... 329Why does the compiler show less RAM than there really is? ......... ........... .......... ........... ..... 330Why does the compiler use the obsolete TRIS?......... .......... ........... .......... ........... .......... ....... 331Why is the RS-232 not working right? ........... .......... ........... .......... ........... .......... ........... .......... 331

EXAMPLE PROGRAMS ............................................................................................................... 333EXAMPLE PROGRAMS ............................................................................................................ 333

SOFTWARE LICENSE AGREEMENT .......................................................................................... 359SOFTWARE LICENSE AGREEMENT ......... ........... .......... ........... .......... ........... .......... ........... ... 359


13/370

1

OVERVIEW

PCB, PCM and PCH Overview

The PCB, PCM, and PCH are separate compilers. PCB is for 12-bit opcodes, PCM is for 14-bitopcodes, and PCH is for 16-bit opcode PIC microcontrollers. Due to many similarities, all threecompilers are covered in this reference manual. Features and limitations that apply to only specificmicrocontrollers are indicated within. These compilers are specifically designed to meet the uniqueneeds of the PIC microcontroller. This allows developers to quickly design applications softwarein a more readable, high-level language.

When compared to a more traditional C compiler, PCB, PCM, and PCH have some limitations. Asan example of the limitations, function recursion is not allowed. This is due to the fact that the PIChas 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 bittwiddling operations. All normal C data types are supported along with pointers to constant arrays,fixed point decimal, and arrays of bits.

Installation

PCB, PCM, PCH, and PCD Installation:Insert the CD ROM and from Windows Start|Run type:D:SETUP

PCW, PCWH, PCWHD, and PCDIDE Installation:Insert the CD ROM, select each of the programs you wish to install and follow the on-screeninstructions.


14/370

C Compiler Reference Manual February 2011

2

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 yearmaintenance 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, ifany, transition difficulty.

To ensure any problem that may occur is corrected quickly and diligently, it is recommended tosend an email to "x-text-underline: normal; [email protected] or use the Technical SupportWizard in PCW. Include the version of the compiler, an outline of the problem and attach any fileswith 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 emailresponses 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 .PJT file

The same directory as the source file

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

The compiler itself is a DLL file. The DLL files are in a DLL directory by default in C:\Program

Files\PICC\DLL. Old compiler versions may be kept by renaming this directory.

Compiler Version 4 and above can tolerate two compilers of different versions in the samedirectory. Install an older version (4.xx ) and rename the devices4.dat file to devices4X.dat where Xis B for PCB, M is for PCM, and H is for PCH. Install the newer compiler and do the same renameof the devices4.dat file.
http://www.ccsinfo.com/download.shtmlhttp://www.ccsinfo.com/download.shtmlhttp://www.ccsinfo.com/download.shtml


15/370

Overview

3

File Formats

The compiler can output 8-bet hex, 16-bit hex, and binary files. Three listing formats are available:1) Standard format resembles the Microchip tools, and may be required by other Third-Party tools.2) Simple format is generated by compiler and is easier to read.

3) Symbolic format uses names versus addresses for registers.

The debug files may be output as Microchip .COD file, Advanced Transdata .MAP file, expanded.COD file for CCS debugging or MPLAB 7.xx .COF file. All file formats and extensions may beselected via Options File Associations option in Windows IDE.

.C This is the source file containing user C source code.

.H These are standard or custom header files used to define pins, register, register bits,functions and preprocessor directives.

.PJT 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 assemblycode generated for that line.

The elements in the .LST file may be selected in PCW under Options>ProjectOptions>File Formats

Matchcode

-Includes the HEX opcode for each instruction

SFRnames

-Instead of an address a name is used. For example instead of 044is will show CORCON

Symbols -Shows variable names instead of addresses

Interpret -Adds a pseudo code interpretation to the right of assemblyinstruction to help understand the operation.For example:LSR W4,#8,W5 : W5=W4>>8

.SYM This is the symbol map which shows each register location and what program variablesare stored in each location.

.STA The statistics file shows the RAM, ROM, and STACK usage. It provides information onthe source codes structural and textual complexities using Halstead and McCabemetrics.

.TRE The tree file shows the call tree. It details each function and what functions it calls alongwith the ROM and RAM usage for each function.


16/370


4

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

.COF This is a binary containing machine code and debugging information.

.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 TextFile.

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

.ESYM This file is generated for the IDE users. The file contains Identifiers and Commentinformation. This data can be used for automatic documentation generation and for theIDE helpers.

.OSYM This file is generated when the compiler is set to export a relocatable object file. This fileis a .sym file for just the one unit.


17/370

Overview

5

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+FS Select SXC (SX) +EO Old error file format+ES Standard error file -T Do not generate a tree file+T Create call tree (.TRE) -A Do not create stats file (.STA)+A 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 +DF Enables the output of a OFF debug file.

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

+P 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

+Z 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 theinclude file paths.

-P Close compile window after compile is complete

+M Generate a symbol file (.SYM)

-M Do not create symbol file

+J Create a project file (.PJT)

-J Do not create PJT file

+ICD Compile for use with an ICD


18/370


6

#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

+V Show compiler version (no compile is done)

+Q 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 thespecified 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 areread from that file before they are processed on the command line.

Examples:CCSC +FM C:\PICSTUFF\TEST.C

CCSC +FM +P +T TEST.C


19/370

Overview

7

PCW Overview

Beginning in version 4.XXX of PCW, the menus and toolbars are set-up in specially organizedRibbons. Each Ribbon relates to a specific type of activity an is only shown when selected. CCS hasincluded a "User Toolbar" Ribbon that allows the user to customize the Ribbon for individual needs.

File MenuClick on this icon for the following items:

New Creates a new File

Open Opens a file to the editor. Includes options for Source, Project, Output, RTF, FlowChart, Hex or Text. Ctrl+O is the shortcut.

Close Closes the file currently open for editing. Note, that while a file is open in PCW forediting, no other program may access the file. Shift+F11 is the shortcut.

Close All Closes all files open in the PCW.

Save Saves the file currently selected for editing. Crtl+S is the shortcut.

Save As Prompts for a file name to save the currently selected file.

Save All All open files are saved.

Encrypt Creates an encrypted include file. The standard compiler #include directive willaccept files with this extension and decrypt them when read. This allows includefiles to be distributed without releasing the source code.

Print Prints the currently selected file.

RecentFiles The right-side of the menu has a Recent Files list for commonly used files.

Exit The bottom of the menu has an icon to terminate PCW.


20/370


8

Project Menu Ribbon

Project Open an existing project (.PJT) file as specified and the main source file is loaded.

PICWizard

This command is a fast way to start a new project. It will bring up a screen with fill-in-the-blanks to create a new project. When items such as RS232 I/O, i2C, timers,interrupts, A/D options, drivers and pin name are specified by the user, the Wizardwill select required pins and pins that may have combined use. After all selectionsare made, the initial .c and .h files are created with #defines, #includes andinitialization commands required for the project.

Create Create a new project with the ability to add/remove source files, include files, globaldefines and specify output files.

Open AllFiles

Open all files in a project so that all include files become known for compilation.

CloseProject

Close all files associated with project.

Find Textin Project

Ability to search all files for specific text string.


21/370

Overview

9

Edit Menu Ribbon

Undo Undoes the last deletion

Redo Re-does the last undo

Cut Moves the selected text from the file to the clipboard.

Copy Copies the selected text to the clipboard.

Paste Applies the clipboard contents to the cursor location.

UnindentSelection

Selected area of code will not be indented.

IndentSelection

Selected area of code will be properly indented.

Select All Highlighting of all text.

Copy fromFile

Copies the contents of a file to the cursor location.

Past toFile

Applies the selected text to a file.

Macros Macros for recording, saving and loading keystrokes and mouse-strokes.


22/370


10

Search Menu Ribbon

Find Locate text in file.

Find Text inProject

Searches all files in project for specific text string.

Find Next Wordat Cursor

Locates the next occurrence of the text selected in the file.

Goto Line Cursor will move to the user specified line number.

Toggle Bookmar Set/Remove bookmark (0-9) at the cursor location.

Goto Bookmark Move cursor to the specified bookmark (0-9).

Options Menu Ribbon

Project Options Add/remove files, include files, global defines and output files.

EditorProperties

Allows user to define the set-up of editor properties for Windows options.

Tools Window display of User Defined Tools and options to add and apply.

SoftwareUpdatesProperties

Ability for user to select which software to update, frequency to remindProperties user and where to archive files.

Printer Setup Set the printer port and paper and other properties for printing.

Toolbar Setup Customize the toolbar properties to add/remove icons and keyboard commands.

FileAssociations

Customize the settings for files according to software being used.


23/370

Overview

11

Compile Menu Ribbon

Compile Compiles the current project in status bar using the current compiler.

Build Compiles one or more files within a project.

Compiler Pull-down menu to choose the compiler needed.

LookupPart

Choose a device and the compiler needed will automatically be selected.

ProgramChip

Lists the options of CCS ICD or Mach X programmers and will connect to SIOWprogram.

Debug Allows for input of .hex and will output .asm for debugging.

C/ASMList

Opens listing file in read-only mode. Will show each C source line code and theassociated assembly code generated.

SymbolMap

Opens the symbol file in read-only mode. Symbol map shows each register locationand what program variable are saved in each location.

Call Tree Opens the tree file in read-only mode. The call tree shows each function and whatfunctions it calls along with the ROM and RAM usage for each.

Statistics Opens the statistics file in read-only mode. The statistics file shows each function,the ROM and RAM usage by file, segment and name.

DebugFile

Opens the debug file in read-only mode. The listing file shows each C source linecode and the associated assembly code generated.


24/370


12

View Menu Ribbon

ValidInterrupts

This displays a list of valid interrupts used with the #INT_keyword for the chip usedin the current project. The interrupts for other chips can be viewed using the dropdown menu.

ValidFuses

This displays a list of valid FUSE used with the #FUSES directive associated withthe chip used in the current project. The fuses for other chips can be viewed usingthe drop down menu.

DataSheets

This tool is used to view the Manufacturer data sheets for all the Microchip partssupported by the compiler.

Part Errata This allows user to view the errata database to see what errata is associated with apart and if the compiler has compensated for the problem.

SpecialRegisters

This displays the special function registers associated with the part.

New EditWindow

This will open a new edit window which can be tiled to view files side by side.

DockEditorWindow

Selecting this checkbox will dock the editor window into the IDE.

ProjectFiles

When this checkbox is selected, the Project files slide out tab is displayed. This willallow quicker access to all the project source files and output files.

ProjectList

Selecting this checkbox displays the Project slide out tab. The Project slide out tabdisplays all the recent project files.

Output Selecting this checkbox will enable the display of warning and error messagesgenerated by the compiler.

IdentifierList

Selecting this checkbox displays the Identifier slide out tab. It allows quick accessto project identifiers like functions, types, variables and defines.


25/370

Overview

13

Tools Menu Ribbon

Device Editor This tool is used to edit the device database used by the compiler to controlcompilations. The user can edit the chip memory, interrupts, fuses and otherperipheral settings for all the supported devices.

DeviceSelector

This tool uses the device database to allow for parametric selection of devices.The tool displays all eligible devices based on the selection criteria.

File Compare This utility is used to compare two files. Source or text files can be comparedline by line and list files can be compared by ignoring the RAM/ROM addressesto make the comparisons more meaningful.

NumericConverter

This utility can be used to convert data between different formats. The user cansimultaneously view data in various formats like binary, hex, IEEE, signed andunsigned.

Serial PortMonitor

This tool is an easy way of connecting a PIC to a serial port. Data can be viewedin ASCII or hex format. An entire hex file can be transmitted to the PIC which isuseful for bootloading application.

Disassembler This tool will take an input hex file and output an ASM.

Convert Datato C

This utility will input data from a text file and generate code is form of a #ROMor CONST statement.

ExtractCalibration

This tool will input a hex file and extract the calibration data to a C include file.This feature is useful for saving calibration data stored at top of programmemory from certain PIC chips.

MACH X This will call the Mach-X.exe program and will download the hex file for thecurrent project onto the chip.

ICD This will call the ICD.exe program and will download the hex file for the currentproject onto the chip.


26/370


14

Debug Menu Ribbon

EnableDebugger

Enables the debugger. Opens the debugger window, downloads the code and on-chip debugger and resets the target into the debugger.

Reset This will reset the target into the debugger.

SingleStep

Executes one source code line at a time. A single line of C source code or ASMcode is executed depending on whether the source code or the list file tab in theeditor is active.

Step Over This steps over the target code. It is useful for stepping over function calls.

Run toCursor

Runs the target code to the cursor. Place the cursor at the desired location in thecode and click on this button to execute the code till that address.

Snapshot This allows users to record various debugging information. Debug information likewatches, ram values, data eeprom values, rom values , peripheral status can beconveniently logged. This log can be saved, printed, overwritten or appended.

Run Script This tool allows the IDE's integrated debugger to execute a C-style script. Thefunctions and variable of the program can be accesses and the debugger creates areport of the results.

DebugWindows

This drop down menu allows viewing of a particular debug tab. Click on the tabname in the drop down list which you want to view and it will bring up that tab in thedebugger window.


27/370

Overview

15

Document Menu Ribbon

FormatSource

This utility formats the source file for indenting, color syntax highlighting, and otherformatting options.

GenerateDocument

This will call the document generator program which uses a user generatedtemplate in .RTF format to merge with comment from the source code to producean output file in .RTF format as source code documentation.

RTF Editor Open the RTF editor program which is a fully featured RTF editor to makeintegration of documentation into your project easier.

Flow Chart Opens a flow chart program for quick and easy charting. This tool can be used togenerate simple graphics including schematics.

Quotes Performs a spell check on all the words within quotes.

Comments Performs a spell check on all the comments in your source code.

Print allFiles

Print all the files of the current project.

Help MenuClick on this icon for the following items:

Contents Help File table of contents

Index Help File index

Keyword atCursor

Index search in Help File for the keyword at the cursor location. Press F1 to usethis feature.

DebuggerHelp

Help File specific to debugger functionality.

Editor Lists the Editor Keys available for use in PCW. Shft+F12 will also call thisfunction help file page for quick review.


28/370


16

Data Types Specific Help File page for basic data types.

Operators Specific Help File page for table of operators that may be used in PCW.

Statements Specific Help File page for table of commonly used statements.

Preprocessor

Commands

Specific Help File page for listing of commonly used preprocessor commands.

Built-inFunctions

Specific Help File page for listing of commonly used built-in functions providedby the compiler.

TechnicalSupport

Technical Support wizard to directly contact Technical Support via email and theability to attach files.

Check forSoftwareUpdates

Automatically invokes Download Manager to view local and current versions ofsoftware.

Internet Direct links to specific CCS website pages for additional information.

About Shows the version of compiler(s) and IDE installed.


29/370

17

PROGRAM SYNTAX

Overall Structure

A program is made up of the following four elements in a file:CommentPre-Processor DirectiveData DefinitionFunction 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 functionscould be called from main or the subfunctions. In a large project functions can also be placed indifferent C files or header files that can be included in the main C file to group the related functionsby 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 directiveslike #fuses to specify the fuses for the chip and #use delay to specify the clock speed. Thefunctions contain the data declarations,definitions,statements and expressions. The compiler alsoprovides a large number of standard C libraries as well as other device drivers that can be includedand used in the programs. CCS also provides a large number of built-in functions to access thevarious peripherals included in the PIC microcontroller.

Comment

Comments Standard CommentsA 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 compilerrecognizes these special types of comments that can be later exported for use in thedocumentation generator. The documentation generator utility uses a user selectable template toexport these comments and create a formatted output document in Rich Text File Format. Thisutility 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. Thecomment names are case sensitive and they must match the case used in the documentation template.For example:

//*PURPOSE This program implements a Bootloader.


30/370


18

//*AUTHOR John Doe

A '//' followed by an * will tell the compiler that the keyword which follows it will be the namedcomment. The actual comment that follows it will be exported as a paragraph to the documentationgenerator.Multiple line comments can be specified by adding a : after the *, so the compiler will notconcatenate the comments that follow. For example:

/**:CHANGES05/16/06 Added PWM loop05/27.06 Fixed Flashing problem

*/

Variable Comments A variable comment is a comment that appears immediately after a variabledeclaration. For example:

int seconds; // Number of seconds since last entrylong day, // Current day of the monthint month, /* Current Month */long year; // Year

Function Comments A function comment is a comment that appears just before a functiondeclaration. 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 mannerto the Global Comments. These comments appear before the function, and the names areexported as-is to the documentation generator.

For example://*PURPOSE This function displays data in BCD formatvoid display_BCD( byte n){display_routine();}


31/370

Program Syntax

19

Trigraph Sequences

The compiler accepts three character sequences instead of some special characters not availableon all keyboards as follows:

Sequence Same as??= #

??( [??/ \??) ]??' ^??< {??! |??> }??- ~

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 subfiles to use the automatic linker included in the compiler. All the header files, standardlibraries 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 sayin:

main.c #include #include #include #include

x.c #include

y.c #include

z.c #include

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 inthat file.

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


32/370


20

Multiple Compilation Units

Traditionally, the CCS C compiler used only one compilation unit and multiple files wereimplemented with #include files. When using multiple compilation units, care must be given thatpre-processor commands that control the compilation are compatible across all units. It isrecommended 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).

The following is an overview of a multiple compilation unit example. For the example used here,see the MCU.zip in the examples directory.

Files Included in Project Example:

main.c Primary file for the first compilation unit.

filter.c Primary file for the second compilation unit.

report.c Primary file for the third compilation unit.

project.h Include file with project wide definitions that should be included by all units.

filter.h Include file with external definitions for filter that should be included by all unitsthat use the filter unit.

report.h Include file with external definitions for report that should be included by all unitsthat use the report unit.

project.c Import file used to list the units in the project for the linker.bat file.

project.pjt Project file used to list the units in the project for the build.bat file.

build.bat Batch file that re-compiles files that need compiling and linking.

buildall.bat Batch file that compiles and links all units.

linker.bat Batch file that compiles and links all units using a script.

File Overview:

main#include:

project.hfilter.h

report.h

Definitions:main() program

Uses:clear_data()filter_data()report_data_line()report_line_number

filter#include:

project.hreport.h

Public Definitions:clear_data()filter_data()

Uses:report_error()

report#include:

project.h

Public Definitions:report_data_line()report_line_numberreport_error()


33/370

Program Syntax

21

Compilation Files:

*.o Relocatable object file that is generated by each unit.

*.err Error file that is generated by each unit.

*.osym Unit symbol file that is generated by each unit.

project.hex Final load image file generated by the project.

project.lst C and ASM listing file generated by the project.

project.sym Project symbols file generated by the project.

project.cof Debugger file generated by the project.

Using Command-Line to Build a Project:

Move all of the source files for the project into a single directory.

Using a text editor, create the file buildall.bat, based off of the following example in order to compilethe files and build the project.

The path should point to the CCSC.exefile in the PIC-C installation directory. Add any additional compiler options. Use the EXPORT option to include the necessary *.cfiles. Use the LINK option to generate a *.hexfile.

Double-click on the buildall.batfile created earlier or use a command prompt by changing thedefault directory to the project directory. Then use the command BUILDALL to build the projectusing all of the files.

Using Command Line to Re-Build Changed Files in a Project:

Using a text editor, create the file project.pjtbased off of the following example in order to includethe files that need to be linked for the project.


34/370


22

Using a text editor, create the file build.batbased off of the following example in order to compileonly the files that changed and re-build the project.

The path should point to the CCSC.exefile in the PIC-C installation directory. Add any additional compiler options. Use the BUILD option to specify the *.pjt file.

Double-click on the build.batfile created earlier or use a command prompt by changing the defaultdirectory to the project directory and then use the command BUILD to re-build the project usingonly the necessary files that changed.

Using a Linker Script:

Using a text editor, create the file project.cbased off of the following example in order to include thefiles that need to be linked for the project.


35/370

Program Syntax

23

Using a text editor, create the file linker.batbased off of the following example in order to compilethe files and build the project.

The path should point to the CCSC.exefile in the PIC-C installation directory. Add any additional compiler options. Use the EXPORT option to include the necessary *.cfiles. The LINK option is replaced with the *.cfile containing the #import commands.

Double-click on the linker.batfile created earlier or use a command prompt by changing the defaultdirectory to the project directory and then use the command LINKER to build the project using all ofthe files.

pic ccs c manual

Documents