AIX Instrumentation - Special Considerations

From OC Systems Wiki!
Jump to: navigation, search


During the instrumentation phase Aprobe will insert code in a probed functions to redirect execution to the specified probe. The most efficient way to do the redirection is with a branch, but on the PowerPC architecture branches are limited in range. This can make it difficult for Aprobe to find patch areas (to hold the probes) that are within range of the branch. Aprobe uses a number of approaches to address this issue. These considerations are not applicable to x86/x64_64 Linux executables.

Sacrificing Functions

One approach used by Aprobe is to "sacrifice" functions. The process of sacrificing application functions during the instrumentation phase of Aprobe startup refers to the relocation of function CSECTs on AIX so that the space once occupied by the function can be used for code patches, which are reachable in a single branch instruction. The sacrificed function is still available to be called either from the application or probes. Sacrificing is performed automatically by Aprobe.

Messages about sacrificing functions are an indication that Aprobe is having difficulty allocating patch areas.

Function sacrificing can be disabled by setting the environment variable APROBE_DISABLE_SACRIFICE=TRUE. This should only be used if program execution has problems under Aprobe. Some remedial action to add back sacrificing in shared libraries like may be necessary. Contact Aprobe support in this case.

When Function Sacrificing Is Not Enough

In some cases Aprobe will not be able to find a patch area in range of a branch from the probed function. Aprobe will report the problem with a warning:

(W) Could not allocate patch space reachable from module c2.eab.
    Patch space within range may be exhausted.
    You can use -v to get more information about your patches.
    You can use -qconserve_patch_space to increase the number
    of patches which can fit in the allocated patch area.
    You can use -qenable_trap_patches to use (slower) trap
    patches when reachable patch areas are not available.
    You can also add text CSECTS labeled 'ap_patchareaXXX' to
    your application modules to be used as additional patch space.
    You can reduce the number of probes to reduce the number
    of patches required.

That rather lengthy message contains quite a lot of information.

First, you can get more information about patching by using the -v option on the Aprobe command line (or in a .apo file. Adding the debug flag -! will give information about patch areas (and a lot of other stuff).

The next approach to try is the following Aprobe command line option:

-q conserve_patch_space

which uses an indirect branch mechanism to reach more distant patch areas. This approach is slightly slower than the direct approach but is usually no problem.

You can also use:

-q enable_patch_alloc

if you are running out of patch space, which is a slightly different problem.

You can also enable trap patches using the following Aprobe command line option:

-q enable_trap_patches

which use the PowerPC trap instructions to redirect from the probe function to the patch. This mechanism is slower, but it overcomes the branch distance limitation. Note that branch redirection will always be used if available, and the trap mechanism will be a fallback, if enabled.

The final approach is to add patch areas to your application. To use this approach you will add CSECTs to your application whose name starts with ap_patcharea. You can add multiple patch area CSECTs by using distinct symbols (typically by adding an integer at the end of the symbol), as long as they are all unique. It is up to you to make sure the patch areas a located in your application where they are "reachable" (within branch range) of the functions you want to probe. Aprobe will search for these patch area symbols at the start of the instrumentation phase and use them as necessary. You can disable the search for patch areas in you application by setting the environment variable: APROBE_DISABLE_PATCHAREA=TRUE.

Controlling Function Sacrificing

You can select which functions Aprobe will not sacrifice using the following command line option:

-q do_not_sacrifice=file

to try and work around a functions sacrifice problem. The file should contain a single function name, in Aprobe syntax, on each line.

You can tell Aprobe which function symbols to sacrifice ahead of time using this kind of probe:

 extern void ap_SacrificeFunctionForPatchArea(ap_FunctionIdT FunctionId);
 static Sacrifice(ap_NameT FunName)
    ap_SymbolIdT sym =

 probe program