M16C/R8C IAR C/C++ Compiler Reference Guide. for Renesas M16C/1X 3X, 6X, and R8C Series of CPU Cores

Transcription

1 M16C/R8C IAR C/C++ Compiler Reference Guide for Renesas M16C/1X 3X, 6X, and R8C Series of CPU Cores

2 COPYRIGHT NOTICE Copyright IAR Systems. All rights reserved. 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 Embedded Workbench, IAR visualstate, IAR MakeApp, and IAR PreQual are registered trademarks owned by IAR Systems. C-SPY is a trademark registered in the European Union and Japan by IAR Systems. IAR, IAR XLINK Linker, IAR XAR Library Builder, and IAR XLIB Librarian are trademarks owned by IAR Systems. Microsoft and Windows are registered trademarks of Microsoft Corporation. All other product names are trademarks or registered trademarks of their respective owners. EDITION NOTICE Second edition: October 2004 Part number: CM16C-2 This guide applies to the M16C/R8C IAR Embedded Workbench version 3.x.

3 Contents Tables... xi Preface... xiii Who should read this guide...xiii How to use this guide...xiii What this guide contains...xiv Other documentation...xv Further reading...xv Document conventions...xvi Typographic conventions...xvi Part 1. Using the compiler...1 Introduction... 3 Building applications...3 Compiling...3 Linking...3 Supported derivatives...4 Data storage...4 Optimization techniques...4 IAR language extension overview...5 Special function types...5 Extended keywords...5 Pragma directives...5 Predefined symbols...6 Intrinsic functions...6 Inline assembler...6 Runtime libraries...6 iii

4 Customization... 7 CPU core...7 Data model...7 Runtime library...8 Data storage Stack, static, and heap memory The stack and auto variables Static memory Dynamic memory on the heap Memory access methods and memory types Memory access methods Memory types Pointers Pointers and memory types Structures and memory types C++ and memory types Non-initialized memory Located variables Absolute location placement Segment placement Accessing special function registers Packed structure types Anonymous structs and unions Functions Code Special function types Interrupt functions Register bank interrupt functions Monitor functions Special page functions C++ and special function types Segment placement iv M16C/R8C IAR C/C++ Compiler Reference Guide

5 Contents Assembler language interface Introduction Memory access methods The data16 memory access method The data20 memory access method The far memory access method The data13 memory access method Runtime model attributes Specifying runtime attributes Predefined runtime attributes Calling conventions M16C calling conventions Function declarations C and C++ linkage Function parameters Returning a value from a function Permanent versus scratch registers Return location Examples Calling assembler routines from C Creating skeleton code Calling assembler routines from C Call frame information Function directives Syntax Parameters Description Segments and memory What is a segment? Linker segment type Placeholder segments Placing segments in memory The contents of the linker command file v

6 Customizing a linker command file Data segments Static memory segments The stack The heap Located data Code segments Startup code Normal code TINYFUNC declared code Exception vectors C++ dynamic initialization Programming hints General programming hints Function prototypes Bitfields Arrays #pragma pack Memory types Constants and variables in different parts of memory Floating-point types Saving stack space and RAM memory Optimization techniques Controlling compiler optimizations Optimization hints Part 2. Compiler reference Data representation Alignment Data types Integer types Floating-point types vi M16C/R8C IAR C/C++ Compiler Reference Guide

7 Contents Pointers Size Casting Structure types Alignment General layout Packed structure types Data types in C Segment reference Summary of segments Descriptions of segments Compiler options Setting command line options Specifying parameters Specifying environment variables Error return codes Options summary Descriptions of options Extended keywords Summary of extended keywords Using extended keywords Data storage Functions Descriptions of extended keywords Pragma directives Summary of pragma directives Descriptions of pragma directives Predefined symbols Summary of predefined symbols Descriptions of predefined symbols vii

8 Intrinsic functions Intrinsic functions summary Descriptions of intrinsic functions Diagnostics Severity levels Setting the severity level Internal error Part 3. Portability Implementation-defined behavior Descriptions of implementation-defined behavior Translation Environment Identifiers Characters Integers Floating point Arrays and pointers Registers Structures, unions, enumerations, and bitfields Qualifiers Declarators Statements Preprocessing directives C library functions IAR CLIB and DLIB libraries IAR C extensions Why should language extensions be used? Descriptions of language extensions Index viii M16C/R8C IAR C/C++ Compiler Reference Guide

9 Tables 1: Typographic conventions used in this guide... xiv 2: Data models : Memory types : Example of runtime model attributes : Runtime model attributes : Call frame information : XLINK segment types : Linker command file example : Memory types : Segments in segment groups : Compiler optimization levels : Integer types : Floating-point types : Data pointers : Segment summary : Environment variables : Error return codes : Compiler options summary : Available data models : Generating a list of dependencies (--dependencies) : Generating a compiler list file (-l) : Directing preprocessor output to file (--preprocess) : Specifying speed optimization (-s) : Specifying size optimization (-z) : Extended keywords summary : Pragma directives summary : Predefined symbols summary : Intrinsic functions summary : Message returned by strerror() ix

10 x M16C/R8C IAR C/C++ Compiler Reference Guide

11 Preface Welcome to the M16C/R8C 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 M16C/R8C 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 M16C/R8C Series of CPU cores and need to get detailed reference information on how to use the M16C/R8C IAR C/C++ Compiler. In addition, you should have a working knowledge of the following: The architecture and instruction set of the M16C/R8C Series of CPU cores. Refer to the documentation from Renesas for information about the M16C/R8C Series of CPU cores 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 M16C/R8C IAR C/C++ Compiler, you should read Part 1. Using the compiler in this reference guide. When you are thoroughly 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 read the initial chapters of the IAR Embedded Workbench IDE User Guide. They give product overviews, as well as tutorials that can help you get started. The IAR Embedded Workbench IDE User Guide also contains a glossary. xi

12 What this guide contains What this guide contains Below is a brief outline and summary of the chapters in this guide. Part 1. Using the compiler Introduction gives an overview of the compiler techniques that allow an application to take full advantage of the M16C/R8C Series of CPU cores: code and data storage features, optimization techniques, and language extensions. Customization describes the available customization options: data model and runtime libraries. Data storage describes how data can be stored in memory, with an emphasis on the different memory types. Functions describes the different ways code can be generated and introduces the concept of code models. Special function types such as interrupt functions are also covered. Assembler language interface contains information required when parts of an application are written in assembler language. This includes the calling convention and the runtime model attributes. Segments and memory describes the concept of segments, introduces the linker command file, and describes how code and data are placed in memory. Programming hints gives hints about programming for the M16C/R8C IAR C/C++ Compiler. Part 2. Compiler reference Data representation describes the available data types, pointers, and structure types. 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 M16C/R8C-specific keywords that are extensions to the standard C language. Pragma directives gives reference information about the #pragma directives. Predefined symbols gives reference information about the predefined preprocessor symbols. Intrinsic functions gives reference information about the functions that can use M16C/R8C-specific low-level features. Diagnostics describes how the compiler s diagnostic system works. xii M16C/R8C IAR C/C++ Compiler Reference Guide

13 Preface Part 3. Portability Implementation-defined behavior describes how IAR C handles the implementation-defined areas of the C language. IAR C extensions describes the IAR extensions to the ISO/ANSI standard for the C programming language. Other documentation The complete set of IAR Systems development tools for the M16C/R8C Series of CPU cores is described in a series of guides. For information about: Using the IAR Embedded Workbench IDE with the IAR C-SPY Debugger, refer to the IAR Embedded Workbench IDE User Guide Programming for the M16C/R8C IAR Assembler, refer to the M16C/R8C IAR Assembler Reference Guide Using the IAR XLINK Linker and the IAR XLIB Librarian, refer to the IAR Linker and Library Tools Reference Guide Using the IAR DLIB Library functions, refer to the online help system Using the IAR CLIB Library functions, refer to the IAR C Library Functions Reference Guide, available from the online help system Using the runtime environment, refer to the IAR Runtime Environment and Library Guide Porting application code and projects created with a previous M16C/R8C IAR Embedded Workbench IDE, refer to M16C/R8C IAR Embedded Workbench Migration Guide. All of these guides are delivered in hypertext PDF or HTML format on the installation media. Some of them are also delivered as printed books. FURTHER READING The following books may be of interest to you when using the IAR Systems development tools: Barr, Michael, and Andy Oram, ed. Programming Embedded Systems in C and C++. O'Reilly & Associates. Harbison, Samuel P. and Guy L. Steele (contributor). C: A Reference Manual. Prentice Hall. Kernighan, Brian W. and Dennis M. Ritchie. The C Programming Language. Prentice Hall. [The later editions describe the ANSI C standard.] Labrosse, Jean J. Embedded Systems Building Blocks: Complete and Ready-To-Use Modules in C. R&D Books. Lippman, Stanley B. and Josee Lajoie. C++ Primer. Addison-Wesley. xiii

14 Document conventions Mann, Bernhard. C für Mikrocontroller. Franzis-Verlag. [Written in German.] Stroustrup, Bjarne. The C++ Programming Language. Addison-Wesley. We recommend that you visit the websites of Renesas and IAR Systems: The Renesas website, contains information and news about the M16C/R8C Series of CPU cores. The IAR website, holds application notes and other product information. Document conventions When, in this text, we refer to the programming language C, the text also applies to C++, unless it is explicitly mentioned. TYPOGRAPHIC CONVENTIONS This guide uses the following typographic conventions: Style computer parameter Used for Text that you enter or that appears on the screen. A label representing the actual value you should enter as part of a command. An optional part of a command. [option] {a b c} Alternatives in a command. bold reference Table 1: Typographic conventions used in this guide Names of menus, menu commands, buttons, and dialog boxes that appear on the screen. A cross-reference within or to another part of this guide. Identifies instructions specific to the versions of the IAR Systems tools for the IAR Embedded Workbench interface. Identifies instructions specific to the command line versions of IAR Systems development tools. xiv M16C/R8C IAR C/C++ Compiler Reference Guide

15 Part 1. Using the compiler This part of the M16C/R8C IAR C/C++ Compiler Reference Guide includes the following chapters: Introduction Customization Data storage Functions Assembler language interface Segments and memory Programming hints. 1

16 2

17 Introduction The M16C/R8C IAR C/C++ Compiler supports C and C++ for Renesas M16C/1X, 2X, 3X, 6X, and R8C Series of CPU cores. This chapter first introduces the concepts of compiling and linking when describing how an application is built. Then the compiler is introduced, including an overview of the techniques that enable applications to take full advantage of the M16C/R8C Series of CPU cores. In the following chapters these techniques will be studied in more detail. Building applications 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 M16C/R8C IAR C/C++ Compiler or the M16C/R8C 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 provided by external suppliers. The IAR XLINK Linker is used for building the final application. XLINK normally uses a linker command file describing the available resources of the target system. COMPILING In the command line interface, the following line compiles the source file myfile.c into the object file myfile.r34 using the default settings: iccm16c myfile.c LINKING The IAR XLINK Linker is used to build the final application. Normally XLINK requires the following: A number of object files and possibly some libraries The standard library containing the runtime environment and the standard language functions A linker command file that describes the memory layout of the target system. In the IAR Embedded Workbench, XLINK is started automatically when you choose the Build option. Part 1. Using the compiler 3

18 Supported derivatives In the command line interface, the following line can be used to start XLINK: xlink myfile.r34 myfile2.r34 -f lnkm16c.xcl clm16cffffwc.r34 In this example, myfile.r34 and myfile2.r34 are object files, lnkm16c.xcl is the linker command file, and clm16cffffwc.r34 is the runtime library. Supported derivatives The M16C/R8C IAR C/C++ Compiler supports all derivatives based on Renesas M16C/1X, 2X, 3X, 6X, and R8C Series of CPU cores, but not for the M16C/80 core. To compile code for the M16C/80 core, you need the M32C IAR C/C++ Compiler. The R8C IAR C/C++ Compiler supports all derivatives based on Renesas R8C Series of CPU cores. In this guide, all examples are made for the M16C/1X, 2X, 3X, and 6X Series of CPU cores, but they are valid also for the R8C CPU core, unless otherwise stated. Data storage One of the characteristics of the M16C/R8C Series of CPU cores is that there is a trade-off regarding the way memory is accessed, ranging from cheap access to small memory areas up to more expensive access methods that can access any location. One of the decisions a developer of embedded systems must make is to decide where the different memory access methods should be used. The M16C/R8C IAR C/C++ Compiler allows you to set a default memory access method by using data models. The compiler also allows the access method to be specified explicitly for each individual variable. The Data storage chapter covers memory access methods in greater detail. Optimization techniques The M16C/R8C IAR C/C++ Compiler is a state-of-the-art compiler with a C/C++ level optimizer that performs, among other things, dead-code elimination, constant propagation, inlining, common sub-expression elimination, and precision reduction. It also performs loop optimizations such as unrolling and induction variable elimination. The user can control the level of optimization and decide if the basic approach is to optimize for speed or for size. It is also possible to disallow individual optimizations. 4 M16C/R8C IAR C/C++ Compiler Reference Guide

19 Introduction For more information about optimization, see the chapter Programming hints. IAR language extension overview This section briefly describes the extensions provided by the M16C/R8C IAR C/C++ Compiler to support specific features of the M16C/R8C Series of CPU cores. SPECIAL FUNCTION TYPES The special hardware features of the M16C/R8C Series of CPU cores are supported by the compiler s special function types: interrupt, monitor, tiny_func, and regbank_interrupt. These allow you to write a complete application without having to write any part of it in assembler language. For detailed information, see Special function types, page 25. EXTENDED KEYWORDS The M16C/R8C IAR C/C++ Compiler provides a set of keywords that can be used to control the behavior of the program. There are, for example, keywords for controlling the memory type for individual variables as well as for declaring special function types. By default language extensions are always enabled in the IAR Embedded Workbench. The command line option -e makes the extended keywords available, and reserves them so that they cannot be used as variable names. See page 105 for additional information. For detailed descriptions of the extended keywords, see the chapter Extended keywords. PRAGMA DIRECTIVES The pragma directives control the behavior of the compiler, for example how it allocates memory, whether it allows extended keywords, and whether it issues warning messages. The pragma directives are always enabled in the M16C/R8C IAR C/C++ Compiler. They are consistent with the ISO/ANSI C and are very useful when you want to make sure that the source code is portable. For detailed descriptions of the pragma directives, see the chapter Pragma directives. Part 1. Using the compiler 5

20 Runtime libraries PREDEFINED SYMBOLS With the predefined preprocessor symbols, you can inspect your compile-time environment, for example the code and data models. For detailed descriptions of the predefined symbols, see the chapter Predefined symbols. INTRINSIC FUNCTIONS The intrinsic functions provide direct access to low-level processor operations and can be very useful in, for example, time-critical routines. The intrinsic functions compile into in-line code, either as a single instruction or as a short sequence of instructions. For detailed reference information, see the chapter Intrinsic functions. INLINE ASSEMBLER The asm keyword assembles and inserts the supplied assembler statement in-line, for example: asm("mov.w R1,R0"); Note: The asm keyword reduces the compiler s ability to optimize the code. We recommend the use of modules written in assembler language instead of inline assembler, since the function call to an assembler routine causes less performance reduction. Runtime libraries The M16C/R8C IAR C/C++ Compiler supports two sets of runtime libraries: The IAR CLIB Library, which is a small, efficient library well-suited for 8- and 16-bit processors. This library is not fully compliant with ISO/ANSI C, and does not fully support IEEE 754 floating-point numbers. C++ is not supported. The IAR DLIB Library, which supports ANSI C and C++. Note: CLIB is the default library, unless you run the compiler in C++ mode. For more information about the runtime libraries and the runtime environment they provide, see the IAR Runtime Environment and Library User Guide. This guide also provides a language overview. For reference information about the library functions, see the online help system. 6 M16C/R8C IAR C/C++ Compiler Reference Guide

21 Customization This chapter covers the configuration of the M16C/R8C IAR C/C++ Compiler including an overview of the available data models. The last section describes the standard runtime libraries that are included and how they correspond to the compiler options. You should read this chapter before you read the remaining chapters in Part 1. Using the compiler and the chapters in Part 2. Compiler reference. CPU core The M16C/R8C IAR C/C++ Compiler supports both the M16C/1X, 2X, 3X, and 6X Series of CPU cores and the R8C Series of CPU cores. The compiler can be used in two different modes, depending on for which CPU core you want code to be produced. To choose which CPU core to use, use the option --cpu and specify M16C or R8C, respectively. The following features of the compiler are not supported if the compiler is used in R8C mode: The data models and the corresponding keywords data20 and far for placing data in either data20 or far memory, and for determining the default data pointer type the tiny_func keyword for making a function to be called with the instruction JSRS via an entry in the special page area the FLIST segment holding the special page vector table. Note that neither of these features, nor the --cpu option, are supported by the R8C IAR C/C++ Compiler. Data model The data model specifies the data memory which is used for storing: Non-stacked variables, that is, global data and variables declared as static Dynamically allocated data, for example data, allocated with malloc or, in C++, the operator new. The data model also affects the location of the runtime stack. Part 1. Using the compiler 7

22 Runtime library The following table summarizes the characteristics of the different data models: Data model Near (default) Default variable Default constant Default data Description memory attribute memory attribute pointer data16 data16 data16 First 64 Kbytes Far data16 far far Variables in the first 64 Kbytes. Small constants anywhere. Huge data16 data20 data20 Variables in the first 64 Kbytes. Constants anywhere. Table 2: Data models In the near data model, the stack must be placed in the first 64 Kbytes of the memory. This is due to the fact that pointers to stack object must be convertible to the default pointer type, which has a size of 16 bits in the near data model. Your program can only use one data model at a time, and the same model must be used by all user modules and all library modules. If you do not specify a data model option, the compiler will use the near data model. To read more about placing constants and variables in different parts of memory, see Constants and variables in different parts of memory, page 60. The default memory attribute can for each individual variable be overridden by the use of extended keywords or pragma directives. See the IAR Embedded Workbench IDE User Guide for information about setting options in the IAR Embedded Workbench. Use the --data_model option to specify the data model for your project; see --data_model, page 101. Note: The different data models are only supported if you use the compiler in M16C mode, that is if you use the option --cpu M16C. Runtime library The prebuilt runtime libraries are configured for different combinations of the following features: the runtime library CLIB or DLIB the cpu core always M16C the option --data_model the option --variable_data the option --constant_data 8 M16C/R8C IAR C/C++ Compiler Reference Guide

23 Customization the option --64bit_doubles the option --align_data the option --low_consts library configuration Normal or Full the option --M30600_patches calling convention Normal or Simple. The runtime library names are constructed in the following way: <type><cpu><data model><variables area><constants area><size of doubles><data alignment><copies constants to near><library configuration><patched for M30600><calling convention>.r34 where type cpu data model variables area constants area size of doubles data alignment is dl for the IAR DLIB library, or cl for the IAR CLIB library, respectively is always m16c (regardless of M16C or R8C) is n, f, or h for near, far, and huge data, respectively is n, f, or h for placing variable data in near, far, and huge memory, respectively is n, f, or h for placing constant data in near, far, and huge memory, respectively is f or d, depending on whether doubles are 32 (f) or 64 (d) bits is w or b, depending on whether the data alignment is 2 bytes (w) or 1 byte (b) copies constants to near is either w, which means that constants are copied to near memory, or c, which means that they are not library configuration patched for M30600 calling convention is one of n or f for normal and full library configuration, respectively (only for DLIB) is 0 if the library is patched to compensate for hardware problems with the M30600 core, otherwise this position in the library name is empty is s if the library uses the simple calling convention, otherwise this position in the library name is empty. Part 1. Using the compiler 9

24 Runtime library Examples clm16cffffwc.r34 is an IAR CLIB library that uses the far data model, places both variable and constant data in far memory and uses 32-bit doubles. It is 2-byte-aligned, does not copy constants to near memory and it has not been patched for use with the M30600 core. It uses the normal calling convention. clm16cnnnfwc0.r34 is an IAR CLIB library that uses the near data model, places both variable and constant data in near memory and uses 32-bit doubles. It is 2-byte-aligned, does not copy constants to near memory and it has been patched for use with the M30600 core. It uses the normal calling convention. clm16cnnndbcs.r34 is an IAR CLIB library that uses the near data model, places both variable and constant data in near memory, and uses 64-bit doubles. It is 1-byte-aligned, does not copy constants to near memory and it has not been patched for use with the M30600 core. It uses the simple calling convention. To create the required runtime environment, you should choose a runtime library and set library options. You may also need to override certain library modules with your own customized versions. For more information about this, see the IAR Runtime Environment and Library User Guide. For reference information about the runtime library functions, refer to the online help system. 10 M16C/R8C IAR C/C++ Compiler Reference Guide

25 Data storage This chapter starts by describing the fundamental ways data can be stored in memory: on the stack, in static (global) memory, or in heap memory. Then the different memory access methods and corresponding memory types are described. Memory types are discussed in relation to pointers, structures, C++ class objects, and non-initialized memory. Then placement in memory of global and static variables is described. Finally, the structure types struct and union are described. Stack, static, and heap memory Data can be stored in memory in three different ways: On the stack. This is memory space that can be used by a function as long as it is executing. When the function returns to its caller, the memory space is no longer valid. Static memory. This kind of memory is allocated once and for all; it remains valid all through the execution of the application. Variables that are either global or declared static are placed in this kind of memory. On the heap. Once memory has been allocated on the heap it remains valid until it is explicitly released back to the system by the application. This type of memory is useful when the number of objects is not known until the application executes. Note that there are potential risks connected with using the heap in systems with a limited amount of memory or systems that are expected to run for a long time. THE STACK AND AUTO VARIABLES Variables that are defined inside a function and not declared static are named auto variables by the C standard. A small number of these variables are placed in processor registers; the rest are placed on the stack. From a semantic point of view this is equivalent. The main differences are that accessing registers is faster and that less memory is required compared to when variables are located on the stack. Auto variables live as long as the function executes; when the function returns, the memory allocated on the stack is released. The stack can contain: Local variables and parameters not stored in registers Temporary results of expressions The return value of functions (unless it is passed in registers) Part 1. Using the compiler 11

26 Stack, static, and heap memory Processor state during interrupts Processor registers that should be restored before the function returns (callee-save registers). The stack is a fixed block of memory, divided into two parts. The first part contains allocated memory used by the function that called the current function, and the function that called it, etc. The second part contains free memory that can be allocated. The borderline between the two areas is called the top of stack and is represented by the stack pointer, which is a dedicated processor register. Memory is allocated on the stack by moving the stack pointer. A function may never refer to the memory in the area of the stack that contains free memory. The reason is that if an interrupt occurs, the called interrupt function can allocate, modify, and of course deallocate memory on the stack. Advantages The main advantage of the stack is that functions in different parts of the program can use the same memory space to store its data. Unlike a heap, a stack will never become fragmented or suffer from memory leaks. It is possible for a function to call itself what is called a recursive function and each invocation can store its own data on the stack. Potential problems The way the stack works makes it impossible to store data that is supposed to live after the function has returned. The following function demonstrates a common programming mistake. It returns a pointer to the variable x, a variable that ceases to exist when the function returns. int * MyFunction() { int x;... do something... return &x; } Another problem is the risk of running out of stack. This will happen when one function calls another, which in turn calls a third, etc., and the sum of the stack usage of each function is larger than the size of the stack. The risk is higher if large data objects are stored on the stack or when recursive functions functions that call themselves either directly or indirectly are used. 12 M16C/R8C IAR C/C++ Compiler Reference Guide

27 Data storage STATIC MEMORY All global and static variables will be placed in static memory. The word static in this context means that the amount of memory allocated for this type of variables does not change while the application is running. The M16C/R8C Series of CPU cores can access memory in different ways. The access methods range from generic but expensive methods that can access the full memory space, to cheap methods that can access limited memory areas. The following memory types and corresponding keywords exist: Data13 memory addressing ( data13) Data16 memory addressing ( data16) Data20 memory addressing ( data20) only supported in M16C mode Far memory addressing ( far) only supported in M16C mode. For information about the M16C mode, see CPU core, page 7. A variable can be placed in a non-default memory area by declaring it using extended keywords or pragma directives, as in these examples: data20 int x; #pragma type_attribute= data16 int y; See Memory access methods and memory types, page 14, for a description of the limitations and advantages of each of these methods. DYNAMIC MEMORY ON THE HEAP Memory for objects allocated on the heap will live until they are explicitly released. This type of memory storage is very useful for applications where the amount of data is not known until runtime. In C, memory is allocated using the standard library function malloc or one of the related functions calloc and realloc. The memory is released again using free. In C++ there is a special keyword, new, designed to allocate memory and run constructors. Memory allocated with new must be released using the keyword delete. Potential problems Systems that are using heap-allocated objects must be designed very carefully, since it is easy to end up in a situation where it is not possible to allocate objects on the heap, either because there is not enough free memory on the heap or because it has become fragmented. Part 1. Using the compiler 13

28 Memory access methods and memory types The heap can become exhausted because the system simply uses too much memory. It can also become full if memory that no longer is in use has not been released back to the system. For each allocated memory block the system requires a few bytes of data for administrative purposes. For applications that allocate a large number of small blocks this administrative overhead can be substantial. There is also the matter of fragmentation; this means a heap where small sections of free memory is separated by memory used by allocated objects. It is not possible to allocate a new object if there is no piece of free memory that is large enough for the object, even though the sum of the size of the free objects exceeds the size of the object. Unfortunately, fragmentation tends to increase as memory is allocated and released. Hence, applications that are designed to run for a long time should try to avoid using memory allocated on the heap. Memory access methods and memory types This section describes the concept of access methods and the corresponding memory types used to access data by the M16C/R8C IAR C/C++ Compiler. For each memory type the capabilities and limitations are discussed. MEMORY ACCESS METHODS The M16C/R8C Series of CPU cores has one continuous memory space. However, the memory can be accessed in different ways. The different methods can access different areas of memory and have different costs when it comes to code space, execution speed, and register usage. The memory type can be specified either by using a keyword or a pragma directive. In this guide we will denote the memory reachable by a memory access method a memory type. For example, the memory accessible using the data16 memory access method is called memory of data16 type, or simply data16 memory. The data model (see Data model, page 7) controls the default memory type, which is used when the memory type is not specified. 14 M16C/R8C IAR C/C++ Compiler Reference Guide

29 Data storage Example The example below defines three variables alpha, beta, and gamma to be placed in data16, data20, and in the default memory type, respectively. Note that the pragma directive only controls the memory placement of the next defined variable. int data16 alpha; #pragma type_attribute= data20 int beta; int gamma; MEMORY TYPES Name Keyword Address range Pointer size Comments data13 data13 0-0x1FFF There is no data13 pointer. Instead the data16 pointer is used. data16 data16 0-0xFFFF 16 bits data20 data20 0-0xFFFFF 20 bits; index pointers 20 bits far far 0-0xFFFFF 20 bits; index pointers 16 bits Table 3: Memory types Objects must not be greater than 64 Kbytes and they must not cross 64-Kbyte boundaries For backward compatibility, the keywords near and huge are available as aliases for data16 and data20, respectively. The memory access methods used for each type of memory are described in Memory access methods, page 30. Pointers Pointers are used for referring to the location of data. This section discusses pointers in the presence of multiple memory types. POINTERS AND MEMORY TYPES In general, a pointer has a type. For example, a pointer that has the type int * points to an integer. Part 1. Using the compiler 15

30 Pointers In the M16C/R8C IAR C/C++ Compiler, a pointer also points to some type of memory. The type of the memory is specified using a memory type keyword before the asterisk. For example, a pointer that points to an integer stored in data20 memory has the type int data20 *. If no memory type is specified, the default memory type is used. Differences between pointer types In the M16C/R8C IAR C/C++ Compiler it is legal, with one exception, to convert pointers between different types without explicit casts. The exception is when casting from a larger pointer type to a smaller. Since the size is the same for pointers to all memory types except for the data16 pointer, it is illegal to cast other pointer types to a data16 pointer. Whenever possible, pointers should be declared without memory attributes. For example, the functions in the standard library are all declared without explicit memory types. Variables as pointers If a variable is declared as a pointer, the memory type of the variable itself can be specified. Examples The following is a series of examples with descriptions. First some integer variables are defined and then pointer variables are introduced. Finally a function accepting a pointer to an integer in data16 memory is declared. The function returns a pointer to an integer in data20 memory. int a; int data16 b; data20 int c; int * d; int data16 * e; int data16 * data20 f; A variable defined in default memory. A variable in data16 memory. A variable in data20 memory. A pointer stored in default memory. The pointer points to an integer in default memory. A pointer stored in default memory. The pointer points to an integer in data16 memory. A pointer stored in data20 memory pointing to an integer stored in data16 memory. 16 M16C/R8C IAR C/C++ Compiler Reference Guide

31 Data storage int data20 * myfunction( int data16 *); A declaration of a function that takes a parameter which is a pointer to an integer stored in data16 memory. The function returns a pointer to an integer stored in data20 memory. In order to read the examples above, start from the left and add one qualifier at each step: int int data16 int data16 * int data16 * data20 The basic type is an integer. It is stored in data16 memory. This is a pointer to it. The pointer is stored in data20 memory. Structures and memory types When a variable is defined, it will be placed in a memory of a certain type. Normally the default memory type is used but another memory type can be specified. For structures, the entire object is placed in the same memory type. It is not possible to place individual structure members in different memory types. Example In the example below, the variable gamma is a structure placed in data20 memory. struct MyStruct { int alpha; int beta; }; data20 struct MyStruct gamma; The following declaration is incorrect: struct MySecondStruct { int blue; data20 int green; /* Error! */ }; Part 1. Using the compiler 17

32 C++ and memory types C++ and memory types A C++ class object is placed in one memory type, in the same way as for normal C structures. However, the class members that are considered to be part of the object are the non-static member variables. The static member variables can be placed individually in any kind of memory. Remember, in C++ there is only one instance of each static member variable, regardless of the number of class objects. Also note that for non-static member functions unless class memory is used the this pointer will be of the default data pointer type. This means that it must be possible to convert a pointer to the object to the default pointer type. The restrictions that apply to the default pointer type also apply to the this pointer. For more information, about C++ and memory types, see the IAR Runtime Environment and Library User Guide. In the near data model, this means that objects of classes with a member function can only be placed in the default memory type (near). Example In the example below an object, named delta, of the type MyClass is defined in data16 memory. The class contains a static member variable that is stored in data20 memory. // The class declaration (placed in a header file): class MyClass { public: int alpha; int beta; data20 static int gamma; }; // Definitions needed (should be placed in a source file): data20 int MyClass::gamma; // A variable definition: data16 MyClass delta; 18 M16C/R8C IAR C/C++ Compiler Reference Guide

33 Data storage Non-initialized memory Normally the runtime environment will initialize all global and static variables when the application is started. The compiler supports the declaration of variables that will not be initialized using the no_init type modifier. They can be specified either as a keyword or using the #pragma object_attribute directive. The compiler places such variables in separate segments, according to the specified memory keyword. See the chapter Segments and memory for more information. For no_init, the const keyword implies that an object is read only, rather than that the object is stored in read-only memory. It is not possible to give a no_init object an initial value. Variables declared using the no_init keyword could, for example, be large input buffers or mapped to special RAM that keeps its content even with the application is turned off. For information about the no_init keyword, see page 127. Note that to use this keyword, language extensions must be enabled; see -e, page 105. For information about the #pragma object_attribute, see page 135. Located variables Global and static variables can be explicitly placed at absolute addresses or in named segments using operator or #pragma location. The variables must be declared either no_init or const. If declared const, it is legal for them to have initializers. C++ static member variables can be placed at an absolute address or in named segments just like any other static variable. ABSOLUTE LOCATION PLACEMENT To place a variable at an absolute address, the argument to the and the #pragma location directive should be a literal number, representing the actual address. The absolute location must fulfill the alignment requirement for this type of variable. Part 1. Using the compiler 19

34 Located variables Example no_init char 0x3D0; /* OK */ #pragma location=0x3d2 const int beta; /* OK */ const int 0x3D4 = 3; /* OK */ int 0x3D6; /* Error, neither */ /* " no_init" nor "const". */ const int 0x3D7; /* Error, misaligned. */ The last line is only misaligned if you are using default data alignment (2). When you use byte alignment (1) it is permitted to place an int like that. Note: A variable placed in an absolute location should be defined in an include file, to be included in every module that uses the variable. An unused definition in a module will be ignored. A normal extern declaration one that does not use an absolute placement directive can refer to a variable at an absolute address; however, that module cannot then optimize based on the knowledge of the absolute address of the variable. SEGMENT PLACEMENT It is possible to place variables into named segments using either operator or the #pragma location directive. The segment is specified as a string literal. For information about segments, see the chapter Segments and memory. Example no_init int "MYSEGMENT"; /* OK */ #pragma location="mysegment" const int beta; /* OK */ const int "MYSEGMENT" = 3; /* OK */ int "MYSEGMENT"; /* Error, neither */ /* " no_init" nor "const" */ ACCESSING SPECIAL FUNCTION REGISTERS Specific header files for a number of M16C/R8C Series of CPU cores are included in the M16C/R8C IAR C/EC++ Compiler delivery. The header files are named iochip.h and define the processor-specific special function registers (SFRs). 20 M16C/R8C IAR C/C++ Compiler Reference Guide

35 Data storage Note: Each header file contains one section used by the compiler, and one section used by the assembler. SFRs with bitfields are declared in the header file; the following example is from iom16c62.h: /* INT3 interrupt control register */ no_init volatile union { unsigned char INT3IC; struct { unsigned char ILVL : 3; unsigned char IR : 1; unsigned char POL : 1; } INT3IC_bit; 0x044; By including the appropriate iochip.h file into the user code it is possible to access either the whole register or any individual bit (or bitfields) from C code as follows: // whole register access INT3IC = 0x15; // Bitfield accesses INT3IC_bit.ILVL = 5; INT3IC_bit.IR = 0; INT3IC_bit.POL = 1; The header files are also suitable to use as templates when creating new header files for other M16C/R8C Series of CPU cores. Packed structure types The M16C/R8C IAR C/EC++ Compiler offers a way to pack the fields of a struct or union tighter than the default alignment allows. This is accomplished by using the #pragma pack directive. The #pragma pack directive has the following syntax: #pragma pack(n) #pragma pack() #pragma pack(push {,name} {,n}) #pragma pack(pop {,name} {,n}) where n is 1, 2, 4, 8, or 16. Part 1. Using the compiler 21

36 Packed structure types The pack(n) affects declarations of struct and union types from the pragma directive to the next #pragma pack or end of file. A #pragma pack within a function will only be active to the end of the function. To access struct members default alignment is used and the compiler will use the most efficient coding possible. For example, a long variable might be loaded or stored with long access. If #pragma pack(1) is used, each access to an object will be byte-wise and the loading of a long variable will be made with 4-byte read operations from memory. A consequence of this is that use of non-default alignment might increase code size and/or decrease execution speed at each access. Therefore, do not use #pragma pack unless required. The pack() resets the alignment to default. pack(push [,name] [,n]) pushes the current alignment with the label name and sets the alignment to n. Notice that both name and n are optional. pack(pop [,name] [,n]) pops to the label name and sets the alignment to n. Notice that both name and n are optional. If name is omitted, only the top alignment is removed. If n is omitted, the alignment is set to the value popped from the stack. #pragma pack() only affects the declarations of struct and union types, not the declaration of variables themselves. An example from the include.h file: #pragma pack(push,include.h,2) // current pack alignment pushed, new pack alignment 2 struct packed { long l,l2; } #pragma pack(pop,include.h) // pop original pack alignment struct sts { short s; long l; int j char arr[6]; } s1; #pragma pack(1) struct sts s2; struct f { char c; 22 M16C/R8C IAR C/C++ Compiler Reference Guide

37 Data storage long l; short s; } f1; In the source.c file: #include "include.h" #pragma pack() struct sts s3; struct f f2; struct packed p; The structures s1, s2, and s3 use default alignment. All elements of f1 and f2 will be accessed one byte at a time as the whole structure has the alignment 1. On the other hand, all elements of p will be accessed at most a 2-byte word at a time as that whole structure has the alignment 2. Anonymous structs and unions An anonymous struct or union is a struct or union object that is declared without a name. Its members are promoted to the surrounding scope. An anonymous struct or union must not have a tag. Notice that anonymous struct and union objects are only available when language extensions are enabled in the M16C/R8C IAR C/C++ Compiler. In EC++, however, anonymous unions are part of the language and thus always available. In the IAR Embedded Workbench, language extensions are enabled by default. Use the -e compiler option to enable language extensions. See -e, page 105, for additional information. Example In the following example, the members in the anonymous union can be accessed, in function f, without explicitly specifying the union name: struct s { char tag; union { long l; float f; }; } st; Part 1. Using the compiler 23