release 2011 - nvidia · 2012. 10. 27. · while every precaution has been taken in the preparation...

The Portland Group

PGI® Visual Fortran Reference Manual Parallel Fortran for Scientists and Engineers

Release 2011

While every precaution has been taken in the preparation of this document, The Portland Group® (PGI®), a wholly-owned subsidiary of STMicroelectronics, Inc., makes nowarranty for the use of its products and assumes no responsibility for any errors that may appear, or for damages resulting from the use of the information contained herein.The Portland Group retains the right to make changes to this information at any time, without notice. The software described in this document is distributed under license fromSTMicroelectronics and/or The Portland Group and may be used or copied only in accordance with the terms of the end-user license agreement ("EULA").

PGI Workstation, PGI Server, PGI Accelerator, PGF95, PGF90, PGFORTRAN, and PGI Unified Binary are trademarks; and PGI, PGHPF, PGF77, PGCC, PGC++, PGI Visual Fortran,PVF, PGI CDK, Cluster Development Kit, PGPROF, PGDBG, and The Portland Group are registered trademarks of The Portland Group Incorporated. Other brands and names areproperty of their respective owners.

No part of this document may be reproduced or transmitted in any form or by any means, for any purpose other than the purchaser's or the end user's personal use without theexpress written permission of STMicroelectronics and/or The Portland Group.

PGI® Visual Fortran Reference ManualCopyright © 2010-2012 STMicroelectronics, Inc.

All rights reserved.

Printed in the United States of AmericaFirst printing: Release 2011, 11.0, December, 2010Second Printing: Release 2011, 11.1, January 2011

Third Printing: Release 2011, 11.3, March 2011Fourth Printing: Release 2011, 11.4, April 2011

Fifth Printing: Release 2011, 11.5, May 2011Sixth Printing: Release 2012, 12.1, January 2012Seventh Printing: Release 2012, 12.6, June 2012

Eighth Printing: Release 2012, 12.9, September 2012

ID: 122621238

Technical support: [email protected]: [email protected]

Web: www.pgroup.com

iii

ContentsPreface .................................................................................................................................... xvii

Audience Description ........................................................................................................... xviiCompatibility and Conformance to Standards ........................................................................... xviiOrganization ....................................................................................................................... xviiiHardware and Software Constraints ....................................................................................... xviiiConventions ......................................................................................................................... xixRelated Publications .............................................................................................................. xxi

1. Fortran Data Types ............................................................................................................ 1Fortran Data Types .................................................................................................................. 1

Fortran Scalars ............................................................................................................... 1FORTRAN 77 Aggregate Data Type Extensions ...................................................................... 3Fortran 90 Aggregate Data Types (Derived Types) ................................................................ 4

2. Command-Line Options Reference ................................................................................. 5PGI Compiler Option Summary ................................................................................................. 5

Build-Related PGI Options ................................................................................................ 6PGI Debug-Related Compiler Options ................................................................................ 8PGI Optimization-Related Compiler Options ........................................................................ 9PGI Linking and Runtime-Related Compiler Options ............................................................. 9

Generic PGI Compiler Options ................................................................................................ 10–M Options by Category ......................................................................................................... 49

Code Generation Controls ............................................................................................... 49Environment Controls .................................................................................................... 53Fortran Language Controls ............................................................................................. 54Inlining Controls ........................................................................................................... 58Optimization Controls .................................................................................................... 60Miscellaneous Controls .................................................................................................. 70

3. OpenMP Reference Information ................................................................................... 79Tasks ................................................................................................................................... 79

Task Characteristics and Activities .................................................................................... 79Task Scheduling Points .................................................................................................. 79

iv

Task Construct .............................................................................................................. 80Parallelization Directives ....................................................................................................... 82ATOMIC .............................................................................................................................. 82BARRIER .............................................................................................................................. 83CRITICAL ... END CRITICAL .................................................................................................... 83C$DOACROSS ...................................................................................................................... 84DO...END DO ...................................................................................................................... 85FLUSH ................................................................................................................................ 87MASTER ... END MASTER ....................................................................................................... 87ORDERED ........................................................................................................................... 88PARALLEL ... END PARALLEL .................................................................................................. 88PARALLEL DO ...................................................................................................................... 90PARALLEL SECTIONS ............................................................................................................. 91PARALLEL WORKSHARE ... END PARALLEL WORKSHARE ............................................................. 92SECTIONS … END SECTIONS ................................................................................................ 93SINGLE ... END SINGLE .......................................................................................................... 94TASK .................................................................................................................................... 95TASKWAIT ............................................................................................................................. 96THREADPRIVATE .................................................................................................................. 97WORKSHARE ... END WORKSHARE ........................................................................................... 98Directive Clauses ................................................................................................................... 98

COLLAPSE (n) .............................................................................................................. 99COPYIN (list) ............................................................................................................... 99COPYPRIVATE(list) ........................................................................................................ 99DEFAULT .................................................................................................................... 100FIRSTPRIVATE(list) ...................................................................................................... 100IF() ........................................................................................................................... 100LASTPRIVATE(list) ........................................................................................................ 100NOWAIT ..................................................................................................................... 100NUM_THREADS ........................................................................................................... 100ORDERED .................................................................................................................. 101PRIVATE ..................................................................................................................... 101REDUCTION ................................................................................................................ 101SCHEDULE .................................................................................................................. 102SHARED ..................................................................................................................... 103UNTIED ...................................................................................................................... 103

OpenMP Environment Variables ............................................................................................. 103OMP_DYNAMIC ........................................................................................................... 103OMP_NESTED ............................................................................................................. 103OMP_MAX_ACTIVE_LEVELS .......................................................................................... 103OMP_NUM_THREADS ................................................................................................. 103OMP_SCHEDULE ......................................................................................................... 104OMP_STACKSIZE ......................................................................................................... 104OMP_THREAD_LIMIT .................................................................................................. 104OMP_WAIT_POLICY ..................................................................................................... 104

PGI® Visual Fortran Reference Manual

v

4. PGI Accelerator Compilers Reference ...................................................................... 107PGI Accelerator Directives .................................................................................................... 107

Accelerator Compute Region Directive ............................................................................ 108Accelerator Data Region Directive .................................................................................. 109Accelerator Loop Mapping Directive ............................................................................... 110Combined Directive ..................................................................................................... 111Accelerator Declarative Data Directive ............................................................................ 111Accelerator Update Directive ......................................................................................... 112

PGI Accelerator Directive Clauses .......................................................................................... 113if (condition) ............................................................................................................. 113Data Clauses ............................................................................................................... 113copy (list) ................................................................................................................. 114copyin (list) ............................................................................................................. 115copyout (list) ............................................................................................................ 115local (list) ................................................................................................................ 115mirror (list) ............................................................................................................. 115updatein|updateout (list) ............................................................................................. 116Loop Scheduling Clauses .............................................................................................. 116cache (list) ................................................................................................................ 117host [(width)] .......................................................................................................... 118independent ................................................................................................................ 118kernel ........................................................................................................................ 118parallel [(width)] ..................................................................................................... 118private (list) .............................................................................................................. 118seq [(width)] ........................................................................................................... 119unroll [(width)] ....................................................................................................... 119vector [(width)] ....................................................................................................... 119Declarative Data Directive Clauses ................................................................................. 120reflected (list) ........................................................................................................... 120Update Directive Clauses .............................................................................................. 120device (list) ............................................................................................................... 120host (list) .................................................................................................................. 121

PGI Accelerator Runtime Routines ......................................................................................... 121acc_allocs .................................................................................................................. 121acc_bytesalloc ............................................................................................................ 121acc_bytesin ................................................................................................................ 122acc_bytesout ............................................................................................................... 122acc_copyins ................................................................................................................ 122acc_copyouts .............................................................................................................. 123acc_disable_time ........................................................................................................ 123acc_enable_time ......................................................................................................... 123acc_exec_time ............................................................................................................ 124acc_frees ................................................................................................................... 124acc_get_device ........................................................................................................... 124acc_get_device_num ................................................................................................... 125

vi

acc_get_free_memory ................................................................................................. 125acc_get_memory ......................................................................................................... 126acc_get_num_devices .................................................................................................. 126acc_init ..................................................................................................................... 126acc_kernels ................................................................................................................ 127acc_on_device ............................................................................................................ 127acc_regions ................................................................................................................ 128acc_set_device ............................................................................................................ 128acc_set_device_num ................................................................................................... 129acc_shutdown ............................................................................................................. 129acc_total_time ............................................................................................................ 130

Accelerator Environment Variables ......................................................................................... 130ACC_DEVICE ............................................................................................................... 130ACC_DEVICE_NUM ...................................................................................................... 131ACC_NOTIFY ............................................................................................................... 131

pgcudainit Utility ................................................................................................................. 131

5. Directives Reference ...................................................................................................... 133PGI Proprietary Fortran Directive Summary ............................................................................. 133

altcode (noaltcode) .................................................................................................... 134assoc (noassoc) .......................................................................................................... 135bounds (nobounds) ................................................................................................... 135cncall (nocncall) ........................................................................................................ 135concur (noconcur) .................................................................................................... 135depchk (nodepchk) .................................................................................................... 135eqvchk (noeqvchk) .................................................................................................... 135invarif (noinvarif) ....................................................................................................... 136ivdep ......................................................................................................................... 136lstval (nolstval) ........................................................................................................... 136prefetch ..................................................................................................................... 136opt ............................................................................................................................ 136safe_lastval ................................................................................................................. 136tp .............................................................................................................................. 138unroll (nounroll) ........................................................................................................ 138vector (novector) ........................................................................................................ 139vintr (novintr) ............................................................................................................ 139

Prefetch Directives ............................................................................................................. 139!DEC$ Directives ................................................................................................................. 139

ALIAS Directive ........................................................................................................... 140ATTRIBUTES Directive .................................................................................................. 141DECORATE Directive .................................................................................................... 142DISTRIBUTE Directive .................................................................................................. 142IGNORE_TKR Directive ................................................................................................. 143

6. Run-time Environment .................................................................................................. 145Win32 Programming Model .................................................................................................. 145


vii

Function Calling Sequence ............................................................................................ 145Function Return Values ................................................................................................ 148Argument Passing ........................................................................................................ 149

Win64 Programming Model .................................................................................................. 152Function Calling Sequence ............................................................................................ 152Function Return Values ................................................................................................ 154Argument Passing ........................................................................................................ 155Win64 Fortran Supplement ........................................................................................... 157

7. PVF Properties ................................................................................................................ 163Property Page Summary ....................................................................................................... 164General Property Page ......................................................................................................... 179

Output Directory ......................................................................................................... 179Intermediate Directory ................................................................................................. 179Extensions to Delete on Clean ....................................................................................... 180Configuration Type ....................................................................................................... 180Build Log File ............................................................................................................. 180Build Log Level ........................................................................................................... 180

Debugging Property Page ..................................................................................................... 180Application Command .................................................................................................. 180Application Arguments ................................................................................................. 181Environment ............................................................................................................... 181Merge Environment ..................................................................................................... 181MPI Debugging ........................................................................................................... 181Working Directory ....................................................................................................... 182Number of Processes ................................................................................................... 182Working Directory ....................................................................................................... 182Additional Arguments: mpiexec ..................................................................................... 182Location of mpiexec .................................................................................................... 182Number of Cores ......................................................................................................... 182Working Directory ....................................................................................................... 182Standard Input ........................................................................................................... 183Standard Output ......................................................................................................... 183Standard Error .......................................................................................................... 183Additional Arguments: job submit .................................................................................. 183Additional Arguments: mpiexec ..................................................................................... 184Location of job.exe ...................................................................................................... 184

Fortran Property Pages ......................................................................................................... 184Fortran | General ................................................................................................................ 184

Display Startup Banner ................................................................................................. 184Additional Include Directories ....................................................................................... 184Module Path ............................................................................................................... 185Object File Name ......................................................................................................... 185Debug Information Format ........................................................................................... 186Optimization ............................................................................................................... 186

Fortran | Optimization .......................................................................................................... 186

viii

Optimization ............................................................................................................... 186Global Optimizations .................................................................................................... 187Vectorization ............................................................................................................... 187Inlining ...................................................................................................................... 187Use Frame Pointer ....................................................................................................... 187Loop Unroll Count ....................................................................................................... 188Auto-Parallelization ...................................................................................................... 188

Fortran | Preprocessing ........................................................................................................ 188Preprocess Source File ................................................................................................. 188Additional Include Directories ....................................................................................... 188Ignore Standard Include Path ....................................................................................... 189Preprocessor Definitions .............................................................................................. 189Undefine Preprocessor Definitions ................................................................................. 189

Fortran | Code Generation .................................................................................................... 189Runtime Library .......................................................................................................... 190

Fortran | Language .............................................................................................................. 190Fortran Dialect ............................................................................................................ 190Treat Backslash as Character ........................................................................................ 190Extend Line Length ...................................................................................................... 191Enable OpenMP Directives ............................................................................................ 191MPI ........................................................................................................................... 191Enable CUDA Fortran ................................................................................................... 191CUDA Fortran Register Limit ......................................................................................... 192CUDA Fortran Use Fused Multiply-Adds ........................................................................... 192CUDA Fortran Use Fast Math Library .............................................................................. 192CUDA Fortran Flush to Zero .......................................................................................... 192CUDA Fortran Toolkit ................................................................................................... 192CUDA Fortran Compute Capability .................................................................................. 193CUDA Fortran CC 1.0 ................................................................................................... 194CUDA Fortran CC 1.1 ................................................................................................... 194CUDA Fortran CC 1.2 ................................................................................................... 194CUDA Fortran CC 1.3 ................................................................................................... 194CUDA Fortran CC 2.0 ................................................................................................... 194CUDA Fortran CC 3.0 ................................................................................................... 194CUDA Fortran Keep Binary ............................................................................................ 195CUDA Fortran Keep Kernel Source ................................................................................. 195CUDA Fortran Keep PTX ............................................................................................... 195CUDA Fortran Keep PTXAS ............................................................................................ 195CUDA Fortran Emulation .............................................................................................. 195

Fortran | Floating Point Options ............................................................................................ 195Floating Point Exception Handling ................................................................................. 195Floating Point Consistency ............................................................................................ 196Flush Denormalized Results to Zero ............................................................................... 196Treat Denormalized Values as Zero ................................................................................ 196IEEE Arithmetic ........................................................................................................... 196

Fortran | External Procedures ............................................................................................... 196


ix

Calling Convention ....................................................................................................... 196String Length Arguments ............................................................................................... 197Case of External Names ................................................................................................ 197

Fortran | Libraries ............................................................................................................... 197Use ACML ................................................................................................................... 198Use IMSL .................................................................................................................... 198Use MKL .................................................................................................................... 198

Fortran | Target Processors .................................................................................................. 198AMD Athlon ................................................................................................................ 198AMD Barcelona ........................................................................................................... 199AMD Bulldozer ........................................................................................................... 199AMD Istanbul .............................................................................................................. 199AMD Shanghai ............................................................................................................ 199Intel Core 2 ................................................................................................................ 199Intel Core i7 ............................................................................................................... 199Intel Penryn ................................................................................................................ 199Intel Pentium 4 ........................................................................................................... 200Intel Sandy Bridge ...................................................................................................... 200Generic x86 [Win32 only] ............................................................................................ 200Generic x86-64 [x64 only] ........................................................................................... 200

Fortran | Target Accelerators ................................................................................................. 200Target NVIDIA Accelerator ............................................................................................ 200NVIDIA: Register Limit ................................................................................................. 201NVIDIA: Use Fused Multiply-Adds ................................................................................... 201NVIDIA: Use Fast Math Library ...................................................................................... 201NVIDIA: Flush to Zero .................................................................................................. 201NVIDIA: Use 24-bit Subscript Multiplication .................................................................... 202NVIDIA: Synchronous Kernel Launch .............................................................................. 202NVIDIA: CUDA Toolkit .................................................................................................. 202NVIDIA: Compute Capability .......................................................................................... 203NVIDIA: CC 1.0 ........................................................................................................... 203NVIDIA: CC 1.1 ........................................................................................................... 203NVIDIA: CC 1.2 ........................................................................................................... 204NVIDIA: CC 1.3 ........................................................................................................... 204NVIDIA: CC 2.0 ........................................................................................................... 204NVIDIA: CC 3.0 ........................................................................................................... 204NVIDIA: Keep Kernel Binary .......................................................................................... 204NVIDIA: Keep Kernel Source ......................................................................................... 204NVIDIA: Keep Kernel PTX ............................................................................................. 204NVIDIA: Enable Profiling .............................................................................................. 204NVIDIA: Analysis Only .................................................................................................. 205Target Host ................................................................................................................. 205

Fortran | Diagnostics ........................................................................................................... 205Warning Level ............................................................................................................. 205Generate Assembly ....................................................................................................... 205Annotate Assembly ....................................................................................................... 205

x

Accelerator Information ............................................................................................... 205CCFF Information ........................................................................................................ 206Fortran Language Information ....................................................................................... 206Inlining Information .................................................................................................... 206IPA Information .......................................................................................................... 206Loop Intensity Information ............................................................................................ 206Loop Optimization Information ...................................................................................... 206LRE Information .......................................................................................................... 206OpenMP Information ................................................................................................... 206Optimization Information .............................................................................................. 206Parallelization Information ............................................................................................ 207Unified Binary Information ........................................................................................... 207Vectorization Information ............................................................................................. 207

Fortran | Profiling ............................................................................................................... 207Function-Level Profiling ................................................................................................ 207Line-Level Profiling ...................................................................................................... 207MPI ........................................................................................................................... 207Suppress CCFF Information ........................................................................................... 208Enable Limited DWARF ................................................................................................. 208

Fortran | Runtime ................................................................................................................ 208Check Array Bounds .................................................................................................... 208Check Pointers ............................................................................................................ 208Check Stack ................................................................................................................ 208Command Line ............................................................................................................ 208

Fortran | Command Line ...................................................................................................... 209Command Line ............................................................................................................ 209

Linker Property Pages .......................................................................................................... 209Linker | General .................................................................................................................. 209

Output File ................................................................................................................. 209Additional Library Directories ....................................................................................... 209Stack Reserve Size ....................................................................................................... 210Stack Commit Size ....................................................................................................... 210Export Symbols ........................................................................................................... 210

Linker | Input ..................................................................................................................... 210Additional Dependencies .............................................................................................. 210

Linker | Command Line ........................................................................................................ 211Command Line ............................................................................................................ 211

Librarian Property Pages ...................................................................................................... 211Librarian | General .............................................................................................................. 211

Output File ................................................................................................................. 211Additional Library Directories ....................................................................................... 212Additional Dependencies .............................................................................................. 212

Librarian | Command Line .................................................................................................... 212Command Line ............................................................................................................ 213

Resources Property Page ...................................................................................................... 213Resources | Command Line .................................................................................................. 213


xi

Command Line ............................................................................................................ 213Build Events Property Page ................................................................................................... 213

Build Event ................................................................................................................. 213Command Line ............................................................................................................ 214Description ................................................................................................................. 214Excluded From Build ................................................................................................... 214

Custom Build Step Property Page ........................................................................................... 214Custom Build Step | General ................................................................................................. 214

Command Line ............................................................................................................ 214Description ................................................................................................................. 214Outputs ...................................................................................................................... 214Additional Dependencies .............................................................................................. 215

8. PVF Build Macros ........................................................................................................... 217

9. Fortran Module/Library Interfaces for Windows ..................................................... 221Source Files ........................................................................................................................ 221Data Types .......................................................................................................................... 221Using DFLIB, LIBM, and DFPORT .......................................................................................... 222

DFLIB ........................................................................................................................ 222LIBM ......................................................................................................................... 223DFPORT ..................................................................................................................... 224

Using the DFWIN module ..................................................................................................... 230Supported Libraries and Modules .......................................................................................... 230

advapi32 .................................................................................................................... 230comdlg32 ................................................................................................................... 232dfwbase ..................................................................................................................... 233dfwinty ....................................................................................................................... 233gdi32 ......................................................................................................................... 233kernel32 .................................................................................................................... 236shell32 ....................................................................................................................... 244user32 ....................................................................................................................... 245winver ....................................................................................................................... 249wsock32 .................................................................................................................... 250

10. Messages ........................................................................................................................ 251Diagnostic Messages ............................................................................................................ 251Phase Invocation Messages ................................................................................................... 252Fortran Compiler Error Messages .......................................................................................... 252

Message Format .......................................................................................................... 252Message List ............................................................................................................... 252

Fortran Run-time Error Messages .......................................................................................... 278Message Format .......................................................................................................... 278Message List ............................................................................................................... 278

Index ...................................................................................................................................... 281

xiii

Tables1. PGI Compilers and Commands .................................................................................................... xx1.1. Representation of Fortran Data Types .......................................................................................... 11.2. Real Data Type Ranges .............................................................................................................. 21.3. Scalar Type Alignment ............................................................................................................... 22.1. PGI Build-Related Compiler Options ............................................................................................ 62.2. PGI Debug-Related Compiler Options .......................................................................................... 82.3. Optimization-Related PGI Compiler Options .................................................................................. 92.4. Linking and Runtime-Related PGI Compiler Options ...................................................................... 92.5. Subgroups for –help Option .................................................................................................... 192.6. –M Options Summary ............................................................................................................. 252.7. Optimization and –O, –g, –Mvect, and –Mconcur Options ............................................................ 333.1. Initialization of REDUCTION Variables ...................................................................................... 1025.1. IGNORE_TKR Example ......................................................................................................... 1446.1. Register Allocation ................................................................................................................ 1466.2. Standard Stack Frame ............................................................................................................ 1466.3. Stack Contents for Functions Returning struct/union .................................................................. 1496.4. Integral and Pointer Arguments .............................................................................................. 1496.5. Floating-point Arguments ....................................................................................................... 1496.6. Structure and Union Arguments .............................................................................................. 1506.7. Register Allocation ................................................................................................................ 1526.8. Standard Stack Frame ............................................................................................................ 1536.9. Register Allocation for Example A-4 ........................................................................................ 1566.10. Win64 Fortran Fundamental Types ......................................................................................... 1576.11. Fortran and C/C++ Data Type Compatibility ............................................................................ 1596.12. Fortran and C/C++ Representation of the COMPLEX Type ......................................................... 1607.1. PVF Property Page Summary ................................................................................................... 1648.1. PVF Build Macros ................................................................................................................. 2179.1. Fortran Data Type Mappings ................................................................................................... 2219.2. DFLIB Function Summary ....................................................................................................... 2229.3. LIBM Functions .................................................................................................................... 2239.4. DFPORT Functions ................................................................................................................ 2249.5. DFWIN advapi32 Functions ..................................................................................................... 230

xv

Examples3.1. OpenMP Task Fortran Example ................................................................................................. 816.1. C Program Calling an Assembly-language Routine ...................................................................... 1516.2. Parameter Passing ................................................................................................................ 1556.3. C Program Calling an Assembly-language Routine ...................................................................... 157

xvii

PrefaceThis guide is part of a set of manuals that describe how to use The Portland Group (PGI) Fortran compilersand program development tools integrated with Microsoft Visual Studio. These tools, combined with VisualStudio and assorted libraries, are collectively known as PGI Visual Fortran®, or PVF®. You can use PVF to edit,compile, debug, optimize, and profile serial and parallel applications for x86 processor-based systems.

The PGI Visual Fortran Reference Manual is the reference companion to the PGI Visual Fortran User’sGuide which provides operating instructions for both the Visual Studio integrated development environment aswell as command-level compilation and general information about PGI’s compilers. Neither guide teaches theFortran programming language.

Audience DescriptionThis manual is intended for scientists and engineers using PGI Visual Fortran. To fully understand this guide,you should be aware of the role of high-level languages, such as Fortran, in the software development process;and you should have some level of understanding of programming. PGI Visual Fortran is available on a varietyof x86 or x64 hardware platforms and variants of the Windows operating system. You need to be familiar withthe basic commands available on your system.

Compatibility and Conformance to StandardsYour system needs to be running a properly installed and configured version of PVF. For information oninstalling PVF, refer to the Release Notes and Installation Guide included with your software.

For further information, refer to the following:

• American National Standard Programming Language FORTRAN, ANSI X3. -1978 (1978).

• ISO/IEC 1539-1 : 1991, Information technology – Programming Languages – Fortran, Geneva, 1991(Fortran 90).

• ISO/IEC 1539-1 : 1997, Information technology – Programming Languages – Fortran, Geneva, 1997(Fortran 95).

• Fortran 95 Handbook Complete ISO/ANSI Reference, Adams et al, The MIT Press, Cambridge, Mass, 1997.

• OpenMP Application Program Interface, Version 2.5, May 2005, http://www.openmp.org.

Organization

xviii

• Programming in VAX Fortran, Version 4.0, Digital Equipment Corporation (September, 1984).

• IBM VS Fortran, IBM Corporation, Rev. GC26-4119.

• Military Standard, Fortran, DOD Supplement to American National Standard Programming LanguageFortran, ANSI x.3-1978, MIL-STD-1753 (November 9, 1978).

OrganizationUsers typically begin by wanting to know how to use a product and often then find that they need moreinformation and facts about specific areas of the product. Knowing how as well as why you might use certainoptions or perform certain tasks is key to using the PGI compilers and tools effectively and efficiently. However,once you have this knowledge and understanding, you very likely might find yourself wanting to know muchmore about specific areas or specific topics.

To facilitate ease of use, this manual contains detailed reference information about specific aspects of thecompiler, such as the details of compiler options, directives, and more. This guide contains these chapters:

Chapter 1, “Fortran Data Types” describes the data types that are supported by the PGI Fortran compilers.

Chapter 2, “Command-Line Options Reference” provides a detailed description of each command-lineoption.

Chapter 3, “OpenMP Reference Information” contains detailed descriptions of each of the OpenMP directivesthat PGI supports.

Chapter 4, “PGI Accelerator Compilers Reference ”contains detailed descriptions of each of the PGIAccelerator directives, runtime routines, and environment variables that PGI supports.

Chapter 5, “Directives Reference” contains detailed descriptions of PGI’s proprietary directives.

Chapter 6, “Run-time Environment” describes the programming model supported for compiler codegeneration, including register conventions and calling conventions for x86 and x64 processor-based systemsrunning a Windows operating system.

Chapter 7, “PVF Properties” provides a description of Property Pages that PGI supports.

Chapter 8, “PVF Build Macros” provides a description of the build macros that PVF supports.

Chapter 9, “Fortran Module/Library Interfaces for Windows” provides a description of the Fortran modulelibrary interfaces that PVF supports.

Chapter 10, “Messages” provides a list of compiler error messages.

Hardware and Software ConstraintsThis guide describes versions of PGI Visual Fortran that are intended for use on x86 and x64 processor-based systems. Details concerning environment-specific values and defaults and system-specific features orlimitations are presented in the release notes delivered with PGI Visual Fortran.

Preface

xix

ConventionsThe PGI Visual Fortran Reference Manual uses the following conventions:

italic

Italic font is for emphasis.

Constant Width

Constant width font is for commands, filenames, directories, examples and for language statements in thetext, including assembly language statements.

[ item1 ]Square brackets indicate optional items. In this case item1 is optional.

{ item2 | item 3}Braces indicate that a selection is required. In this case, you must select either item2 or item3.

filename...Ellipsis indicate a repetition. Zero or more of the preceding item may occur. In this example, multiplefilenames are allowed.

FORTRAN

Fortran language statements are shown in the text of this guide using upper-case characters and a reducedpoint size.

The PGI compilers and tools are supported on both 32-bit and 64-bit variants of Windows operating systemson a variety of x86-compatible processors. There are a wide variety of releases and distributions of each ofthese types of operating systems. Further, the PGI Visual Fortran Reference Manual uses a number of termswith respect to these platforms.

For a complete definition of these terms and other terms in this guide with which you may be unfamiliar, PGIprovides a glossary of terms which you can access at www.pgroup.com/support/definitions.htm.

AMD64 Large arrays SSE Win32

barcelona -mcmodel=small SSE1 Win64

DLL -mcmodel=medium SSE2 Windows

driver MPI SSE3 x64

dynamic library MPICH SSE4A and ABM x86

EM64T multi-core SSSE3 x87

hyperthreading (HT) NUMA static linking

IA32 shared library

Conventions

xx

The following table lists the PGI compilers and tools and their corresponding commands:

Table 1. PGI Compilers and Commands

Compiler or Tool Language or Function CommandPGF77 FORTRAN 77 pgf77

PGF95 Fortran 90/95/2003 pgf95

PGFORTRAN PGI Fortran pgfortran

PGPROF Performance profiler pgprof

Note

The commands pgf95 and pgfortran are equivalent.

In general, the designation PGI Fortran is used to refer to The Portland Group’s Fortran 90/95/2003 compiler,and pgfortran is used to refer to the command that invokes the compiler. A similar convention is used for eachof the PGI compilers and tools.

For simplicity, examples of command-line invocation of the compilers generally reference the pgfortrancommand, and most source code examples are written in Fortran. Usage of the PGF77 compiler, whosefeatures are a subset of PGF95 or PGFORTRAN, is similar.

There are a wide variety of x86-compatible processors in use. All are supported by the PGI compilers andtools. Most of these processors are forward-compatible, but not backward-compatible, meaning that codecompiled to target a given processor will not necessarily execute correctly on a previous-generation processor.

A table listing the processor options that PGI supports is available in the Release Notes. The table also includesthe features utilized by the PGI compilers that distinguish them from a compatibility standpoint.

In this manual, the convention is to use "x86" to specify the group of processors that are "32-bit" but not "64-bit." The convention is to use "x64" to specify the group of processors that are both "32-bit" and "64-bit." x86processor-based systems can run only 32-bit operating systems. x64 processor-based systems can run either32-bit or 64-bit operating systems, and can execute all 32-bit x86 binaries in either case. x64 processorshave additional registers and 64-bit addressing capabilities that are utilized by the PGI compilers and toolswhen running on a 64-bit operating system. The prefetch, SSE1, SSE2 and SSE3 processor features furtherdistinguish the various processors. Where such distinctions are important with respect to a given compileroption or feature, it is explicitly noted in this manual.

Note

The default for performing scalar floating-point arithmetic is to use SSE instructions on targets thatsupport SSE1 and SSE2.

Preface

xxi

Related PublicationsThe following documents contain additional information related to the x86 and x64 architectures, and thecompilers and tools available from The Portland Group.

• PGI Fortran Reference manual describes the FORTRAN 77, Fortran 90/95, Fortran 2003, and HPFstatements, data types, input/output format specifiers, and additional reference material related to use of thePGI Fortran compilers.

• System V Application Binary Interface Processor Supplement by AT&T UNIX System Laboratories, Inc.(Prentice Hall, Inc.).

• System V Application Binary Interface X86-64 Architecture Processor Supplement, www.x86-64.org/abi.pdf.

• Fortran 95 Handbook Complete ISO/ANSI Reference, Adams et al, The MIT Press, Cambridge, Mass, 1997.

• Programming in VAX Fortran, Version 4.0, Digital Equipment Corporation (September, 1984).

• IBM VS Fortran, IBM Corporation, Rev. GC26-4119.

• OpenMP Application Program Interface, Version 2.5 May 2005 (OpenMP Architecture Review Board,1997-2005).

1

Chapter 1. Fortran Data TypesThis chapter describes the scalar and aggregate data types recognized by the PGI Fortran compilers, the formatand alignment of each type in memory, and the range of values each type can have on x86 or x64 processor-based systems running a 32-bit operating system. For more information on x86-specific data representation,refer to the System V Application Binary Interface, Processor Supplement, listed in “Related Publications,” onpage xxi. This chapter specifically does not address x64 processor-based systems running a 64-bit operatingsystem, because the application binary interface (ABI) for those systems is still evolving. For the latest versionof the ABI, refer to www.x86-64.org/abi.pdf.

Fortran Data TypesFortran Scalars

A scalar data type holds a single value, such as the integer value 42 or the real value 112.6. The next tablelists scalar data types, their size, format and range. Table 1.2, “Real Data Type Ranges,” on page 2 showsthe range and approximate precision for Fortran real data types. Table 1.3, “Scalar Type Alignment,” on page2 shows the alignment for different scalar data types. The alignments apply to all scalars, whether they areindependent or contained in an array, a structure or a union.

Table 1.1. Representation of Fortran Data Types

Fortran Data Type Format RangeINTEGER 2's complement integer -231 to 231-1

INTEGER*2 2's complement integer -32768 to 32767

INTEGER*4 2's complement integer -231 to 231-1

INTEGER*8 2's complement integer -263 to 263-1

LOGICAL 32-bit value true or false

LOGICAL*1 8-bit value true or false




Fortran Data Types

2

Fortran Data Type Format RangeBYTE 2's complement -128 to 127

REAL Single-precision floating point 10-37 to 1038(1)

REAL*4 Single-precision floating point 10-37 to 10 38(1)

REAL*8 Double-precision floating point 10-307 to 10 308(1)

DOUBLE PRECISION Double-precision floating point 10-307 to 10308 (1)

COMPLEX Single-precision floating point 10-37 to 1038 (1)

DOUBLE COMPLEX Double-precision floating point 10-307 to 10308 (1)

COMPLEX*16 Double-precision floating point 10-307 to 10308(1)

CHARACTER*n Sequence of n bytes

(1) Approximate value

The logical constants .TRUE. and .FALSE. are all ones and all zeroes, respectively. Internally, the value of alogical variable is true if the least significant bit is one and false otherwise. When the option –Munixlogicalis set, a logical variable with a non-zero value is true and with a zero value is false.

NoteA variable of logical type may appear in an arithmetic context, and the logical type is then treated as aninteger of the same size.

Table 1.2. Real Data Type Ranges

Data Type Binary Range Decimal Range Digits of PrecisionREAL -2-126 to 2128 10-37 to 1038 (1) 7-8

REAL*8 -2-1022 to 21024 10-307 to 10308 (1) 15-16

Table 1.3. Scalar Type Alignment

This Type... ...Is aligned on this size boundaryLOGICAL*1 1-byte

LOGICAL*2 2-byte

LOGICAL*4 4-byte

LOGICAL*8 8-byte

BYTE 1-byte

INTEGER*2 2-byte

INTEGER*4 4-byte

INTEGER*8 8-byte

REAL*4 4-byte

REAL*8 8-byte

Chapter 1. Fortran Data Types

3

This Type... ...Is aligned on this size boundaryCOMPLEX*8 4-byte

COMPLEX*16 8-byte

FORTRAN 77 Aggregate Data Type ExtensionsThe PGF77 compiler supports de facto standard extensions to FORTRAN 77 that allow for aggregate datatypes. An aggregate data type consists of one or more scalar data type objects. You can declare the followingaggregate data types:

• An array consists of one or more elements of a single data type placed in contiguous locations from first tolast.

• A structure can contain different data types. The members are allocated in the order they appear in thedefinition but may not occupy contiguous locations.

• A union is a single location that can contain any of a specified set of scalar or aggregate data types. A unioncan have only one value at a time. The data type of the union member to which data is assigned determinesthe data type of the union after that assignment.

The alignment of an array, a structure or union (an aggregate) affects how much space the object occupies andhow efficiently the processor can address members. Arrays use the alignment of their members.

Array typesalign according to the alignment of the array elements. For example, an array of INTEGER*2 data aligns ona 2byte boundary.

Structures and Unionsalign according to the alignment of the most restricted data type of the structure or union. In the nextexample, the union aligns on a 4byte boundary since the alignment of c, the most restrictive element, isfour.

STRUCTURE /astr/UNION MAP INTEGER*2 a ! 2 bytes END MAP MAP BYTE b ! 1 byte END MAP MAP INTEGER*4 c ! 4 bytes END MAPEND UNIONEND STRUCTURE

Structure alignment can result in unused space called padding. Padding between members of the structure iscalled internal padding. Padding between the last member and the end of the space is called tail padding.

The offset of a structure member from the beginning of the structure is a multiple of the member’s alignment.For example, since an INTEGER*2 aligns on a 2-byte boundary, the offset of an INTEGER*2 member from thebeginning of a structure is a multiple of two bytes.

Fortran Data Types

4

Fortran 90 Aggregate Data Types (Derived Types)The Fortran 90 standard added formal support for aggregate data types. The TYPE statement begins a derivedtype data specification or declares variables of a specified user-defined type. For example, the following woulddefine a derived type ATTENDEE:

TYPE ATTENDEE CHARACTER(LEN=30) NAME CHARACTER(LEN=30) ORGANIZATION CHARACTER (LEN=30) EMAILEND TYPE ATTENDEE

In order to declare a variable of type ATTENDEE and access the contents of such a variable, code such as thefollowing would be used:

TYPE (ATTENDEE) ATTLIST(100). . .ATTLIST(1)%NAME = ‘JOHN DOE’

5

Chapter 2. Command-Line OptionsReference

A command-line option allows you to specify specific behavior when a program is compiled and linked.Compiler options perform a variety of functions, such as setting compiler characteristics, describing theobject code to be produced, controlling the diagnostic messages emitted, and performing some preprocessorfunctions. Most options that are not explicitly set take the default settings. This reference chapter describes thesyntax and operation of each compiler option. For easy reference, the options are arranged in alphabeticalorder.

For an overview and tips on which options are best for which tasks, refer to Chapter 6, “Using Command LineOptions” in the PGI Compiler User’s Guide, which also provides summary tables of the different options.

This chapter uses the following notation:

[item]Square brackets indicate that the enclosed item is optional.

{item | item}Braces indicate that you must select one and only one of the enclosed items. A vertical bar (|) separatesthe choices.

...Horizontal ellipses indicate that zero or more instances of the preceding item are valid.

PGI Compiler Option SummaryThe following tables include all the PGI compiler options that are not language-specific. The options areseparated by category for easier reference.

For a complete description of each option, see the detailed information later in this chapter.

PGI Compiler Option Summary

6

Build-Related PGI OptionsThe options included in the following table are the ones you use when you are initially building your programor application.

Table 2.1. PGI Build-Related Compiler Options

Option Description–# Display invocation information.

–### Shows but does not execute the driver commands (same as theoption –dryrun).

–Bdynamic Compiles for and links to the DLL version of the PGI runtimelibraries.

–Bstatic_pgi Compiles for and links to the static version of the PGI runtimelibraries.

–c Stops after the assembly phase and saves the object code infilename.o.

–D Defines a preprocessor macro.

–dryrun Shows but does not execute driver commands.

–drystdinc Displays the standard include directories and then exists thecompiler.

–E Stops after the preprocessing phase and displays the preprocessedfile on the standard output.

–F Stops after the preprocessing phase and saves the preprocessedfile in filename.f (this option is only valid for the PGI Fortrancompilers).

--flagcheck Simply return zero status if flags are correct.

–flags Display valid driver options.

–I Adds a directory to the search path for #include files.

–i2, –i4 and –i8 –i2: Treat INTEGER variables as 2 bytes.

–i4: Treat INTEGER variables as 4 bytes.

–i8: Treat INTEGER and LOGICAL variables as 8 bytes and use 64-bits for INTEGER*8 operations.

–K Requests special compilation semantics with regard to conformanceto IEEE 754.

--keeplnk If the compiler generates a temporary indirect file for a long linkercommand, preserves the temporary file instead of deleting it.

–L Specifies a library directory.

Chapter 2. Command-Line Options Reference

7

Option Description–l Loads a library.

–m Displays a link map on the standard output.

–M Selects variations for code generation and optimization.

–module Save/search for module files in directory .

–mp[=all, align,bind,[no]numa] Interpret and process user-inserted shared-memory parallelprogramming directives (see Chapters 5 and 6).

–noswitcherror Ignore unknown command line switches after printing an warningmessage.

–o Names the object file.

–pc (–tp px/p5/p6/piii targets only) Set precision globally for x87floating-point calculations; must be used when compiling the mainprogram. may be one of 32, 64 or 80.

–pgf77libs Append PGF77 runtime libraries to the link line.

–pgf90libs Append PGF90/PGF95/PGFORTRAN runtime libraries to the link line.

–r4 and –r8 –r4: Interpret DOUBLE PRECISION variables as REAL.

–r8: Interpret REAL variables as DOUBLE PRECISION.

–rc file Specifies the name of the driver's startup file.

–S Stops after the compiling phase and saves the assembly–languagecode in filename.s.

–show Display driver's configuration parameters after startup.

–silent Do not print warning messages.

–time Print execution times for the various compilation steps.

–u Initializes the symbol table with , which is undefined forthe linker. An undefined symbol triggers loading of the first memberof an archive library.

–U Undefine a preprocessor macro.

–V[release_number] Displays the version messages and other information, or allowsinvocation of a version of the compiler other than the default.

–v Displays the compiler, assembler, and linker phase invocations.

–W Passes arguments to a specific phase.

–w Do not print warning messages.

PGI Compiler Option Summary

8

PGI Debug-Related Compiler Options

The options included in the following table are the ones you typically use when you are debugging yourprogram or application.

Table 2.2. PGI Debug-Related Compiler Options

Option Description–C (Fortran only) Generates code to check array bounds.

–c Instrument the generated executable to perform array boundschecking at runtime.

–E Stops after the preprocessing phase and displays the preprocessedfile on the standard output.

--flagcheck Simply return zero status if flags are correct.

–flags Display valid driver options.

–g Includes debugging information in the object module.

–gopt Includes debugging information in the object module, but forcesassembly code generation identical to that obtained when –gopt isnot present on the command line.


--keeplnk If the compiler generates a temporary indirect file for a long linkercommand, preserves the temporary file instead of deleting it.



–[no]traceback Adds debug information for runtime traceback for use with theenvironment variable PGI_TERM.


9

PGI Optimization-Related Compiler OptionsThe options included in the following table are the ones you typically use when you are optimizing yourprogram or application code.

Table 2.3. Optimization-Related PGI Compiler Options

Option Description–fast Generally optimal set of flags for targets that support SSE capability.

–fastsse Generally optimal set of flags for targets that include SSE/SSE2capability.


–mp[=all, align,bind,[no]numa] Interpret and process user-inserted shared-memory parallelprogramming directives (see Chapters 5 and 6).

–O Specifies code optimization level where is 0, 1, 2, 3, or 4.


PGI Linking and Runtime-Related Compiler OptionsThe options included in the following table are the ones you typically use to define parameters related tolinking and running your program or application code.

Table 2.4. Linking and Runtime-Related PGI Compiler Options

Option Description–Bdynamic Compiles for and links to the DLL version of the PGI runtime

libraries.

–Bstatic_pgi Compiles for and links to the static version of the PGI runtimelibraries.

–byteswapio (Fortran only) Swap bytes from big-endian to little-endian or viceversa on input/output of unformatted data

–i2 Treat INTEGER variables as 2 bytes.

–i4 Treat INTEGER variables as 4 bytes.

–i8 Treat INTEGER and LOGICAL variables as 8 bytes and use 64-bits forINTEGER*8 operations.



Generic PGI Compiler Options

10

Generic PGI Compiler OptionsThe following descriptions are for all the PGI options. For easy reference, the options are arranged inalphabetical order. For a list of options by tasks, refer to the tables in the beginning of this chapter.

–#

Displays the invocations of the compiler, assembler and linker.

Default: The compiler does not display individual phase invocations.

Usage: The following command-line requests verbose invocation information.

$ pgfortran -# prog.f

Description: The –# option displays the invocations of the compiler, assembler and linker. These invocationsare command-lines created by the driver from your command-line input and the default value.

Related options: –Minfo, –V, –v.

–###

Displays the invocations of the compiler, assembler and linker, but does not execute them.

Default: The compiler does not display individual phase invocations.

Usage: The following command-line requests verbose invocation information.

$ pgfortran -### myprog.f

Description: Use the –### option to display the invocations of the compiler, assembler and linker but not toexecute them. These invocations are command lines created by the compiler driver from the rc files and thecommand-line options.

Related options: –#, –dryrun, –Minfo, –V

–Bdynamic

Compiles for and links to the DLL version of the PGI runtime libraries.

Default: The compiler uses static libraries.

Usage: You can create the DLL obj1.dll and its import library obj1.lib using the following series ofcommands:

% pgfortran -Bdynamic -c object1.f% pgfortran -Mmakedll object1.obj -o obj1.dll

Then compile the main program using this command:


11

$ pgfortran -# prog.f

For a complete example, refer to the example: “Build a DLL: Fortran” in the “Creating and Using Libraries”chapter of the PGI Compiler User’s Guide.

Description: Use this option to compile for and link to the DLL version of the PGI runtime libraries. This flagis required when linking with any DLL built by the PGI compilers. This flag corresponds to the /MD flag usedby Microsoft’s cl compilers.

Note

On Windows, –Bdynamic must be used for both compiling and linking.

When you use the PGI compiler flag –Bdynamic to create an executable that links to the DLL form of theruntime, the executable built is smaller than one built without –Bdynamic. The PGI runtime DLLs, however,must be available on the system where the executable is run. The –Bdynamic flag must be used when anexecutable is linked against a DLL built by the PGI compilers.

Note

C++ on Windows does not support –Bdynamic.

Related options:–Bstatic, –Mmakedll

–Bstatic

Compiles for and links to the static version of the PGI runtime libraries.


Usage: The following command line explicitly compiles for and links to the static version of the PGI runtimelibraries:

% pgfortran -Bstatic -c object1.f

Description: You can use this option to explicitly compile for and link to the static version of the PGI runtimelibraries.

Note

On Windows, –Bstatic must be used for both compiling and linking.

For more information on using static libraries on Windows, refer to “Creating and Using Static Libraries onWindows” in the “Creating and Using Libraries” chapter of the PGI Compiler User’s Guide.

Related options: –Bdynamic, –Bstatic_pgi, –Mdll

Generic PGI Compiler Options

12

–Bstatic_pgiLinux only. Compiles for and links to the static version of the PGI runtime libraries. Implies –Mnorpath.


Usage: The following command line explicitly compiles for and links to the static version of the PGI runtimelibraries:

% pgfortran -Bstatic -c object1.f

Description: You can use this option to explicitly compile for and link to the static version of the PGI runtimelibraries.

NoteOn Linux, –Bstatic_pgi results in code that runs on most Linux systems without requiring aPortability package.

For more information on using static libraries on Windows, refer to “Creating and Using Static Libraries onWindows” in the “Creating and Using Libraries” chapter of the PGI Compiler User’s Guide.

Related options: –Bdynamic, –Bstatic, –Mdll

–byteswapioSwaps the byte-order of data in unformatted Fortran data files on input/output.

Default: The compiler does not byte-swap data on input/output.

Usage: The following command-line requests that byte-swapping be performed on input/output.

$ pgfortran -byteswapio myprog.f

Description: Use the –byteswapio option to swap the byte-order of data in unformatted Fortran data fileson input/output. When this option is used, the order of bytes is swapped in both the data and record controlwords; the latter occurs in unformatted sequential files.

You can use this option to convert big-endian format data files produced by most RISC workstations and high-end servers to the little-endian format used on x86 or x64 systems on the fly during file reads/writes.

This option assumes that the record layouts of unformatted sequential access and direct access files are thesame on the systems. It further assumes that the IEEE representation is used for floating-point numbers. Inparticular, the format of unformatted data files produced by PGI Fortran compilers is identical to the formatused on Sun and SGI workstations; this format allows you to read and write unformatted Fortran data filesproduced on those platforms from a program compiled for an x86 or x64 platform using the –byteswapiooption.

Related options: None.


13

–C

Enables array bounds checking. This option only applies to the PGI Fortran compilers.

Default: The compiler does not enable array bounds checking.

Usage: In this example, the compiler instruments the executable produced from myprog.f to perform arraybounds checking at runtime:

$ pgfortran -C myprog.f

Description: Use this option to enable array bounds checking. If an array is an assumed size array, thebounds checking only applies to the lower bound. If an array bounds violation occurs during execution, anerror message describing the error is printed and the program terminates. The text of the error messageincludes the name of the array, the location where the error occurred (the source file and the line number inthe source), and information about the out of bounds subscript (its value, its lower and upper bounds, and itsdimension).

Related options: –M[no]bounds.

–c

Halts the compilation process after the assembling phase and writes the object code to a file.

Default: The compiler produces an executable file (does not use the –c option).

Usage: In this example, the compiler produces the object file myprog.obj in the current directory.

release 2011 - nvidia · 2012. 10. 27. · while every precaution has been taken in the preparation...

Documents