Document definitions and computations provided by llvm-bcanalyzer.

llvm-svn: 16044

docs/CommandGuide/llvm-bcanalyzer.pod

@@ -25,6 +25,7 @@ Output is written to the standard output.
 
 =head1 OPTIONS
 
+
 =over
 
 =item B<-nodetails>
@@ -55,12 +56,262 @@ Print a summary of command line options.
 If B<llvm-bcanalyzer> succeeds, it will exit with 0.  Otherwise, if an error
 occurs, it will exit with a non-zero value, usually 1.
 
+=head1 SUMMARY OUTPUT DEFINITIONS
+
+The following items are always printed by llvm-bcanalyzer. They comprize the
+summary output.
+
+=over
+
+=item B<Bytecode Analysis Of Module>
+
+This just provides the name of the module for which bytecode analysis is being
+generated.
+
+=item B<Bytecode Version Number>
+
+The bytecode version (not LLVM version) of the file read by the analyzer.
+
+=item B<File Size>
+
+The size, in bytes, of the entire bytecode file.
+
+=item B<Module Bytes>
+
+The size, in bytes, of the module block. Percentage is relative to File Size.
+
+=item B<Function Bytes>
+
+The size, in bytes, of all the function blocks. Percentage is relative to File
+Size.
+
+=item B<Global Types Bytes>
+
+The size, in bytes, of the Global Types Pool. Percentage is relative to File
+Size. This is the size of the definitions of all types in the bytecode file.
+
+=item B<Constant Pool Bytes>
+
+The size, in bytes, of the Constant Pool Blocks Percentage is relative to File
+Size.
+
+=item B<Module Globals Bytes>
+
+Ths size, in bytes, of the Global Variable Definitions and their initializers.
+Percentage is relative to File Size.
+
+=item B<Instruction List Bytes>
+
+The size, in bytes, of all the instruction lists in all the functions.
+Percentage is relative to File Size. Note that this value is also included in
+the Function Bytes.
+
+=item B<Compaction Table Bytes>
+
+The size, in bytes, of all the compaction tables in all the functions.
+Percentage is relative to File Size. Note that this value is also included in
+the Function Bytes.
+
+=item B<Compaction Table Bytes>
+
+The size, in bytes, of all the symbol tables in all the functions. Percentage is
+relative to File Size. Note that this value is also included in the Function
+Bytes.
+
+=item B<Dependent Libraries Bytes>
+
+The size, in bytes, of the list of dependent libraries in the module. Percentage
+is relative to File Size. Note that this value is also included in the Module
+Global Bytes.
+
+=item B<Number Of Bytecode Blocks>
+
+The total number of blocks of any kind in the bytecode file.
+
+=item B<Number Of Functions>
+
+The total number of function definitions in the bytecode file.
+
+=item B<Number Of Types>
+
+The total number of types defined in the Global Types Pool.
+
+=item B<Number Of Constants>
+
+The total number of constants (of any type) defined in the Constant Pool.
+
+=item B<Number Of Basic Blocks>
+
+The total number of basic blocks defined in all functions in the bytecode file.
+
+=item B<Number Of Instructions>
+
+The total number of instructions defined in all functions in the bytecode file.
+
+=item B<Number Of Long Instructions>
+
+The total number of long instructions defined in all functions in the bytecode
+file. Long instructions are those taking greater than 4 bytes. Typically long
+instructions are GetElementPtr with several indices, PHI nodes, and calls to
+functions with large numbers of arguments.
+
+=item B<Number Of Operands>
+
+The total number of operands used in all instructions in the bytecode file.
+
+=item B<Number Of Compaction Tables>
+
+The total number of compaction tables in all functions in the bytecode file.
+
+=item B<Number Of Symbol Tables>
+
+The total number of symbol tables in all functions in the bytecode file.
+
+=item B<Number Of Dependent Libs>
+
+The total number of dependent libraries found in the bytecode file.
+
+=item B<Total Instruction Size>
+
+The total size of the instructions in all functions in the bytecode file.
+
+=item B<Average Instruction Size>
+
+The average number of bytes per instruction across all functions in the bytecode
+file. This value is computed by dividing Total Instruction Size by Number Of
+Instructions.
+
+=item B<Maximum Type Slot Number>
+
+The maximum value used for a type's slot number. Larger slot number values take 
+more bytes to encode.
+
+=item B<Maximum Value Slot Number>
+
+The maximum value used for a value's slot number. Larger slot number values take 
+more bytes to encode.
+
+=item B<Bytes Per Value>
+
+The average size of a Value definition (of any type). This is computed by
+dividing File Size by the total number of values of any type.
+
+=item B<Bytes Per Global>
+
+The average size of a global definition (constants and global variables).
+
+=item B<Bytes Per Function>
+
+The average number of bytes per function definition. This is computed by
+dividing Function Bytes by Number Of Functions.
+
+=item B<# of VBR 32-bit Integers>
+
+The total number of 32-bit integers encoded using the Variable Bit Rate
+encoding scheme.
+
+=item B<# of VBR 64-bit Integers>
+
+The total number of 64-bit integers encoded using the Variable Bit Rate encoding
+scheme.
+
+=item B<# of VBR Compressed Bytes>
+
+The total number of bytes consumed by the 32-bit and 64-bit integers that use
+the Variable Bit Rate encoding scheme.
+
+=item B<# of VBR Expanded Bytes>
+
+The total number of bytes that would have been consumed by the 32-bit and 64-bit
+integers had they not been compressed with the Variable Bit Rage encoding
+scheme.
+
+=item B<Bytes Saved With VBR>
+
+The total number of bytes saved by using the Variable Bit Rate encoding scheme.
+The percentage is relative to # of VBR Expanded Bytes.
+
+=back
+
+=head1 DETAILED OUTPUT DEFINITIONS
+
+The following definitions occur only if the -nodetails option was not given.
+The detailed output provides additional information on a per-function basis.
+
+=over
+
+=item B<Type>
+
+The type signature of the function.
+
+=item B<Byte Size>
+
+The total number of bytes in the function's block.
+
+=item B<Basic Blocks>
+
+The number of basic blocks defined by the function.
+
+=item B<Instructions>
+
+The number of instructions defined by the function.
+
+=item B<Long Instructions>
+
+The number of instructions using the long instruction format in the function.
+
+=item B<Operands>
+
+The number of operands used by all instructions in the function.
+
+=item B<Instruction Size>
+
+The number of bytes consumed by instructions in the function.
+
+=item B<Average Instruction Size>
+
+The average number of bytes consumed by the instructions in the funtion. This
+value is computed by dividing Instruction Size by Instructions.
+
+=item B<Bytes Per Instruction>
+
+The average number of bytes used by the function per instruction. This value is
+computed by dividing Byte Size by Instructions. Note that this is not the same
+as Average Instruction Size. It computes a number relative to the total function
+size not just the size of the instruction list.
+
+=item B<# of VBR 32-bit Integers>
+
+The total number of 32-bit integers found in this function (for any use).
+
+=item B<# of VBR 64-bit Integers>
+
+The total number of 64-bit integers found in this function (for any use).
+
+=item B<# of VBR Compressed Bytes>
+
+The total number of bytes in this function consumed by the 32-bit and 64-bit 
+integers that use the Variable Bit Rate encoding scheme.
+
+=item B<# of VBR Expanded Bytes>
+
+The total number of bytes in this function that would have been consumed by 
+the 32-bit and 64-bit integers had they not been compressed with the Variable 
+Bit Rate encoding scheme.
+
+=item B<Bytes Saved With VBR>
+
+The total number of bytes saved in this function by using the Variable Bit 
+Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes.
+
+=back
+
 =head1 SEE ALSO
 
 L<llvm-dis|llvm-dis>, L<http://llvm.cs.uiuc.edu/docs/BytecodeFormat.html>
 
 =head1 AUTHORS
 
-Maintained by the LLVM Team (L<http://llvm.cs.uiuc.edu>).
+Maintained by Reid Spencer (L<http://llvm.x10sys.com/rspencer>).
 
 =cut