Home

Clang UPC Configuration Options

The first step of building Clang UPC is the configuration of the source code to better suite the user. As mentioned before, cmake (preferred fo Clang UPC) or configure is used for this purpose. Beside the regular [Clang/LLVM configuration options[(http://llvm.org/docs/CMake.html#llvm-specific-variables), Clang UPC provides some additional options that can be used to configure UPC language as well as the selected runtime.

1.1 General Options

  • -DCMAKE_INSTALL_PREFIX:PATH:=directory

    Sets the installation prefix. This follows the standard convention. Executables are placed in directory/bin, library files go in directory/lib and so on. The default is /usr/local.

  • -DCMAKE_BUILD_TYPE:=[Debug|Release]

    Possible values are empty (no optimization, no debug info), Debug (No optimization, debug info), Release (optimization, no debug info), RelWithDebInfo (optimization, debug info), MinSizeRel (-Os, no debug info). Defaults to None.

  • -DLLVM_TARGETS_TO_BUILD:=semicolon-separated-list

    Specifies a list of architectures for which Clang will be able to generate code. Clang UPC supports x86 and PowerPC. Other targets supported by LLVM can be built, but they may or may not work. Defaults to all.

  • -DCMAKE_C_COMPILER:=path-to-c-compiler

    Specify the C compiler used by the build process.

  • -DCMAKE_CXX_COMPILER:=path-to-c++-compiler

    Specify the C++ compiler used by the build process.

1.2 UPC Language Options

The following options control the UPC compiler generated code.

  • -DUPC_PTS:=[packed|struct]

    Default UPC pointer to shared representation. Defaults to packed.

  • -DUPC_PACKED_BITS:=comma-separated-list

    Default UPC packed pointer to shared bits per field (phase,thread,addr). Defaults to ‘20,10,34’.

  • -DUPC_PTS_VADDR_ORDER:=[first|last]

    Default UPC pointer to shared field order. Defaults to first.

  • -DLIBUPC_CONFIGURATIONS:=semicolon-separated-list

    Controls the library variants that will be built. Each representation of UPC pointers requires a separate library.

    p
    Indicates the packed representation. (default)
    s
    Use the struct representation.
    f
    Put the virtual address field last. (default)
    l
    Put the virtual address field last.
    phase-thread-address
    Specify the bits in the packed representation. (default 20-10-34)

    Thus, p;s;p-l-18-14-32 would build three library variants. p` is the default, _s is for -fupc-pts=struct, and p-l-18-14-32 is for -fupc-packed-bits=18,14,32 -fupc-pts-vaddr-order=last.

    The default is to build 4 library variants, p;s;p-l;s-l, corresponding to -fupc-pts=[packed|struct] and -fupc-pts-vaddr-order=[first|last].

The following options are used in the case when “-fupc-ir” option is used on the command line:

  • -DUPC_IR_RP_BITS:=thread,address

    UPC Remote Pointer representation. Number of bits in thread and address must add to 64. This option is valid on 64 bits architectures only.

  • -DUPC_IR_RP_ADDRSPACE:=number

    LLVM address space for UPC Remote Pointer. 16 by default. This option is valid on 64 bits architectures only.

1.3 Linking Options

  • -DLIBUPC_ENABLE_LINK_SCRIPT:=[TRUE|FALSE]

    Enable UPC’s use of a custom linker script. This option must turned of for systems without the GNU LD (e.g. Mac OS X).

1.4 Runtime Debugging Options

  • -DLIBUPC_ENABLE_BACKTRACE:=[TRUE|FALSE]

    Enable stack frame backtrace report when UPC runtime fatal errors occur or by user request (via signal) (TRUE by default).

  • -DLIBUPC_ENABLE_BACKTRACE_ADDR2LINE

    Enable usage of addr2line for program backtrace on fatal errors or on user’s request.

  • -DLIBUPC_BACKTRACE_ADDR2LINE:=path-to-addr2line

    Path of the addr2line for program backtrace on fatal errors or on user’s request.

  • -DLIBUPC_ENABLE_BACKTRACE_GDB

    Enable usage of GDB for program backtrace on fatal errors.

  • -DLIBUPC_BACKTRACE_GDB:=path-to-gdb

    Path to gdb executable used for program backtrace on fatal events.

  • -DLIBUPC_ENABLE_BACKTRACE_SIGNAL

    Enable usage of signals for backtrace on user’s request (SIGUSR1 by default).

  • -DLIBUPC_BACKTRACE_SIGNAL:=signal

    Specify signal name used of backtrace on user’s request. Defauls to SIGUSR1.

1.5 Runtime Options

  • -DLIBUPC_MAX_LOCKS:=count

    The maximum number of locks that can be held by a single UPC thread.

  • -DLIBUPC_MEMORY_PAGE_SIZE=number-of-bytes

    Select target memory page size (4096 by default)

  • -DLIBUPC_TREE_FANOUT=count

    The maximum number of children in each sub-tree used to implement UPC collectives operations (e.g. upc_barrier) (4 by default).

  • -DLIBUPC_RUNTIME_MODEL:=[smp|portals4]

    Specify the runtime implementation model for UPC, where model may be: ‘smp’ for symmetric multiprocessing or ‘portals4’ for Infiniband with Portals4 package.

  • -DLIBUPC_ENABLE_RUNTIME_OMP_CHECKS:=[0|1]

    OMP children threads are not allowed to access UPC shared data. Enable the check only in debugging mode as this checks affects performance.

1.6 SMP Runtime Options

  • -DLIBUPC_ENABLE_AFFINITY:=[True|False]

    Enable UPC thread process affinity.

  • -DLIBUPC_ENABLE_NUMA:=[True|False]

    Enable UPC thread processor/memory NUMA affinity.

1.7 Portals 4 Runtime Options

Some of the configuration options are included to support the Infiniband (Portals4) based runtimes:

  • -DLIBUPC_POTALS4:=path-to-portals-package-install

    Directory path for installed Portals4 package (e.g. /usr/local/portals4).

  • -DLIBUPC_JOB_LAUNCHER:=[slurm|yod]`

    Specify the job launcher for Infiniband based runtime (slurm by default)

  • -DLIBUPC_BOUNCE_BUFFER_SIZE:=size`

    The size (in bytes) of the bounce buffer that is used by the UPC runtime to buffer network data (256Kb by default).

  • -DLIBUPC_GLOBAL_EXIT_TIMEOUT:=seconds

    upc_global_exit() time to wait for other threads to exit (2 seconds by defualt).

  • -DLIBUPC_PTE_BASE:=number

    Base index of the first Portals4 PTE used by the UPC runtime (16 by default)

  • -DLIBUPC_ENABLE_TRIGGERED_OPS:=[0|1]

    Enable UPC runtime support for Portals4 triggered operations (enabled by default)

  • -DLIBUPC_MAX_OUTSTANDING_PUTS:=count

    Maximum number of outstanding Portals 4 put operations (256 by default)

  • -DLIBUPC_LOCAL_MEM:=[posix|mmap|none]`

    Specify type of shared memory used for node local memory accesses (posix by default). Option none disables node local memory accesses.

  • -DLIBUPC_ENABLE_RUNTIME_CHECKS:=[0|1]

    Enable internal UPC runtime checks that validate arguments, and check for inconsistent runtime state (off (0) by default).

  • -DLIBUPC_ENABLE_RUNTIME_DEBUG:=[0|1]

    Enable UPC runtime debugging mode (off (0) by default).

  • -DLIBUPC_ENABLE_RUNTIME_STATS:=[0|1]

    Enable internal UPC runtime statistics collection support; these statistics count the number of various significant internal operations, and dump those counts into a per-process statistics file (off (0) by default).

  • -DLIBUPC_ENABLE_RUNTIME_TRACE:=[0|1]

    Enable internal UPC runtime trace collection support; a runtime trace is a time stamped log that records various significant internal events; this trace is written to a per-process log file (off (0) by default).