*========================================================================== * IBM(R) XL Fortran Advanced Edition V9.1 for Linux(R) 5724-K76 * (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 IBM XL Fortran Advanced Edition V9.1 for Linux that was not available in our online help and documentation. By using IBM XL Fortran Advanced Edition V9.1 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/xlf/9.1 with the following names: - LicenseAgreement.pdf - license.pdf You will need a Portable Document Format (PDF) viewer to view these files. Note: IBM XL Fotran Advanced Edition V9.1 for Linux is a server product that has two charge units: per authorized user and per concurrent user. These are available in fixed order quantities of one authorized user or one concurrent user. Authorized user: An authorized user is defined as an individual or specific-named user authorized to have access to the program or any portion of the program. An authorized user license is required for each distinct person who will access and use the program. You may install the program on more than one machine, provided that You are the only user using it and only one copy of the program is in use at one time. The Proof of Entitlement for this program is evidence of the authorization. Concurrent user: A concurrent user is defined as any person who accesses and uses the program or any portion of the program within a designated network. The program may be installed on an unlimited number of machines within the designated network. A concurrent user license entitles any user within the designated network to access and use the program as long as the total number of users concurrently accessing and using the program at any one time does not exceed the total number of concurrent user licenses acquired. You must acquire an additional license for each additional concurrent user and/or designated network on which the program is used. The Proof of Entitlement for the program is evidence of the authorization. This document contains the following sections: I. Viewing Documentation on Linux II. Installation Issues III. Late-breaking Updates IV. Known Limitations for IBM XL Fortran Advanced Edition V9.1 for Linux V. IBM XL Fortran Advanced Edition V9.1 for Linux and GDB VI. Documentation Additions and Corrections VII. SUSE Linux Enterprise Server Considerations VIII. Red Hat Enterprise Linux AS 4 Considerations IX. Y-HPC Considerations X. Support Information XI. Further Updates I. Viewing Documentation on Linux ================================= Documentation on installing and using IBM XL Fortran Advanced Edition V9.1 for Linux can be found in the .pdf and .htm files included as part of this package. To view the documentation remotely, you must have an X-server running on your local system. In addition, you need to have the appropriate viewers, such as a frames-capable HTML browser like Mozilla or a PDF viewer, such as gv or Xpdf installed on your system. II. Installation Issues ======================= Operating System Support ------------------------ IBM XL Fortran Advanced Edition V9.1 for Linux is supported on the following Linux distributions: - Red Hat Enterprise Linux AS 3 Update 3 (RHEL3) - Red Hat Enterprise Linux AS 4 (RHEL4) - SUSE LINUX Enterprise Server 9 (SLES9) - Terra Soft's Y-HPC v20050115 (Y-HPC) See the "IBM XL Fortran Advanced Edition V9.1 for Linux Installation Guide" for installation instructions. Uninstalling Evaluation or Beta Versions ----------------------------------------- Before installing the fully-licensed version of the product, you must uninstall any Beta or Evaluation version of the product you have on your system. If you have the Evaluation version, follow the uninstall intructions in the README that came with your Evaluation version. If you have the Y-HPC Beta, uninstall the Beta as follows: Beta Uninstallation Instructions -------------------------------- rpm -e xlf.samples-8.99.9999-0 rpm -e xlf.help-8.99.9999-0 rpm -e xlf.cmp-8.99.9999-0 rpm -e xlf.lib-8.99.9999-0 rpm -e xlf.rte.lnk-8.99.9999-0 rpm -e xlf.rte-8.99.9999-0 rpm -e xlf.msg.rte-8.99.9999-0 rpm -e xlmass.lib-3.99.9999-0 rpm -e xlsmp.lib-1.4.9999-0 rpm -e xlsmp.rte-1.4.9999-0 rpm -e xlsmp.msg.rte-1.4.9999-0 Upgrading the Operating System or GCC ------------------------------------- If you upgrade the operating system or the GCC compiler after installing XL Fortran, 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/xlf/9.1/xlf.cfg 2. Change the name of this file or move it to a different location. 3. Run the new_install or xlf_configure executable, as described in the "IBM XL Fortran Advanced Edition for Linux Installation Guide". This will create a new default configuration file. 4. If you have created any other configuration files, you must manually update these files to reflect any changes in the default configuration file. III. Late-breaking Updates ========================== Compiler Options ---------------- The following new compiler options were introduced in this update: -qsmallstack=dynlenonheap, -qipa=threads, -qfloat=hsflt, and -qfloat=hssngl. Please refer to the XL Fortran Advanced Edition V9.1 for Linux User's Guide for more information. -qinlglue --------- Syntax: -qinlglue | -qnoinlglue ----------- Specifying this compiler option inlines glue code that optimizes external function calls in your application, when compiling at -q64 and -O2 and higher. To aid performance, the optimizer automatically inlines glue code when you compile with -qtune=pwr4, pwr5, ppc970, or -qtune=auto when compiling on a machine with the appropriate processor. Use the -qnoinlglue option to prevent the compiler from automatically inlining glue code on these architectures. The inlining of glue code can increase the size of your code. Specifying -qcompact overrides -qinlglue to prevent code growth. Specifying -qnoinlglue or -qcompact can degrade performance; please use with discretion. -qoldmod Option --------------- Syntax: -qoldmod=compat This option specifies that object files containing module data compiled using earlier versions of XL Fortran for Linux either do not contain uninitialized module data or were ported using the convert_syms script provided below. The mangling scheme that XL Fortran uses for uninitialized module variables was changed with this Update. The old mangling scheme used the @ sign, which confused the Linux linker when creating shared libraries. The Linux linker reserves the @ sign for symbol versioning. As a result of this change, Fortran modules containing uninitialized module variables and any compilation units using these modules need to be recompiled with this Update or later. If recompilation is not feasible, you can port the object files created by older compilers using the following script: > cat convert_syms #!/bin/bash if [[ $# = 0 || "$1" = "-?" ]] then echo "Usage: $0 object-files" echo "e.g. $0 *.o *.a" exit fi for file in $* do XLFSYMS="" for i in `nm $file | grep -o "&&[NI]&@.*$" | sort -u` do XLFSYMS="$XLFSYMS --redefine-sym $i=`echo $i | sed -e 's/@/\&/'`" done if [[ -n "$XLFSYMS" ]]; then echo Converting symbols in $file... objcopy $XLFSYMS $file fi done Module symbol files (*.mod) do not need to be ported. Example: # If old_module.o and old_module.mod were produced using the original # release of XL Fortran Advanced Edition V9.1 for Linux, you'll get # the following error when you try to use them in new programs: # > xlf95 new_program.f old_module.o "new_program.f", line 1.5: 1517-022 (S) Module old_module was compiled using an incompatible version of the compiler. Please see the -qoldmod option for information on recovery. 1501-511 Compilation failed for file new_program.f. # Convert the object file. This needs to be done only once. # > ./convert_syms old_module.o > # You can now use the updated object file safely. # Specify -qoldmod=compat # > xlf95 new_program.f old_module.o -qoldmod=compat ** _main === End of Compilation 1 === 1501-510 Compilation successful for file new_program.f. > C_LONG_DOUBLE, and C_LONG_DOUBLE_COMPLEX Constants -------------------------------------------------- The value of the C_LONG_DOUBLE, and C_LONG_DOUBLE_COMPLEX constants as provided by the ISO_C_BINDING module have been changed to 16 from the previous value of 8. The C parts of new programs using these constants must be compiled with an option that enables 16-byte long doubles. Existing programs using C_LONG_DOUBLE or C_LONG_DOUBLE_COMPLEX will continue to work as long as the parts dependent on the value of these constants are not recompiled. If recompiling and a type interoperable with an 8-byte long double, or long double _Complex is expected, you can use the C_DOUBLE and C_DOUBLE_COMPLEX constants, respectively. Please note that the IBM XL Fortran Advanced Edition V9.1 for Linux extended-precision floating-point values are currently in a format that is not fully compatible with the format used by gcc 16-byte long doubles and long double _Complex. IV. Known Limitations for IBM XL Fortran Advanced Edition V9.1 for Linux ======================================================================== The following are known limitations for IBM XL Fortran Advanced Edition V9.1 for Linux running on any supported Linux distribution: -qflttrap=enable ---------------- The compiler option -qflttrap=enable does not need to be specified for trapping to occur. CPU_TIME -------- Due to a known limitation of threads on Linux, an application calling the CPU_TIME intrinsic procedure may give unexpected results when compiled using the -qsmp compiler option. Disassembling/Re-assembling Code with VMX Instructions ------------------------------------------------------ The disassembler on the BladeCenter JS20 server running SLES 9 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. Version and Linker Scripts -------------------------- When you specify the compiler options "-qipa", "-O4", "-O5", "-qpdf1 -O2", "-qpdf2 -O2", "-qpdf1 -O3", or "-qpdf2 -O3", version/linker scripts are not supported except linker scripts containing only the 'group' keyword. V. IBM XL Fortran Advanced Edition V9.1 for Linux and GDB ========================================================= Currently GDB offers debugging support for Fortran. However, GDB does not support all of the features found in IBM XL Fortran Advanced Edition V9.1 for Linux. VI. Documentation Additions and Corrections =========================================== Language Reference ------------------ The following corrections and additions apply to the IBM XL Fortran Advanced Edition V9.1 for Linux Language Reference: ROTATELM(RS, SHIFT, MASK) Hardware Intrinsic -------------------------------------------- The RS type description incorrectly states that integers must be less than 8 bytes. 8-byte integers are supported provided that the target architecture is a 64-bit capable Power PC. Specify -qarch=ppc64 as a minimum. SNAPSHOT Directive ------------------ The following is an added consideration for users of the SNAPSHOT directive: At high optimization levels, SNAPSHOT does not consistently preserve the contents of variables with a static storage class. SWDIV and SWDIV_NOCHK Intrinsic Procedures ------------------------------------------ Documentation on the hardware-specific intrinsic procedures SWDIV and SWDIV_NOCHK has been updated. Please refer to the IBM XL Fortran Advanced Edition V9.1 for Linux Language Reference for further information. User's Guide Errata ------------------- The following corrections and additions apply to the IBM XL Fortran Advanced Edition V9.1 for Linux User's Guide: startproc/stride XLSMPOPTS Options ---------------------------------- The description for the startproc and stride XLSMPOPTS environment variable options now read: startproc= Enables thread binding and specifies the CPU ID to which the first thread binds. If the value provided is outside the range of available processors, the SMP run time issues a warning message and no threads are bound. stride= Specifies the increment used to determine the CPU ID to which subsequent threads bind. must be greater than or equal to 1. If the value provided causes a thread to bind to a CPU outside the range of available processors, a warning message is issued and no threads are bound. VII. SUSE Linux Enterprise Server Considerations ================================================ Passing Complex Values and GCC 3.3 on SLES9 ------------------------------------------- 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 Fortran 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 the XL Fortran V9.1 Beta that is configured for GCC 3.3. VIII. Red Hat Enterprise Linux AS 4 Considerations ================================================== Naming Conflicts of 128-bit Long Double Floating Point Routines --------------------------------------------------------------- The libgcc of GCC 3.4 on RHEL4 exports routines _xlqadd(), _xlqsub(), _xlqmul(), and _xlqdiv() for 128-bit long double floating point operations. The same entry points exist in XL Fortran's libxl.a. However, the libgcc and libxl.a implementations of these routines differ. As a result, there may be differences in results and performance. If you use a command other than the XL Fortran compiler commands to link your application, for example 'ld', position libxl.a in front of libgcc on the command to link XL Fortran-generated object files to get the expected results. IX. Y-HPC Considerations ======================== GCC Binary Incompatibility -------------------------- There is a known binary incompatability between GCC 3.3.3 on SLES 9 and GCC 3.3.3-16 on Y-HPC when passing complex float/double arguments on the stack. XL Fortran passes arguments at the 8-byte boundary as does GCC 3.3.3 (SLES 9), whereas GCC 3.3.3-16 (Y-HPC)passes arguments at the 4-byte boundary. X. Support Information ====================== The following site contains support information for the IBM XL Fortran Advanced Edition V9.1 for Linux product: http://www.ibm.com/software/awdtools/fortran/xlfortran/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 XI. Further Updates =================== Additional information and documentation errata for the August 2005 XL Fortran Advanced Edition V9.1 for Linux Update and all future XL Fortran Advanced Edition V9.1 for Linux Updates can be found at the following url: http://www-1.ibm.com/support/docview.wss?uid=swg21206681