include/llvm/Bytecode/Analyzer.h

   1 //===-- llvm/Bytecode/Analyzer.h - Analyzer for Bytecode files --*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by Reid Spencer and is distributed under the
   6 // University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This functionality is implemented by the lib/Bytecode/Analysis library.
  11 // This library is used to read VM bytecode files from a file or memory buffer
  12 // and print out a diagnostic analysis of the contents of the file. It is
  13 // intended for three uses: (a) understanding the bytecode format, (b) ensuring
  14 // correctness of bytecode format, (c) statistical analysis of generated
  15 // bytecode files.
  16 //
  17 //===----------------------------------------------------------------------===//
  18
  19 #ifndef LLVM_BYTECODE_ANALYZER_H
  20 #define LLVM_BYTECODE_ANALYZER_H
  21
  22 #include <string>
  23 #include <map>
  24
  25 namespace llvm {
  26
  27 /// This structure is used to contain the output of the Bytecode Analysis
  28 /// library. It simply contains fields to hold each item of the analysis
  29 /// results.
  30 /// @brief Bytecode Analysis results structure
  31 struct BytecodeAnalysis {
  32   unsigned byteSize;            ///< The size of the bytecode file in bytes
  33   unsigned numTypes;        ///< The number of types
  34   unsigned numValues;       ///< The number of values
  35   unsigned numFunctions;    ///< The number of functions defined
  36   unsigned numConstants;    ///< The number of constants
  37   unsigned numGlobalVars;   ///< The number of global variables
  38   unsigned numInstructions; ///< The number of instructions in all functions
  39   unsigned numBasicBlocks;  ///< The number of BBs in all functions
  40   unsigned numOperands;     ///< The number of BBs in all functions
  41   unsigned maxTypeSlot;     ///< The maximum slot number for types
  42   unsigned maxValueSlot;    ///< The maximum slot number for values
  43   double   density;         ///< Density of file (bytes/defs)
  44
  45   /// A structure that contains various pieces of information related to
  46   /// an analysis of a single function.
  47   struct BytecodeFunctionInfo {
  48     unsigned byteSize;        ///< The size of the function in bytecode bytes
  49     unsigned numInstructions; ///< The number of instructions in the function
  50     unsigned numBasicBlocks;  ///< The number of basic blocks in the function
  51     unsigned numOperands;     ///< The number of operands in the function
  52     double density;           ///< Density of function
  53     double vbrEffectiveness;  ///< Effectiveness of variable bit rate encoding.
  54     ///< This is the average number of bytes per unsigned value written in the
  55     ///< vbr encoding. A "perfect" score of 1.0 means all vbr values were
  56     ///< encoded in one byte. A score between 1.0 and 4.0 means that some
  57     ///< savings were achieved. A score of 4.0 means vbr didn't help. A score
  58     ///< greater than 4.0 means vbr negatively impacted size of the file.
  59   };
  60
  61   /// A mapping of function names to the collected information about the
  62   /// function.
  63   std::map<std::string,BytecodeFunctionInfo> FunctionInfo;
  64
  65   /// The content of the bytecode dump
  66   std::string BytecodeDump;
  67
  68   /// Flags for what should be done
  69   bool dumpBytecode;     ///< If true, BytecodeDump has contents
  70   bool detailedResults;  ///< If true, FunctionInfo has contents
  71 };
  72
  73 /// This function is the main entry point into the bytecode analysis library. It
  74 /// allows you to simply provide a \p filename and storage for the \p Results
  75 /// that will be filled in with the analysis results.
  76 /// @brief Analyze contents of a bytecode File
  77 void AnalyzeBytecodeFile(
  78       const std::string& Filename, ///< The name of the bytecode file to read
  79       BytecodeAnalysis& Results,   ///< The results of the analysis
  80       std::string* ErrorStr = 0    ///< Errors, if any.
  81     );
  82
  83 /// This function is an alternate entry point into the bytecode analysis
  84 /// library. It allows you to provide an arbitrary memory buffer which is
  85 /// assumed to contain a complete bytecode file. The \p Buffer is analyzed and
  86 /// the \p Results are filled in.
  87 /// @brief Analyze contents of a bytecode buffer.
  88 void AnalyzeBytecodeBuffer(
  89        const unsigned char* Buffer, ///< Pointer to start of bytecode buffer
  90        unsigned BufferSize,         ///< Size of the bytecode buffer
  91        BytecodeAnalysis& Results,   ///< The results of the analysis
  92        std::string* ErrorStr = 0    ///< Errors, if any.
  93      );
  94
  95 /// This function prints the contents of rhe BytecodeAnalysis structure in
  96 /// a human legible form.
  97 /// @brief Print BytecodeAnalysis structure to an ostream
  98 void PrintBytecodeAnalysis(BytecodeAnalysis& bca, std::ostream& Out );
  99
 100 /// @brief std::ostream inserter for BytecodeAnalysis structure
 101 inline std::ostream& operator<<(std::ostream& Out, BytecodeAnalysis& bca ) {
 102     PrintBytecodeAnalysis(bca,Out);
 103     return Out;
 104 }
 105
 106 } // End llvm namespace
 107
 108 #endif