[Next] [Previous] [Top] [Contents] [Index]
Aprobe
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 where the PDB file is not delivered). The ADI file is generated from an executable or DLL 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 program without debug information.
An ADI file is binary file whose format is not specified. Its name must end in .adi.
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 Visual C++, links it with the Aprobe shared library and other object code, to produce a UAL file, which is a DLL.
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" in Chapter 3) 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 or, for advanced features, in Aprobe\probes.
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 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 Appendix A, "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.
The default size of a single APD file is 1M.
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.
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.
User Action Library File
A UAL file is a DLL created by the apc command by invoking the link 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.
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
>
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 Chapter 5, "Writing Java Probes" for more information.