======================================================================== * IBM(R) XL C/C++ Advanced Edition V7.0 for Linux(R) 5724-K77 * (C) COPYRIGHT International Business Machines Corp. 1990, 2005 * All Rights Reserved * Licensed Materials - Property of IBM * * US Government Users Restricted Rights - Use, duplication or * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. * IBM, BladeCenter, iSeries, and pSeries are trademarks of IBM Corp. * * Linux is a trademark of Linus Torvalds in the United States, other * countries, or both. * * Other company, product, and service names may be trademarks or service * marks of others. ======================================================================== This README file contains the latest information about XL C/C++ Advanced Edition V7.0 for Linux that was not available for our online help and documentation. By using IBM XL C/C++ Advanced Edition V7.0 for Linux, you agree to the terms of the license as specified in the following files: * LicAgree.pdf * LicInfo.pdf These files are located in the root directory of the installation CD. After installation, they are located in the following directory: /opt/ibmcmp/vacpp/7.0/ with the following names: * LicenseAgreement.pdf * license.pdf You will need a PDF viewer to view these files. Note: IBM XL C/C++ Advanced Edition V7.0 for Linux is licensed based on a charge unit of one authorized user per operating system. Separate user authorizations are required by individual users for each operating system on which the Program is used. For each user authorization on a given operating system, the Program may be stored on more than one machine, provided that the Program is not in active use by that individual user on more than one machine at the same time. An authorized user is an individual or specific named user authorized to have access to the Program or any portion of the Program on a single operating system. The Proof of Entitlement for this Program is evidence of your authorization. Each individual or specific named user must obtain a Proof of Entitlement for each operating system on which the Program is used. This document contains the following sections: I. Viewing Documentation on Linux II. Installation Issues III. Important Update IV. February 2005 XL C/C++ Advanced Edition V7.0 for Linux Update V. Late-Breaking Updates (GA Version) VI. Known Limitations for IBM XL C/C++ Advanced Edition V7.0 for Linux VII. Operating System Considerations VIII. Documentation Corrections IX. Support Information I. Viewing Documentation on Linux ================================= Documentation on installing and using IBM XL C/C++ Advanced Edition V7.0 for Linux can be found in the .pdf and .htm files included as part of this package. To view the documentation, you must have X-server working on your system. In addition, you need to have the appropriate viewers, such as a frames-capable HTML browser, such as Mozilla, or a PDF viewer, such as gv or Xpdf. II. Installation Issues ======================= Operating System Support ------------------------ IBM XL C/C++ Advanced Edition V7.0 for Linux is supported on the following Linux distributions, running on IBM iSeries(TM), pSeries(TM), or BladeCenter(TM) computers: * Red Hat Enterprise Linux AS for POWER V3 (RHEL 3), Update 3 * SUSE LINUX Enterprise Server 9 for POWER (SLES 9) See the IBM XL C/C++ Advanced Edition V7.0 for Linux Installation Guide for installation instructions. Uninstalling Beta or Evaluation Versions ---------------------------------------- Before installing the fully-licensed version of XL C/C++ Advanced Edition V7.0 for Linux, you must uninstall the Beta or Evaluation version of the product you have on your system. Beta Uninstallation Instructions -------------------------------- rpm -e vacpp.cmp-6.0.9999-0 rpm -e vacpp.rte.lnk-6.0.9999-0 rpm -e vacpp.rte-6.0.9999-0 rpm -e vac.cmp-6.0.9999-0 rpm -e vac.lic-6.0.9999-0 rpm -e xlsmp.lib-1.3.9999-0 rpm -e xlsmp.rte-1.3.9999-0 rpm -e xlsmp.msg.rte-1.3.9999-0 rpm -e vacpp.samples-6.0.9999-0 rpm -e vacpp.help-6.0.9999-0 Evaluation Uninstallation Instructions -------------------------------------- rpm -e vacpp.cmp-7.0.0-0 rpm -e vacpp.lib-7.0.0-0 rpm -e vacpp.rte.lnk-7.0.0-0 rpm -e vacpp.rte-7.0.0-0 rpm -e vac.cmp-7.0.0-0 rpm -e vac.lib-7.0.0-0 rpm -e xlsmp.lib-1.5.0-0 rpm -e xlsmp.rte-1.5.0-0 rpm -e xlsmp.msg.rte-1.5.0-0 rpm -e vacpp.samples-7.0.0-0 rpm -e vacpp.help-7.0.0-0 Upgrading the Operating System or GCC ------------------------------------- If you upgrade the operating system or the GCC compiler after installing XL C/C++, you may need to update the default configuration file (and any configuration files you created) to reflect changes in file names and paths. After you upgrade the operating system or GCC, do the following: 1. Locate the default configuration file: /etc/opt/ibmcmp/vacpp/7.0/vac.cfg 2. Change the name of this file or move it to a different path. 3. Run the new_install or vac_configure executable, as described in the IBM XL C/C++ Advanced Edition V7.0 for Linux Installation Guide. This will create a new default configuration file. 4. If you created any other configuration files, manually update these files to reflect any changes in the default configuration file. III. Important Update ===================== 1. Red Hat Enterprise Linux AS 3 Update 4 Notice 2. Applications can fail when an exception is thrown in a shared object 1. Red Hat Enterprise Linux AS 3 Update 4 Notice --------------------------------------------- Installing the Red Hat Enterprise Linux AS 3 Update 4, can cause unexpected behavior in VisualAge C++ Version 7.0 for Linux. For an updated list of issues and solutions, see: http://www-1.ibm.com/support/docview.wss?rs=32&context=SSEP5D&dc= DB520&uid=swg21194555&loc=en_US&cs=utf-8&lang=en You can also use the following link: http://www.ibm.com/support/us/ and enter the following reference number into the search field: 1194555 2. Applications can fail when an exception is thrown in a shared object -------------------------------------------------------------------- An application linked with a shared object gives a segmentation fault error at runtime when an exception is thrown due to code inside the shared object. The segmentation fault occurs due to the Linux linker (ld), a component of the binutils package. When ld checks the encoding of the Language Specific Data Area (LSDA) in the eh_frame section while creating a shared library, ld incorrectly converts the encoding of the data in LSDA to a PC-relative encoding. Instructions on how to address this issue can be found at: http://www.ibm.com/support/docview.wss?rs=32&context=SSEP5D&dc= DB520&uid=swg21192592&loc=en_US&cs=utf-8&lang=en You can also use the following link: http://www.ibm.com/support/us/ and enter the following reference number into the search field: 1192592 IV. February 2005 XL C/C++ Advanced Edition V7.0 for Linux Update =================================================================== Compiler Options ---------------- -O0 Option ---------- You can specify the -O0 option as a synonym for -qnooptimize. Specifying -O0 disables almost all optimizations. #pragma ibm snapshot -------------------- The following is an added consideration for users of the snapshot pragma: At high optimization levels, snapshot does not consistently preserve the contents of variables with a static storage class. -qfloat=[no]complexgcc Option ----------------------------- This option enables compatibility with GCC call linkage conventions for the _Complex type. In 32-bit mode the default is -qfloat=complexgcc. If the compiler is configured for GCC 3.2 in 64-bit mode, the default is -qfloat=complexgcc. This ensures binary compatibility with objects built using GCC 3.2. If the compiler is configured for GCC 3.3 and above in 64-bit mode, the default is -qfloat=nocomplexgcc. Compiler Reference Errata ------------------------- xlCcore Invocation Command -------------------------- Please disregard the xlCcore compiler invocation command as the gcc C++ Runtime is currently used. Getting Started Errata ---------------------- mlong-double-64 and mlong-double-128 Options -------------------------------------------- Please disregard the option mapping for mlong-double-64 and mlong-double-128. Documentation Errata -------------------- Please note that all errata have been included in the February 2005 Update documentation. V. Late-Breaking Updates ======================== The following updates have been made available to the V7.0 release of the IBM XL C/C++ compiler: -qinlglue Option Defaults ------------------------- For performance enhancement on selected architectures, inlining of glue code is now automated through the selection of hardware tuning options. Specifying -qtune=pwr4, -qtune=pwr5, -qtune=ppc970, or -qtune=auto on a system that uses one of these architectures, along with -q64, will automatically enable the -qinlglue option. Note, however, that -qcompact overrides the -qinlglue setting regardless of other options specified, so if you want -qinlglue to be enabled, do not specify -qcompact. C++ Template Options -------------------- The default settings for the automatic template instantiation options are -qnotempinc and -qnotemplateregistry. To enable automatic template instantiation, you must specify -qtempinc or -qtemplateregistry. A new informational message is emitted if your compilation uses template implementation files but does not specify the -qtempinc option. VI. Known Limitations for IBM XL C/C++ Advanced Edition V7.0 for Linux ====================================================================== The following are known limitations for IBM XL C/C++ Advanced Edition V7.0 for Linux running on any supported Linux distribution: C99-Compliant Header File ------------------------- On systems that support C99, there are two complex.h header files. One is a C++ legacy complex.h header file, the other is a C99-style complex.h header file. If you compile with the -qlanglvl=c99complex or -qlanglvl=c99complexheader compiler option to use the C99-compliant header file, the compiler will issue an error. #pragma block_loop ------------------ Applying #pragma block_loop to a loop with dependencies, or a loop with alternate entry or exit points may produce unexpected results. The following are known limitations for IBM XL C/C++ Advanced Edition V7.0 for Linux running on SLES 9: Disassembling/Re-assembling Code with VMX Instructions ------------------------------------------------------ The disassembler on the BladeCenter JS20 server does not yet provide VMX support. Thus, the disassembler will not be able to decipher VMX instructions and will leave them hex-encoded. Any relocations associated with VMX instructions will also be lost, so passing a disassembled file containing VMX instructions through an assembler may not produce a working program. VII. Operating System Considerations ==================================== The following are considerations for IBM XL C/C++ Advanced Edition V7.0 for Linux running on any supported Linux distribution: Passing Structures with a Single Floating-Point Member in 64-Bit Mode --------------------------------------------------------------------- The parameter passing conventions in GCC and XL C/C++ are different under the following conditions: * The function is compiled for 64-bit mode * The parameter is a structure with a single floating-point member. For such parameters, GCC passes them in floating-pointer registers. XL C/C++, following the ABI convention, passes them in general purpose registers. SUSE LINUX Enterprise Server 9 (SLES 9) Considerations ------------------------------------------------------ The following are considerations for IBM XL C/C++ Advanced Edition V7.0 for Linux running on SUSE LINUX Enterprise Server 9 (SLES 9) only: Passing Complex Values and GCC 3.3 ---------------------------------- GCC 3.3 on SLES 9 has changed the conventions for passing or returning complex numbers in 64-bit mode. Object files that: * Are compiled for 64-bit mode; and * Pass complex type arguments or return values; and * Are compiled for 64-bit mode by GCC 3.2 or earlier, or by XL C/C++ that was configured for GCC 3.2 or earlier with the -Qfloat=complexgcc compiler option will need to be recompiled by GCC 3.3 or XL C/C++ V7.0 that is configured for GCC 3.3. VIII. Documentation Additions and Corrections ============================================= Getting Started Guide Errata ---------------------------- The following corrections apply to the IBM XL C/C++ Advanced Edition V7.0 for Linux Getting Started guide: New XL C/C++ Options -------------------- -qnotrigraph: The default setting of this option for all invocation commands is -qtrigraph. New Built-In Functions for Floating-Point Division -------------------------------------------------- For the __swdiv_nochk and __swdivs_nochck functions, argument restrictions also include: the numerator divided by the denominator equalling positive or negative infinity is also not allowed. GNU C and C++ to XL C/C++ Option Mapping ---------------------------------------- -qinline=limit=n is not a valid suboption in XL C/C++. The -finline-limit=n GCC suboption cannot be mapped to this suboption. gxlc and gxlc++ Syntax ---------------------- Multiple gcc or g++ options are delimited by the space character, not the comma character. Compiler Reference and Manual Pages Errata ------------------------------------------ The following corrections apply to the IBM XL C/C++ Advanced Edition V7.0 for Linux Compiler Reference and manual pages: -qarch Option ------------- Specifying -qarch=ppc or -qarch=ppcgr together with -q64 implies -qarch=ppc64grsq. -qdollar Option --------------- When -qdollar is in effect, the compiler treats occurrences of $ in an identifier in the same manner as a base character. If -qnodollar is in effect but -qlanglvl=ucs is on, occurrences of $ are treated as an extended character and translated into \u0024. -qinline Option --------------- The valid suboptions and syntax for this command are as follows: * -qnoinline (C and C++) * -qinline (C and C++) * -qinline=threshold (C only) * -qinline+func1:func2 (C only) * -qinline-func1:func2 (C only) -qinline=limit=n is not a valid suboption. -qstrict_induction Option ------------------------- The default setting of this option for optimization levels 2 and higher is -qnostrict_induction, and -qstrict_induction otherwise. It is not necessary to specify -qnostrict_induction with -O2, as this setting is implied. -qtrigraph Option ----------------- The default setting of this option for all invocation commands is -qtrigraph. The following additions and corrections apply to the IBM XL C/C++ Advanced Edition V7.0 for Linux Compiler Reference only: Summary of Command Line Compiler Options ---------------------------------------- The default setting for -qarch is ppc64grsq. -O Option --------- At -O2, -qnostrict_induction is implied by default. To turn off effects of -O2 that might change the semantics of a program, specify -qstrict_induction. #pragma stream_unroll --------------------- -O3 or -qipa=level=2 is not sufficient to enable stream unrolling; you must additionally specify -qhot or -qsmp, or use -O4 or higher. If a loop unrolling factor is not specified, and if -qhot, -qsmp, or -O4 or higher is specified, the optimizer determines an appropriate unrolling factor for each nested loop. If you combine block_loop and stream_unroll directives for the same for loop, no warning messages will be issued, but the compiler may choose to not apply stream_unroll optimization. Combining unroll, nounroll, unrollandfuse, or nounrollandfuse directives with stream_unroll will result in a warning message. Note that if the -qstrict option is in effect, no stream unrolling will take place. Therefore, if you want to enable stream unrolling with the -qhot option alone, you must also specify -qnostrict. #pragma unroll -------------- If a loop unrolling factor is not specified, and if -qhot, -qsmp, or -O4 or higher is specified, the optimizer determines an appropriate unrolling factor for each nested loop. #pragma unrollandfuse --------------------- If a loop unrolling factor is not specified, and if -qhot, -qsmp, or -O4 or higher is specified, the optimizer determines an appropriate unrolling factor for each nested loop. #pragma weak ------------ The first example should read as follows: // Begin Compilation Unit 1 #include extern int foo; #pragma weak foo int main() { int *ptr; ptr = &foo if (ptr == 0) printf("foo has been assigned a value of 0\n"); else printf("foo was already defined\n"); } //End Compilation Unit 1 // Begin Compilation Unit 2 int foo = 1; // End Compilation Unit 2 In the case where only Compilation Unit 1 is compiled to produce an executable, identifier foo will be defined and assigned a value of 0. The output from execution will be "foo has been assigned a value of 0". Built-In Functions ------------------ For the __swdiv_nochk and __swdivs_nochck functions, arguments for which the numerator divided by the denominator equals positive or negative infinity are also not permitted. Programming Guide Errata ------------------------ The following corrections apply to the IBM XL C/C++ Advanced Edition V7.0 for Linux Programming Guide: Using the Mathematical Acceleration Subsystem (MASS) ---------------------------------------------------- Vector Libraries: The correct header file to include for C++ programs, as for C programs, is massv.h. Compiling and Linking a Program with MASS: The default installation directory for the MASS libraries is opt/ibmcmp/xlmass/4.1/lib/ for the 32-bit vector library and opt/ibmcmp/xlmass/4.1/lib/lib64/ for the 64-bit vector library. Using Alignment Modes and Modifiers ----------------------------------- The __align specifier sets the alignment for a single aggregate, not for all members in an aggregate. For -qalign=power or -qalign=full settings, all members of an aggregate of the following data types are aligned on 8-byte boundaries: long long, long int and unsigned long int (64-bit mode), and pointer (64-bit mode). Rules for Bit-Packed Alignment ------------------------------ A non-bit field member that follows a bit field is aligned on the next byte boundary. Assigning Priorities to Objects ------------------------------- The #pragma priority directive is also supported on Mac OS X. Optimizing for System Architecture ---------------------------------- The default options of -qenablevmx erroneously include a setting for Red Hat 4. Red Hat 4 is not supported in this release of XL C/C++. Getting the Most Out of -qhot ----------------------------- The compiler assumes an optimization level of -O2 if you use -qhot. Using Shared Memory Parallelism ------------------------------- The default setting of -qsmp, or -qsmp=auto, causes the compiler to recognize OpenMP and all other SMP programming constructs. -qsmp=omp causes the compiler to recognize only constructs that conform strictly to the OpenMP standard API. Language Reference Errata ------------------------- The following corrections and additions apply to the IBM XL C/C++ Advanced Edition V7.0 for Linux Language Reference: The asm Declaration ------------------- There is a limit on the total number of instructions in one asm statement. Note that the compiler generates additional code to handle the operands in the operand list. The total number of instructions, including the compiler-generated ones, cannot exceed 63. IX. Support Information ======================= The following site contains support information for the IBM XL C/C++ Advanced Edition V7.0 for Linux product: http://www.ibm.com/software/awdtools/vacpp/support In addition, this support site includes information and guidelines on any Linux operating system considerations that can impact compiler behavior or performance. Check this site for a list of known considerations and solutions. For additional information on the MASS libraries, see the following site: http://www.ibm.com/software/awdtools/vacpp/mass