Linking Your Application with the HIA
TotalView puts its Heap Interposition Agent (HIA) between your program and its heap library, which allows the HIA to intercept the calls that your program makes to this library. After it intercepts the call, it checks the call for errors and then sends it on to the library so that it can be processed. The TotalView HIA does not replace standard memory functions; it just monitors what they do.
In most cases, TotalView arranges for the HIA to be loaded automatically when it starts your program. In some cases, however, special steps must be taken to ensure the HIA loads. One example is when you are starting an MPI program using a launcher that does not propagate environment variables. (If you start your MPI program in TotalView using the Add Parallel Program page, TotalView propagates the information for you.) Another is when you want to start your program outside, or independently of, TotalView, and want to attach to the program later after it has started.
There are two ways you can arrange for the HIA to be loaded
Link the application with the HIA, as described in this section.
Request that the heap HIA be preloaded by setting the runtime loader's preloading environment variable. See Using env to Insert the HIA.
Here is some important platform-specific information:
On AIX, the malloc replacement code and HIA application must be in directories searched by the dynamic loader. If they are not in any of the standard directories (you can check with your system administrator), you can set LIBPATH to search these directories when you run the program. Another option is to add the directories to the program's list of search directories when you link the program. To do this, use the -L option as described in the table below. If you are in doubt about the directories being searched, you can obtain a list of the searched directories with dump -Hv <program-name>.For additional requirements with AIX, see Installing tvheap_mr.a on AIX on page 15.
On Cray, TotalView supports both static and dynamic linking. See the table below for the link lines you need to use.On Apple Mac OSX, you cannot link the HIA into your program.Table 22 lists additional command-line linker options that you must use when you link your program:
Platform | Compiler | Binary Interface | Additional linker options |
|---|---|---|---|
Cray XT, XE, XK CLE (dynamic) | - | 64 | -dynamic -L<path> -ltvheap_64 -Wl,-rpath,<path> |
Cray XT, XE, XK CLE (static) | - | 64 | -L<path> -ltvheap_cnl |
IBM RS/6000 (all) | IBM/GCC | 32/64 | -L<path_mr> -L<path> |
AIX 5 | IBM/GCC | 32 | -L<path_mr> -L<path> <path>/aix_malloctype.o |
64 | -L<path_mr> -L<path> <path>/aix_malloctype64_5.o | ||
Linux x86-64 1 | GCC/Intel/PGI | 32 | -L<path> -ltvheap -Wl,-rpath,<path> |
64 | -L<path> -ltvheap_64 -Wl,-rpath,<path> | ||
64 | -L<path> -ltvheap_64 -Wl,-rpath,<path> | ||
Linux PowerLE | GCC | 64 | -L<path> -ltvheap_64 -Wl,-rpath,<path> |
Linux ARM64 | GCC | 64 | -L<path> -ltvheap_64 -Wl,-rpath,<path> |
Sun | Sun/Apogee | 32 | -L<path> -ltvheap -R <path> |
Sun | 64 | -L<path> -ltvheap_64 -R <path> | |
GCC | 32 | -L<path> -ltvheap -Wl,-R,<path> | |
64 | -L<path> -ltvheap_64 -Wl,-R,<path> |
1 On Ubuntu platforms, if the link line fails to start TotalView, try adding the additional flag -Wl,-no-as-needed. This flag should occur before the linking of tvheap, so on 64-bit platforms the link line would be:
-L<path> -Wl,-no-as-needed -ltvheap_64 -Wl,-rpath,<path>
-L<path> -Wl,-no-as-needed -ltvheap_64 -Wl,-rpath,<path>
Table Options:
<path>The absolute path to the HIA in the TotalView installation hierarchy, located at:
<installdir>/toolworks/TotalView.<version>/<platform>/lib
<installdir>The installation base directory name
<version>TotalView version number
<platform>The platform tag
<path_mr> The absolute path of the malloc replacement library. This value is determined by the person who installs the TotalView malloc replacement library.
