(Parte 1 de 5)

CC5X

C Compiler for the PICmicro Devices

Version 3.1

User's Manual

B Knudsen Data Trondheim - Norway

CC5X C Compiler B Knudsen Data

This manual and the CC5X compiler is protected by Norwegian copyright laws and thus by corresponding copyright laws agreed internationally by mutual consent. The manual and the compiler may not be copied, partially or as a whole without the written consent from the author. The PDF-edition of the manual can be printed to paper for private or local use, but not for distribution. Modification of the manual or the compiler is strongly prohibited. All rights reserved.

LICENSE AGREEMENT: By using the CC5X compiler, you agree to be bound by this agreement. Only one person may use a licensed CC5X compiler at the same time. If more than one person want to use the compiler for each license, then this have to be done by some manual handshaking procedure (not electronic automated), for instance by exchanging this manual as a permission key. You may make backup copies of the software, and copy it to multiple computers. You may not distribute copies of the compiler to others. B Knudsen Data assumes no responsibility for errors or defects in this manual or in the compiler. This also applies to problems caused by such errors.

Copyright © B Knudsen Data, Trondheim, Norway, 1992 - 2000

This manual covers CC5X version 3.1 and related topics. New versions may contain changes without prior notice.

Microchip and PICmicro are trademarks of Microchip Technology Inc., Chandler, U.S.A.

The compiler has been carefully tested and debugged. It is, however, not possible to guarantee a 100 % error free product.

If the compiler generates application code bugs, it is almost always possible to rewrite the program slightly in order to avoid the bug. #pragma optimize can be used to avoid optimization bugs. Other #pragma statements are also useful.

Please report cases of bad generated code and other serious program errors.

1) Investigate and describe the problem. If possible, please provide a short code sample which demonstrates the problem. A fragment of the generated assembly file (use cut and paste) is normally enough. Alternatively a short and complete C program (10 - 100 lines). 2) This service is intended for difficult compiler problems (not application problems). 3) Language: English 4) State the compiler version. 5) Send your report to support@bknd.com or by fax to (+47) 73 96 51 84.

CC5X C Compiler B Knudsen Data

1 INTRODUCTION7
1.1 SUPPORTED DEVICES8
1.2 INSTALLATION AND SYSTEM REQUIREMENTS8
Support for Long File Names8
User Interface8
1.3 MPLAB SUPPORT9
1.4 SUMMARY OF DELIVERED FILES9
1.5 SHORT PROGRAM EXAMPLE10
1.6 DEFINING THE PICMICRO DEVICE1
1.7 WHAT TO DO NEXT12
2 VARIABLES13
2.1 INFORMATION ON RAM ALLOCATION13
2.2 DEFINING VARIABLES13
Integer variables14
Floating point14
IEEE754 interoperability15
Fixed point variables16
Assigning variables to RAM addresses17
Supported type modifiers18
Local Variables19
Temporary Variables19
Arrays, structures and unions20
Bitfields20
Typedef21
2.3 USING RAM BANKS21
The bank type modifier21
RAM Bank Selection Bits2
Local user update regions2
2.4 POINTERS23
Pointer models23
The 12 bit Core24
The 14 bit core: the IRP bit25
2.5 CONST DATA SUPPORT26
Storing 14 bit data27
Data of size 16 bit or more27
Code pages28
Merging data28
Examples28
3 SYNTAX29
3.1 STATEMENTS29
if statement29
while statement29
for statement29
do statement30
switch statement30
break statement30
continue statement31
return statement31
goto statement31

CONTENTS 3.2 ASSIGNMENT AND CONDITIONS ....................................................................................................... 31

CC5X C Compiler B Knudsen Data

Special syntax examples31
Conditions32
Bit variables32
Multiplication, division and modulo3
Precedence of C operators3
Mixed variable sizes are allowed34
3.3 CONSTANTS34
Constant Expressions34
Enumeration35
3.4 FUNCTIONS35
Function return values35
Parameters in function calls35
Internal functions35
3.5 TYPE CAST36
3.6 ACCESSING PARTS OF A VARIABLE37
3.7 C EXTENSIONS37
3.8 PREDEFINED SYMBOLS38
Automatically defined macros and symbols39
3.9 UPWARD COMPATIBILITY39
4 PREPROCESSOR DIRECTIVES40
#define40
#include40
#undef40
#if40
#ifdef41
#ifndef41
#elif41
#else41
#endif41
#error41
#pragma41
4.1 THE PRAGMA STATEMENT41
#pragma asm2var 142
#pragma assert [/] <type> <text field>42
#pragma assume *<pointer> in rambank <n>42
#pragma bit <name> @ <N.B or variable[.B]>42
#pragma cdata[ADDRESS] = <VXS>, .., <VXS>42
#pragma char <name> @ <constant or variable>43
#pragma chip [=] <device>43
#pragma codepage [=] <0,1,2,3>43
#pragma computedGoto [=] <0,1,2>43
#pragma config <id> = <state> [, <id> = <state>]43
#pragma config_def [=] <value>4
#pragma library <0/1>4
#pragma location [=] <0,1,2,3,->4
#pragma optimize [=] [N:] <0,1>4
#pragma origin [=] <n>4
#pragma rambank [=] <0,1,2,3,->45
#pragma rambase [=] <n>45
#pragma ramdef <ra> : <rb> [MAPPING]45
#pragma resetVector <n>45
#pragma return[<n>] = <strings or constants>45
#pragma stackLevels <n>46
#pragma update_FSR [=] <0,1>46

CC5X C Compiler B Knudsen Data

#pragma update_PAGE [=] <0,1>46
#pragma update_RP [=] <0,1>46
#pragma wideConstData [<N>]47
4.2 PICMICRO CONFIGURATION47
5 COMMAND LINE OPTIONS48
5.1 OPTIONS ON A FILE50
6 PROGRAM CODE51
6.1 PROGRAM CODE PAGES51
Another way of locating functions51
The page type modifier52
Page selection bits52
6.2 SUBROUTINE CALL LEVEL CHECKING52
Stack level checking when using interrupt52
Recursive functions53
6.3 INTERRUPTS53
6.4 STARTUP AND TERMINATION CODE54
Clearing ALL RAM locations54
6.5 LIBRARY SUPPORT5
Math libraries5
Integer libraries56
Fixed point libraries57
Floating point libraries58
Floating point library functions59
Fast and compact inline operations61
Using prototypes and multiple code pages61
Fixed point example62
Floating point example62
How to save code63
6.6 INLINE ASSEMBLY63
Generating Single Instructions67
6.7 OPTIMIZING THE CODE68
Optimized Syntax68
Peephole optimization69
6.8 LINKER SUPPORT70
Variables70
Local variables71
Header files71
Using RAM banks71
Bank bit updating72
Functions72
Using code pages72
Interrupts72
Call level checking73
Computed goto73
Recommendations when using MPLINK73
MPLAB and MPASM support74
The MPLINK script file75
Example with 3 modules7
6.9 THE CDATA STATEMENT80
Storing EEPROM data80
Using the cdata statement81
7 DEBUGGING83

5 7.1 COMPILATION ERRORS..................................................................................................................... 83

CC5X C Compiler B Knudsen Data

Error and warning details84
Some common compilation problems84
7.2 MPLAB DEBUGGING SUPPORT84
ICD debugging85
7.3 ASSERT STATEMENTS85
7.4 DEBUGGING IN ANOTHER ENVIRONMENT86
8 FILES PRODUCED8
8.1 HEX FILE8
8.2 ASSEMBLY OUTPUT FILE8
8.3 VARIABLE FILE89
8.4 LIST FILE90
8.5 FUNCTION CALL STRUCTURE90
9 APPLICATION NOTES91
9.1 DELAYS91
9.2 COMPUTED GOTO92
Built in skip() function for computed goto93
Computed Goto Regions93
9.3 THE SWITCH STATEMENT96
APPENDIX97
A1 USING INTERRUPTS97
A2 PREDEFINED REGISTER NAMES98
A3 ASSEMBLY INSTRUCTIONS98
Addition for the 14 bit core9

CC5X C Compiler B Knudsen Data

1 INTRODUCTION

Welcome to the CC5X C compiler for the Microchip PICmicro family of microcontrollers. The CC5X compiler enables programming using a subset of the C language. Assembly is no longer required. The reason for moving to C is clear. Assembly language is generally hard to read and errors are easily produced.

C enables the following advantages compared to assembly: • Source code standardization

• Faster program development

• Improved source code readability

• Easier documentation

• Simplified maintenance

• Portable code

The CC5X compiler was designed to generate tight and optimized code. The optimizer automatically squeezes the code to a minimum. It is possible to write code that compiles into single instructions, but with C syntax. This means that the code can be optimized by rewriting C instead of rewriting assembly.

The design priority was not to provide full ANSI C support, but to enable best possible usage of the limited code and RAM resources. If the compiler generated less optimal code, this would force assembly to be used for parts of the code.

CC5X features

• Local and global variables of 1, 8, 16, 24 and 32 bits • Efficient reuse of local variable space

• Generates tight and optimized code

• Produces binary, assembly, list, COD, error, function outline and variable files

• Automatic updating of the page selection bits

• Automatic updating of the bank selection bits

• Enhanced and compact support of bit operations, including bit functions

• Floating and fixed point math up to 32 bit

• Math libraries including functions like sin(), log(), exp(), sqrt(), etc.

• Supports standard C constant data and strings in program memory (const)

• Automatic storing of compressed 7 bit data in PIC16F87X devices

• Pointer models of 8 and 16 bits, mixed sizes in same application allowed

• RAM and/or ROM pointers

• The size of single pointers can be automatically chosen by the compiler

• Linker support (MPLINK), interfaces with assembly (MPASM) modules

• Extended call level by using GOTO instead of CALL when possible

• Inserts links to "hidden" subroutines

• Access to all assembly instructions through corresponding C statements

• Lookup tables: #pragma return[] = "Hello world"

• Integrated interrupt support

• Chip configuration information in source code

Size (in bits) of the variables supported by the different compiler editions: RED+FREE STANDARD EXTENDED integer 8+16 8+16+24 8+16+24+32 fixed - 8+16+24 8+16+24+32 float 24 24+32 16+24+32

CC5X C Compiler B Knudsen Data

1.1 Supported devices

12 bit core (PIC16C5X, PIC12C50X, etc.): • up to 2048 words of code on 1 - 4 code pages

• up to 73 byte RAM in 1 - 4 banks

14 bit core (PIC12C67X, PIC14000, PIC16CXX, etc.): • up to 8192 words of code on 1 - 4 code pages

• up to 512 byte RAM in 1 - 4 banks

1.2 Installation and System Requirements

The CC5X compiler uses 32 bit processing and runs on IBM-PC compatible machines using MSDOS or Windows (NT/95/98/2000).

Installing CC5X is done by first creating a directory/folder on the hard disk where the compiler files should be located. Then copy all CC5X files to this directory.

CC5X is now ready to compile C files. Header and C source files have to be edited by a separate editor (not included), for instance in MPLAB.

If you are mainly working in a MSDOS window, it may be useful to modify PATH in the AUTOEXEC.BAT file to allow the operating system to find the compiler from any directory (PATH ...;C:\CC5X;...). This is not a required step.

The CC5X files can be deleted without any un-installation procedure.

Support for Long File Names

CC5X supports long file names. Currently, it is not possible to use spaces in file names or in directory names. The truncated short format must then be used.

The truncated form is decided by the file system according to some rules. The best guess consists of the 6 first characters of the long name plus ~1. The last number is different (~2) if the first 6 characters are equal to another name in the same directory.

If the path should be: "C:\Program Files\MPLAB\longfilename" the equivalent short format is often: C:\PROGRA~1\MPLAB\LONGFI~1

The name "C file" becomes CFILE~1 because spaces must be removed.

MPLAB use and display the short format only. The short format name can be found when using Open File and point-and-click to move along a particular path.

User Interface

The CC5X compiler is a command-line program. It requires a list of command line options to compile a C source file and produce the required files.

Starting CC5X from Windows can be done by selecting the Start->Run menu. Then type the full path name including cc5x (or use Browse). The list of compiler command line options are then written to the screen. The normal way of using CC5X is to use it as a tool from an integrate environment like MPLAB.

Compiling a program (in a MSDOS window) requires a file name and command line options: cc5x -a sample1.c <enter>

CC5X C Compiler B Knudsen Data

1.3 MPLAB Support

CC5X can be selected as a tool in MPLAB which offers an integrated environment including editor and tool support (compilers, assemblers, simulators, emulators, device programmers). Compilation errors are easily handled. MPLAB supports point-and-click to go directly to the source line that needs correction. CC5X supports the COD file format used by MPLAB for program debugging. CC5X offers two modes of source file debugging is available: C or assembly mode. Thus, tracing programs in MPLAB can be done using assembly instructions or C statements. MPLAB is free, and can be downloaded from the Microchip Internet site.

Please refer to the supplied file ‘install.txt’ for a description on how to install and use CC5X in the MPLAB environment.

1.4 Summary of Delivered Files

CC5X.EXE : compiler

INTRO.TXT : introduction INSTALL.TXT : installation guide and MPLAB setup CC5X.TXT : basic documentation on CC5X PRAGMA.TXT : the pragma statement INLINE.TXT : information on inline assembly syntax DEBUG.TXT : debugging details, MPLAB support CHIP.TXT : how to make new chip definitions CONFIG.TXT : the PICmicro configuration bits CDATA.TXT : info on the #pragma cdata statement CONST.TXT : standard C strings and constant data GLOBDEF.TXT : PICmicro registers STARTUP.TXT : special startup sequences LINKER.TXT : how to link several modules (C or asm)

INT16CXX.H : interrupt header file INLINE.H : emulating inline instructions

CC5X.MTC : MPLAB tool configuration file TLCC5X.INI : MPLAB tool configuration file

OP.INC : command line options on a file RELOC.INC : options for object modules (MPLINK)

SAMPLE1.C : minimal program example IICBUS.C : IIC-bus interface IIC-COM.C : IIC-bus communication SERIAL.C : serial communication (RS232, RS485) STATE.C : state machines DELAY.C : implementing delays INT16XX.C : simple interrupt example

MATH.TXT : Math library support MATH16.H : 8-16 bit math library MATH16M.H : 8-16 bit multiply, speed

1) MATH24.H : 8-24 bit math library 1) MATH24M.H : 8-24 bit multiply, speed 2) MATH32.H : 8-32 bit math library 2) MATH32M.H : 8-32 bit multiply, speed

CC5X C Compiler B Knudsen Data

1) MATH16X.H : 16 bit fixed point library 1) MATH24X.H : 24 bit fixed point library 2) MATH32X.H : 32 bit fixed point library

2) MATH16F.H : 16 bit floating point library

MATH24F.H : 24 bit floating point library 1) MATH32F.H : 32 bit floating point library

MATH24LB.H : 24 bit floating point functions (log,sqrt,cos,..) 1) MATH32LB.H : 32 bit floating point functions (log,sqrt,cos,..)

12C508.H16C924.H : PICmicro header files

NEWS.TXT : Recent added features README.TXT

1) Not available on the RED and FREE editions 2) Not available on the RED, STANDARD and FREE editions

1.5 Short Program Example

/* global variables */ char a; bit b1, b2;

/* assign names to port pins */ #pragma bit in @ PORTB.0

#pragma bit out @ PORTB.1 void sub( void) { char i; /* a local variable */

// clearRAM(); // clear all RAM

/* first decide the initial output level on the output port pins, and then define the input/output configuration. This avoids spikes at the output pins. */

CC5X C Compiler B Knudsen Data

PORTA = 0b.0010; /* out=1* / TRISA = 0b.1.0001; /* x 0001 */

// if (some condition) // goto WARM_RESET;

/* main is terminated by a SLEEP instruction */ }

1.6 Defining the PICmicro Device CC5X offers 3 ways to select the PICmicro device in an application:

1) By a command line option. In MPLAB, the device command line option is selected in Project->Edit Project..(target)..Node Properties.

-p16C73 -pPIC16F877

2) By a pragma statement in the source code: #pragma chip PIC16F84

3) By an include file. #include "16c73.h"

NOTE 1: When using a pragma statement or header files, remember to use this the beginning of the C program so that it is compiled first. However, some preprocessor statements like #define and #if may proceed the #include/#pragma statement.

NOTE 2: When using the command line option or the pragma statement, CC5X will use the internal definitions for some devices. If the device is not known internally, automatic include of a header file is started. The internal known devices are: 16C54,5,56,57,58, 61,64,65, 71,73,74, 84, 620,621,622.

NOTE 3: If the header file does not reside in the default project folder, then the path name is required. This can be supplied by a command line option as an include folder/directory (-Ipath).

NOTE 4: New header files can be defined according to file ‘chip.txt’.

NOTE 5: ICD debugging requires defining a symbol first:

a) Command line options: -DICD_DEBUG -p16F877 b) #define ICD_DEBUG // or by command line -DICD_DEBUG

#pragma chip PIC16F877

CC5X C Compiler B Knudsen Data c) #define ICD_DEBUG // or by command line -DICD_DEBUG

#include "16F877.H"

1.7 What to do next

It is important to know the PICmicro family and the tools well. The easiest way to start is to read the available documentation and experiment with the examples. Then move on to a simple project. Some suggestions:

• study the supplied program samples

• compile code fragments and check out what the compiler accepts

• study the optional assembly file produced by the compiler

Note that using more than one ram bank or code page requires pragma instructions.

Typical steps when developing programs is as follows: • describe the system, make requirements

• suggest solutions that satisfy these requirements

• write detailed code in the C language

• compile the program using the CC5X compiler

• test the program on a prototype or a simulator

Writing programs for the PICmicro microcontroller family requires careful planning. Program and RAM space are limited, and the key question is often: Will the application code fit into the selected controller?

Important:

File ‘readme.txt’ contains information on how to write code that can be compiled by CC5X.

CC5X C Compiler B Knudsen Data

2 VARIABLES

The compiler prints information on the screen when compiling. Most important are error messages, and how much RAM and PROGRAM space the program requires. The compiler output information is also written to file *.occ. Example:

2.1 Information on RAM allocation

The compiler prints information on RAM allocation. This map is useful to check out which RAM locations are still free. The map for the 16C57 chip may look like this:

Symbols: * : free location - : predefined or pragma variable = : local variable(s) . : global variable 7 : 7 free bits in this location

RAM: 00h : -------- ----==== ==3.7********

16C71 map: RAM: 20h : ******** ********

2.2 Defining Variables

CC5X supports integer, fixed and floating point variables. The variable sizes are 1, 8, 16, 24 and 32 bit. The default int size is 8 bit, and long is 16 bit. Char variables are unsigned by default and thus range from 0 to 255. Note that 24 and 32 bit variables are not supported by all CC5X editions.

Math libraries have to be included for math operations (Section 6.5 Library Support).

CC5X uses (stores) LOW ORDER FIRST. This means that the least significant byte of a variable is assigned to the lowest address. All variables are allocated from low RAM addresses and upwards. Each

CC5X C Compiler B Knudsen Data

RAM location can contain 8 bit variables. Address regions used for special purpose registers are not available for normal allocation. An error message is produced when there is no space left.

(Parte 1 de 5)

Comentários