MN102L00 MN10200 12220-060E PC-9800 CC102L HP9000 EXEGCC98 PC-9801 95/98/NT3 - Datasheet Archive

 

MN102L00 MN10200 Series Linear Addressing Version C Compiler User's Manual Usage Guide Pub.No.12220-060E MS-DOS is a registered

 

MICROCOMPUTER MN102L00 MN102L00 MN10200 MN10200 Series Linear Addressing Version C Compiler User's Manual Usage Guide Pub.No.12220-060E 12220-060E MS-DOS is a registered trademark of Microsoft Corporation. PC-9800 PC-9800 is a registered trademark of NEC Corporation. PC/AT is a registered trademark of the International Business Machines Corporation. SUN4 and SPARC System are trademarks of SPARC International, Inc. (USA) and are licensed solely by Sun Microsystems (USA). SunOS is a trademark of Sun Microsystems (USA). Unix is a registered trademark licensed by X/Open Co., Ltd. in the US and other countries. PanaXSeries is a trademark of Matsushita Electric Industrial Co., Ltd. The other corporation names, logotype and product names written in this book are trademarks or registered trademarks of their corresponding corporations. Request for your special attention and precautions in using the technical information and semiconductors described in this book (1) An export permit needs to be obtained from the competent authorities of the Japanese Government if any of the products or technologies described in this book and controlled under the "Foreign Exchange and Foreign Trade Law" is to be exported or taken out of Japan. (2) The contents of this book are subject to change without notice in matters of improved function.When finalizing your design, therefore, ask for the most up-to-date version in advance in order to check for any changes. (3) We are not liable for any damage arising out of the use of the contents of this book, or for any infrigement of patents or any other rights owned by a third party. (4) No part of this book may be reprinted or reproduced by any means without written permission from our company. If you have any inquiries or questions about this book or our semiconductors, please contact one of our sales offices listed at the back of this book or Matsushita Electronics Corporation's Sales Department. Manual Organization The C compiler linear addressing version documentation for this series consist of the following three manuals. q MN10200 MN10200 Series Linear Addressing Version C Compiler User's Manual: Usage Guide The Usage Guide describes the commands and options actually used, starting with compiler installation. This manual also describes the start-up routine and interrupt handling required by embedded microcomputers. Chapter 6, "Diagnostic Messages", provides details on the error messages output during compilation. q MN10200 MN10200 Series Linear Addressing Version C Compiler User's Manual: Language Description The Language Description describes the syntax of the C programming language. In addition to standard C syntax, this manual also provides detailed descriptions of the special rules associated with the MN10200 MN10200 Series and points that require special attention when programming embedded microcomputers. It also describes in detail the new C syntax aspects introduced by the ANSI standard. This document can be used as a C language reference manual. q MN10200 MN10200 Series Linear Addressing Version C Compiler User's Manual: Library Reference The Library Reference describes the standard library provided with the MN10200 MN10200 Series C Compiler. This manual describes the library functions specified by the ANSI standard and provides usage examples for those functions. It is organized in alphabetic order for quick reference and is an easy to use C library reference manual. This document is the "MN10200 MN10200 Series Linear Addressing Version C Compiler User's Manual: Usage Guide", which describes the use of the compiler. Note that the following related documents are available. Contact your Matsushita sales office for details. q "MN10200 MN10200 Series Linear Addressing Version LSI User's Manual" q "MN10200 MN10200 Series Linear Addressing Version Instruction Manual" q "MN10200 MN10200 Series Linear Addressing Version Cross-assembler User's Manual" q "MN10200 MN10200 Series Linear Addressing Version C Source Code Debugger User's Manual" (NOTE: Not required for C Source Code Debugger for Windows users.) q "MN10200 MN10200 Series Linear Addressing Version C Source Code Debugger for Windows® User's Manual" q "MN10200 MN10200 Series Linear Addressing Version Installation Manual" About This Manual This manual is intended for programmers who will be using the CC102L CC102L compiler and covers the usage of the CC102L CC102L compiler itself starting with the installation procedure. It also provides notes on programming in C. s Manual Features · Chapter 1 provides an overview of the compiler so that users can easily grasp its structure. · This manual describes the installation and basic usage of the CC102L CC102L compiler so that it can be used even by first time users. · The CC102L CC102L compiler options are described with examples. The diagnostic messages are presented together with their cause and recovery procedure in a table format. Thus this manual functions as a message reference. · A special chapter is also provided to describe points that require care when writing programs for embedded microcomputers. · Items that depend on the CC102L CC102L compiler itself are collected in appendix. s Document Structure The entries in this document are composed of the following elements: titles, text, supplementary descriptions, notes, input examples and option descriptions. The example below is used to describe the layout and meaning of each of these elements. s Heading Chapter5 Microcomputer Programming 5.3 The name of each chapter is placed here to ease searching the manual. Control Registers The MN10200 MN10200 Series microcomputer registers that control the peripheral functions and CPU operation are mapped to memory addresses. Since these registers are allocated to addresses that are specific for each product, handling a given control register as a single variable in C requires associating the control register name with the actual address in the compiler. s Control Register Declaration in C Normally, variable and text allocation addresses are determined at link time when programming in C. However, it is possible to program at the C source code level as though certain variables have their addresses determined in advance by using the syntax described below. However, since these objects are not actually variables, they cannot be handled as symbols by the debugger. The technique involves casting an address value to a pointer. Here, the control register name is defined (with #define) to be that cast expression and then the control register name can be used as though it were a variable. #define control register name (*(volatile variable type *) address) The volatile declaration is required to prevent reads or writes to the control register from being removed by the optimization. s Notes Items that require special care when programming embedded microcomputers or using the compiler are extracted as notes. First time users should carefully read these notes when developing programs. Example: #define #define #define #define #define #define #define #define CPUM_adr cpum MCR_adr mcr IAGR_adr iagr NMICR_adr nmicr 0x00FC00 (*(volatile 0x00FC02 (*(volatile 0x00FC0E (*(volatile 0x00FC40 (*(volatile unsigned int *)CPUM_adr) unsigned int *)MCR_adr) unsigned int *)IAGR_adr) unsigned int *)NMICR_adr) This technique can be used for address other than control register addresses. However, expressions that attempt to reference 16-bit or larger data structures at an odd address are not allowed. 90 Control Registers s Sample programs These are presented to describe the assembler code generated by the compiler or assembler programs that the user writes. Chapter4 Command Reference s Option This field shows an option string specified when invoking the compiler. 4.2.1 Output File Options s Option description o output file name This field provides a simple description of the corresponding option field. Specifies the output file name. s Functional Description s Input example This option specifies the file name for the output file generated by the CC102L CC102L system. The CC102L CC102L system can generate either an executable file, an object file, an assembler source file, or a preprocessor output file. However, the -o option is invalid when there are multiple input files specified and one of the -P, -c or -S options is specified. These lines are command input examples for the various option items. s Syntax Enter a lower case "o" and the file name immediately after the option specifier character "". Spaces may not be inserted between the "o" and the file name. cc102L -S -otest.asm test1.c s Defaults A file with the default name is generated if the "o" option is not specified or if it is invalid. The file name generated by default differs depending on the format of the file the driver attempts to generate. -P option (when a preprocessor output file is generated) A file in which the extension of the input file is changed to ".i" is generated in the current directory. -S option (when an assembler source file is generated) A file in which the extension of the input file is changed to ".asm" is generated in the current directory. -c option (when an object file is generated) A file in which the extension of the input file is changed to ".rf" is generated in the current directory. No options (when an executable file is generated) A file with the name "m102L.ex" is generated in the current directory. Compiler Options 41 s Reference Techniques This document supports four techniques for quickly finding the required information. 1. Use the index at the front of the document when searching for the beginning of a chapter. 2. Use the table of contents at the front of the document when searching for titles. 3. The chapter name and the intermediate title are listed at the top and bottom edges respectively on each page. Thus the content of each page can be seen at a glance. 4. Use the index at the end of the document to search for technical terms. Table of Contents Chapter1 Compiler Overview Chapter2 Installation Chapter3 Using the Compiler Chapter4 Command Reference Chapter5 Microcomputer Programming Chapter6 Diagnostic Messages Chapter7 Appendix Index 0 1 2 3 4 5 6 7 8 Table of Contents Chapter 1 Compiler Overview 1.1 System Structure.3 1.2 Compiler Processing.4 Chapter 2 Installation 2.1 Installing the Workstation Version of the Compiler .11 2.1.1 Operating Environment .11 2.1.2 Installation .12 2.1.3 Environment Setup .14 2.2 Installing the PC Version of the Compiler.19 2.2.1 Operating Environment .19 2.2.2 Installation .20 2.2.3 Environment Setup .22 2.3 Differences between Workstation and PC Versions .23 Chapter 3 Using the Compiler 3.1 Using the Compiler .27 3.2 Division into Sections .31 Chapter 4 Command Reference 4.1 Starting the Compiler .37 4.2 Compiler Options .40 4.2.1 Output File Options .41 4.2.2 Compiler Control Options .43 4.2.3 Optimization Options .46 4.2.4 Diagnostic Message Options .48 4.2.5 Code Generation Control Options.56 4.2.6 Bit-Field Control Option .64 4.2.7 Directory Specification Options.67 4.2.8 Debugging Options.71 4.2.9 Preprocessor Options.72 0 Chapter 5 Microcomputer Programming 5.1 Startup Routine.79 5.2 Interrupt Handling .84 5.2.1 Interrupt Mechanism .84 5.2.2 Interrupt Preprocessing and Postprocessing.85 5.3 Control Registers.90 5.4 Linking with Assembler Programs.91 5.4.1 Stack Frame.92 5.4.2 Argument Passing and Return Value Return .95 5.4.3 External Reference and External Definition for Symbols.100 Chapter 6 Diagnostic Messages 6.1 Message Format .103 6.2 Diagnostic Message Table.105 Chapter 7 Appendix 7.1 Processing System Dependencies .155 7.1.1 Limits.155 7.1.2 Tokens and Elements.156 7.1.3 Type Conversion.157 7.1.4 Types .159 7.1.5 Expressions.159 7.1.6 Structures.159 7.1.7 The #pragma Directive.160 7.1.8 The asm Statement .164 Index .165 Compiler Overview The CC102L CC102L compiler is a software system that converts programs written in the C programming language to machine language codes for MN10200 MN10200 Series microcomputers. This chapter describes the structure of the CC102L CC102L system to provide an overview of the compiler. 1 Chapter1 Compiler Overview 1.1 System Structure 1 The CC102L CC102L system includes several processing modules and the standard C library. cc102L/ bin/ CC102L CC102L executable modules include/ Standard header files lib/ Standard C library sample/ Sample programs Figure 1-1-1: CC102L CC102L System Structure System Structure 3 Chapter1 Compiler Overview 1.2 Compiler Processing The CC102L CC102L system basically consists of four executable modules and a driver for controlling their operation. Figure 1-2-1 shows the programs that form the CC102L CC102L system and the associated input and output files. Input File Driver Output File C source file cmp102L .c .i Preprocessor output C source file .i Assembler file temp1 .asm opt102L temp2 Assembler file Object file as102L00 .asm .rf temp3 Object file Assembly listing file .lst Executable file ld102L00 .rf .ex Library file Map file .lib .map cc102L Figure 1-2-1: Structure of the Compiler System 4 Compiler Processing Chapter1 Compiler Overview s Executable Modules ·Driver (cc102L) The driver accepts the options and input and output files specified on the command line, and invokes and passes appropriate arguments to the modules that follow. The driver also reads and interprets the environment settings file if it exists. · Compiler itself (cmp102L) The compiler itself parses the C source file passed from the driver and performs global optimizations and code generation. The compiler itself includes the preprocessor and a preprocessor output file can be generated by specifying an option to the compiler itself. · Optimizer (opt102L) The optimizer performs local optimizations at the instruction level on the assembler file generated by the compiler itself. · Assembler (as102L00) The assembler assembles assembly language source files generated by the compiler or written by the user and generates object files. The assembler can be invoked by the driver or by the user from the command line. [ "MN10200 MN10200 Series Linear Addressing Version Cross-assembler User's Manual" ] · Linker( ld102L00) The linker links object files generated by the assembler and library files to produce MN10200 MN10200 Series microcomputer executable format files. The linker can be invoked by the driver or by the user from the command line. [ "MN10200 MN10200 Series Linear Addressing Version Cross-assembler User's Manual" ] s Input and Output Files · C source file (.c) C source files are source code files written by the user in the C programming language. Header files (.h) can also be considered to be C source code files. · Preprocessor output C source file (.i) Preprocessor output C source files are output files for which the compiler itself has only performed preprocessor processing. A preprocessor output C source file can be generated by specifying the -P option to the driver. Compiler Processing 5 Chapter1 Compiler Overview · Assembler file (.asm) Assembler files are assembly language files generated from a C source file by the compiler itself. Files written in assembly language by the user are also referred to as assembler source files. · Object file (.rf) Object files are generated by the assembler from assembler files. Although these files are already translated into MN10200 MN10200 Series instruction codes, they cannot be executed by the debugger since they still contain relocation information. These files cannot be viewed by the user since they are in a binary format. · Assembly listing file (.lst) Assembly listing files are generated by the assembler from an assembler file. The content of an assembly listing file is formatted as a printer listing so the user can directly see the machine code that is the result of the assembly. An assembly listing file is created at the same time as the object file when specified by a driver or assembler option. · Library file (.lib) Library files consist of multiple object files collected into a single file by the library manager. The linker searches the specified library file for symbols that are undefined in the object file at link time and links in the required object file(s) from the library. · Executable file (.ex) Executable files are created by linking object files and library files, and can be executed by an MN10200 MN10200 Series microcomputer. This file cannot be viewed by the user since they are in a binary format. When an executable file is created with the debugging option specified, debugging information will be included in the file. · Map file (.map) Map files contain data specifying the final address for the symbols generated when the linker generates the executable file. A map file is generated when specified by an option when the linker is invoked. This option can also be passed to the linker by the driver. · Temporary files Temporary files are generated when the driver executes the compiler modules. These files exist only temporarily and are deleted by the driver after each module completes its processing. As a result, they are not normally seen by the user. 6 Compiler Processing Chapter1 Compiler Overview s Associated Tools · Library manager (slib102L) A utility for managing libraries. · File conversion utility (excv102) A utility for converting assembler .ex format executable files to the Intel hex format. The following command is only supported by the PC version · Assembler customization tool (PAINST.EXE) This is a utility for assembler and linker customization. Configuration files are used for assembler and linker customization in the workstation version. [ "MN10200 MN10200 Series Linear Addressing Version Cross-assembler User's Manual"] Compiler Processing 7 Installation This chapter describes the installation of the CC102L CC102L system on a workstation and the environment setup required to allow execution of the compiler system. 2 Chapter2 Installation 2.1 Installing the Workstation Version of the Compiler This section describes the procedures for installing the compiler on a workstation. 2 2.1.1 Operating Environment This system runs on the following workstations. Machine SUN4 HP9000 HP9000 OS SunOS 4.0.3 or later (but not SunOS 5.X or Solaris 2.X) HP/UX A.09.05 or later And systems compatible with the above. The following resources are required to use this system on a workstation. Disk space Memory size About 1.7 Mbytes 32 Mbytes Note that the required disk space listed above is the total space for the executable modules, the standard C libraries and header files and sample programs included in the provided CC102L CC102L system. During actual program development, additional disk space will be required corresponding to the size of the programs developed. Also note that compile times may become longer if large programs are compiled under a windowing system with less than the recommended amount of memory. We strongly recommend installing adequate additional memory above 32 Mbyte if at all possible. Installing the Workstation Version of the Compiler 11 Chapter2 Installation 2.1.2 Installation This section describes the installation procedure for the CC102L CC102L system in the delivery formats provided by Matsushita. s Delivery Formats The CC102L CC102L system can be provided in either of the formats listed below according to user needs for compiler installation. · floppy disks · 8 mm tape (SunOS Desktop SPARC System) (SunOS Desktop SPARC System) The files required for the compiler system are written using the SunOS tar command for both the floppy disk and tape media. The description that follows shows the procedure for installing the compiler system in the /usr/local directory. When the installation is complete, the compiler system will be stored in the cc102L directory under /usr/local. Note that UNIX allows file write protect/enable bits to be set for directories. Confirm that you can write to the /usr/local directory before starting the installation. cc102L/ bin/ cc102L cmp102L opt102L slib102L as102L00 ld102L00 excv102 .as102L00rc .ld102L00rc include/ lib/ errno.h ctype.h limits.h float.h math.h setjmp.h stdarg.h stddef.h stdio.h string.h stdlib.h cc102L.lib sample/ sample programs Figure 2-1-1: Files Provided with the Compiler System 12 Installing the Workstation Version of the Compiler Chapter2 Installation Although the CC102L CC102L system consists of multiple files and directories as shown in Figure 2-1-1, these files and directories are stored as a single compressed tar file (cc102L.tar.Z) on the delivery media. This file was created with the tar and gzip commands. Use the following procedure to install the CC102L CC102L system. s Transferring the Compiler System and Expanding the Files The CC102L CC102L system is installed by first transferring the files and then expanding the files using the following procedure. (1) File transfer using the tar command · floppy disks % tar xvf /dev/rfd0 (when rfd0 is the floppy disk device driver) · 8 mm tape % tar xvf /dev/rst1 (when rst1 is the 8 mm tape device driver) The file cc102L.tar.Z will be transferred to the /usr/local directory. (2) File recovery using the gzip command % gzip -d cc102L.tar.gZ After installation, the file cc102L.tar will be left in the /usr/local directory. This file is no longer necessary and should be deleted if the installation completed correctly. This command uncompresses the file and creates the file cc102L.tar in the /usr/local directory. (3) File expansion using the tar command % tar xvf cc102L.tar This command will create the cc102L directory under the /usr/local directory and expand all the files. This procedure should have copied the CC102L CC102L system from the delivery media and stored it on the workstation disk. At this point, confirm that the system was installed correctly. If it was not installed correctly, first confirm that there is adequate disk space and then check that the commands used were entered correctly. Installing the Workstation Version of the Compiler 13 Chapter2 Installation 2.1.3 Environment Setup After the compiler system has been installed on the disk with the procedure described in section 2.1.2, "Installation", the environment must be set up so that the compiler can be run. s Command Path Setup In the procedure described in section 2.1.2, "Installation", the CC102L CC102L system is installed in the /usr/local/cc102L directory. Set up the path environment variable to include the /usr/local/cc102L/bin directory so that the CC102L CC102L driver can be executed. On UNIX systems, environment variables are normally set in the file .cshrc in the user's home directory. Use a text editor to modify .cshrc, logout, re-login or execute .cshrc with the source command. s Environment Settings File The CC102L CC102L system can be run if the command path is set up as described above. However, it can be convenient during program development to set up the path(s) for include files shared by the whole project and to set up in advance the path for the C compiler's standard library. An environment settings file is used for these settings with the CC102L CC102L system. The following seven items can be set in an environment settings file. (1) One or more standard directories for include files not specified as absolute paths in C source files (2) One or more library files to be linked automatically when running the linker from the driver (3) One or more standard directories for library files linked automatically by the linker (4) A standard directory to use for temporary files (5) One or more standard directories for the commands run by the driver (6) The character set used in the C source code files (7) The language and character set for messages generated by the compiler The CC102L CC102L driver looks for an environment settings file with the name .cc102Lrc in directories specified in the path environment variable and compiles according to the information contained in that file. 14 Installing the Workstation Version of the Compiler Chapter2 Installation s Environment Settings File Syntax Environment settings file entries have the following syntax. keyword arg There are seven items that can be set in the environment settings file. The keyword field specifies the item to be set and the arg field specifies a standard directory or library file name for the item specified by keyword. At least one space or tab character must appear between the keyword and arg strings. A single directory or file name can be specified for a single keyword. Multiply directories or files are specified by starting a new line and specifying a different directory or file with the same keyword. Each item must be terminated with a new line. In particular, a new line is required for the last item in the file. This point is important because some text editors insert an EOF at the end of the file without a new line at the end of the last line. Installing the Workstation Version of the Compiler 15 Chapter2 Installation The following terms can be specified as the keyword. Description keyword Specifies a directory to search for include files specified in C source programs. Note that this search is not applied to include files specified as an absolute path starting with "/". The include keyword can be specified multiple times. include The CC102L CC102L compiler searches for include files in the following order. (1) The directory that holds the source file in which the #include directive appeared However, this directory is not searched if the include file is specified with angle brackets (). (2) -Directories specified with the -I option (3) Directories specified in the environment settings file. Specifies a directory to search for libraries to be linked automatically by the driver at link time.The libdir keyword can be specified multiple times. The CC102L CC102L linker searches for libraries in the following order. libdir (1) Directories specified with the -A option (2) Directories specified in the environment settings file Specifies the file name of a library to be linked automatically by the driver at link stdlib time. The stdlib keyword can be specified multiple times. temp Specifies the directory for the temporary files created by the CC102L CC102L system. The temp keyword can only be specified once. Specifies a directory to search for the executable modules called by the driver. The path keyword can be specified multiple times. The CC102L CC102L driver searches for executable modules in the following order. path (1) Directories specified with the -B option (2) When invoked with an absolute path: the directory that holds the driver Other cases: the current directory (3) Directories specified in the environment settings file (4) Directories specified in the path UNIX environment variable 16 Installing the Workstation Version of the Compiler Chapter2 Installation Description keyword Specifies the character set for processing Japanese characters in the C source code files: ASCII, EUC, SJIS (Shift JIS), or JIS. In the absence of a specification, the default depends on the host machine and its operating system. SUN4 EUC HP9000 HP9000 Shift JIS NEC PC-9800 PC-9800 Shift JIS DOS/V Shift JIS PC/AT file ASCII Japanese is allowed only in comments, character constants, and string literals. All other contexts produce compiler errors. Other errors may result if the specification does not match the actual character set used in the C source code file. Specifies the language and, for Japanese, the character set for diagnostic and help messages generated by the compiler: ENGLISH, EUC, SJIS (Shift JIS), or JIS. In the absence of a specification, the default depends on the host machine and its operating system. SUN4 English HP9000 HP9000 English NEC PC-9800 PC-9800 Japanese, Shift JIS DOS/V Japanese, Shift JIS PC/AT message English The compiler also ignores specifications not considered feasible for the host machine and its operating system. These are indicated with X's in the following table. Host Machine/OS ENGLISH EUC SJIS JIS SUN4 r r r r HP9000 HP9000 r r r r NEC PC-9800 PC-9800 r X r X DOS/V r X r X PC/AT r X X X Installing the Workstation Version of the Compiler 17 Chapter2 Installation Examples: include libdir stdlib stdlib temp path file message /usr/local/cc102L/include /usr/local/cc102L/lib cc102L.lib usrlib.lib /tmp /usr/local/cc102L/bin EUC JIS Multiple file names or multiple directories cannot be specified on a single line. 18 Installing the Workstation Version of the Compiler Chapter2 Installation 2.2 Installing the PC Version of the Compiler This section describes the procedures for installing the compiler on a personal computer. 2.2.1 Operating Environment This series of the compiler is an application that runs under an extender (EXEGCCV, EXEGCC98 EXEGCC98) with the following system requirements. Machine NEC PC-9801 PC-9801 or PC/AT or compatible CPU Intel 80386 or higher Memory Minimum of 5.6 Mbytes free (recommended) Note) This software uses extended memory, so does not run on personal computers with only 640 Kbytes of memory. Memory manager Fully compliant with the VCPI standard OS MS-DOS: Ver. 3.3 or later Windows: 95/98/NT3 95/98/NT3.51/NT4 51/NT4.01/2000 A longfile name cannot be used uder WindowsNT3.51/ NT4.01/2000. This software does not operate under the memory manager (EMM386 EMM386.SYS) included with MS-DOS version 5. Memory managers complying with the DPMI standard have a default block size of 2 Mbytes. If "out of memory" messages indicate that the program is too large, boost this to four Mbytes with the following environment variable setting. SET EXESW=-a,4096 Installing the PC Version of the Compiler 19 Chapter2 Installation 2.2.2 Installation This section describes the installation procedure for the PC version of this software. s Delivery Format The PC version of this software ships in the following format. · One floppy disk The following procedure installs the compiler system in CC102L CC102L, a subdirectory of \USER\PANAX. The compiler system consists of the directories and files shown in Figure 2-2-1. It ships as a single, self-extracting LHA (Note2) archive, CC102LXX CC102LXX.EXE. CC102L CC102L BIN INCLUDE LIB SAMPLE DOC CC102L CC102L.EXE CMP102L CMP102L.EXE OPT102L OPT102L.EXE SLIB102L SLIB102L.EXE AS102L00 AS102L00.EXE LD102L00 LD102L00.EXE PAINST.EXE EXCV102 EXCV102.EXE AS102L00 AS102L00.OUT LD102L00 LD102L00.OUT EXEGCCV.EXE* AS102L00 AS102L00.RC LD102L00 LD102L00.RC SLIB102L SLIB102L.OUT ERRNO.H LIMITS.H MATH.H STDARG.H STDIO.H STRING.H CTYPE.H FLOAT.H SETJMP.H STDDEF.H STDLIB.H CC102L CC102L.LIB Sample programs Documentation *The PC-9801 PC-9801 version uses EXEGCC98 EXEGCC98.EXE. Figure 2-2-1. File in Compiler Distribution (Note 2) LHA is a compression and archiving utility copyrighted by Haruyasu Yoshizaki. 20 Installing the PC Version of the Compiler Chapter2 Installation s Decompressing the Archive The compiler system ships as an LHA archive. Use the following procedure to install it on the hard disk. (1) Back up the distribution disk. Make a backup copy of the distribution disk and store the original in a safe place. (2) Copy the archive to the hard disk. The floppy disk contains a single file, CC102LXX CC102LXX.EXE. Copy this to the target directory on the hard disk. If the floppy is in drive A: and the target directory is C:\USR\PANAX, one way to do this is with the following command sequence. >C: >CD C:\USR\PANAX >COPY A:\CC102L CC102L*.EXE (3) Expand the archive. Before running the self-expanding archive, make sure that the current directory is the target directory and that the disk has at least 3 megabytes free. Run the self-expanding archive by typing its name at the prompt. >CC102LXX CC102LXX Check the disk directory to make sure that all the files shown in Figure 2.2.1 have been properly installed. The XX in the archive name indicates the platform: AT for PC/AT, LV for DOS/V, or 98 for NEC PC-9801 PC-9801. Installing the PC Version of the Compiler 21 Chapter2 Installation 2.2.3 Environment Setup After the compiler system has been installed on the hard disk, configure its operating environment. (1) Set environment variables. Add the directory containing the executables to the environment variable PATH. If the installation directory was \USR\PANAX\CC102L CC102L, this directory is \USR\PANAX\CC 102L\BIN. Specify the directory for temporary files with the environment variable TMP. The normal place for setting such environment variables is AUTOEXEC.BAT. PATH Executables are in the directory CC102L CC102L\BIN. TMP Specify the directory for temporary files. (2) Modify CONFIG.SYS. Make sure that CONFIG.SYS contains FILES and BUFFERS commands with settings greater than or equal to the ones shown below. FILES=20 BUFFERS=20 (3) Create an environment settings file. Creat an environment setting file for the compiler. The file name is CC102L CC102L.RC. For details, see the description for the workstation version in. [ 2.1.3 Environment Setup ] Create this file in a directory named in the environment variable PATH. Modifications to AUTOEXEC.BAT or CONFIG.SYS do not take effect until you reboot. If you are using a DPMI memory manager and get frequent "out of memory" messages, set the environment variable EXESW. [ 22 Installing the PC Version of the Compiler 2.2.1 Operating Environment] Chapter2 Installation 2.3 Differences between Workstation and PC Versions The following table summarizes the differences between the compiler system versions for workstations and personal computers. Table 2-3-1 Differences between Workstation and PC Versions Workstation version PC version Shipping media 3.5-inch floppy disk or 8-mm tape in Unix tar format 3.5-inch floppy disk in MS-DOS or PC-DOS format Installation Expand with tar and gzip LHA self-extracting archive None .cc102Lrc .as102L00rc .ld102Loorc None PAINST.EXE CC102L CC102L.RC Components Customization utility Environment settings files Document files Notes LHA.DOC DPMI memory managers have a default memory size of 2 Mbytes. An environment variable changes this default. Command lines are limited to 127 bytes each. Differences between Workstation and PC Versions 23 Using the Compiler This chapter describes the procedures used to create an executable program from a C source file using the CC102L CC102L system. This chapter only presents the most basic operations. See chapter 4, "Command Reference", for detailed descriptions of the CC102L CC102L options. Refer to the "MN10200 MN10200 Series Linear Addressing Version Crossassembler User's Manual" for descriptions of the assembler, linker and library manager. 3 Chapter3 Using the Compiler 3.1 Using the Compiler The CC102L CC102L system can be started by entering the following command line. cc102L [ options ] file name The cc102L program is a driver program for the compiler. It supports generation of an assembler file (.asm file), an object file (.rf file) and an executable file (.ex file) from one or more C source files according to the options specified. -S option -c option No options Generates an assembler file Generates an object file Generates an executable file Examples: cc102L -S sample.c Compiles the file sample.c and generates the file sample.asm. cc102L -c test1.c test2.c Compiles and assembles the files test1.c and test2.c and generates the files test1.rf and test2.rf. Multiple input files can be specified. cc102L -otest.ex startup.asm test1.c test2.c Compiles and/or assembles and links the three input files startup.asm, test1.c and test2.c and generates the file test.ex. The -o option specifies the name of the generated executable file. s Creating an Executable File Application code is normally split up into several files by function or processing type when developing a program for an embedded microcomputer. Breaking up applications into multiple files allows efficient development, especially during the debugging phase, since compile times can be reduced. The standard make utility provided by UNIX systems is effective for managing applications with multiple files, although a description of make is beyond the scope of this document. Using the Compiler 27 3 Chapter3 Using the Compiler This section describes the ordinary techniques for creating an executable file. C source file C source file (1) Object files are created from the C source files. C source file Compiler Assembler Object file Object file Assembler file Object file Linker (2) Object files are created from the assembler files. Object file Library file (3) An executable file is created by linking the object files and a library file. Executable file Figure 3-1-1: Compilation Procedure (1) Object files (.rf files) are created from the C source files. Specify the -c option to the driver. If the C source files are the files sample1.c, sample2.c and sample3.c, the object files can be created as follows. Example: % cc102L -c -O -g sample1.c % cc102L -c -O -g sample2.c % cc102L -c -O -g sample3.c Here, -O is the optimization option, -g is the debugging option. 28 Using the Compiler Chapter3 Using the Compiler (2) The assembler is used to create .rf files from .asm files. The assembler can also be called from the CC102L CC102L driver. In that case, specify the -c option to the driver. If the assembler file is the file startup.asm, an object file can be created as follows. Example: % cc102L -c -g startup.asm Here, -g is the debugging option. (3) The linker is used to link all the files together to produce a single .ex file. When the object files produced in steps (1) and (2) and the CC102L CC102L standard library file are available, an executable file can be created as follows. Example: % ld102L00 -g -osample.ex -T_TEXT=0x080000 -T_DATA=f000 startup.rf sample1.rf sample2.rf sample3.rf Here, -g is the debugging option. Also, the start address of the _TEXT and _DATA sections are specified with the -T option. s Notes on Linking There are several points that require attention when linking. · Always link a startup routine into the .ex file. In microcomputer programming, registers and RAM must be initialized by a startup routine before starting the function main. The function main cannot be executed if there is no startup routine. Also, programs usually quickly runs away if the registers are not initialized. Note that failing to specify a startup routine at link time does not generate an error. Thus the programmer must remember to link in a startup routine. [ 5.1 Startup Routines ] Using the Compiler 29 Chapter3 Using the Compiler · Linking the standard library The compiler supports double, float, and long arithmetic with in-line subroutines (abbreviated to insub elsewhere in this document) from the standard library cc102L.lib. Since the compiler provides the insub routines in the standard library format (cc102L.lib), only the required routines are linked. It is not possible to determine when and where the insub routines will be called at the C source level. Therefore, the standard library must be specified together with the user programs at link time. Thus we recommend specifying the standard library in advance in the control file when linking using the driver. [ 2.1.3 Environment Setup ] Similarly, we recommend specifying this in the options file when running the linker independently. [ "MN10200 MN10200 Series Linear Addressing Version Cross-assembler User's Manual" ] · Section address setup When using the CC102L CC102L system, programs and data will normally occupy multiple sections. Programs and data must be allocated in optimal locations according to the structure of the hardware used when programming microcomputers. The CC102L CC102L system allows address specification for each individual section. Each section address must be carefully specified so that programs or data are not allocated to addresses for which there is no memory present and so that programs or data are not allocated to memory mapped control registers. [ 3.2 Division into Sections ] 30 Using the Compiler Chapter3 Using the Compiler 3.2 Division into Sections In the MN10200 MN10200 Series microcomputers, ROM and RAM are allocated in a single address space. In the CC102L CC102L compiler, the RAM area is divided into groups for variables, such as static and external variables and the ROM area is also divided into groups, such as text and data tables (ROM tables). The CC102L CC102L compiler adopts the section concept to differentiate these ROM and RAM areas. s CC102L CC102L Generated Sections Sections are classified according to the following elements. · Section name The section name is used to differentiate the different sections. The compiler generates up to nine section names according to usage. · Section attribute For the MN10200 MN10200 Series, the section attribute indicates whether the memory for the section will be allocated in ROM or in RAM. "CODE" specifies that the area be allocated in ROM and "DATA" specifies that the area be allocated in RAM. · Allocation attribute The allocation attribute specifies address adjustment when allocating the section in memory. Since the MN10200 MN10200 Series microcomputers cannot access 16-bit data (data of type int) from odd addresses, all sections other than text sections are allocated from even addresses. Division into Sections 31 Capter3 Using the Compiler Table 3-2-1 lists the sections generated by the CC102L CC102L system. Table 3-2-1: CC102L CC102L Generated Sections Section Name Section Allocation Use Attribute Attribute The program's executable instructions are 1 _TEXT (text area) CODE 1 stored in this section. A program's executable instruction section is normally referred to as "text". This section has three uses. (1)As the area for static const variables 2 _CONST (constant area) CODE 2 (2)As the data area for string literals used in the program (3)As the area for data tables generated internally by the compiler 3 _GCONST (external constant area) CODE 2 Used as the area for external const variables. Used as the area for initialized static 4 _DATA (initialized data area) DATA 2 variables. Only the area is allocated, with the initial values being taken from _ROMDATA. 5 _BSS (noninitialized data area) DATA 2 Used as the area for noninitialized static variables. Used as the area for initialized external 6 _GDATA (initialized external data area) DATA 2 variables. Only the area is allocated, with the initial values being taken from _GROMDATA. 7 _GBSS (noninitialized external data area) DATA 2 Used as the area for noninitialized external variables. The area used to store the initial values of 8 _ROMDATA (ROM data area) CODE 2 initialized static variables. The area for these variables themselves is allocated in _DATA. The area used to store the initial values of 9 _GROMDATA (ROM external data area) CODE 2 initialized external variables. The area for these variables themselves is allocated in _GDATA. 10 _CODEEND Division into Sections 2 11 _BSSEND 32 CODE DATA 2 This section describes the end of the area _ROMDATA,_GROMDATA. This section describes the end of the area _BSS,_GBSS. Chapter3 Using the Compiler The section attribute is used to specify the allocation in ROM and RAM. Section attribute Memory allocation CODE ROM DATA RAM Programs written in the C programming language can be classified as text, data and initial value data. Note that this differs from the meaning of the section attribute DATA. Example: _TEXT _CONST _GCONST _DATA _BSS _GDATA _GBSS _ROMDATA _GROMDATA _CODEEND SECTION SECTION SECTION SECTION SECTION SECTION SECTION SECTION SECTION SECTION CODE,PUBLIC,1 CODE,PUBLIC,2 CODE,PUBLIC,2 DATA,PUBLIC,2 DATA,PUBLIC,2 DATA,PUBLIC,2 DATA,PUBLIC,2 CODE,PUBLIC,2 CODE,PUBLIC,2 CODE,PUBLIC,2 s Programming Notes When using the C compiler to create programs, the programmer must be aware of the sections generated by the compiler to perform the following operations. · Section address specification As briefly mentioned in section 3.1, "Using the Compiler", the programmer must specify which sections are allocated from which addresses in ROM or RAM. Since address allocation is specified for each section name, the programmer must be aware of the section names generated by the CC102L CC102L compiler. If a section's address is not specified, a section with the CODE attribute and a section with the DATA attribute may be allocated consecutively. Be sure to specify section addresses at link time that correspond to the structure of the system hardware. Division into Sections 33 Capter3 Using the Compiler · Transfer of initial value In the CC102L CC102L compiler, when a variable is initialized in its declaration, the compiler allocates separate areas for the variable itself and for the initial value. Static variable External variable Variable Area _DATA _GDATA Initial Value Area _ROMDATA _GROMDATA When variables are initialized in the startup routine the data in the _ROMDATA section must be copied to the _DATA section and the data in the _GROMDATA section must be copied to the _GDATA section. [ 5.1 Startup Routines ] · Sections for assembler routines When writing assembler routines at the same time as a C program, the section names must be specified directly. When using the section names generated by the CC102L CC102L compiler, be sure to specify the attributes for those sections in a form that matches. Errors may occur during linking if the attributes do not match. 34 Division into Sections Command Reference The CC102L CC102L system supports command line options to customize compiler processing to match the user's programming style. This chapter describes the function and usage of these options. 4 Chapter4 Command Reference 4.1 Starting the Compiler The CC102L CC102L compiler is started in the same way as other UNIX commands, namely, by entering a command name and the parameters. s General Command Syntax The following line shows the general syntax for invoking the CC102L CC102L compiler. cc102L [options] source files Square brackets ([]) indicate that the item(s) contained may be omitted. Note that multiple source files can be specified. s Option Syntax An option consists of the option specifier character ("-" minus sign) followed by a character string that expresses the option. Upper and lower case characters are differentiated and must be used precisely. When a given option is omitted, the CC102L CC102L system compiles the source file(s) according to default settings specified in advance. [ 4.2 Compiler Options, for details on the defaults for omitted options. ] Table 4-1-1 lists the CC102L CC102L options. Starting the Compiler 37 4 Chapter4 Command Reference Table:4-1-1 Compiler Options (1/2) Option Type Output file options Symbol o output file name L Description Specifies the output file name. Generates an assembly listing file. E Executes only the preprocessor and output the result to standard output. P Executes only the preprocessor and output the result to a file. S Executes only the compiler and output the result to a file. The assembler is not executed. c Executes only the compiler and the assembler and output the result to a file. The linker is not executed. v Displays the commands that the driver invokes and the version numbers. -@file Specifies an option file to be used during compiling. Compiler control options @file O Optimization options Os Ot Specifies an option file to be used during linking. Optimizes for both code size and execution time. Optimizes for the smallest possible code size. Optimizes for the shortest possible execution time. j Specifies Japanese with the default character set for diagnostic and help messages generated by the compiler. je Specifies Japanese with the EUC character set for diagnostic and help messages generated by the compiler. js Specifies Japanese with the Shift JIS character set for diagnostic and help messages generated by the compiler. jj Specifies Japanese with the JIS character set for diagnostic and help messages generated by the compiler. e Specifies English for diagnostic and help messages generated by the compiler. h Displays a help screen. w [message number] Suppresses the output of warning and informational options messages. w [message number] Suppresses the output of informative messages. funsigned-char Generates code that handles the char type as unsigned char. Diagnostic message options funsigned-bfield fenable-asm fwritable-string Interprets bit-fields as unsigned. Recognizes "asm" as a reserved word. Makes string literals writable. fwritable-const Assigns variables declared const to writable sections. fswitch-table-on-data Code generation control options Allocates the area for jump tables generated during switch statement optimization in the _DATA section. fno-switch-opt fpack-struct 38 Starting the Compiler Turns off switch statement optimization. Compresses structures. Chapter4 Command Reference Table:4-1-1 Compiler Options (2/2) Option Type Bit-field control option Symbol fchar-bfield flong-bfield fmsb-bfield Description Allows bits-fields of type char or short to be declared. Enables use of long bit-fields. Allocates bit-fields in MSB order. B directory A directory Searches for libraries specified with the -l option in the specified directory. t directory Specifies the directory in which to create temporary files. l library Links the specified library. g Includes source code debugging information in the compiler output. C Directory Searches for commands to be executed in the specified directory. Does not remove comments during preprocessor processing. specification options Debugging options Preprocessor options I directory D macro [=replacement string] U macro Specifies a search directory for include files. Define a macro. Deletes the definition of a system defined macro. Starting the Compiler 39 Chapter4 Command Reference 4.2 Compiler Options This section describes the functions of the CC102L CC102L compiler options in detail. 40 Compiler Options Chapter4 Command Reference 4.2.1 Output File Options o output file name Specifies the output file name. s Functional Description This option specifies the file name for the output file generated by the CC102L CC102L system. The CC102L CC102L system can generate either an executable file, an object file, an assembler source file, or a preprocessor output file. However, the -o option is invalid when there are multiple input files specified and one of the -P, -c or -S options is specified. s Syntax Enter a lower case "o" and the file name immediately after the option specifier character "". Spaces may not be inserted between the "o" and the file name. cc102L -S -otest.asm test1.c s Defaults A file with the default name is generated if the "o" option is not specified or if it is invalid. The file name generated by default differs depending on the format of the file the driver attempts to generate. -P option (when a preprocessor output file is generated) A file in which the extension of the input file is changed to ".i" is generated in the current directory. -S option (when an assembler source file is generated) A file in which the extension of the input file is changed to ".asm" is generated in the current directory. -c option (when an object file is generated) A file in which the extension of the input file is changed to ".rf" is generated in the current directory. No options (when an executable file is generated) A file with the name "m102L.ex" is generated in the current directory. Compiler Options 41 Chapter4 Command Reference L Generates an assembly listing file. s Functional Description The assembler generates an assembly listing file when executed. The name of the assembly listing file is the input file name with the extension changed to ".lst". This option is invalid when the -S option is specified. s Syntax Enter an upper case "L" immediately after the option specifier character "-". cc102L -c -L sample.c s Defaults An assembly listing file is not generated. If the option is invalid, only an assembler source file is generated. An assembler listing file is not generated. 42 Compiler Options Chapter4 Command Reference 4.2.2 Compiler Control Options Executes only the preprocessor and output the result to standard output. E s Functional Description Only the preprocessor is executed. The result is output to standard output and no file is generated. s Syntax Enter an upper case "E" immediately after the option specifier character "-". cc102L -E sample.c s Defaults The result of preprocessor processing is not output to standard output and compiler execution continues. P Executes only the preprocessor and output the result to a file. s Functional Description The driver executes only the preprocessor and generates a file. If the output file name is not specified, a file whose name is the input file name with the extension changed to ".i" is created in current directory. s Syntax Enter an upper case "P" immediately after the option specifier character "-". cc102L -P sample.c s Defaults The driver skips preprocessor file output and proceeds to the next translation phase, the compiler. Compiler Options 43 Chapter4 Command Reference Executes only the compiler and output the result to a file. The assembler is not executed. S s Functional Description The driver executes only the compiler and generates an assembler source file. If the output file name is not specified, a file whose name is the input file name with the extension changed to ".asm" is created in current directory. No processing is performed if the input file name extension is ".asm". s Syntax Enter an upper case "S" immediately after the option specifier character "-". cc102L -S sample.c s Defaults The driver skips assembly language file output and proceeds to the next translation phase, the assembler. Executes only the compiler and the assembler and output the result to a file. The linker is not executed. c s Functional Description The driver executes the compiler and the assembler and generates an object file. If the output file name is not specified, a file whose name is the input file name with the extension changed to ".rf" is created in current directory. s Syntax Enter a lower case "c" immediately after the option specifier character "-". cc102L -c sample.c s Defaults The driver skips object file output and proceeds to the next translation phase, the linker. 44 Compiler Options Chapter4 Command Reference v Displays command lines and version numbers. s Functional Description Displays, on standard output, the command line and version number information for each command that the driver invokes. Only the driver version number is displayed if no input file is specified. s Syntax Enter a lower case "v" immediately after the option specifier character "-". cc102L -S -v sample.c s Defaults The driver does not display the execution state. -@file Specifies an option file to be used during compiling. s Functional Description The driver reads additional options from the specified file. This option is for systems with upper limits on command lines. s Syntax Enter a hyphen and an at mark. Do not leave any spaces between the at mark and the file name. cc102L -@file sample.c s Defaults The driver uses only the options specified on the command line. Compiler Options 45 Chapter4 Command Reference @file Specifies an option file to be used during linking. s Functional Description Specifies an option file to be used when the driver invokes the linker. s Syntax Either the name of the option file after an at mark. Space may not be inserted between the at mark and the file name. cc102L @linkfile sample.rf s Defaults When no file name is specified, no option file is read when the linker is started. See the "MN10200 MN10200 Series Linear Addressing Version Cross-assembler User's Manual" for details on this option file. 4.2.3 Optimization Options O Optimizes for both code size and execution time. s Functional Description The compiler optimizes the code produced for both code size and execution speed. s Syntax Enter an upper case "O" immediately after the option specifier character "-". cc102L -S -O sample.c s Defaults Optimization is not performed. 46 Compiler Options Chapter4 Command Reference Os Optimizes for the smallest possible code size. s Functional Description The compiler optimizes the code produced for the smallest possible code size. s Syntax Enter an upper case "O" and a lower case "s" immediately after the option specifier character "-". Spaces may not be inserted between the "O" and the "s". cc102L -S -Os sample.c s Defaults Optimization is not performed. Ot Optimizes for the shortest possible execution time. s Functional Description The compiler optimizes the code produced for the shortest possible execution time. s Syntax Enter an upper case "O" and a lower case "t" immediately after the option specifier character "-". Spaces may not be inserted between the "O" and the "t". cc102L -S -Ot sample.c s Defaults Optimization is not performed. Compiler Options 47 Chapter4 Command Reference 4.2.4 Diagnostic Message Options j Specifies Japanese with the default character set for diagnostic messages. s Functional Description Specifies Japanese with the default character set for all error, warning, informative and help messages during compiler runs. The default character set depends on the host machine and its operating system. Host machine Character set SUN4 EUC HP9000 HP9000 Shift JIS NEC PC-9800 PC-9800 series Shift JIS DOS/V series Shift JIS PC/AT series Not supported. (Warning messages are suppressed because Japanese language support is not available.) s Syntax Enter a lower case j after the option specifier character ("-"). cc102L -S -j sample.c s Defaults The default language used depends on the host machine and its operation system. Host machine SUN4 English NEC PC-9800 PC-9800 series Japanese, Shift JIS DOS/V series Japanese, Shift JIS PC/AT series Compiler Options English HP9000 HP9000 48 Language English Chapter4 Command Reference je Specifies Japanese with the EUC character set for diagnostic messages. s Functional Description Specifies Japanese with the EUC character set for all error, warning, informative and help messages during compiler runs. s Syntax Enter a lower case je after the option specifier character ("-"). cc102L -S -je sample.c s Defaults The default language used depends on the host machine and its operation system. Host machine Language SUN4 English HP9000 HP9000 English NEC PC-9800 PC-9800 series Japanese, Shift JIS DOS/V series Japanese, Shift JIS PC/AT series English This option is ignored on NEC PC-9800 PC-9800, DOS/V, and PC/AT machines. Compiler Options 49 Chapter4 Command Reference js Specifies Japanese with the Shift JIS character set for diagnostic messages. s Functional Description Specifies Japanese with the Shift JIS character set for all error, warning, informative and help messages during compiler runs. s Syntax Enter a lower case js after the option specifier character ("-"). cc102L -S -js sample.c s Defaults The default language used depends on the host machine and its operation system. Host machine Language SUN4 English HP9000 HP9000 English NEC PC-9800 PC-9800 series Japanese, Shift JIS DOS/V series Japanese, Shift JIS PC/AT series English This option is ignored on PC/AT machines. 50 Compiler Options Chapter4 Command Reference jj Specifies Japanese with the JIS character set for diagnostic messages. s Functional Description Specifies Japanese with the JIS character set for all error, warning, informative and help messages during compiler runs. s Syntax Enter a lower case jj after the option specifier character ("-"). cc102L -S -jj sample.c s Defaults The default language used depends on the host machine and its operation system. Host machine Language SUN4 English HP9000 HP9000 English NEC PC-9800 PC-9800 series Japanese, Shift JIS DOS/V series Japanese, Shift JIS PC/AT series English This option is ignored on NEC PC-9800 PC-9800, DOS/V, and PC/AT machines. Compiler Options 51 Chapter4 Command Reference e Specifies English for diagnostic messages. s Functional Description Specifies English for all error, warning, informative and help messages during compiler runs. s Syntax Enter a lower case e after the option specifier character ("-"). cc102L -S -e sample.c s Defaults The default language used depends on the host machine and its operation system. Host machine SUN4 English NEC PC-9800 PC-9800 series Japanese, Shift JIS DOS/V series Japanese, Shift JIS PC/AT series Compiler Options English HP9000 HP9000 52 Language English Chapter4 Command Reference w[message number] Suppresses the output of warning and imformational messages. s Functional Description While the CC102L CC102L compiler issues error messages for situations where it cannot generate code, there are two other classes of messages provided. The first class consists of messages (warning messages) for situations that are syntax errors but for which error recovery is possible and code can be generated. The other class consists of messages (imformational messages) for situations that are not syntax errors but require attention. The warning message with the specified message number is not output. The message number can be omitted. This option can be specified multiple times. Note that if the "w" option is specified independently with the message number omitted, all warning and informational messages will be suppressed. s Syntax Enter a lower case "w" and the message number immediately after the option specifier character "-". The message number can be omitted. See chapter 6, "Diagnostic Messages", for details on message types and message numbers. cc102L -S -w sample.c s Defaults Both warning and informational messages are output. [ Chapter 6 "Diagnostic Messages" ] Compiler Options 53 Chapter4 Command Reference W[message number] Suppresses the output of imformational messages. s Functional Description While the CC102L CC102L compiler issues error messages for situations where it cannot generate code, there are two other classes of messages provided. The first class consists of messages (warning messages) for situations that are syntax errors but for which error recovery is possible and code can be generated. The other class consists of messages (imformational messages) for situations that are not syntax errors but require attention. The informational message with the specified message number is not output. The message number can be omitted. This option can be specified multiple times. Note that if the "W" option is specified independently with the message number omitted, all informational messages will be suppressed. s Syntax Enter an upper case "W" and the message number immediately after the option specifier character "-". The message number can be omitted. See chapter 6, "Diagnostic Messages", for details on message types and message numbers. cc102L -S -W sample.c s Defaults Informational messages are output. [ Chapter 6 54 Compiler Options "Diagnostic Messages ] Chapter4 Command Reference h Displays a help screen. s Functional Description Specifies a help screen summarizing driver options. The language and character set depends on such options as -j, -je, -js, -jj, and -e. s Syntax Enter a lower case h after the option specifier character ("-"). File name does not need to be specified. cc102L -h s Defaults The driver displays no help screen. Compiler Options 55 Chapter4 Command Reference 4.2.5 Code Generation Control Options funsigned-char Generates code that handles the char type as unsigned char. s Functional Description The compiler generates code that handles data coded as type char in the C source program as type unsigned char. s Syntax Enter a lower case "f" and the string "unsigned-char" in lower case immediately after the option specifier character "-". Spaces may not be inserted between the "f" and the "unsigned-char". cc102L -S -funsigned-char sample.c s Defaults The compiler generates code that handles data specified as type char in the C source program as type signed char. 56 Compiler Options Chapter4 Command Reference fpack-struct Compresses structures. s Functional Description Suppresses the extra byte added to a structure or union consisting entirely of members of type char and containing an odd number of bytes so that the structure or union starts at an odd offset within other structures and an odd address in memory. Here type char includes char, signed char, and unsigned char as well as arrays and bit-fields with these types. s Syntax Enter a lower case f plus the lower case string pack-struct after the option specifier character ("-"). Space may not be inserted between the "f" and the "pack-struct". cc102L -s -fpack-struct sample.c s Defaults Structures and unions normally have their sizes rounded upwards to an even number of bytes so that they start at an even offset within other structures and an even address in memory. If a structure or union contains any members not of type char (according to the expanded definition above), the fpack-struct option has no effect. The size is always adjusted to an even number of bytes. Compiler Options 57 Chapter4 Command Reference funsigned-bfield Interprets bit-fields as unsigned. s Functional Description In the absence of a specific signed or unsigned declaration, the compiler defaults to unsigned for bit-fields of type int, char, and short. (The last two are enabled with the -fcharbfield option.) s Syntax Enter a lower case "f" and the string "unsigned-bfield" in lower case immediately after the option specifier character "-". Spaces may not be inserted between the "f" and the "unsigned-bfield". cc102L -S -funsigned-bfield sample.c s Defaults The compiler defaults to signed for bit-fields. The compiler always defaults to signed for types int and short in other contexts. The default is also signed for type char unless overridden with the -funsigned-char option. 58 Compiler Options Chapter4 Command Reference fenable-asm Recognizes "asm" as a reserved word. s Functional Description The compiler handles "asm" as a reserved word thus enabling the use of inline assembling. s Syntax Enter a lower case "f" and the string "enable-asm" in lower case immediately after the option specifier character "-". Spaces may not be inserted between the "f" and the "enableasm". cc102L -S -fenable-asm sample.c s Defaults Since the compiler does not recognize "asm" as a reserved word, inline assembling cannot be used. However, "asm" can be used as an identifier for variable or function names. Compiler Options 59 Chapter4 Command Reference fwritable-string Makes string literals writable. s Functional Description The compiler makes string literals writable by assigning them to the _DATA section in RAM instead of the _CONST section in ROM. String literals cannot be assigned to the _GDATA or _GCONST sections. s Syntax Enter a lower case "f" and the string "writable-string" in lower case immediately after the option specifier character "-". Spaces may not be inserted between the "f" and the "writable-string". cc102L -S -fwritable-string sample.c s Defaults The compiler makes string literals read only by assigning them to the _CONST in ROM. String literals cannot be assigned to the _GDATA or _GCONST sections. Although the character string area will be allocated in RAM, the content of the character string will be stored in ROM. Therefore, these strings must be copied from ROM to RAM by the startup routine or some other initialization process. 60 Compiler Options Chapter4 Command Reference fwritable-const Assigns variables declared const to writable sections. s Functional Description The compiler makes variables declared const writable by assigning them to the _DATA or _GDATA sections in RAM. s Syntax Enter a lower case "f" and the string "writable-const" in lower case immediately after the option specifier character "-". Spaces may not be inserted between the "f" and the "writable-const". cc102L -S -fwritable-const sample.c s Defaults The compiler makes variables declared const read only by assigning them to the _CONST or _GCONST sections in ROM. Although the const data area will be allocated in RAM, the initial values will be stored in ROM. Therefore, this data must be copied from ROM to RAM by the startup routine or some other initialization process. Compiler Options 61 Chapter4 Command Reference fswitch-table-on-data Allocates the area for jump tables generated during switch statement optimization in the _DATA section. s Functional Description The CC102 CC102 compiler generates jump tables when optimizing switch statements. This option specifies that these jump tables be stored in the _DATA section. s Syntax Enter a lower case "f" and the string "switch-table-on-data" in lower case immediately after the option specifier character "-". Spaces may not be inserted between the "f" and the "switch-table-on-data". cc102L - S-fswitch-table-on-data sample.c s Defaults The jump tables generated by the CC102L CC102L compiler during switch statement optimization are allocated in the _CONST section. Although the jump table area will be allocated in RAM, the table data will be stored in ROM. Therefore, this data must be copied from ROM to RAM by the startup routine or some other initialization process. 62 Compiler Options Chapter4 Command Reference fno-switch-opt Turns off switch statement optimization. s Functional Description The CC102L CC102L compiler does not optimize switch statements even if optimization is specified. s Syntax Enter a lower case "f" and the string "no-switch-opt" in lower case immediately after the option specifier character "-". Spaces may not be inserted between the "f" and the "noswitch-opt". cc102L -S -fno-switch-opt sample.c s Defaults Switch statements will be optimized if optimization is specified. The CC102L CC102L compiler generates a jump table in the _CONST section when it optimizes a switch statement. Compiler Options 63 Chapter4 Command Reference 4.2.6 Bit-Field Control Options fchar-bfield Allows bit-fields of type char or short to be declared. s Functional Description The compiler allows the declaration of bit-fields of type char and short as well as signed and unsigned variants of same. Note) The default for bit-fields is signed unless overridden with the -funsigned-bfield option. Declaring a bit-field width greater than the storage size (8 bits for char and 16 bits for short) produces a compiler error. Both of these bit-field types are allocated in the order declared from the low-order bit to the high-order bit in a storage area of the declared size. A bit-field of type char is never allocated in the same storage area as a bit-field of type short or int. s Syntax Enter a lower case "f" and the string "char-bfield" in lower case immediately after the option specifier character "-". Spaces may not be inserted between the "f" and the "charbfield". cc102L -S -fchar-bfield sample.c s Defaults Declaring a bit-field of type char or short produces a compiler error. Since bit-fields of type short are handled identically to bit-fields of type int, they may be allocated within the same storage area as a bit-field of type int. 64 Compiler Options Chapter4 Command Reference flong-bfield Enables use of long bit-fields. s Functional Description The compiler allows the declaration of bit-fields of type long as well as signed and unsigned variants of same. Note) The default for bit-fields is signed unless overridden with the -funsigned-bfield option. Declaring a bit-field width greater than the storage size (32 bits) produces a compiler error. This bit-field type is allocated in the order declared from the low-order bit to the highorder bit in a storage area of the declared size. A bit-field of type long is never allocated in the same storage area as a bit-field of type char, short, or int. s Syntax Enter a lower case "f" and the string "long-bfield" in lower case immediately after the option specifier character "-". Spaces may not be inserted between the "f" and the "longbfield". cc102L -S -flong-bfield sample.c s Defaults Declaring a bit-field of type long produces a compiler error. Compiler Options 65 Chapter4 Command Reference fmsb-bfield Allocates bit-fields starting with the MSB. s Functional Description The bit-fields within a structure are assigned to the specified storage sizes in the order starting from the most significant bit in the structure. s Syntax Enter a lower case "f" and the string "msb-bfield" in lower case immediately after the option specifier character "-". Spaces may not be inserted between the "f" and the "msbbfield". cc102L -S -fmsb-bfield sample.c s Defaults Fields are assigned starting from the least significant bit in the structure. 66 Compiler Options Chapter4 Command Reference 4.2.7 Directory Specification Options B directory Searches for commands to be executed in the specified directory. s Functional Description The CC102L CC102L driver searches for the programs it executes in the specified directory. The driver searches directories for the programs that it invokes in the following order. (1) The directories specified with the -B option (2) The current directory (PC version only) (3) The directory containing the executed driver (4) The directories specified in the environment settings file (5) The directories specified in the environment variable path [ 2.1.3 Environment Setup ] s Syntax Enter an upper case "B" and the directory immediately after the option specifier character "-". Spaces may not be inserted between the "B" and the directory. cc102L -S -B/usr/new/bin sample.c s Defaults Search starts from item (2) listed above when this option is not specified. Compiler Options 67 Chapter4 Command Reference A directory Searches for libraries specified with the -l option in the specified directory. s Functional Description The linker searches for libraries specified with the -l option in the specified directory. The CC102L CC102L system searches for libraries in the following directories in the order listed. (1) The directory specified with the -A option (2) Directories specified in the environment settings file [ 2.1.3 Environment Setup ] s Syntax Enter an upper case "A" and the directory immediately after the option specifier character "-". Spaces may not be inserted between the "A" and the directory. cc102L- S-A/usr/new/li bsample.c s Defaults Search starts from item (2) listed above when this option is not specified. 68 Compiler Options Chapter4 Command Reference t directory Specifies the directory in which to create temporary files. s Functional Description The compiler creates temporary files in the specified directory. The directory in which the CC102L CC102L system creates temporary files can also be specified in the environment settings file. [ 2.1.3 Environment Setup ] s Syntax Enter a lower case "t" and the directory immediately after the option specifier character "". Spaces may not be inserted between the "t" and the directory. cc102L -S -t/tmp sample.c s Defaults Temporary files are created in the current directory if this option is not specified. Compiler Options 69 Chapter4 Command Reference l library Links the specified library. Functional Description The linker searches for and links the specified library. It searches in the directory specified by the -A option and the directories specified in the environment settings file. [ 2.1.3 Environment Setup ] s Syntax Enter a lower case "l" and the library immediately after the option specifier character "-". Spaces may not be inserted between the "l" and the library. cc102L -S -lcc102L.lib sample.c s Defaults The linker does not link a library if no library is specified. Always specify that a CC102L CC102L supplied standard library be linked. 70 Compiler Options Chapter4 Command Reference 4.2.8 Debugging Options Generates debugging information for the source code debugger. g s Functional Description The compiler generates debugging information (symbol information, line number information and information for resource allocation) to allow source code level debugging. Only disassembler based debugging is possible if the debugging information is not included in the executable file. s Syntax Enter a lower case "g" immediately after the option specifier character "-". cc102L -c -g sample.c s Defaults Debugging information is not generated. Compiler Options 71 Chapter4 Command Reference 4.2.9 Preprocessor Options Does not remove comments during preprocessor processing. C s Functional Description Comments are not removed from the result of preprocessor processing. The -E or -P option must be specified at the same time as this option. s Syntax Enter an upper case "C" immediately after the option specifier character "-". cc102L- P-C sample.c s Defaults Comments are removed by the preprocessor. This option is ignored if the -E or -P option is not specified at the same time. 72 Compiler Options Chapter4 Command Reference I directory Specifies a search directory for include files. s Functional Description The preprocessor searches for include files referenced in a C source file in the specified directory. This option is invalid for include files specified with an absolute path starting with a slash (/). Include file search directories can also be specified in the environment settings file. The CC102L CC102L compiler searches for include files in the following directories in the order listed. (1) The directory containing the source file in which the #include appeared. However, this directory is not searched for include files enclosed in angle brackets (). (2) The directory specified with the -I option (3) Directories specified in the environment settings file. [ 2.1.3 Environment Setup ] s Syntax Enter an upper case "I" and the directory immediately after the option specifier character "-". Spaces may not be inserted between the "I" and the directory. cc102L -S -I/usr/new/include sample.c s Defaults The CC102 CC102 compiler searches directories in items (1) and (3) when this option is not specified. Although this option can be specified multiple times, the number of times is limited. [ 7.1.1 Limits ] Compiler Options 73 Chapter4 Command Reference D macro [=replacement string] Defines a macro. s Functional Description The preprocessor defines a macro in the same manner as the #define directive used in a C source program. If a replacement string is specified the macro is defined as the specified replacement string. s Syntax Enter an upper case "D" and the macro name immediately after the option specifier character "-". If a replacement string is specified, use the following sequence: the option specifier character "-", an upper case "D", the macro name, an equal sign (=) and the replacement string. Spaces may not be inserted between any of these elements. cc102L -S -DDEBUG sample.c s Defaults No user macros are defined. Although this option can be specified multiple times, the number of times is limited. [ 2.1.3 Environment Setup ] Note that the CC102L CC102L system compiles source programs with the macros _ _MN102L MN102L_ _ and _ _CC102 CC102_ _ defined in advance as follows. -D_ _MN102L MN102L_ _=1 -D_ _CC102 CC102_ _=2 The compiler version number is assigned as the value of the _ _CC102 CC102_ _ macro. 74 Compiler Options Chapter4 Command Reference U macro Deletes the definition of a system defined macro. s Functional Description This option deletes the definition of the specified system defined macro. s Syntax Enter an upper case "U" and the macro name immediately after the option specifier character "-". Spaces may not be inserted between the "U" and the macro name. cc102L- S -U_ _MN102L MN102L_ _ sample.c s Defaults Source files are compiled with the system defined macros seen as valid. The _ _MN102L MN102L_ _ and _ _CC102 CC102_ _ macros are defined in advance in the CC102L CC102L system. Compiler Options 75 Microcomputer Programming There are several aspects of embedded microcomputer C programming that differ from workstation or personal computer programming and thus require special attention. Furthermore, the MN10200 MN10200 Series microcomputers support a unique programming technique called multiple code bank programming (or multi-bank programming). This chapter describes the items that require special care during program development. 5 Chapter5 Microcomputer Programming 5.1 Startup Routine In general, when power is applied or the reset state is cleared in an embedded microcomputer, the microcomputer either executes an instruction at a particular location, or jumps to an address specified by the contents of a particular location. Since the states of RAM and the microcomputer internal registers are usually undefined at this time, ordinary C programs will not execute correctly. In C, program execution normally starts from the function called "main". However, in embedded microcomputers, the hardware must be initialized by a startup routine before the function main is executed. This section describes the initialization processing (startup processing) required when developing embedded microcomputer programs in C. s Startup Routine Microcomputers in the MN10200 MN10200 Series execute the instruction stored at location 08000000 (0X080000 0X080000) when reset. Therefore a branch instruction to an actual startup routine must be coded at location 08000000. Example: _TEXT Specifies the _TEXT section. SECTION The startup routine is allocated starting at location 080000. Allocation specifications are handled by the linker. global Reset ;*-reset start address -* Reset: jmp Startup Codes a branch instruction to the startup routine at location 080000. The startup processing must handle the following items. · Register initialization · Control register setup · RAM initialization · Branch to the function main The remainder of this section describes the items handled by the startup routine in detail. Startup Routine 79 5 Chapter5 Microcomputer Programming (1) Register Initialization The MN10200 MN10200 Series CPU has several types of register for holding data. [ "MN10200 MN10200 Series Linear Addressing Version LSI User's Manual"] Of these registers, the registers that must be initialized include the stack pointer (A3). · Stack pointer The startup routine sets the stack pointer to the start of the stack area used by the CC102L CC102L system. Since the CC102L CC102L system uses the A3 register as the stack pointer, the startup routine must set the A3 register to the address that will be the start address of the stack area. Since the stack grows down in memory (from higher addresses to lower addresses) the start address will be the highest address in the stack area. (2) Control Register Setup The microcomputers in the MN10200 MN10200 Series have address-space mapped registers that are used for controlling the CPU and peripheral functions. [ "MN10200 MN10200 Series Linear Addressing Version LSI User's Manual" ] Since most of these control registers have initial values at reset that are defined in advance, initialization is not required as long as the application can use the default values. However, in some cases it will be necessary to reset these registers to values appropriate for the user's application. The following registers require special attention. · CPU mode control register This register controls the CPU operating state and the watchdog timer. Note that when the watchdog timer is used, the watchdog timer reset flag must be set to 0. · Memory control register This register is used for bus access control. Use extra care setting this register, since external devices may become inaccessible if the number of wait states is incorrect. To use peripheral functions such as the timers, serial communication interface and A/D converter, the initial values of the control registers must be set according to the functions used. Since the peripheral function control registers differ depending on the particular microcomputer used, refer to the LSI Description manual for the microcomputer being used. 80 Startup Routine Chapter5 Microcomputer Programming (3) RAM Initialization The state of RAM is undefined immediately following a reset in the MN10200 MN10200 Series. Embedded microcomputer programs written in assembler normally initialize RAM to 0 after a reset. The C programming language allows variables to be initialized at the same time they are declared. The CC102L CC102L compiler allocates a variable area in RAM and the initial values in ROM when external and static variables are initialized at the same time they are declared. Therefore, the initial value data in ROM must be copied to the variable area in memory to implement variable initialization. If this processing is neglected, the C program will not run as written. A variable area is allocated in RAM for noninitialized variables. We recommend initializing these areas to 0. [ 3.2 Division into Sections ] ROM Area RAM Area _TEXT section The contents of the _ROMDATA section are copied here. _DATA section _CONST section _BSS section The contents of the _GROMDATA section are copied here. _GCONST section _ROMDATA section _GDATA section _GROMDATA section _GBSS section We recommend initializing these sections to 0. Figure 5-1-1 Data Area Initialization (4) Branching to the Function main When the startup routine has completed the operations described in items (1) to (3) it branches to the function main. Note that the function main refers to the function executed first in a C program. The name of this function is not required to be "main" in the MN10200 MN10200 Series. The compiler converts function names in C to labels in the assembler code by attaching an underscore at the front of the name. Startup Routine 81 Chapter5 Microcomputer Programming Example: Startup routine global _main _TEXT SECTION global Reset ;*- reset start address -* Reset: jmp Startup nop ; ; Code the interrupt handler starting at location 080008. ; ; ;*- program initialize routine -* Startup: mov MCR_SET,d0 mov d0,(MCR) Initializes the memory control register. mov CPUM_NWDT,d0 mov d0,(CPUM) Initializes the CPU mode register. mov STACKTOP,a3 Initializes the stack pointer. ;*- set Interrupt Enable Flag -* mov IRQ_DISABLE,d0 mov d0,psw Initializes the interrupt enable flag. ;*- RAM clear -* ramclear: mov _DATA,a0 Clears the whole RAM area. mov RAMSIZE,d1 sub d0,d0 clear1: mov d0,(a0) add 0x2,a0 add -2,d1 bgt clear1 raminit: mov mov cmp ble Transfers an initial value to the data initialization area. _DATA,a1 ROMDATA area DATA area _GROMDATA-_ROMDATA,d1 0,d1 next1 mov mov add add add bne (a0),d0 d0,(a1) 0x2,a0 0x2,a1 -2,d1 init1 mov _ROMDATA,a0 init1: 82 Startup Routine Chapter5 Microcomputer Programming next1: mov mov cmp ble Transfers an initial value to the data initialization area. _GDATA,a1 GROMDATA area GDATA area _GODEEND-_GROMDATA,d1 0,d1 next2 mov mov add add add bne (a0),d0 d0,(a1) 0x2,a0 0x2,a1 -2,d1 init2 sub mov mov mov d0,d0 d0,a0 d0,a1 d0,a2 jsr mov mov nop nop nop bra nop nop _main CPUM_STOP1,d0 d0,(CPUM) mov _GROMDATA,a0 init2: next2: Initializes the address registers. _loop1: Calls the function main. _loop1 END Startup Routine 83 Chapter5 Microcomputer Programming 5.2 Interrupt Handling While the MN10200 MN10200 Series microcomputers support several internal and external interrupts, interrupt preprocessing and postprocessing is required to recognize which interrupt has occurred and to initiate the corresponding interrupt handling routine. This section describes the MN10200 MN10200 Series interrupt mechanism and the interrupt preprocessing and postprocessing. 5.2.1 Interrupt Mechanism When an interrupt occurs in a microcomputer, an interrupt handling routine that corresponds to that interrupt must be executed immediately. There are two techniques for starting the interrupt handling routine. These differ depending on the internal structure of the microcomputer. · Microcomputers that jump to the individual interrupt handling routine using an interrupt vector table · Microcomputers that start from a fixed location, read the number of the interrupt that occurred from a register and then jump to the interrupt handling routine in software. The MN10200 MN10200 Series microcomputers adopt the latter technique, i.e. jumping to the interrupt handling routine in software. The MN10200 MN10200 Series microcomputers divide interrupts into 32 groups and allow the user to assign priorities to those groups. Up to four interrupts can be assigned to each group. Therefore, the software must determine which interrupt group and which interrupt within the group has occurred. [ "MN10200 MN10200 Series Linear Addressing Version LSI User's Manual" ] The following operations are performed in conjunction with the operations described to the right. · The corresponding interrupt group number is loaded into a register (IAGR). · The corresponding interrupt request flag in the interrupt register is set. 84 Interrupt Handling The following is an overview of the hardware operations that are performed when an interrupt occurs. Interrupt Occurrence 1. Six bytes are allocated on the stack as an area to save the return address and the processor status word (PSW). 2. The return address and the PSW are saved. 3. The PSW contents are updated. The interrupt level setting and the interrupt enable flag (IEF) are cleared. 4. The program starting at location 080008 is executed. Chapter5 Microcomputer Programming 5.2.2 Interrupt Preprocessing and Postprocessing Interrupt preprocessing consists of determining which interrupt occurred in accordance with the MN10200 MN10200 Series microcomputer hardware operation and branching to the interrupt handling routine corresponding to that interrupt. Postprocessing consists of returning to the original program. During interrupt preprocessing, the registers are saved and a branch to the interrupt handling routine is executed. In interrupt postprocessing, the saved registers are restored and program control returns to the original program. Interrupt Preprocessing and Postprocessing Figure 5-2-1 shows the flow of control during interrupt preprocessing and postprocessing. Normal Program Interrupt Preprocessing and Postprocessing Location 080008 Registers saved Interrupt Interrupt group number acquisition Interrupt handling routine address acquisition Branch to the interrupt handling routine JSR instruction Interrupt handling routin RTS instruction Registers restored RTI instruction Figure 5-2-1 Control Flow During Interrupt Handling Interrupt Handling 85 Chapter5 Microcomputer Programming · Register saving In MN10200 MN10200 Series microcomputers, interrupt handling routines are implemented as single independent functions. Therefore, registers whose values are destroyed by the interrupt handling routine must be saved during interrupt preprocessing. When coding interrupt handling routines in C, the D0, D1, A0 and mdr registers must be saved during interrupt preprocessing. Since the compiler generates code that saves the D2, D3, A2 and A1 registers within the interrupt handling routine, these registers do not need to be saved during interrupt preprocessing. Interrupt handling routines coded in assembler must save all registers used within the interrupt handling routine itself. · Interrupt group number acquisition When an interrupt occurs in an MN10200 MN10200 Series microcomputer, the hardware sets the interrupt group number register (IAGR) to the group number of the interrupt that occurred. The group number will be an even number between 0 and 0x3E. The interrupt handler reads the group number from IAGR. ·