Difference between revisions of "AUG Files Reference"

From OC Systems Wiki!
Jump to: navigation, search
m (APC file)
m (Probe Syntax)
Line 34: Line 34:
  
 
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 ('''/*''' ... '''<nowiki>*/</nowiki>''') which may ''not'' be nested.<br /> C style comments (everything from '''//''' to the end of a line) are also supported.
  <nowiki>
+
   
 
  probe ::= probe_specification [ probe_name ] |
 
  probe ::= probe_specification [ probe_name ] |
 
     probe_type
 
     probe_type
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
 
</nowiki>
 
  
 
== APD file ==
 
== APD file ==

Revision as of 21:43, 8 May 2017

Next Previous Top Contents Index

Aprobe User Guide

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

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

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-9.html#MARKER-9-1075 aprobe] tool in order to add its executable content to the executable being probed. The same UAL files are input to [aprobe-9.html#MARKER-9-1035 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-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.

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