Difference between revisions of "Porting Probe Apc Files"

From OC Systems Wiki!
Jump to: navigation, search
m (Swn moved page Porting Probe App Files to Porting Probe Apc Files without leaving a redirect: Correct name)
m (Line Numbers)
Line 75: Line 75:
 
==Line Numbers==
 
==Line Numbers==
  
Line numbers can vary between the various target compilers.  Of course, the source line is not changing, it is really that different object code is generated for the source lines by the compiler.  Aprobe works from the debug line information supplied by the compiler.
+
Line numbers can vary between the various target compilers.  Of course, the source line is not changing, it is really that different object code is generated for the source lines by the compiler.  Aprobe works from the debug line information supplied by the compiler.  Because of such variances between compilers (and the likelihood of application code modification),  line numbers are the least portable construct.  In general, <code>on_entry</code> and <code>on_exit</exit> actions are much more portable.
  
 +
You can use the <code>apcgen</code> tool to generate a dictionary of functions and source lines to help with your conversion.  For example:
 +
<nowiki>
 +
apcgen -D my app.exe
 +
</nowiki>
 +
will generate something like:
 +
<nowiki>
 +
extern:"base::op2(int,int)" -- line 36 in /home/swn/aprobe/test/apcgen/i2423b/base.h
 +
  line 43 (0000-000d)
 +
  line 44 (000e-0013)
 +
  line 44 (0014-0019)
 +
  line 46 (001a-0020)
 +
  line 50 (0021-0028)
 +
  line 52 (0029-002b)
 +
extern:"base::op3(int,int)" -- line 4 in /home/swn/aprobe/test/apcgen/i2423b/base.cpp
 +
  line 5 (0000-000d)
 +
  line 6 (000e-0013)
 +
  line 6 (0014-0019)
 +
  line 8 (001a-0020)
 +
  line 12 (0021-0028)
 +
  line 14 (0029-002b)
 +
</nowiki>
  
 
==Aprobe Library Functions==
 
==Aprobe Library Functions==

Revision as of 20:35, 7 December 2018

This topic describes some of the issues with and approaches to creating probes which are portable between AIX and Linux. In general, this topics will assume you are porting from AIX to Linux; it is relatively easy to figure out the reverse direction form this topic.

General

There are several categories of items which can be different between Aprobe targets:

  • Symbol names – the name that comes after ‘probe‘ will often be different
  • Module names – for example, “libc.a(shr.o)” becomes “libc.so”
  • Line numbers - what is line 123 on AIX might be 121 on Linux
  • Aprobe library function names - ap_RaisePowerAdaException becomes ap_RaiseGnatException.
  • Target expression scope - $(“x”, “-file unit.ads”) might become $(“x”, “-file unit.adb”)
  • Compiler-generated field names in target expressions, like “.AnonField_5” will be removed or different
  • Function return values
  • Ada out parameters

The following sections describe these categories in detail.

Symbol Names

Getting the right linux symbol for each probe is the first change to make. If the apc compiler doesn’t find the symbol for a probe, it will cause more errors for on_line and $expression within the probe.

Start by generating the list of symbols for your executable, for example:

 apcgen –L my_driver.eab > my_driver.syms
 

or

 apcgen –L $GENAPPS_PATH/apps/edsm/rpd/src/c2.eab –f  fls-flights.adb > fls-flights.syms
 

Next, make a pass through your apc file looking for “b]”, as in extern:“pkg.subp[1b]”. These symbols are generated only by PowerAda for package-body-local subprograms. For Linux, GNAT generates a true file-scoped symbol like “pkg.adb”:”pkg.subp[1]”. So these are straightforward replacements to make:

Before:

  probe extern:”pkg.subp[1b]” 
 

After:

 #ifdef _AIX
   probe extern:”pkg.subp[1b]” 
 #else
   probe “pkg.adb”:”pkg.subp[1]” 
 #endif
 

TBD

Module Names

Module names differ between AIX and Linux targets. Module names are typically used in probe target designations (after the in keyword), but may also be used in Aprobe runtime calls. References tot he application module generally do not need a module name.

ON AIX the Aprobe module names will reference an archive member. For example:

 probe extern:"malloc" in “libc.a(shr.o)”
 

On Linux the Aprobe module names will references shared libraries. For example:

 probe extern:"malloc" in “libc.so”
 

A simple preprocessor statement can help here:

 #ifdef (AIX)
 #define LIBC_NAME "libc.a{shr.o)"
 #else
 #define LIBC_NAME "libc.so"
 #endif
 
 probe extern:"malloc" in LIBC_NAME
 {
 }
 

Line Numbers

Line numbers can vary between the various target compilers. Of course, the source line is not changing, it is really that different object code is generated for the source lines by the compiler. Aprobe works from the debug line information supplied by the compiler. Because of such variances between compilers (and the likelihood of application code modification), line numbers are the least portable construct. In general, on_entry and on_exit</exit> actions are much more portable.

You can use the apcgen tool to generate a dictionary of functions and source lines to help with your conversion. For example:

 apcgen -D my app.exe
 

will generate something like:

 extern:"base::op2(int,int)" -- line 36 in /home/swn/aprobe/test/apcgen/i2423b/base.h
  line 43 (0000-000d)
  line 44 (000e-0013)
  line 44 (0014-0019)
  line 46 (001a-0020)
  line 50 (0021-0028)
  line 52 (0029-002b)
 extern:"base::op3(int,int)" -- line 4 in /home/swn/aprobe/test/apcgen/i2423b/base.cpp
  line 5 (0000-000d)
  line 6 (000e-0013)
  line 6 (0014-0019)
  line 8 (001a-0020)
  line 12 (0021-0028)
  line 14 (0029-002b)
 

Aprobe Library Functions

Target Expression Scope

Compiler-Generated Field Names

Function Return Values

Ada Out Parameters

Ada out parameters are usually read or modified in on_exit actions of a probe. Ada out parameters are handled differently by the PowerAda/AIX compiler and the Gnat/Linux compiler.

On PowerAda/AIX Ada out parameter values are returned in the canonical parameters location, which is usually a register. but can be a stack location. Reading or setting these out parameters is as simple as using the proper target expression or:

 $my_out_param = new-value;
 

On Gnat/Linux the out parameters will be returned in a structure/record passed into the subprogram as a hidden first parameter. The Apc compiler will try to hide this fact and allow you to use the same target expression to read or modify the out parameter as above. In some cases you may have to help out the Apc compiler by referencing the out parameter as a field in the hidden structure, named "return":

 $return.my_out_param = new-value;