docs/CommandGuide/llvm-bcanalyzer.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 llvm-bcanalyzer - LLVM bytecode analyzer
   6
   7 =head1 SYNOPSIS
   8
   9 B<llvm-bcanalyzer> [I<options>] [I<filename>]
  10
  11 =head1 DESCRIPTION
  12
  13 The B<llvm-bcanalyzer> command is a small utility for analyzing bytecode files.
  14 The tool reads a bytecode file (such as generated with the B<llvm-as> tool) and
  15 produces a statistical report on the contents of the byteocde file.  The tool
  16 will also dump a low level but human readable version of the bytecode file.
  17 This tool is probably not of much interest or utility except for those working
  18 directly with the bytecode file format. Most LLVM users can just ignore
  19 this tool.
  20
  21 If F<filename> is omitted or is C<->, then B<llvm-bcanalyzer> reads its input
  22 from standard input. This is useful for combining the tool into a pipeline.
  23
  24 Output is written to the standard output.
  25
  26 =head1 OPTIONS
  27
  28
  29 =over
  30
  31 =item B<-nodetails>
  32
  33 Causes B<llvm-bcanalyzer> to abbreviate its output by writing out only a module
  34 level summary. The details for individual functions are not displayed.
  35
  36 =item B<-dump>
  37
  38 Causes B<llvm-bcanalyzer> to dump the bytecode in a human readable format. This
  39 format is significantly different from LLVM assembly and provides details about
  40 the encoding of the bytecode file.
  41
  42 =item B<-verify>
  43
  44 Causes B<llvm-bcanalyzer> to verify the module produced by by reading the
  45 bytecode. This ensures that the statistics generated are based on a consistent
  46 module.
  47
  48 =item B<--help>
  49
  50 Print a summary of command line options.
  51
  52 =back
  53
  54 =head1 EXIT STATUS
  55
  56 If B<llvm-bcanalyzer> succeeds, it will exit with 0.  Otherwise, if an error
  57 occurs, it will exit with a non-zero value, usually 1.
  58
  59 =head1 SUMMARY OUTPUT DEFINITIONS
  60
  61 The following items are always printed by llvm-bcanalyzer. They comprize the
  62 summary output.
  63
  64 =over
  65
  66 =item B<Bytecode Analysis Of Module>
  67
  68 This just provides the name of the module for which bytecode analysis is being
  69 generated.
  70
  71 =item B<Bytecode Version Number>
  72
  73 The bytecode version (not LLVM version) of the file read by the analyzer.
  74
  75 =item B<File Size>
  76
  77 The size, in bytes, of the entire bytecode file.
  78
  79 =item B<Module Bytes>
  80
  81 The size, in bytes, of the module block. Percentage is relative to File Size.
  82
  83 =item B<Function Bytes>
  84
  85 The size, in bytes, of all the function blocks. Percentage is relative to File
  86 Size.
  87
  88 =item B<Global Types Bytes>
  89
  90 The size, in bytes, of the Global Types Pool. Percentage is relative to File
  91 Size. This is the size of the definitions of all types in the bytecode file.
  92
  93 =item B<Constant Pool Bytes>
  94
  95 The size, in bytes, of the Constant Pool Blocks Percentage is relative to File
  96 Size.
  97
  98 =item B<Module Globals Bytes>
  99
 100 Ths size, in bytes, of the Global Variable Definitions and their initializers.
 101 Percentage is relative to File Size.
 102
 103 =item B<Instruction List Bytes>
 104
 105 The size, in bytes, of all the instruction lists in all the functions.
 106 Percentage is relative to File Size. Note that this value is also included in
 107 the Function Bytes.
 108
 109 =item B<Compaction Table Bytes>
 110
 111 The size, in bytes, of all the compaction tables in all the functions.
 112 Percentage is relative to File Size. Note that this value is also included in
 113 the Function Bytes.
 114
 115 =item B<Compaction Table Bytes>
 116
 117 The size, in bytes, of all the symbol tables in all the functions. Percentage is
 118 relative to File Size. Note that this value is also included in the Function
 119 Bytes.
 120
 121 =item B<Dependent Libraries Bytes>
 122
 123 The size, in bytes, of the list of dependent libraries in the module. Percentage
 124 is relative to File Size. Note that this value is also included in the Module
 125 Global Bytes.
 126
 127 =item B<Number Of Bytecode Blocks>
 128
 129 The total number of blocks of any kind in the bytecode file.
 130
 131 =item B<Number Of Functions>
 132
 133 The total number of function definitions in the bytecode file.
 134
 135 =item B<Number Of Types>
 136
 137 The total number of types defined in the Global Types Pool.
 138
 139 =item B<Number Of Constants>
 140
 141 The total number of constants (of any type) defined in the Constant Pool.
 142
 143 =item B<Number Of Basic Blocks>
 144
 145 The total number of basic blocks defined in all functions in the bytecode file.
 146
 147 =item B<Number Of Instructions>
 148
 149 The total number of instructions defined in all functions in the bytecode file.
 150
 151 =item B<Number Of Long Instructions>
 152
 153 The total number of long instructions defined in all functions in the bytecode
 154 file. Long instructions are those taking greater than 4 bytes. Typically long
 155 instructions are GetElementPtr with several indices, PHI nodes, and calls to
 156 functions with large numbers of arguments.
 157
 158 =item B<Number Of Operands>
 159
 160 The total number of operands used in all instructions in the bytecode file.
 161
 162 =item B<Number Of Compaction Tables>
 163
 164 The total number of compaction tables in all functions in the bytecode file.
 165
 166 =item B<Number Of Symbol Tables>
 167
 168 The total number of symbol tables in all functions in the bytecode file.
 169
 170 =item B<Number Of Dependent Libs>
 171
 172 The total number of dependent libraries found in the bytecode file.
 173
 174 =item B<Total Instruction Size>
 175
 176 The total size of the instructions in all functions in the bytecode file.
 177
 178 =item B<Average Instruction Size>
 179
 180 The average number of bytes per instruction across all functions in the bytecode
 181 file. This value is computed by dividing Total Instruction Size by Number Of
 182 Instructions.
 183
 184 =item B<Maximum Type Slot Number>
 185
 186 The maximum value used for a type's slot number. Larger slot number values take
 187 more bytes to encode.
 188
 189 =item B<Maximum Value Slot Number>
 190
 191 The maximum value used for a value's slot number. Larger slot number values take
 192 more bytes to encode.
 193
 194 =item B<Bytes Per Value>
 195
 196 The average size of a Value definition (of any type). This is computed by
 197 dividing File Size by the total number of values of any type.
 198
 199 =item B<Bytes Per Global>
 200
 201 The average size of a global definition (constants and global variables).
 202
 203 =item B<Bytes Per Function>
 204
 205 The average number of bytes per function definition. This is computed by
 206 dividing Function Bytes by Number Of Functions.
 207
 208 =item B<# of VBR 32-bit Integers>
 209
 210 The total number of 32-bit integers encoded using the Variable Bit Rate
 211 encoding scheme.
 212
 213 =item B<# of VBR 64-bit Integers>
 214
 215 The total number of 64-bit integers encoded using the Variable Bit Rate encoding
 216 scheme.
 217
 218 =item B<# of VBR Compressed Bytes>
 219
 220 The total number of bytes consumed by the 32-bit and 64-bit integers that use
 221 the Variable Bit Rate encoding scheme.
 222
 223 =item B<# of VBR Expanded Bytes>
 224
 225 The total number of bytes that would have been consumed by the 32-bit and 64-bit
 226 integers had they not been compressed with the Variable Bit Rage encoding
 227 scheme.
 228
 229 =item B<Bytes Saved With VBR>
 230
 231 The total number of bytes saved by using the Variable Bit Rate encoding scheme.
 232 The percentage is relative to # of VBR Expanded Bytes.
 233
 234 =back
 235
 236 =head1 DETAILED OUTPUT DEFINITIONS
 237
 238 The following definitions occur only if the -nodetails option was not given.
 239 The detailed output provides additional information on a per-function basis.
 240
 241 =over
 242
 243 =item B<Type>
 244
 245 The type signature of the function.
 246
 247 =item B<Byte Size>
 248
 249 The total number of bytes in the function's block.
 250
 251 =item B<Basic Blocks>
 252
 253 The number of basic blocks defined by the function.
 254
 255 =item B<Instructions>
 256
 257 The number of instructions defined by the function.
 258
 259 =item B<Long Instructions>
 260
 261 The number of instructions using the long instruction format in the function.
 262
 263 =item B<Operands>
 264
 265 The number of operands used by all instructions in the function.
 266
 267 =item B<Instruction Size>
 268
 269 The number of bytes consumed by instructions in the function.
 270
 271 =item B<Average Instruction Size>
 272
 273 The average number of bytes consumed by the instructions in the funtion. This
 274 value is computed by dividing Instruction Size by Instructions.
 275
 276 =item B<Bytes Per Instruction>
 277
 278 The average number of bytes used by the function per instruction. This value is
 279 computed by dividing Byte Size by Instructions. Note that this is not the same
 280 as Average Instruction Size. It computes a number relative to the total function
 281 size not just the size of the instruction list.
 282
 283 =item B<# of VBR 32-bit Integers>
 284
 285 The total number of 32-bit integers found in this function (for any use).
 286
 287 =item B<# of VBR 64-bit Integers>
 288
 289 The total number of 64-bit integers found in this function (for any use).
 290
 291 =item B<# of VBR Compressed Bytes>
 292
 293 The total number of bytes in this function consumed by the 32-bit and 64-bit
 294 integers that use the Variable Bit Rate encoding scheme.
 295
 296 =item B<# of VBR Expanded Bytes>
 297
 298 The total number of bytes in this function that would have been consumed by
 299 the 32-bit and 64-bit integers had they not been compressed with the Variable
 300 Bit Rate encoding scheme.
 301
 302 =item B<Bytes Saved With VBR>
 303
 304 The total number of bytes saved in this function by using the Variable Bit
 305 Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes.
 306
 307 =back
 308
 309 =head1 SEE ALSO
 310
 311 L<llvm-dis|llvm-dis>, L<http://llvm.cs.uiuc.edu/docs/BytecodeFormat.html>
 312
 313 =head1 AUTHORS
 314
 315 Maintained by Reid Spencer (L<http://llvm.x10sys.com/rspencer>).
 316
 317 =cut