REJ10B0161-0100 H8/300 H8S/2600 H8S/2000 H8/300H H8/300L IEEE-694 C0005 C0300 - Datasheet Archive

 

H8S, H8/300 Series C/C+ Compiler, Assembler, Optimizing Linkage Editor Compiler Package Ver.6.01 User's Manual Renesas

 

REJ10B0161-0100 REJ10B0161-0100 H8S, H8/300 H8/300 Series C/C+ Compiler, Assembler, Optimizing Linkage Editor Compiler Package Ver.6.01 User's Manual Renesas Microcomputer Development Environment System Rev.1.00 Revision Date: Jan. 12, 2005 Keep safety first in your circuit designs! 1. Renesas Technology Corp. puts the maximum effort into making semiconductor products better and more reliable, but there is always the possibility that trouble may occur with them. Trouble with semiconductors may lead to personal injury, fire or property damage. Remember to give due consideration to safety when making your circuit designs, with appropriate measures such as (i) placement of substitutive, auxiliary circuits, (ii) use of nonflammable material or (iii) prevention against any malfunction or mishap. Notes regarding these materials 1. These materials are intended as a reference to assist our customers in the selection of the Renesas Technology Corp. product best suited to the customer's application; they do not convey any license under any intellectual property rights, or any other rights, belonging to Renesas Technology Corp. or a third party. 2. Renesas Technology Corp. assumes no responsibility for any damage, or infringement of any thirdparty's rights, originating in the use of any product data, diagrams, charts, programs, algorithms, or circuit application examples contained in these materials. 3. All information contained in these materials, including product data, diagrams, charts, programs and algorithms represents information on products at the time of publication of these materials, and are subject to change by Renesas Technology Corp. without notice due to product improvements or other reasons. It is therefore recommended that customers contact Renesas Technology Corp. or an authorized Renesas Technology Corp. product distributor for the latest product information before purchasing a product listed herein. The information described here may contain technical inaccuracies or typographical errors. Renesas Technology Corp. assumes no responsibility for any damage, liability, or other loss rising from these inaccuracies or errors. Please also pay attention to information published by Renesas Technology Corp. by various means, including the Renesas Technology Corp. Semiconductor home page (http://www.renesas.com). 4. When using any or all of the information contained in these materials, including product data, diagrams, charts, programs, and algorithms, please be sure to evaluate all information as a total system before making a final decision on the applicability of the information and products. Renesas Technology Corp. assumes no responsibility for any damage, liability or other loss resulting from the information contained herein. 5. Renesas Technology Corp. semiconductors are not designed or manufactured for use in a device or system that is used under circumstances in which human life is potentially at stake. Please contact Renesas Technology Corp. or an authorized Renesas Technology Corp. product distributor when considering the use of a product contained herein for any specific purposes, such as apparatus or systems for transportation, vehicular, medical, aerospace, nuclear, or undersea repeater use. 6. The prior written approval of Renesas Technology Corp. is necessary to reprint or reproduce in whole or in part these materials. 7. If these products or technologies are subject to the Japanese export control restrictions, they must be exported under a license from the Japanese government and cannot be imported into a country other than the approved destination. Any diversion or reexport contrary to the export control laws and regulations of Japan and/or the country of destination is prohibited. 8. Please contact Renesas Technology Corp. for further details on these materials or the products contained therein. This manual describes the facilities and operating procedures for the H8S, H8/300 H8/300 series C/C+ compiler (hereinafter H8S, H8/300 H8/300 compiler or simply the compiler). The compiler translates source programs written in C/C+ into object programs and load modules for Renesas H8SX series, H8S/2600 H8S/2600 series, H8S/2000 H8S/2000 series, H8/300H H8/300H series, H8/300 H8/300 series, and H8/300L H8/300L series microcomputers. Please read this H8S, H8/300 H8/300 Series C/C+ Compiler User's Manual before using the compiler to fully understand the system. Notes on Symbols: The following symbols are used in this manual. Symbols Used in This Manual Symbol Explanation Indicates an item to be specified. [] Indicates an item that can be omitted. . Indicates that the preceding item can be repeated. Indicates one or more blanks. (RET) Indicates the carriage return key (return key). | Indicates that one of the items must be selected. (CNTL) Indicates that the control key should be held down while pressing the key that follows. 1 This manual is intended for UNIX* , Microsoft® Windows® 98 operating system, Microsoft® Windows® Millennium Edition operating system, Microsoft® Windows NT® operating system, 2 Microsoft® Windows® 2000 operating system, Microsoft® Windows® XP operating system* and other compatible systems. In this document, the compiler functioning on a UNIX system is 3 referred to as the UNIX version. The compiler operating in IBM PC* and other compatible computers are referred to as the PC version. Notes: 1. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. ® ® ® 2. Microsoft , Windows , and WindowsNT are registered trademarks of Microsoft Corporation in the United States and/or other countries. 3. IBM is a registered trademark of International Business Machines Corporation. i Contents Section 1 1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 Section 2 2.1 2.2 4.2 ii Assembler Options .65 Command Line Format . 65 List of Options . 65 3.2.1 Source Options. 66 3.2.2 Object Options . 71 3.2.3 List Options. 78 3.2.4 Tuning Options . 84 3.2.5 Other Options. 86 3.2.6 CPU Options . 87 3.2.7 Options Other Than Above. 93 Section 4 4.1 C/C+ Compiler Operating Method.7 Command Line Format . 7 Interpretation of Options. 7 2.2.1 Source Options. 8 2.2.2 Object Options . 12 2.2.3 List Options. 22 2.2.4 Optimize Options. 25 2.2.5 Other Options. 41 2.2.6 CPU Options . 50 2.2.7 Options Other Than Above. 60 Section 3 3.1 3.2 Overview .1 Procedures for Developing Programs . 1 Compiler . 3 Assembler . 3 Optimizing Linkage Editor . 4 Prelinker. 4 Standard Library Generator . 4 Stack Analysis Tool . 5 Format Converter . 5 Optimizing Linkage Editor Options .101 Option Specifications. 101 4.1.1 Command Line Format . 101 4.1.2 Subcommand File Format. 101 List of Options . 101 4.2.1 Input Options . 102 4.2.2 Output Options. 107 4.2.3 4.2.4 4.2.5 4.2.6 4.2.7 4.2.8 4.2.9 4.2.10 Section 5 5.1 5.2 8.3 8.4 Environment Variables . 149 Environment Variables List .149 Compiler Implicit Declaration .153 Section 8 8.1 8.2 Operating Stack Analysis Tool . 147 Overview.147 Starting the Stack Analysis Tool.147 Section 7 7.1 7.2 Standard Library Generator Operating Method. 141 Comand Line Format .141 Option Descriptions .141 5.2.1 Additional Options.142 5.2.2 Options Unavailable for Standard Library Generator .145 5.2.3 Notes on Specifying Options .146 Section 6 6.1 6.2 List Options.117 Optimize Options .119 Section Options.125 Verify Options .127 Other Options.129 Subcommand File Option .137 CPU Option.138 Options Other Than Above .139 File Specifications. 155 Naming Files .155 Compiler Listings.157 8.2.1 Structure of Compiler Listings.157 8.2.2 Source Listing .158 8.2.3 Error Information .160 8.2.4 Symbol Allocation Information .161 8.2.5 Object Information.164 8.2.6 Statistics Information .166 Assembler Listings.167 8.3.1 Structure of Assembler Listings.167 8.3.2 Source Listing .167 8.3.3 Cross Reference Listing .169 8.3.4 Section Information Listing .171 Linkage Listings.171 8.4.1 Structure of Linkage Listing .172 8.4.2 Option Information .173 8.4.3 Error Information .173 8.4.4 Linkage Map Information .174 iii 8.5 8.4.5 Symbol Information . 174 8.4.6 Symbol Deletion Optimization Information . 176 8.4.7 Variable Access Optimization Symbol Information . 176 8.4.8 Function Access Optimization Symbol Information. 178 8.4.9 Cross-Reference Information. 179 Library Listings. 180 8.5.1 Structure of Library Listing . 180 8.5.2 Option Information . 181 8.5.3 Error Information. 182 8.5.4 Library Information . 182 8.5.5 Module, Section, and Symbol Information within Library . 183 Section 9 9.1 9.2 9.3 9.4 Programming .185 Program Structure . 185 9.1.1 Sections. 185 9.1.2 C/C+ Program Sections . 185 9.1.3 Assembly Program Sections . 189 9.1.4 Linking Sections . 191 Creation of Initial Setting Programs . 195 9.2.1 Memory Allocation. 195 9.2.2 Execution Environment Settings. 205 Linking C/C+ Programs and Assembly Programs. 244 9.3.1 Method for Mutual Referencing of External Names. 244 9.3.2 Function Calling Interface . 246 9.3.3 Examples of Parameter Assignment . 257 9.3.4 Using the Registers and Stack Area. 267 Important Information on Program Creation . 272 9.4.1 Important Information on Program Coding . 272 9.4.2 Important Information on Compiling a C Program with the C+ Compiler. 275 9.4.3 Important Information on Program Development. 276 Section 10 C/C+ Language Specifications.279 10.1 Language Specifications . 279 10.1.1 Compiler Specifications. 279 10.1.2 Internal Data Representation. 288 10.1.3 Floating-Point Number Specifications. 302 10.1.4 Operator Evaluation Order. 310 10.2 Extended Functions. 311 10.2.1 #pragma Extension Specifiers and Keywords. 311 10.2.2 Section Address Operator . 359 10.2.3 Intrinsic Functions . 361 10.3 C/C+ Libraries . 390 10.3.1 Standard C Libraries . 390 iv 10.3.2 Embedded C+ Class Libraries .533 10.3.3 Reentrant Library .620 10.3.4 Unsupported Libraries.625 Section 11 Assembly Specifications. 627 11.1 Program Elements .627 11.1.1 Source Statements.627 11.1.2 Reserved Words .631 11.1.3 Symbols .631 11.1.4 Constants.635 11.1.5 Location Counter .637 11.1.6 Expressions .638 11.1.7 String Literal .647 11.1.8 Local Label .648 11.2 Executable Instructions .650 11.2.1 Overview of Executable Instructions .650 11.2.2 Notes on Executable Instructions.652 11.3 Assembler Directives .674 11.4 File Inclusion Function .749 11.5 Conditional Assembly Function.752 11.5.1 Overview of the Conditional Assembly Function.752 11.5.2 Conditional Assembly Directives .758 11.6 Macro Function .774 11.6.1 Overview of the Macro Function .774 11.6.2 Macro Function Directives.776 11.6.3 Macro Body .780 11.6.4 Macro Call .784 11.6.5 String Literal Manipulation Functions .786 11.7 Overview of Structured Assembly .790 11.7.1 Notes on Structured Assembly.791 11.7.2 Structured Assembly Directives.792 Section 12 Compiler Error Messages . 815 12.1 Error Format and Error Levels.815 12.2 Error Messages.815 12.3 C Library Function Error Messages .882 Section 13 Assembler Error Messages . 885 13.1 Error Message Format and Error Levels .885 13.2 Error Messages.885 Section 14 Error Messages for the Optimizing Linkage Editor. 903 14.1 Error Format and Error Levels.903 v 14.2 List of Messages . 903 Section 15 Error Messages for the Standard Library Generator and Format Converter 917 15.1 Error Format and Error Levels. 917 15.2 List of Messages . 917 Section 16 Limitations.921 16.1 Limitations of the Compiler. 921 16.2 Limitations of the Assembler . 924 Section 17 Supporting AE5 Features .925 17.1 Compiler Functions. 925 17.1.1 Overview. 925 17.1.2 Compiler Options. 925 17.1.3 Intrinsic Functions . 927 17.2 Assembler Functions. 930 Section 18 Notes on Version Upgrade .933 18.1 Notes on Version Upgrade. 933 18.1.1 Guaranteed Program Operation . 933 18.1.2 Compatibility with the Earlier Version . 934 18.1.3 Command-line Interface . 937 18.1.4 Provided Contents. 940 18.1.5 List File Specification . 941 18.2 Additions and Improvements . 941 18.2.1 Common Additions and Improvements . 941 18.2.2 Added and Improved Compiler Features . 942 18.2.3 Added and Improved Features for the Assembler. 953 18.2.4 Added and Improved Features for the Optimizing Linkage Editor. 954 18.3 Operating Format Converter . 956 18.3.1 Object File Format . 956 18.3.2 Compatibility with Earlier Versions . 956 18.3.3 Command Line Format . 957 18.3.4 Interpretation of Options. 957 Section 19 Appendix .961 19.1 S-Type and HEX File Format . 961 19.1.1 S-Type File Format. 961 19.1.2 HEX File Format . 963 19.2 ASCII Code List . 965 19.3 Access Range of Short Absolute Addresses . 966 vi Index . 967 vii viii Section 1 Overview 1.1 Procedures for Developing Programs Figure 1.1 shows the procedures for developing programs. The shaded parts show software provided in the Renesas C/C+ Compiler Package for H8, H8S and H8SX family. The C/C+ compiler, assembler, optimizing linkage editor, standard library generator, stack analysis tool, and format converter are explained in this manual. 1 User include file User C/C+ source file H8S,H8/300 H8/300 series C/C+ compiler Standard include file User assembly program Prelinker Assembly source program H8S,H8/300 H8/300 series standard libraly generator H8S,H8/300 H8/300 series assembler SYSROF object/ library SYSROF load module Note: Relocatable object file Standard library file Optimizing linkage editor object/ library ELF/DWARF format converter Additional information file*1 Load module ELF/DWARF1 load module Profile informayion Debugger User library Stack information Stack analysis tool : Input/output : : Initiation *1 Assitional information files includes: -Template information files -Parameter information files -Instance information files -Tentative defined variable information files Called information Figure 1.1 Procedures for Developing Programs 2 Outlines of the C/C+ compiler, assembler, optimizing linkage editor, prelinker, standard library generator, stack analysis tool, and format converter are given in the following sections. 1.2 Compiler The H8S, H8/300 H8/300 series C/C+ compiler (hereinafter referred to as compiler) is software that takes source programs written in C or C+ language as inputs, and produces relocatable object programs or assembly source programs for the H8S, H8/300 H8/300 series microcomputers. Features of this compiler are as follows: 1. Generates an object program that can be written to ROM for installation in a user system. 2. Supports an optimization that improves the speed of execution of object programs and minimizes program size. 3. Supports extended features and options to take advantage of CPU's features such as short absolute addressing mode and indirect addressing mode. 4. Supports the C and C+ programming languages. 5. Supports features that are essential for the programming of embedded programs but are not standards in the C and C+ languages as extended features. Such features include interrupt functions and descriptions of system instructions. 6. Supports output of debugging information to enable C/C+ source-level debugging by the debugger. 7. Either an assembly source program or a relocatable object program can be selected for output. 8. Supports output of an inter-module optimization information used by the optimizing linkage editor. 1.3 Assembler The H8S, H8/300 H8/300 series assembler (hereinafter referred to as assembler) takes source programs written in assembly language, and outputs relocatable object programs for the H8S, H8/300 H8/300 series microcomputers. Features of this assembler are as follows: 1. Enables the efficient writing of source programs by providing the preprocessor functions listed below: File include function Conditional assembly function Macro function Structured assembly function 2. The mnemonics for execution instructions and assembly directives conform to the naming rules laid out in the IEEE-694 IEEE-694 specifications, and the system is uniform. 3 1.4 Optimizing Linkage Editor The optimizing linkage editor is software that takes multiple object programs output by the compiler or assembler and produces a load module or a library file. Features of this optimizing linkage editor are as follows: 1. Optimization can be applied to a set of several object files, depending on memory allocation and relations among function calls which cannot be optimized by the compiler. 2. Any of the following five types of load modules can be selected for output: Relocatable ELF format Absolute ELF format S-type format HEX format Binary format 3. Generates and edits library files. 4. Outputs symbol reference count list. 5. Deletes debugging information from library and load module files. 6. Specifies the output of a stack information file for use by the stack analysis tool. 1.5 Prelinker The prelinker is called from the optimizing linkage editor. When a C+ program template or runtime type information is used, the prelinker calls the compiler and makes it generate the necessary object files. When neither a C+ program template nor the runtime type information is used, the speed of linkage can be improved by specifying the noprelink option for the optimizing linkage editor. 1.6 Standard Library Generator The H8S, H8/300 H8/300 series standard library generator (hereinafter referred to as the standard library generator) is a software system for the reconfiguration of standard library files provided, using user-specified options. The standard library functions provided with the compiler include the standard set of C library functions, a set of C+ class library functions for embedded systems, and a set of runtime routines (arithmetic operations that are necessary for the execution of a program). In some cases, runtime routines will be necessary, even though the use of library functions in source programs has not been specified. 4 1.7 Stack Analysis Tool The stack analysis tool is software that takes the stack information file that is output by the optimizing linkage editor and calculates the size of the stack that will be used by C/C+ programs. 1.8 Format Converter The ELF/DWARF format converter (hereinafter referred to as format converter) takes object files and library files that have been output by an earlier version of the compiler or assembler and converts them to the ELF format. It can also take an ELF-format absolute load module and convert it to the output format of an earlier version of the linkage editor. 5 6 Section 2 C/C+ Compiler Operating Method 2.1 Command Line Format The format of the command line to initiate the compiler is as follows: ch38[.][[.] .] :-[=][,.] 2.2 Interpretation of Options In the command line format, uppercase letters indicate the abbreviation and characters underlined indicate the defaults setting. The dialog menus of the HEW is shown in the form of Tab name [Item]. The order of options correspond to that of the tabs and the categories in the HEW. 7 2.2.1 Source Options Table 2.1 Source Options Item Command Line Format Dialog Menu Include file directory Include = [,.] C/C+ [Show entries for :] [Include file directories] Specification Specifies include-file include path name. Default include PREInclude = file [,.] C/C+ [Show entries for :] [Preinclude files] Includes the specified files at the head of compiling units. Macro name definition DEFine = [,.] : [=] C/C+ [Show entries for :] [Defines] Defines as . Information message output control Message C/C+ [Show entries for :] [Messages] [Display information level messages] Outputs information message. C/C+ [Show entries for :] [File inline path] Specifies the path name where obtains a file that has function definitions to be expanded as inline functions. NOMessage [= [-