Atmel CAVR-4 User Manual

AVR® IAR C/C++ Compiler

Reference Guide

for Atmel® Corporation’s

AVR® Microcontroller

No part of this document may be reproduced without the prior written consent of IAR Systems. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license.

DISCLAIMER

The information in this document is subject to change without notice and does not represent a commitment on any part of IAR Systems. While the information contained herein is assumed to be accurate, IAR Systems assumes no responsibility for any errors or omissions.

In no event shall IAR Systems, its employees, its contractors, or the authors of this document be liable for special, direct, indirect, or consequential damage, losses, costs, charges, claims, demands, claim for lost profits, fees, or expenses of any nature or kind.

TRADEMARKS

IAR Systems, From Idea to Target, IAR Embedded Workbench, visualSTATE, IAR MakeApp and C-SPY are trademarks owned by IAR Systems AB.

Atmel is a registered trademark of Atmel Corporation. AVR is a registered trademark of Atmel Corporation.

Microsoft and Windows are registered trademarks of Microsoft Corporation.

All other product names are trademarks or registered trademarks of their respective owners.

EDITION NOTICE

Fourth edition: February 2005

Part number: CAVR-4

This guide applies to version

4.x of AVR IAR Embedded Workbench®.

Brief contents

Tables ...................................................................................................................... xv

Preface ................................................................................................................... xix

Part 1. Using the compiler ......................................................... 1

Getting started .................................................................................................... 3

Data storage ...................................................................................................... 15

Functions ............................................................................................................. 27

Placing code and data .................................................................................... 33

The DLIB runtime environment ............................................................... 53

The CLIB runtime environment .............................................................. 85

Assembler language interface ................................................................... 93

Using C++ .......................................................................................................... 109

Efficient coding for embedded applications ...................................... 121

Part 2. Compiler reference .................................................... 135

Data representation ...................................................................................... 137

Segment reference ......................................................................................... 149

Compiler options ........................................................................................... 167

Extended keywords ....................................................................................... 203

Pragma directives ............................................................................................ 215

The preprocessor ........................................................................................... 227

Intrinsic functions ........................................................................................... 237

Library functions ............................................................................................. 243

iii

Implementation-defined behavior .......................................................... 255

IAR language extensions ............................................................................. 269

Diagnostics ......................................................................................................... 279

Index ..................................................................................................................... 281

AVR® IAR C/C++ Compiler

Reference Guide

Tables ...................................................................................................................... xv

Preface ................................................................................................................... xix

Who should read this guide .............................................................. xix

How to use this guide ......................................................................... xix

What this guide contains ..................................................................... xx

Other documentation .......................................................................... xxi

Further reading .................................................................................. xxi

Document conventions ......................................................................xxii

Typographic conventions .................................................................xxii

Part 1. Using the compiler ......................................................... 1

Getting started .................................................................................................... 3

IAR language overview ........................................................................... 3

Building applications—an overview .................................................. 4

Compiling ............................................................................................. 4

Linking ................................................................................................. 4

Basic settings for project configuration .......................................... 5

Processor configuration ........................................................................ 5

Memory model ..................................................................................... 9

Size of double floating-point type ...................................................... 10

Optimization for speed and size ......................................................... 10

Runtime environment ......................................................................... 11

Special support for embedded systems ........................................ 12

Extended keywords ............................................................................ 12

Pragma directives ............................................................................... 13

Predefined symbols ............................................................................ 13

Header files for I/O ............................................................................ 13

Accessing low-level features ............................................................. 13

Data storage ...................................................................................................... 15

Introduction .............................................................................................. 15

Storing data ........................................................................................ 15

Extended keywords for data ............................................................... 16

Memory models ...................................................................................... 17

Specifying a memory model .............................................................. 17

Memory types and memory attributes ......................................... 18

Using data memory attributes ............................................................ 19

Pointers and memory types ................................................................ 20

Structures and memory types ............................................................ 21

More examples ................................................................................... 21

C++ and memory types ...................................................................... 22

The stack and auto variables ............................................................. 23

Dynamic memory on the heap ........................................................ 25

Functions ............................................................................................................. 27

Controlling functions ............................................................................ 27

Extended keywords for functions ...................................................... 27

Function storage ..................................................................................... 28

Special function types .......................................................................... 29

Interrupt functions ............................................................................. 29

Monitor functions ............................................................................... 30

C++ and special function types ......................................................... 32

Function directives ............................................................................. 32

AVR® IAR C/C++ Compiler

Reference Guide

Placing code and data .................................................................................... 33

Segments and memory ........................................................................ 33

What is a segment? ............................................................................ 33

Placing segments in memory ............................................................ 34

Customizing the linker command file ................................................ 35

Data segments ......................................................................................... 37

Static memory segments ................................................................... 37

Segments for static data in the linker command file .......................... 41

The data stack .................................................................................... 41

Contents

The return address stack .................................................................... 43

The heap ............................................................................................ 44

Located data ....................................................................................... 46

User-defined data segments ............................................................... 46

Code segments ....................................................................................... 46

Interrupt and reset vectors ................................................................. 46

Functions ............................................................................................ 46

User-defined segments ....................................................................... 47

Compiler-generated segments ......................................................... 47

Efficient usage of segments and memory .................................... 47

Controlling data and function placement ........................................... 47

Using user-defined segments ............................................................. 49

Verifying the linked result of code and data placement ........ 50

Segment too long errors and range errors .......................................... 50

Linker map file ................................................................................... 50

Managing multiple memory spaces ................................................... 51

The DLIB runtime environment ............................................................... 53

Introduction to the runtime environment .................................. 53

Runtime environment functionality ................................................... 53

Library selection ................................................................................ 54

Situations that require library building .............................................. 55

Library configurations ........................................................................ 55

Debug support in the runtime library ................................................. 56

Using a prebuilt library ........................................................................ 56

Customizing a prebuilt library without rebuilding ............................. 58

Choosing formatters for printf and scanf ..................................... 59

Choosing printf formatter ................................................................... 59

Choosing scanf formatter .................................................................. 60

Overriding library modules ................................................................ 61

Building and using a customized library ....................................... 62

Setting up a library project ................................................................. 63

Modifying the library functionality .................................................... 63

Using a customized library ................................................................ 63

vii

System startup and termination ...................................................... 64

System startup .................................................................................... 65

System termination ............................................................................ 65

Customizing system initialization ................................................... 66

__low_level_init ............................................................................... 66

Modifying the file cstartup.s90 ......................................................... 67

Standard streams for input and output ........................................ 67

Implementing low-level character input and output .......................... 67

Configuration symbols for printf and scanf ................................. 69

Customizing formatting capabilities .................................................. 70

File input and output ............................................................................. 70

Locale ........................................................................................................... 71

Locale support in prebuilt libraries .................................................... 71

Customizing the locale support .......................................................... 71

Changing locales at runtime ............................................................... 72

Environment interaction ..................................................................... 73

Signal and raise ........................................................................................ 73

Time ............................................................................................................. 74

Strtod ........................................................................................................... 74

Assert ........................................................................................................... 75

Heaps ........................................................................................................... 75

C-SPY Debugger runtime interface .............................................. 76

Low-level debugger runtime interface ............................................... 76

The debugger terminal I/O window ................................................... 77

Checking module consistency ........................................................... 77

Runtime model attributes .................................................................. 77

Using runtime model attributes .......................................................... 78

Predefined runtime attributes ............................................................. 79

User-defined runtime model attributes .............................................. 80

Implementation of system startup code ...................................... 81

Modules and segment parts ................................................................ 81

Added C functionality ........................................................................... 82

stdint.h ................................................................................................ 83

stdbool.h ............................................................................................. 83

AVR® IAR C/C++ Compiler

viii

Reference Guide

Contents

math.h ................................................................................................. 83

stdio.h ................................................................................................. 83

stdlib.h ................................................................................................ 83

printf, scanf and strtod ....................................................................... 84

The CLIB runtime environment .............................................................. 85

Runtime environment .......................................................................... 85

Input and output ..................................................................................... 87

Character-based I/O ........................................................................... 87

Formatters used by printf and sprintf ................................................. 87

Formatters used by scanf and sscanf .................................................. 89

System startup and termination ...................................................... 89

System startup .................................................................................... 89

System termination ............................................................................ 90

Overriding default library modules ................................................ 90

Customizing system initialization ................................................... 90

Implementation of cstartup .............................................................. 90

C-SPY runtime interface .................................................................... 91

The debugger terminal I/O window ................................................... 91

Termination ........................................................................................ 91

Checking module consistency ........................................................... 91

Assembler language interface ................................................................... 93

Mixing C and assembler ....................................................................... 93

Intrinsic functions .............................................................................. 93

Mixing C and assembler modules ...................................................... 94

Inline assembler ................................................................................ 95

Calling assembler routines from C ................................................. 96

Creating skeleton code ....................................................................... 96

Compiling the code ............................................................................ 97

Calling assembler routines from C++ ............................................ 98

Calling convention .................................................................................. 99

Choosing a calling convention ........................................................... 99

Function declarations ...................................................................... 100

C and C++ linkage ........................................................................... 100

Preserved versus scratch registers ................................................... 101

Function call .................................................................................... 102

Function exit ................................................................................... 105

Return address handling ................................................................... 106

Restrictions for special function types ............................................. 106

Examples .......................................................................................... 107

Call frame information ....................................................................... 108

Using C++ .......................................................................................................... 109

Overview .................................................................................................. 109

Standard Embedded C++ ................................................................. 109

IAR Extended Embedded C++ ........................................................ 110

Enabling C++ support ...................................................................... 110

Feature descriptions ............................................................................ 111

Classes .............................................................................................. 111

Functions .......................................................................................... 114

New and Delete operators ................................................................ 114

Templates ........................................................................................ 115

Variants of casts ............................................................................... 118

Mutable ............................................................................................ 118

Namespace ...................................................................................... 119

The STD namespace ........................................................................ 119

Pointer to member functions ............................................................ 119

Using interrupts and EC++ destructors ............................................ 119

AVR® IAR C/C++ Compiler

Reference Guide

Efficient coding for embedded applications ...................................... 121

Taking advantage of the compilation system ........................... 121

Controlling compiler optimizations ................................................. 122

Fine-tuning enabled transformations ............................................... 123

Selecting data types and placing data in memory .................. 125

Locating strings in ROM, RAM and flash ....................................... 125

Using efficient data types ................................................................. 126

Memory model and memory attributes for data ............................... 128

Using the best pointer type ............................................................... 128

Anonymous structs and unions ........................................................128

Contents

Writing efficient code ......................................................................... 130

Saving stack space and RAM memory ............................................ 131

Function prototypes .......................................................................... 131

Integer types and bit negation .......................................................... 132

Protecting simultaneously accessed variables .................................. 132

Accessing special function registers ................................................ 133

Non-initialized variables .................................................................. 134

Part 2. Compiler reference .................................................... 135

Data representation ...................................................................................... 137

Alignment ................................................................................................ 137

Alignment in the AVR IAR C/C++ Compiler ................................. 137

Basic data types .................................................................................... 138

Integer types ..................................................................................... 138

Floating-point types ........................................................................ 139

Pointer types .......................................................................................... 141

Function pointers .............................................................................. 141

Data pointers .................................................................................... 141

Casting ............................................................................................. 142

Structure types ...................................................................................... 143

Alignment ......................................................................................... 143

General layout ................................................................................. 143

Type and object attributes ............................................................... 144

Type attributes .................................................................................. 144

Object attributes ............................................................................... 145

Declaring objects in source files ...................................................... 146

Declaring objects volatile ................................................................ 146

Data types in C++ ................................................................................. 147

Segment reference ......................................................................................... 149

Summary of segments ...................................................................... 149

Descriptions of segments .................................................................. 151

Compiler options ........................................................................................... 167

Setting command line options ........................................................ 167

Specifying parameters ...................................................................... 168

Specifying environment variables .................................................... 169

Error return codes ............................................................................. 169

Options summary ................................................................................. 169

Descriptions of options ...................................................................... 173

Extended keywords ....................................................................................... 203

Summary of extended keywords ................................................... 203

Descriptions of extended keywords ............................................. 204

Pragma directives ............................................................................................ 215

Summary of pragma directives ...................................................... 215

Descriptions of pragma directives ................................................ 216

The preprocessor ........................................................................................... 227

Overview of the preprocessor ........................................................ 227

Predefined symbols .............................................................................. 227

Summary of predefined symbols ..................................................... 228

Descriptions of predefined symbols ................................................. 229

Preprocessor extensions ................................................................... 235

AVR® IAR C/C++ Compiler

xii

Reference Guide

Intrinsic functions ........................................................................................... 237

Intrinsic functions summary ............................................................ 237

Descriptions of intrinsic functions ................................................. 238

Library functions ............................................................................................. 243

Introduction ............................................................................................ 243

Header files ...................................................................................... 243

Library object files ........................................................................... 244

Reentrancy ....................................................................................... 244

IAR DLIB Library .................................................................................. 244

C header files ................................................................................... 245

C++ header files ............................................................................... 246

Contents

Library functions as intrinsic functions ........................................... 248

IAR CLIB Library .................................................................................. 248

Library definitions summary ............................................................ 249

AVR–specific library functions ........................................................ 249

Specifying read and write formatters ............................................... 250

Implementation-defined behavior .......................................................... 255

Descriptions of implementation-defined behavior ................255

Translation ....................................................................................... 255

Environment ..................................................................................... 256

Identifiers ......................................................................................... 256

Characters ......................................................................................... 256

Integers ............................................................................................. 258

Floating point ................................................................................... 258

Arrays and pointers .......................................................................... 259

Registers ........................................................................................... 259

Structures, unions, enumerations, and bitfields ............................... 259

Qualifiers .......................................................................................... 260

Declarators ....................................................................................... 260

Statements ........................................................................................ 260

Preprocessing directives ................................................................... 260

IAR CLIB Library functions ............................................................ 262

IAR DLIB Library functions ............................................................ 265

IAR language extensions ............................................................................. 269

Why should language extensions be used? ................................ 269

Descriptions of language extensions ............................................ 269

Diagnostics ......................................................................................................... 279

Message format ..................................................................................... 279

Severity levels ........................................................................................ 279

Setting the severity level .................................................................. 280

Internal error .................................................................................... 280

Index ..................................................................................................................... 281

xiii

AVR® IAR C/C++ Compiler

xiv

Reference Guide

Ta b l e s

1: Typographic conventions used in this guide ....................................................... xxii

2: Mapping of processor options ................................................................................. 6

3: Summary of processor configuration ...................................................................... 8

4: Summary of memory models ................................................................................ 10

5: Command line options for specifying library and dependency files ..................... 12

6: Memory model characteristics .............................................................................. 18

7: Memory attributes for data .................................................................................... 19

8: Memory attributes for functions ............................................................................ 28

9: XLINK segment memory types ............................................................................ 34

10: Memory layout of a target system (example) ..................................................... 35

11: Segment name suffixes ....................................................................................... 38

12: Heaps, memory types, and segments .................................................................. 44

13: Library configurations ......................................................................................... 55

14: Levels of debugging support in runtime libraries ............................................... 56

15: Prebuilt libraries .................................................................................................. 57

16: Customizable items ............................................................................................. 58

17: Formatters for printf ............................................................................................ 59

18: Formatters for scanf ............................................................................................ 60

19: Descriptions of printf configuration symbols ..................................................... 69

20: Descriptions of scanf configuration symbols ...................................................... 69

21: Low-level I/O files .............................................................................................. 70

22: Heaps and memory types .................................................................................... 75

23: Functions with special meanings when linked with debug info ......................... 76

24: Example of runtime model attributes .................................................................. 78

25: Predefined runtime model attributes ................................................................... 79

26: Prebuilt libraries .................................................................................................. 86

27: Registers used for passing parameters .............................................................. 102

28: Passing parameters in registers ......................................................................... 103

29: Registers used for returning values ................................................................... 106

30: Compiler optimization levels ............................................................................ 122

31: Integer types ...................................................................................................... 138

32: Floating-point types .......................................................................................... 139

33: Function pointers ............................................................................................... 141

34: Data pointers ..................................................................................................... 141

35: size_t typedef .................................................................................................... 142

36: ptrdiff_t typedef ................................................................................................ 143

37: Volatile objects with special handling .............................................................. 147

38: Segment summary ............................................................................................. 149

39: Memory models ................................................................................................ 151

40: Heap memory address range ............................................................................. 157

41: Environment variables ...................................................................................... 169

42: Error return codes .............................................................................................. 169

43: Compiler options summary ............................................................................... 169

44: Generating a list of dependencies (--dependencies) .......................................... 175

45: Specifying switch type ...................................................................................... 182

46: Accessing variables with aggregate initializers ................................................ 184

47: Generating a compiler list file (-l) ..................................................................... 185

48: Enabling MISRA C rules (--misrac) ................................................................. 187

49: Directing preprocessor output to file (--preprocess) ......................................... 193

50: Specifying speed optimization (-s) .................................................................... 195

51: Processor variant command line options ........................................................... 197

52: Specifying size optimization (-z) ...................................................................... 200

53: Summary of extended keywords for functions ................................................. 203

54: Summary of extended keywords for data .......................................................... 204

55: EEPROM address ranges .................................................................................. 205

56: Near address ranges ........................................................................................... 206

57: Far address ranges ............................................................................................. 206

58: Farflash address ranges ..................................................................................... 206

59: Farfunc pointer size ........................................................................................... 207

60: Flash address ranges .......................................................................................... 208

61: Generic pointer size ........................................................................................... 208

62: Huge address ranges .......................................................................................... 208

63: Hugeflash address ranges .................................................................................. 209

64: I/O address ranges ............................................................................................. 210

65: Near address ranges ........................................................................................... 210

AVR® IAR C/C++ Compiler

xvi

Reference Guide

Ta b l e s

66: Nearfunc pointer size ........................................................................................ 211

67: Tiny address ranges ........................................................................................... 213

68: Tinyflash address ranges ................................................................................... 213

69: Pragma directives summary .............................................................................. 215

70: Predefined symbols summary ........................................................................... 228

71: Predefined memory model symbol values ........................................................ 232

72: Intrinsic functions summary .............................................................................. 237

73: Traditional standard C header files—DLIB ...................................................... 245

74: Embedded C++ header files .............................................................................. 246

75: Additional Embedded C++ header files—DLIB ............................................... 246

76: Standard template library header files ............................................................... 247

77: New standard C header files—DLIB ................................................................ 247

78: IAR CLIB Library header files ......................................................................... 249

79: Miscellaneous IAR CLIB Library header files ................................................. 249

80: Message returned by strerror()—IAR CLIB library ......................................... 265

81: Message returned by strerror()—IAR DLIB library ......................................... 268

xvii

AVR® IAR C/C++ Compiler

xviii

Reference Guide

Preface

Welcome to the AVR® IAR C/C++ Compiler Reference Guide. The purpose of this guide is to provide you with detailed reference information that can help you to use the AVR IAR C/C++ Compiler to best suit your application requirements. This guide also gives you suggestions on coding techniques so that you can develop applications with maximum efficiency.

Who should read this guide

You should read this guide if you plan to develop an application using the C or C++ language for the AVR microcontroller and need to get detailed reference information on how to use the AVR IAR C/C++ Compiler. In addition, you should have a working knowledge of the following:

● The architecture and instruction set of the AVR microcontroller. Refer to the

documentation from Atmel® Corporation for information about the AVR microcontroller

● The C or C++ programming language

● Application development for embedded systems

● The operating system of your host machine.

How to use this guide

When you start using the AVR IAR C/C++ Compiler, you should read Part 1. Using the compiler in this guide.

When you are familiar with the compiler and have already configured your project, you can focus more on Part 2. Compiler reference.

If you are new to using the IAR toolkit, we recommend that you first study the AV R® IAR Embedded Workbench™ IDE User Guide. This guide contains a product overview, tutorials that can help you get started, conceptual and user information about IAR Embedded Workbench and the IAR C-SPY Debugger, and corresponding reference information. The AVR® IAR Embedded Workbench™ IDE User Guide also contains a glossary.

xix

What this guide contains

Below is a brief outline and summary of the chapters in this guide.

Part 1. Using the compiler

● Getting started gives the information you need to get started using the AVR IAR

C/C++ Compiler for efficiently developing your application.

● Data storage describes how data can be stored in memory, with emphasis on the

different memory models and memory type attributes.

● Functions describes the special function types, such as interrupt functions and

monitor functions.

● Placing code and data describes the concept of segments, introduces the linker

command file, and describes how code and data are placed in memory.

● The DLIB runtime environment describes the runtime environment in which an

application executes. It covers how you can modify it by setting options, overriding default library modules, or building your own library. The chapter also describes system initialization and introduces the file

cstartup, as well as how to use

modules for locale, and file I/O.

● The CLIB runtime environment gives an overview of the runtime libraries and how

they can be customized. The chapter also describes system initialization and introduces the file cstartup.

● Assembler language interface contains information required when parts of an

application are written in assembler language. This includes the calling convention.

● Using C++ gives an overview of the two levels of C++ support: The

industry-standard EC++ and IAR Extended EC++.

● Efficient coding for embedded applications gives hints about how to write code that

compiles to efficient code for an embedded application.

Part 2. Compiler reference

● Data representation describes the available data types, pointers, and structure types.

This chapter also gives information about type and object attributes.

● Segment reference gives reference information about the compiler’s use of

segments.

● Compiler options explains how to set the compiler options, gives a summary of the

options, and contains detailed reference information for each compiler option.

● Extended keywords gives reference information about each of the AVR-specific

keywords that are extensions to the standard C/C++ language.

● Pragma directives gives reference information about the pragma directives.

● The preprocessor gives a brief overview of the preprocessor, including reference

information about the different preprocessor directives, symbols, and other related information.

● Intrinsic functions gives reference information about the functions that can be used

for accessing AVR-specific low-level features.

AVR® IAR C/C++ Compiler

Reference Guide

[option] An optional part of a command.

{a | b | c} Alternatives in a command.

bold Names of menus, menu commands, buttons, and dialog boxes that

appear on the screen.

refe rence A cross-reference within this guide or to another guide.

… An ellipsis indicates that the previous item can be repeated an arbitrary

number of times.

Identifies instructions specific to the IAR Embedded Workbench interface.

Identifies instructions specific to the command line interface.

Identifies helpful tips and programming hints.

AVR® IAR C/C++ Compiler

xxii

Reference Guide

Table 1: Typographic conventions used in this guide

Part 1. Using the compiler

This part of the AVR® IAR C/C++ Compiler Reference Guide includes the following chapters:

● Getting started

● Data storage

● Functions

● Placing code and data

● The DLIB runtime environment

● The CLIB runtime environment

● Assembler language interface

● Using C++

● Efficient coding for embedded applications.

IAR language overview

Getting started

This chapter gives the information you need to get started using the AVR IAR C/C++ Compiler for efficiently developing your application.

First you will get an overview of the supported programming languages, followed by a description of the steps involved for compiling and linking an application.

Next, the compiler is introduced. You will get an overview of the basic settings needed for a project setup, including an overview of the techniques that enable applications to take full advantage of the AVR microcontroller. In the following chapters, these techniques will be studied in more detail.

There are two high-level programming languages available for use with the AVR IAR C/C++ Compiler:

● C, the most widely used high-level programming language used in the embedded

systems industry. Using the AVR IAR C/C++ Compiler, you can build freestanding applications that follow the standard ISO 9899:1990. This standard is commonly known as ANSI C.

● C++, a modern object-oriented programming language with a full-featured library

well suited for modular programming. IAR Systems supports two levels of the C++ language:

● Embedded C++ (EC++), a subset of the C++ programming standard, which is

intended for embedded systems programming. It is defined by an industry consortium, the Embedded C++ Technical committee. See the chapter Using C++.

● IAR Extended EC++, with additional features such as full template support,

namespace support, the new cast operators, as well as the Standard Template Library (STL).

Each of the supported languages can be used in strict or relaxed mode, or relaxed with IAR extensions enabled. The strict mode adheres to the standard, whereas the relaxed mode allows some deviations from the standard.

It is also possible to implement parts of the application, or the whole application, in assembler language. See the AVR® IAR Assembler Reference Guide.

Part 1. Using the compiler

Building applications—an overview

For more information about the Embedded C++ language and IAR Extended Embedded C++, see the chapter Using C++.

Building applications—an overview

A typical application is built from a number of source files and libraries. The source files can be written in C, C++, or assembler language, and can be compiled into object files by the AVR IAR C/C++ Compiler or the AVR IAR Assembler.

A library is a collection of object files. A typical example of a library is the compiler library containing the runtime environment and the C/C++ standard library. Libraries can also be built using the IAR XAR Library Builder, the IAR XLIB Librarian, or be provided by external suppliers.

The IAR XLINK Linker is used for building the final application. XLINK normally uses a linker command file, which describes the available resources of the target system.

Below, the process for building an application on the command line is described. For information about how to build an application using the IAR Embedded Workbench IDE, see the AVR® IAR Embedded Workbench™ IDE User Guide.

COMPILING

In the command line interface, the following line compiles the source file myfile.c into the object file myfile.r90 using the default settings:

iccavr myfile.c

In addition, you need to specify some critical options, see Basic settings for project configuration, page 5.

LINKING

The IAR XLINK Linker is used for building the final application. Normally, XLINK requires the following information as input:

● A number of object files and possibly certain libraries

● The standard library containing the runtime environment and the standard language

functions

● A program start label

● A linker command file that describes the memory layout of the target system

● Information about the output format.

On the command line, the following line can be used for starting XLINK:

xlink myfile.r90 myfile2.r90 -s __program_start -f lnkm128s.xcl cl3s-ec.r90 -o aout.a90 -FIntel-extended

AVR® IAR C/C++ Compiler

Reference Guide

In this example, myfile.r90 and myfile2.r90 are object files, lnkm128s.xcl is the linker command file, and the label where the application starts. The option -o specifies the name of the output file, and the option -F can be used for specifying the output format. (The default output format is

Motorola.)

The IAR XLINK Linker produces output according to your specifications. Choose the output format that suits your purpose. You might want to load the output to a debugger—which means that you need output with debug information. Alternatively, you might want to load the output to a flash loader—in which case you need output without debug information, such as Intel-hex or Motorola S-records.

Basic settings for project configuration

This section gives an overview of the basic settings for the project setup that are needed to make the compiler generate the best code for the AVR device you are using. You can specify the options either from the command line interface or in the IAR Embedded Workbench IDE. For details about how to set options, see Setting command line options, page 167, and the AVR® IAR Embedded Workbench™ IDE User Guide, respectively.

The basic settings available for the AVR microcontroller are:

● Processor configuration

● Memory model

● Size of double floating-point type

● Optimization for speed and size

● Runtime environment.

In addition to these settings, there are many other options and settings available for fine-tuning the result even further. See the chapter Compiler options for a list of all available options.

Getting started

cl3s-ec.r90 is the runtime library. The option -s specifies

PROCESSOR CONFIGURATION

To make the compiler generate optimum code you should configure it for the AVR microcontroller you are using.

The --cpu option versus the -v option

There are two processor options that can be used for configuring the processor support:

--cpu=derivative and -vn

Your program may use only one processor option at a time, and the same processor option must be used by all user and library modules in order to maintain consistency.

Part 1. Using the compiler

Basic settings for project configuration

Both options set up default behavior—implicit assumptions—but note that the

--cpu

option is more precise because it contains more information about the intended target than the more generic

-v option. The --cpu option knows, for example, how much flash

memory is available in the given target and allows the compiler to optimize accesses to code memory in a way that the

-v option does not. See Mapping of processor options

--cpu and -v, page 6.

The

--cpu=derivative option implicitly sets up all internal compiler settings needed

to generate code for the processor variant you are using. The following options are implicitly controlled when you use the

--eeprom_size, --enhanced_core, --spmcr_address, -v and --64k_flash.

Because these options are automatically set when you use the

--cpu option: --eecr_address,

--cpu option, you cannot

set them explicitly. For information about implicit assumptions when using the -v option, see Summary of processor configuration, page 8. To read more about the generated code, see -v, page 197.

See the AVR® IAR Embedded Workbench™ IDE User Guide for information about setting project options in IAR Embedded Workbench.

Use the --cpu or -v option to specify the AVR derivative; see the chapter Compiler options for syntax information.

Mapping of processor options --cpu and -v

The following table shows the mapping of processor options and which AVR microcontrollers they support:

Processor variant Generic processor option Supported AVR derivative

--cpu=1200 -v0 AT90S1200

--cpu=2313 -v0 AT90S2313

--cpu=2323 -v0 AT90S2323

--cpu=2333 -v0 AT90S2333

--cpu=2343 -v0 AT90S2343

--cpu=4414 -v1 AT90S4414

--cpu=4433 -v0 AT90S4433

--cpu=4434 -v1 AT90S4434

--cpu=8515 -v1 AT90S8515

--cpu=8534 -v1 AT90S8534

--cpu=8535 -v1 AT90S8535

Table 2: Mapping of processor options

AVR® IAR C/C++ Compiler

Reference Guide

Getting started

Processor variant Generic processor option Supported AVR derivative

--cpu=at43usb320a -v3 AT43USB320A

--cpu=at43usb325 -v3 AT43USB325

--cpu=at43usb326 -v3 AT43USB326

--cpu=at43usb351m -v3 AT43USB351m

--cpu=at43usb353m -v3 AT43USB353m

--cpu=at43usb355 -v3 AT43USB355

--cpu=at94k -v3 FpSLic

--cpu=at86rf401 -v0 AT86RF401

--cpu=can128 -v3 AT90CAN128

--cpu=m8 -v1 AT me ga 8

--cpu=m16 -v3 AT me ga 1 6

--cpu=m32 -v3 AT me ga 3 2

--cpu=m48 -v1 AT me ga 4 8

--cpu=m64 -v3 AT me ga 6 4

--cpu=m88 -v1 AT me ga 8 8

--cpu=m103 -v3 ATmega103

--cpu=m128 -v3 ATmega128

--cpu=m161 -v3 ATmega161

--cpu=m162 -v3 ATmega162

--cpu=m163 -v3 ATmega163

--cpu=m165 -v3 ATmega165

--cpu=m168 -v3 ATmega168

--cpu=m169 -v3 ATmega169

--cpu=m2560 -v5 ATmega2560

--cpu=m2561 -v5 ATmega2561

--cpu=m323 -v3 ATmega323

--cpu=m325 -v3 ATmega325

--cpu=m3250 -v3 ATmega3250

Table 2: Mapping of processor options (Continued)

Part 1. Using the compiler

Basic settings for project configuration

Processor variant Generic processor option Supported AVR derivative

--cpu=m329 -v3 ATmega329

--cpu=m3290 -v3 ATmega3290

--cpu=m406 -v3 ATmega406

--cpu=m645 -v3 ATmega645

--cpu=m6450 -v3 ATmega6450

--cpu=m649 -v3 ATmega649

--cpu=m6490 -v3 ATmega6490

--cpu=m8515 -v1 ATmega8515

--cpu=m8535 -v1 ATmega8535

--cpu=tiny10 -v0 ATt in y1 0

--cpu=tiny11 -v0 ATt in y1 1

--cpu=tiny12 -v0 ATt in y1 2

--cpu=tiny13 -v0 ATt in y1 3

--cpu=tiny15 -v0 ATt in y1 5

--cpu=tiny25 -v0 ATt in y2 5

--cpu=tiny26 -v0 ATt in y2 6

--cpu=tiny28 -v0 ATt in y2 8

--cpu=tiny45 -v1 ATt in y4 5

--cpu=tiny85 -v1 ATt in y8 5

--cpu=tiny2313 -v0 ATtiny2313

Table 2: Mapping of processor options (Continued)

AVR® IAR C/C++ Compiler

Reference Guide

Summary of processor configuration

The following table summarizes the memory characteristics for each -v option:

Generic processor

option

Available

memory models

-v0 Tiny __nearfunc ≤ 256 bytes ≤ 8 Kbytes

-v1 Tiny, Small __nearfunc ≤ 64 Kbytes ≤ 8 Kbytes

Table 3: Summary of processor configuration

Function

memory

attribute

Max addressable

data

Max module and/or

program size

+ 293 hidden pages

Atmel CAVR-4 User Manual

Brief contents

Contents

Ta b l e s

Preface

Who should read this guide

How to use this guide

What this guide contains

Other documentation

FURTHER READING

Document conventions

TYPOGRAPHIC CONVENTIONS

Part 1. Using the compiler

IAR language overview

Getting started

COMPILING

LINKING

Basic settings for project configuration

PROCESSOR CONFIGURATION

The --cpu option versus the -v option

Mapping of processor options --cpu and -v

Summary of processor configuration