======================================================================== * IBM(R) XL C Enterprise Edition V7.0 for AIX(R) 5724-I10 * (C) COPYRIGHT International Business Machines Corp. 1990, 2004 * 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. * AIX, IBM, and i5/OS are trademarks of IBM Corp. * * Other company, product, and service names may be trademarks or service * marks of others. ======================================================================== This README file contains the latest information about XL C Enterprise Edition V7.0 for AIX that was not available for our online help and documentation. By using IBM XL C Enterprise Edition V7.0 for AIX, 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: /usr/vac/ with the following names: * LicenseAgreement.pdf * license.pdf You will need a PDF viewer to view these files. Note: IBM XL C Enterprise Edition V7.0 for AIX 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. Late-Breaking Updates II. Viewing Documentation on AIX III. Installation Issues IV. November 2004 XL C Enterprise Edition V7.0 for AIX Update V. Known Limitations for IBM XL C Enterprise Edition V7.0 for AIX VI. Documentation Corrections VII. Support Information I. Late-Breaking Updates ======================== The following updates have been made available to the V7.0 release of the IBM XL 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, will automatically enable the -qinlglue option. If you use the -qtune option with any of these suboptions and want to disable inlining of glue code, be sure to specify -qnoinlglue as well. 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. MASS Libraries -------------- The prototype for the dnint function is provided in the include file mass.h, located in the standard include directory. To call the dnint function, be sure to include mass.h in the calling program. The prototypes for the vcosisin and vscosisin functions have changed since the last version of the MASS libraries was published on the Web. For more information, see Programming Guide Errata later in this README. II. Viewing Documentation on AIX ================================ Documentation on installing and using IBM XL C Enterprise Edition V7.0 for AIX can be found in the .pdf files included as part of this package, and in the XHTML-based information center. To view the documentation, you must have X-Windows 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 Adobe Reader. To start the XHTML-based information center, first launch the Eclipse server by logging in with root authority and executing the following command: /usr/xlhelp/bin/xlhelp When the Eclipse server has started, you can view the information center from the server machine or any client. For more information, see the XL C Enterprise Edition V7.0 for AIX Installation Guide. III. Installation Issues ======================== Operating System Support ------------------------ IBM XL C Enterprise Edition V7.0 for AIX is supported on the following AIX operating systems: * AIX 5L V5.1, AIX 5L V5.2, or AIX 5L for POWER V5.3 See the IBM XL C Enterprise Edition V7.0 for AIX Installation Guide for installation instructions. Portable Application Solutions Environment (i5/OS(R) PASE) Support ------------------------------------------------------------------ IBM XL C Enterprise Edition V7.0 for AIX can be installed and operated in the i5/OS PASE V5R2 and V5R3 environment. Deinstalling Evaluation Version ------------------------------- Before installing the fully-licensed version of XL C Enterprise Edition V7.0 for AIX, you must deinstall any Evaluation version of the product you have on your system. To do so, at the command prompt, log in as root, and type the following command: installp -ug vac* xlsmp* memdbg* xlhelp* xlC.adt.include xlC.msg* Note that you should take caution when deinstalling common components (xlsmp*, xlhelp*, xlC.*, memdbg*), as this will also deinstall any fully-licensed version of the product you have installed. Additional MASS Filesets ------------------------ The MASS libraries and header files are packaged in three additional filesets: Fileset Name Fileset Description xlmass.lib IBM Mathematical Acceleration Subsystem Libraries xlmass.aix51.lib IBM Mathematical Acceleration Subsystem Libraries for AIX 5.1 xlmass.adt.include IBM Mathematical Acceleration Subsystem Include Files For instructions on installing compiler filesets, see the XL C Enterprise Edition V7.0 for AIX Installation Guide. Note: Do not overwrite the MASS files installed as part of the compiler with MASS files available on the Web. The XL C installation creates the symbolic links necessary to compile and link the MASS header files and libraries automatically. Location of MASS Components --------------------------- The default directories and symbolic links that are created for the MASS components are as follows: Component Default Location Symbolic Link libmass.a /usr/xlmass/lib/aix51/ /usr/lib/ libmassv.a /usr/xlmass/lib/aix51/ /usr/lib/ libmassvp3.a /usr/xlmass/lib/aix51/ /usr/lib/ libmassvp4.a /usr/xlmass/lib/aix51/ /usr/lib/ mass.h /usr/xlmass/include/ /usr/include/ massv.h /usr/xlmass/include/ /usr/include/ mass.include /usr/xlmass/include/ /usr/include/ massv.include /usr/xlmass/include/ /usr/include/ Note that both XL C Enterprise Edition V7.0 for AIX and XL Fortran Enterprise Edition V9.1 for AIX install the MASS components to the same directories, so if you are using both products, the MASS components will be located in a single common directory. License Use Management ---------------------- It is no longer necessary to enroll your product licenses with the AIX License Use Management (LUM) utility after you have installed XL C. You can begin to use XL C Enterprise Edition V7.0 for AIX immediately after installation and system configuration. Configuring the Compiler ------------------------ The XL C drivers are not automatically installed in /usr/bin/. To invoke the compiler without having to specify the full path, do one of the following: 1. Create symbolic links for the specific drivers from /usr/bin/ to /usr/vac/bin/. 2. Add /usr/vac/bin/ to your path environment variable. If you use a method other than the AIX installp command or the SMIT utility to install XL C (such as the non-default install script), the location of the drivers will be different from the default locations mentioned above. IV. November 2004 XL C Enterprise Edition V7.0 for AIX Update ============================================================== Important Update ---------------- In case you are installing the November 2004 C Enterprise Edition V7.0 for AIX PTF and download the November C++ Run-Time library, the following applies: On machines running AIX 5.1, AIX 5.2, or AIX 5.3 you must install the fix associated with the APAR appropriate to your operating system before installing the November 2004 XL C Enterprise Edition for AIX Update . The following prerequisites are related to new functionality in the November 2004 XL C/C++ Enterprise Edition for AIX and C++ Standard Locale Library Header File. AIX 5.1 - APAR IY58419 The following are the new levels for the updated AIX 5.1 filesets: bos.adt.include 5.1.0.61 bos.rte.libc 5.1.0.62 You can update these filesets by downloading APAR IY58419 at: http://www-1.ibm.com/support/docview.wss?uid=isg1IY58419 AIX 5.2 - APAR IY58421 The following are the new levels for the updated AIX 5.2 filesets: bos.adt.include 5.2.0.41 bos.mp64 5.2.0.42 bos.adt.prof 5.2.0.41 bos.rte 5.2.0.41 bos.adt.syscalls 5.2.0.41 bos.rte.libc 5.2.0.41 bos.mp 5.2.0.41 bos.up 5.2.0.41 You can update these filesets by downloading APAR IY58421 at: http://www-1.ibm.com/support/docview.wss?uid=isg1IY58421 AIX 5.3 - APAR IY58143 The following are the new levels for the updated AIX 5.3 filesets: bos.adt.include 5.3.0.1 bos.rte.libc 5.3.0.1 You can update these fileset by downloading APAR IY58143 at: http://www-1.ibm.com/support/docview.wss?uid=isg1IY58143 Please note that the installation of the November 2004 XL C Enterprise Edition for AIX Update fails if you do not have the bos.adt.include and bos.rte.libc files installed. installp Error Messages ----------------------- In the XL C Enterprise Edition V7.0 for AIX Update, further requisites were added to the OS-specifc levels of bos.rte.libc and bos.adt.include filesets. Here is a listing of error message that will be returned if the correct fileset levels are not installed on your system or if these filesets have not been installed at the time of the PTF release. AIX 5.1 At least 1 of the following: | * bos.rte.libc 5.1.0.62 | * bos.rte v=5, r>1 AIX 5.2 At least 1 of the following: | At least 1 of the following: | | * bos.rte v=5, r>2 | | * bos.rte v=5, r<2 | * bos.rte.libc 5.2.0.41 AIX 5.3 At least 1 of the following: | At least 1 of the following: | | * bos.rte v=5, r>3 | | * bos.rte v=5, r<3 | * bos.rte.libc 5.3.0.1 Compiler Reference Errata ------------------------- -qshowpdf option ----------------- Under the -qshowpdf option, the following text: When specified together with -qpdf1, the compiler will insert additional profiling information into the compiled application to collect call and block counts for all procedures in the application. Now reads: When specified with -qpdf1 and a minimum optimization level of -O, the compiler inserts additional profiling information into the compiled application to collect call and block counts for all procedures in the application. In the example, to compile the source, you must use the following command string: xlc -qpdf1 -O -qshowpdf hello.c -g option --------- Under the -g option, the following text: -g -O No inlining Now reads: -g -O Inline declared functions. Getting Started Guide Errata ---------------------------- What's new in version 7 ----------------------- Under the heading "New optimization utilities", the following text: The utility requires compilation under the options -qpdf1 and -qshowpdf. Now reads: The showpdf utility requires compilation with the options -qpdf1, -qshowpdf, and a minimum optimization level of -O. The following text: When specified with -qpdf1, the compiler inserts additional profiling information into the compiled application to collect call and block counts for all procedures in the application. Now reads: -qshowpdf: When specified with -qpdf1 and a minimum optimization level of -O, the compiler inserts additional profiling information into the compiled application to collect call and block counts for all procedures in the application. Getting started with optimization --------------------------------- Under the heading "Selected compiler options for optimization", the following text: -qpdf1: The compiler uses profile-directed feedback to optimize the application based on an analysis of how often different sections of code are typically executed. Now reads: -qpdf1: When specified with a minimum optimization level of -O, the compiler uses profile-directed feedback to optimize the application based on an analysis of how often different sections of code are typically executed. Optimizing your applications ---------------------------- Under the heading "Using profile-directed feedback", the following text: You first compile the program with the -qpdf1 option, which generates profile data by using the compiled program in the same ways that users will typically use it. Now reads: You first compile the program with the -qpdf1 option (with a minimum optimization level of -O), which generates profile data by using the compiled program in the same ways that users will typically use it. Please note: In all steps, when using -qpdf1, you must also specify a minimum optimization level of -O. V. Known Limitations for IBM XL C Enterprise Edition V7.0 for AIX ================================================================= The following are known limitations for IBM XL C Enterprise Edition V7.0 for AIX: #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. VI. Documentation Additions and Corrections =========================================== Installation Guide Errata ------------------------- The following additions and corrections apply to the IBM XL C Enterprise Edition V7.0 for AIX Installation guide: Viewing the HTML Documentation ------------------------------ To launch the Eclipse server, you must be logged in as a user with root privileges. For more information, see Viewing Documentation on AIX in this README. XL C Packaging and Filesets --------------------------- Separate filesets for the MASS components have been added to the installation package. See Installation Issues in this README. Locations of XLOPT and MASS Components -------------------------------------- The installation directories and symbolic links for MASS components have changed. See Installation Issues in this README. Getting Started Guide Errata ---------------------------- The following corrections apply to the IBM XL C Enterprise Edition V7.0 for AIX Getting Started guide: New XL C Options ---------------- -qweaksymbol: The default is -qnoweaksymbol on AIX 5.1 and -qweaksymbol on AIX 5.2 and higher. 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. Diagnostics for Link-Time Errors -------------------------------- It is not necessary to specify -qweaksymbol on AIX 5.2, as this setting is the default. Options Summary: C Compiler --------------------------- The -qrndflt option is now deprecated. Selected Compiler Options for Optimization ------------------------------------------ On the AIX platform, -O5 also turns on -qhot=vector. -qhot=simd is not a valid suboption, and AltiVec data types are not supported by the operating system. GNU C to XL C Option Mapping ----------------------------- -qinline=limit=n is not a valid suboption in XL C. The -finline-limit=n GCC suboption cannot be mapped to this suboption. Compiler Reference and Manual Pages Errata ------------------------------------------ The following corrections apply to the IBM XL C Enterprise Edition V7.0 for AIX Compiler Reference and manual pages: -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 * -qinline * -qinline=threshold * -qinline+func1:func2 * -qinline-func1:func2 -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. -qweaksymbol Option ------------------- The default setting of this option is -qnoweaksymbol on AIX 5.1 and -qweaksymbol on AIX 5.2 and higher. The following additions and corrections apply to the IBM XL C Enterprise Edition V7.0 for AIX Compiler Reference only: -qrndflt Option --------------- This option is now deprecated. -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. 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. Predefined Macros ----------------- The __powerpc64__, __PPC64__ and _PPC64_ macros are not supported on AIX. Programming Guide Errata ------------------------ The following corrections apply to the IBM XL C Enterprise Edition V7.0 for AIX Programming Guide: Using the Mathematical Acceleration Subsystem (MASS) ---------------------------------------------------- Scalar Libraries: The scalar function dnint accepts a pointer to a double-precision argument. To provide the prototype for dnint, you must include the file mass.h in the calling program. Vector Libraries: The default prototype for the vcosisin function is: void vcosisin (double _Complex y[], double x[], int *n); and for the vscosisin function: void vscosisin (float _Complex y[], float x[], int *n); If you compile with -D__nocomplex macro, this will define the functions as: void vcosisin (double y[][2], double *x, int *n); and void vscosisin (float y[][2], float *x, int *n); Compiling and Linking a Program with MASS: The default installation directory for the MASS libraries is /usr/xlmass/lib/aix51/. 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. Other Optimization Options -------------------------- The -qinlglue and -qtbtable options are supported in both 32-bit and 64-bit modes. Language Reference Errata ------------------------- The following corrections and additions apply to the IBM XL C Enterprise Edition V7.0 for AIX 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. VII. Support Information ======================== The following site contains support information for the IBM XL C Enterprise Edition V7.0 for AIX product: http://www.ibm.com/software/awdtools/vacpp/support For the latest documentation on XL C, as well as the IBM Distributed Debugger, see the AIX Compiler Information Center at: http://publib.boulder.ibm.com/infocenter/comphelp/index.jsp