AUG Files Reference

From OC Systems Wiki!
Jump to: navigation, search

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_specification ::= probe_program |
     probe_thread  |
     probe_format  |
     probe_all     |
 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_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_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 |
 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 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

<!ELEMENT bean ((parameter | instrument_target | probe)*)>
<!ATTLIST bean

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

<!ATTLIST target
  parameters %parameter.mode;
  lines %boolean;
        remove %boolean;

<!ELEMENT list_target EMPTY>
<!ATTLIST list_target
  parameters %parameter.mode;
  lines %boolean;

<!ELEMENT target_list EMPTY>
<!ATTLIST target_list
        remove %boolean;

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

<!ELEMENT parameter EMPTY>
<!ATTLIST parameter


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.

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 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.