docs/CommandGuide/llvm-bcanalyzer.pod

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