Difference between revisions of "AUG Files Reference"

From OC Systems Wiki!
Jump to: navigation, search
m (UAL file)
 
(17 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
<div><div>
 
<div><div>
  
[[AUG_Aprobe_API|Next]] [[AUG_Tools_Reference|Previous]] [[AUG_Top|Top]] [[AUG_Contents|Contents]] [[AUG_Index|Index]]
+
[[AUG_Aprobe_API|[Next]]] [[AUG_Tools_Reference|[Previous]]] [[AUG_Top|[Top]]] [[AUG_Contents|[Contents]]] [[AUG_Index|[Index]]]
  
 
Aprobe User Guide
 
Aprobe User Guide
Line 17: Line 17:
 
Aprobe requires symbol and line information to be available in a load module in order to probe it. An ADI file allows aprobe to be used in an environment where a module is stripped of this information (for example by the strip command). The ADI file is generated from an executable or shared library while the symbolic information is still available, using the [[AUG_Tools_Reference#apmkadi|apmkadi]] command. The ADI file may then be used in combination with previously-generated probes ([[#UAL File| UAL file]]s) to probe a stripped program.
 
Aprobe requires symbol and line information to be available in a load module in order to probe it. An ADI file allows aprobe to be used in an environment where a module is stripped of this information (for example by the strip command). The ADI file is generated from an executable or shared library while the symbolic information is still available, using the [[AUG_Tools_Reference#apmkadi|apmkadi]] command. The ADI file may then be used in combination with previously-generated probes ([[#UAL File| UAL file]]s) to probe a stripped program.
  
An ADI file is binary file whose format is not specified. Its name must end in '''.adi'''.
+
An ADI file is binary file whose format is not specified. Its name must end in <code>.adi</code>.
  
 
== APC file ==
 
== APC file ==
Line 23: Line 23:
 
'''Aprobe Control File'''
 
'''Aprobe Control File'''
  
The APC '''file''' contains ANSI C statements augmented with APC preprocessor directives. An APC file name ends in '''.apc''', and the file must be preprocessed by the [[AUG_Tools_Reference#apc|aprobe-9.htmlapc]]'preprocessor, which also submits the resulting C file to your C compiler, links it with the Aprobe shared library and other object code, to produce a [[#UAL File|UAL file]].
+
The APC <code>file</code> contains ANSI C statements augmented with APC preprocessor directives. An APC file name ends in <code>.apc</code>, and the file must be preprocessed by the [[AUG_Tools_Reference#apc|apc]] preprocessor, which also submits the resulting C file to your C compiler, links it with the Aprobe shared library and other object code, to produce a [[#UAL File|UAL file]].
  
An APC file may simply be a legal ANSI C program, but generally consists of one or more Aprobe preprocessor directives (see [[AUG_3_Writing_APC_Probes#The Probe Preprocessor Directives|"The Aprobe Preprocessor Directives"]]) mixed with C code. The outermost preprocessor directive is a '''probe''', as described below. The APC file may contain zero or more probes, in addition to other normal C code they may reference.
+
An APC file may simply be a legal ANSI C program, but generally consists of one or more Aprobe preprocessor directives (see [[AUG_3_Writing_APC_Probes#The Probe Preprocessor Directives|"The Aprobe Preprocessor Directives"]]) mixed with C code. The outermost preprocessor directive is a <code>probe</code>, as described below. The APC file may contain zero or more probes, in addition to other normal C code they may reference.
  
 
The remainder of this section gives a detailed syntax of a probe. Full page width is used to improve readability. However, it is recommended you first look in <code>$APROBE/examples</code>, <code>$APROBE/ada_examples)</code> or, for advanced features, in <code>$APROBE/probes.</code>
 
The remainder of this section gives a detailed syntax of a probe. Full page width is used to improve readability. However, it is recommended you first look in <code>$APROBE/examples</code>, <code>$APROBE/ada_examples)</code> or, for advanced features, in <code>$APROBE/probes.</code>
Line 33: Line 33:
 
The syntax of an APC probe is expressed, here, using a variant of Backus-Naur Form. The boldface words, like probe, are keywords. Words in ''italics'' or enclosed in angle brackets &lt;&gt; are descriptive and are not defined further. Square brackets [] enclose optional items that may appear only once; curly brackets {} enclose an item that may be repeated multiple times. A vertical line separates alternative items. A character enclosed in a pair of apostrophes, like '{', means that the character itself must appear, verbatim, but without the apostrophes. For brevity, ANSI C constructions are not documented here.
 
The syntax of an APC probe is expressed, here, using a variant of Backus-Naur Form. The boldface words, like probe, are keywords. Words in ''italics'' or enclosed in angle brackets &lt;&gt; are descriptive and are not defined further. Square brackets [] enclose optional items that may appear only once; curly brackets {} enclose an item that may be repeated multiple times. A vertical line separates alternative items. A character enclosed in a pair of apostrophes, like '{', means that the character itself must appear, verbatim, but without the apostrophes. For brevity, ANSI C constructions are not documented here.
  
All identifiers and keywords are case-sensitive. Comments are C style ('''/*''' ... '''<nowiki>*/</nowiki>''') which may ''not'' be nested.<br /> C style comments (everything from '''//''' to the end of a line) are also supported.
+
All identifiers and keywords are case-sensitive. Comments are C style (<code>/* ... */</code>) which may ''not'' be nested.<br /> C style comments (everything from '''//''' to the end of a line) are also supported.
+
<pre>
 
  probe ::= probe_specification [ probe_name ] |
 
  probe ::= probe_specification [ probe_name ] |
 
     probe_type
 
     probe_type
Line 108: Line 108:
 
  log_parameter ::= log_value | array_slice
 
  log_parameter ::= log_value | array_slice
 
  array_slice ::= array_identifier '[' log_value ''''..'''' log_value ']'
 
  array_slice ::= array_identifier '[' log_value ''''..'''' log_value ']'
  <code>log_value ::= apc_expression
+
  log_value ::= apc_expression
  </code>apc_expression ::= &lt;''C expression''&gt; | target_expression
+
  apc_expression ::= &lt;''C expression''&gt; | target_expression
 
   
 
   
 
  format_subprogram ::= &lt;''C function name''&gt;
 
  format_subprogram ::= &lt;''C function name''&gt;
Line 150: Line 150:
 
  ppc_register_name ::= r0  | r1  | r2  | r3  | ... | r29  | r30  | r31  |
 
  ppc_register_name ::= r0  | r1  | r2  | r3  | ... | r29  | r30  | r31  |
 
     f0  | f1  | f2  | f3  | ... | f29  | f30  | f31
 
     f0  | f1  | f2  | f3  | ... | f29  | f30  | f31
 +
</pre>
  
 
== APD file ==
 
== APD file ==
Line 157: Line 158:
 
APD files are produced as a side-effect of running an executable under control of the [[AUG_Tools_Reference#aprobe|aprobe]] tool. They are read by the [[AUG_Tools_Reference#apformat|apformat]] command.
 
APD files are produced as a side-effect of running an executable under control of the [[AUG_Tools_Reference#aprobe|aprobe]] tool. They are read by the [[AUG_Tools_Reference#apformat|apformat]] command.
  
The '''aprobe''' command provides several options to control the number and size of the APD files created by an execution; see [[AUG_Tools_Reference#aprobe|aprobe]] for a description of these options.
+
The <code>aprobe</code> command provides several options to control the number and size of the APD files created by an execution; see [[AUG_Tools_Reference#aprobe|aprobe]] for a description of these options.
  
 
The group of APD files created by aprobe is referred to as an "APD ring" and the number of files in the ring is called the "ring size". The base filename may be specified on the aprobe command line, but usually it is derived from the executable name.
 
The group of APD files created by aprobe is referred to as an "APD ring" and the number of files in the ring is called the "ring size". The base filename may be specified on the aprobe command line, but usually it is derived from the executable name.
Line 163: Line 164:
 
There is always at least one file, ''filename''.apd, that is not part of the ring. This is the only file created if the ring size is 0 (which would be appropriate if no data is logged.) The ''filename''.apd file contains persistent data about aprobe session, including which APD files are written to. The actual logged data is written to files ''filename''-''N''.apd, where ''N'' is an integer greater than zero.
 
There is always at least one file, ''filename''.apd, that is not part of the ring. This is the only file created if the ring size is 0 (which would be appropriate if no data is logged.) The ''filename''.apd file contains persistent data about aprobe session, including which APD files are written to. The actual logged data is written to files ''filename''-''N''.apd, where ''N'' is an integer greater than zero.
  
The content of these files is a proprietary binary format which can only be read by the '''apformat''' tool. The executable, UAL files, and APD files are all read by apformat. This requires a consistent set of APD files created by having run aprobe on the same target executable with the same UAL files.
+
The content of these files is a proprietary binary format which can only be read by the <code>apformat</code> tool. The executable, UAL files, and APD files are all read by apformat. This requires a consistent set of APD files created by having run aprobe on the same target executable with the same UAL files.
  
The default ring size is 1; that is, only ''filename''-1.apd is written to. The ring-size is changed using the -n option on the '''aprobe''' command, or else by setting the environment variable APROBE_RING_SIZE.
+
The default ring size is 1; that is, only ''filename''-1.apd is written to. The ring-size is changed using the -n option on the <code>aprobe</code> command, or else by setting the environment variable APROBE_RING_SIZE.
  
 
The default maximum size of a single APD file is 256M if the ring size is 1, and 2M if the ring size is greater than 1. A file is initially 0 bytes long and is extended in 4K increments as data is written to it. This increment may be changed on the aprobe command line.
 
The default maximum size of a single APD file is 256M if the ring size is 1, and 2M if the ring size is greater than 1. A file is initially 0 bytes long and is extended in 4K increments as data is written to it. This increment may be changed on the aprobe command line.
  
As '''aprobe''' runs, the highest-numbered file always contains the newest data..
+
As <code>aprobe</code> runs, the highest-numbered file always contains the newest data..
  
 
When the ''filename''-''N''.apd file is "full" (has reached its specified or default maximum size), the file numbered ''N-(ringsize-1)'' is deleted.
 
When the ''filename''-''N''.apd file is "full" (has reached its specified or default maximum size), the file numbered ''N-(ringsize-1)'' is deleted.
Line 179: Line 180:
 
'''Aprobe Options File'''
 
'''Aprobe Options File'''
  
An '''APO''' file is a textual set of options which are read by the '''libdal.so''' Dynamic Action Linker or the '''run_with_aprobe_apo''' script as described in [[AUG_4_Advanced_Topics#Loading Probes Without aprobe|"Loading Probes Without aprobe"]]. The APO file provides the options to aprobe when it is invoked implicitly with one of these mechanisms.
+
An <code>APO</code> file is a textual set of options which are read by the <code>libdal.so</code> Dynamic Action Linker or the <code>run_with_aprobe_apo</code> script as described in [[AUG_4_Advanced_Topics#Loading Probes Without Aprobe|"Loading Probes Without aprobe"]]. The APO file provides the options to aprobe when it is invoked implicitly with one of these mechanisms.
  
 
The APO file is simply a list of valid options which can be passed to the aprobe command. The characters #, !, //, and --, when appearing as the first character(s) on a line, denote comments which continue to the end of the line.
 
The APO file is simply a list of valid options which can be passed to the aprobe command. The characters #, !, //, and --, when appearing as the first character(s) on a line, denote comments which continue to the end of the line.
  
 
The APO file must have the same name as the executable but end in ".apo", and must be present in the current working directory when the probed executable is invoked.
 
The APO file must have the same name as the executable but end in ".apo", and must be present in the current working directory when the probed executable is invoked.
 +
 +
== BC file ==
 +
 +
'''Test Coverage Detail Data File'''
 +
 +
A BC file is an ASCII file with suffix<code>.bc</code>, which is generated when apformat is run on data produced by the coverage predefined probe. The BC files can be used to produce an annotated source listing with line counts using the [[AUG_Tools_Reference#apbc|apbc]] tool.  BC files can also be produced from merged TC files using [[AUG_Tools_Reference#atcmerge|atcmerge]].
 +
 +
The format of the BC file is not specified.
 +
 +
== BRC file ==
 +
 +
'''Branch Coverage Data File'''
 +
 +
A BRC file is an XML file with suffix <code>.brc</code>, which is generated when apformat is run on data produced by the coverage and brcov predefined probe. The BRC files can be used to produce summary reports and an annotated source listing with line and branch counts using the [[AUG_Tools_Reference#abrmerge|abrmerge]] tool. 
 +
 +
The format of the BRC file is not specified.
  
 
== TC file ==
 
== TC file ==
Line 189: Line 206:
 
'''Test Coverage Data File'''
 
'''Test Coverage Data File'''
  
A TC file is an ASCII file with suffix '''.tc''', which is generated when apformat is run on data produced by the coverage predefined probe. A formatted report is generated from one or more TC files using the [[AUG_Tools_Reference#atcmerge|atcmerge]] tool, which may also be used to generate another (summary) TC file.
+
A TC file is an ASCII file with suffix <code>.tc</code>, which is generated when apformat is run on data produced by the coverage predefined probe. A formatted report is generated from one or more TC files using the [[AUG_Tools_Reference#atcmerge|atcmerge]] tool, which may also be used to generate another (summary) TC file.
  
 
The format of the TC file is not specified.
 
The format of the TC file is not specified.
Line 197: Line 214:
 
'''User Action Library File'''
 
'''User Action Library File'''
  
A UAL file is a shared object library created by the [[AUG_Tools_Reference#apc|apc]]  command by invoking the host system linker (the '''ld''' command) to collect the object code for a single [[#APC File|APC file]] (see above), the Aprobe runtime, and any additional object files or libraries that may be specified on the '''apc''' command line.
+
A UAL file is a shared object library created by the [[AUG_Tools_Reference#apc|apc]]  command by invoking the host system linker (the <code>ld</code> command) to collect the object code for a single [[#APC File|APC file]] (see above), the Aprobe runtime, and any additional object files or libraries that may be specified on the <code>apc</code> command line.
  
 
One or more UAL files are then dynamically loaded by the [[AUG_Tools_Reference#aprobe|aprobe]] tool in order to add its executable content to the executable being probed. The same UAL files are input to [[AUG_Tools_Reference#apformat|apformat]], which formats data using format routines defined in the UAL.
 
One or more UAL files are then dynamically loaded by the [[AUG_Tools_Reference#aprobe|aprobe]] tool in order to add its executable content to the executable being probed. The same UAL files are input to [[AUG_Tools_Reference#apformat|apformat]], which formats data using format routines defined in the UAL.
Line 271: Line 288:
 
==== DTD for XMJ ====
 
==== DTD for XMJ ====
  
One or more XMJ files are read by the [aprobe-9.html#MARKER-9-1075 aprobe] or [aprobe-9.html#MARKER-9-1061 apjava] tools in order to associate the Java probe classes with an application's Java methods. See [aprobe-8.html#MARKER-9-910 Chapter 5, "Writing Java Probes"] for more information.
+
One or more XMJ files are read by the [[AUG_Tools_Reference#aprobe|aprobe]] or [[AUG_Tools_Reference#apjava|apjava]] tools in order to associate the Java probe classes with an application's Java methods. See [[AUG_5_Writing_Java_Probes|"Writing Java Probes"]] for more information.
  
 
== compiler_profiles file ==
 
== compiler_profiles file ==
Line 329: Line 346:
 
|}
 
|}
  
All profiles go from the PROFILENAME keyword to the next PROFILENAME. The only mandatory keyword for a given profile is CC_COMMAND; all others will be initialized to null values If you need to use the '#' character in a parameter, use the escape character (e.g. instead of -# use -\#). OC Systems cannot support all known compilers. The default '''compiler_profiles''' file contains the only supported compilers for each platform.
+
All profiles go from the PROFILENAME keyword to the next PROFILENAME. The only mandatory keyword for a given profile is CC_COMMAND; all others will be initialized to null values If you need to use the '#' character in a parameter, use the escape character (e.g. instead of -# use -\#). OC Systems cannot support all known compilers. The default <code>compiler_profiles</code> file contains the only supported compilers for each platform.
  
 
For Solaris, these are Sun Workshop cc and gcc.
 
For Solaris, these are Sun Workshop cc and gcc.
Line 335: Line 352:
 
For AIX these are xlc and gcc, and for Linux, just gcc.
 
For AIX these are xlc and gcc, and for Linux, just gcc.
  
You may attempt to use this file to configure Aprobe for use with a different compiler but if you run into difficulties, OC Systems will not necessarily be able to assist you. As always, contact <code>support@ocsystems.com</code> if you need further information. The first profile defined is used as the default in the absence of either a '''-cc_command''' option on the [aprobe-9.html#MARKER-9-987 apc] command line or a valid profile name in $APROBE_CC_COMMAND (see [aprobe-9.html#MARKER-9-968 "Environment Variables" in Appendix A]). Note that the <code>-cc_command</code> argument and the value of the APROBE_CC_COMMAND environment variable must be the name of a PROFILENAME listed in the <code>compiler_profiles</code> file, ''not'' the name of a compiler executable itself.
+
You may attempt to use this file to configure Aprobe for use with a different compiler but if you run into difficulties, OC Systems will not necessarily be able to assist you. As always, contact <code>support@ocsystems.com</code> if you need further information. The first profile defined is used as the default in the absence of either a <code>-cc_command</code> option on the [[AUG_Tools_Reference#apc|apc]] command line or a valid profile name in $APROBE_CC_COMMAND (see [[AUG_Tools_Reference#Environment Variables|Environment Variables]]). Note that the <code>-cc_command</code> argument and the value of the APROBE_CC_COMMAND environment variable must be the name of a PROFILENAME listed in the <code>compiler_profiles</code> file, ''not'' the name of a compiler executable itself.
  
 
</div><div>
 
</div><div>
 
----
 
----
  
[[AUG_Aprobe_API|Next]] [[AUG_Tools_Reference|Previous]] [[AUG_Top|Top]] [[AUG_Contents|Contents]] [[AUG_Index|Index]]
+
[[AUG_Aprobe_API|[Next]]] [[AUG_Tools_Reference|[Previous]]] [[AUG_Top|[Top]]] [[AUG_Contents|[Contents]]] [[AUG_Index|[Index]]]
  
 
Copyright 2006-2017 OC Systems, Inc.
 
Copyright 2006-2017 OC Systems, Inc.

Latest revision as of 14:44, 30 March 2020

Files Reference


ADI file

Aprobe Debug Information File

Aprobe requires symbol and line information to be available in a load module in order to probe it. An ADI file allows aprobe to be used in an environment where a module is stripped of this information (for example by the strip command). The ADI file is generated from an executable or shared library while the symbolic information is still available, using the apmkadi command. The ADI file may then be used in combination with previously-generated probes ( UAL files) to probe a stripped program.

An ADI file is binary file whose format is not specified. Its name must end in .adi.

APC file

Aprobe Control File

The APC file contains ANSI C statements augmented with APC preprocessor directives. An APC file name ends in .apc, and the file must be preprocessed by the apc preprocessor, which also submits the resulting C file to your C compiler, links it with the Aprobe shared library and other object code, to produce a UAL file.

An APC file may simply be a legal ANSI C program, but generally consists of one or more Aprobe preprocessor directives (see "The Aprobe Preprocessor Directives") mixed with C code. The outermost preprocessor directive is a probe, as described below. The APC file may contain zero or more probes, in addition to other normal C code they may reference.

The remainder of this section gives a detailed syntax of a probe. Full page width is used to improve readability. However, it is recommended you first look in $APROBE/examples, $APROBE/ada_examples) or, for advanced features, in $APROBE/probes.

Probe Syntax

The syntax of an APC probe is expressed, here, using a variant of Backus-Naur Form. The boldface words, like probe, are keywords. Words in italics or enclosed in angle brackets <> are descriptive and are not defined further. Square brackets [] enclose optional items that may appear only once; curly brackets {} enclose an item that may be repeated multiple times. A vertical line separates alternative items. A character enclosed in a pair of apostrophes, like '{', means that the character itself must appear, verbatim, but without the apostrophes. For brevity, ANSI C constructions are not documented here.

All identifiers and keywords are case-sensitive. Comments are C style (/* ... */) which may not be nested.
C style comments (everything from // to the end of a line) are also supported.

 probe ::= probe_specification [ probe_name ] |
     probe_type
 probe_specification ::= probe_program |
     probe_thread  |
     probe_format  |
     probe_all     |
     probe_function
 
 probe_program ::= probe program probe_program_body
 probe_thread  ::= probe thread  probe_thread_body
 probe_format  ::= probe format  probe_thread_body
 probe_all ::= probe all     probe_function_body
 
 probe_function  ::= probe target_function probe_function_body |
     probe_object_decl
 
 probe_type  ::= '''typedef probe''' probe_function_body probe_type_name '''';''''
 probe_type_name ::= ''identifier ''
 probe_object_decl ::= probe_type_name ''identifier'' ''''('''' target_function '''')'''' '''';''''
 
 probe_name  ::= ''identifier'' ';'
 target_function ::= '''all''' |
     [filename ''':''']symbol_name        [in module_name] |
     [filename ''':''']user_function_name [in module_name]
 
 symbol_name ::= quoted_string
 filename  ::= quoted_string | '''extern '''module_name ::= quoted_string
 quoted_string ::= '"'<a string literal>'"'
 
 user_function_name  ::=  [class_name '::' ] ''identifier'' [ profile ]
 profile ::= '(' [ <''type'' [ ',' ''type'' ... ]] ')'
 
 probe_program_body  ::= '{' probe_program_decls | probe_actions '}'
 probe_thread_body ::= '{' probe_thread_decls  | probe_actions '}'
 probe_function_body ::= '{' probe_function_decls | probe_actions '}'
 probe_program_decls ::= { <C declarations> | probe_thread }
 probe_thread_decls  ::= { <C declarations> | probe_function }
 probe_function_decls  ::= { probe_variable_decl | probe_function }
 probe_variable_decl ::= <C variable declaration>
 
 probe_actions ::= { probe_action  apc_statements }
 probe_action  ::= on_entry  |
     on_exit   |
     on_line   '(' line_numbers ')' |
     on_line   '( all )' |
 line_numbers  ::= line_range | line_range ',' line_numbers
 line_range  ::= line_number_expr | line_number_expr ''''..'''' line_number_expr
 line_number_expr  ::= <''constant expr of'' line_number>
 line_number ::=  absolute_line_number | '''first''' | '''last'''
 absolute_line_number  ::= <''unsigned_integer>''
     on_offset '(' offset_constants ')' |
     on_offset '( all )'
 offset_constants  ::= integer | integer '''','''' offset_constants
 apc_statements  ::= apc_statement { apc_statement }
 apc_statement ::= <C statement> |
     log_statement  |
     delete_statement |
     probe_allocation
 probe_allocation  ::= probe_instance_ptr =' probe_allocator;
 probe_allocator ::= new probe_type_name ''''('''' ''FunctionId'' [, instance_data] '''')' '''instance_data ::=   <''ap_DataPointerT value> ''delete_statement ::= delete probe_instance_ptr
 probe_instance_ptr  ::= <''object of type ProbeInstancePtrT''>
 
 log_statement ::= log [ event_kind ] '(' log_parameters ')'; |
     log '(' log_parameters ')'  with format_subprogram
       [ to LogMethodIDT ] ';'
     log '(' log_parameters ')'
       [ '''as''' LogIdT ]
       [ to LogMethodIDT ] ';'
 
 event_kind  ::= identifier | quoted_string
 log_parameters  ::= log_parameter | { ',' log_parameter }
 log_parameter ::= log_value | array_slice
 array_slice ::= array_identifier '[' log_value ''''..'''' log_value ']'
 log_value ::= apc_expression
 apc_expression ::= <''C expression''> | target_expression
 
 format_subprogram ::= <''C function name''>
 
 LogIdT  ::= <user-defined LogID, see aprobe.h>
 LogMethodIDT  ::= <user-defined LogMethod, see aprobe.h>
 
 type_specification  ::= ''<C type>'' | type_constructor
 type_constructor  ::= '''typeof''' ''''('''' apc_expression '''')''''
 
 target_expression ::= ''''$$'''' register_name   |
     ''''$*''''   |
     ''''$return''''    |
     ''''$'''' parameter_position   |
     ''''$'''' target_entity_name   |
     ''''$("'''' target_entity_name ''''"''''
       ['''','''' ''''"'''' context_description ''''"'''' ] '''')''''
 parameter_position  ::= <nonnegative integer>
 target_entity_name  ::= <name in target program visible at probed location>
 context_description ::= [[user_function_name ] [ module_spec ][file_spec]]
 module_spec ::= ''''-module'''' module_name
 file_spec ::= ''''-file'''' file_name
 
 register_name ::= x86_register_name |
     sparc_register_name |
     ppc_register_name
 
 x86_register_name ::= ESP | EBP | EAX | EBX | ECX | EDX | ESI | EBI |
     ST  | ST0  | ST1  | ST2 | ST3 | ST4 | ST5 | ST6 | ST7
 
 sparc_register_name ::= g0 | g1 | g2 | g3 | g4 | g5 | g6 | g7 |
     o0 | o1 | o2 | o3 | o4 | o5 | o6 | o7 |
     l0 | l1 | l2 | l3 | l4 | l5 | l6 | l7 |
     i0 | i1 | i2 | i3 | i4 | i5 | i6 | i7 |
     f0  | f1  | f3  | ... | f63  |
     fd0 | fd2 | fd4 | ... | fd62 |
     fq0 | fq4 | fq8 | ... | fq60
 
 
 ppc_register_name ::= r0  | r1  | r2  | r3  | ... | r29  | r30  | r31  |
     f0  | f1  | f2  | f3  | ... | f29  | f30  | f31

APD file

Aprobe Data File

APD files are produced as a side-effect of running an executable under control of the aprobe tool. They are read by the apformat command.

The aprobe command provides several options to control the number and size of the APD files created by an execution; see aprobe for a description of these options.

The group of APD files created by aprobe is referred to as an "APD ring" and the number of files in the ring is called the "ring size". The base filename may be specified on the aprobe command line, but usually it is derived from the executable name.

There is always at least one file, filename.apd, that is not part of the ring. This is the only file created if the ring size is 0 (which would be appropriate if no data is logged.) The filename.apd file contains persistent data about aprobe session, including which APD files are written to. The actual logged data is written to files filename-N.apd, where N is an integer greater than zero.

The content of these files is a proprietary binary format which can only be read by the apformat tool. The executable, UAL files, and APD files are all read by apformat. This requires a consistent set of APD files created by having run aprobe on the same target executable with the same UAL files.

The default ring size is 1; that is, only filename-1.apd is written to. The ring-size is changed using the -n option on the aprobe command, or else by setting the environment variable APROBE_RING_SIZE.

The default maximum size of a single APD file is 256M if the ring size is 1, and 2M if the ring size is greater than 1. A file is initially 0 bytes long and is extended in 4K increments as data is written to it. This increment may be changed on the aprobe command line.

As aprobe runs, the highest-numbered file always contains the newest data..

When the filename-N.apd file is "full" (has reached its specified or default maximum size), the file numbered N-(ringsize-1) is deleted.

As a special case, if the number of APD files is 1 (the default) and the file filename-1.apd is full, the logging of any further data to the APD file is stopped and an error message is given.

APO file

Aprobe Options File

An APO file is a textual set of options which are read by the libdal.so Dynamic Action Linker or the run_with_aprobe_apo script as described in "Loading Probes Without aprobe". The APO file provides the options to aprobe when it is invoked implicitly with one of these mechanisms.

The APO file is simply a list of valid options which can be passed to the aprobe command. The characters #, !, //, and --, when appearing as the first character(s) on a line, denote comments which continue to the end of the line.

The APO file must have the same name as the executable but end in ".apo", and must be present in the current working directory when the probed executable is invoked.

BC file

Test Coverage Detail Data File

A BC file is an ASCII file with suffix.bc, which is generated when apformat is run on data produced by the coverage predefined probe. The BC files can be used to produce an annotated source listing with line counts using the apbc tool. BC files can also be produced from merged TC files using atcmerge.

The format of the BC file is not specified.

BRC file

Branch Coverage Data File

A BRC file is an XML file with suffix .brc, which is generated when apformat is run on data produced by the coverage and brcov predefined probe. The BRC files can be used to produce summary reports and an annotated source listing with line and branch counts using the abrmerge tool.

The format of the BRC file is not specified.

TC file

Test Coverage Data File

A TC file is an ASCII file with suffix .tc, which is generated when apformat is run on data produced by the coverage predefined probe. A formatted report is generated from one or more TC files using the atcmerge tool, which may also be used to generate another (summary) TC file.

The format of the TC file is not specified.

UAL file

User Action Library File

A UAL file is a shared object library created by the apc command by invoking the host system linker (the ld command) to collect the object code for a single APC file (see above), the Aprobe runtime, and any additional object files or libraries that may be specified on the apc command line.

One or more UAL files are then dynamically loaded by the aprobe tool in order to add its executable content to the executable being probed. The same UAL files are input to apformat, which formats data using format routines defined in the UAL.

XMJ file

XML Java Probe deployment descriptor file

An XMJ file is user-created text file containing an XML description of Java probes. The DTD for this is shown below, and is on-line in $APROBE/html/xmj.dtd.


<!-- This DTD is for the RootCause / Aprobe XMJ format. -->

<!ENTITY % parameter.mode "(none | readonly | read_only | readwrite | read_write | read-write) 'readonly'">
<!ENTITY % boolean "(false | FALSE | true | TRUE) 'false'">

<!ELEMENT probe_deployment ((target_list_definition*, (bean | probe) ))>

<!ELEMENT target_list_definition (list_target*)>
<!ATTLIST target_list_definition
  name ID #REQUIRED
>

<!ELEMENT bean ((parameter | instrument_target | probe)*)>
<!ATTLIST bean
  class CDATA #REQUIRED
  name CDATA #IMPLIED
>

<!ELEMENT probe ((parameter | target | target_list)*)>
<!ATTLIST probe
  class CDATA #REQUIRED
  parameters %parameter.mode;
  lines %boolean;
>

<!ELEMENT target EMPTY>
<!ATTLIST target
  value CDATA #REQUIRED
  parameters %parameter.mode;
  lines %boolean;
        remove %boolean;
>

<!ELEMENT list_target EMPTY>
<!ATTLIST list_target
  value CDATA #REQUIRED
  parameters %parameter.mode;
  lines %boolean;
>

<!ELEMENT target_list EMPTY>
<!ATTLIST target_list
  name IDREF #REQUIRED
        remove %boolean;
>

<!ELEMENT instrument_target ((target | target_list)*)>
<!-- Id and type are deprecated and this DTD doesn't support them. -->
<!ATTLIST instrument_target
  name CDATA #IMPLIED
  parameters %parameter.mode;
  lines %boolean;
>

<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
  name CDATA #REQUIRED
  value CDATA #REQUIRED
>

DTD for XMJ

One or more XMJ files are read by the aprobe or apjava tools in order to associate the Java probe classes with an application's Java methods. See "Writing Java Probes" for more information.

compiler_profiles file

The compiler_profiles file is a text file in the directory $APROBE/lib/compiler_profiles, or as specified by the APROBE_COMPILER_PROFILES environement variable. Its format is documented at the top of the file itself. The file describes the "profile" for a C compiler that will be invoked by the APC command. Each compiler is defined by the syntax given below. Anything following '#' is treated as a comment; keywords are case-insensitive.

  Keyword
Parameter Notes
PROFILENAME profile name The unique name for a given compiler profile, e.g. PROFILENAME cc
CC_COMMAND command The Compiler executable, e.g. cc, xlc, or gcc
CFLAGS flags Compiler options, e.g. -v
LINKFLAGS flags Link / bind flags, e.g. -z defs
CFLAGS_UNDEF flags same as CFLAGS, if apc -u given
LINKFLAGS_UNDEF flags same as LINKFLAGS, if apc -u
DEBUG flags Flags to compile with debug, e.g. -g -xs
VERBOSE flags Flags to compiler verbosely, e.g. -#
PREPROCESS flags Flags to pass to the pre-process phase; this must include any flags needed to send the pre-processor output to stdout, e.g. -E
MAPFILE flags Flag to invoke the linker's mapfile option. e.g. -Xlinker -M -Xlinker
UALSTUB code Any code which needs to be added to the main UAL c file to stub functions required by the linker. This may be specified multiple times. e.g. int main () {return 0;}

All profiles go from the PROFILENAME keyword to the next PROFILENAME. The only mandatory keyword for a given profile is CC_COMMAND; all others will be initialized to null values If you need to use the '#' character in a parameter, use the escape character (e.g. instead of -# use -\#). OC Systems cannot support all known compilers. The default compiler_profiles file contains the only supported compilers for each platform.

For Solaris, these are Sun Workshop cc and gcc.

For AIX these are xlc and gcc, and for Linux, just gcc.

You may attempt to use this file to configure Aprobe for use with a different compiler but if you run into difficulties, OC Systems will not necessarily be able to assist you. As always, contact support@ocsystems.com if you need further information. The first profile defined is used as the default in the absence of either a -cc_command option on the apc command line or a valid profile name in $APROBE_CC_COMMAND (see Environment Variables). Note that the -cc_command argument and the value of the APROBE_CC_COMMAND environment variable must be the name of a PROFILENAME listed in the compiler_profiles file, not the name of a compiler executable itself.


[Next] [Previous] [Top] [Contents] [Index]

Copyright 2006-2017 OC Systems, Inc.