include/llvm/ExecutionEngine/RuntimeDyldChecker.h

   1 //===---- RuntimeDyldChecker.h - RuntimeDyld tester framework -----*- C++ -*-=//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef LLVM_EXECUTIONENGINE_RUNTIMEDYLDCHECKER_H
  10 #define LLVM_EXECUTIONENGINE_RUNTIMEDYLDCHECKER_H
  11
  12 #include "llvm/ADT/Optional.h"
  13
  14 #include <cstdint>
  15 #include <memory>
  16 #include <string>
  17 #include <utility>
  18
  19 namespace llvm {
  20
  21 class StringRef;
  22 class MCDisassembler;
  23 class MemoryBuffer;
  24 class MCInstPrinter;
  25 class RuntimeDyld;
  26 class RuntimeDyldCheckerImpl;
  27 class raw_ostream;
  28
  29 /// RuntimeDyld invariant checker for verifying that RuntimeDyld has
  30 ///        correctly applied relocations.
  31 ///
  32 /// The RuntimeDyldChecker class evaluates expressions against an attached
  33 /// RuntimeDyld instance to verify that relocations have been applied
  34 /// correctly.
  35 ///
  36 /// The expression language supports basic pointer arithmetic and bit-masking,
  37 /// and has limited disassembler integration for accessing instruction
  38 /// operands and the next PC (program counter) address for each instruction.
  39 ///
  40 /// The language syntax is:
  41 ///
  42 /// check = expr '=' expr
  43 ///
  44 /// expr = binary_expr
  45 ///      | sliceable_expr
  46 ///
  47 /// sliceable_expr = '*{' number '}' load_addr_expr [slice]
  48 ///                | '(' expr ')' [slice]
  49 ///                | ident_expr [slice]
  50 ///                | number [slice]
  51 ///
  52 /// slice = '[' high-bit-index ':' low-bit-index ']'
  53 ///
  54 /// load_addr_expr = symbol
  55 ///                | '(' symbol '+' number ')'
  56 ///                | '(' symbol '-' number ')'
  57 ///
  58 /// ident_expr = 'decode_operand' '(' symbol ',' operand-index ')'
  59 ///            | 'next_pc'        '(' symbol ')'
  60 ///            | 'stub_addr' '(' file-name ',' section-name ',' symbol ')'
  61 ///            | symbol
  62 ///
  63 /// binary_expr = expr '+' expr
  64 ///             | expr '-' expr
  65 ///             | expr '&' expr
  66 ///             | expr '|' expr
  67 ///             | expr '<<' expr
  68 ///             | expr '>>' expr
  69 ///
  70 class RuntimeDyldChecker {
  71 public:
  72   RuntimeDyldChecker(RuntimeDyld &RTDyld, MCDisassembler *Disassembler,
  73                      MCInstPrinter *InstPrinter, raw_ostream &ErrStream);
  74   ~RuntimeDyldChecker();
  75
  76   // Get the associated RTDyld instance.
  77   RuntimeDyld& getRTDyld();
  78
  79   // Get the associated RTDyld instance.
  80   const RuntimeDyld& getRTDyld() const;
  81
  82   /// Check a single expression against the attached RuntimeDyld
  83   ///        instance.
  84   bool check(StringRef CheckExpr) const;
  85
  86   /// Scan the given memory buffer for lines beginning with the string
  87   ///        in RulePrefix. The remainder of the line is passed to the check
  88   ///        method to be evaluated as an expression.
  89   bool checkAllRulesInBuffer(StringRef RulePrefix, MemoryBuffer *MemBuf) const;
  90
  91   /// Returns the address of the requested section (or an error message
  92   ///        in the second element of the pair if the address cannot be found).
  93   ///
  94   /// if 'LocalAddress' is true, this returns the address of the section
  95   /// within the linker's memory. If 'LocalAddress' is false it returns the
  96   /// address within the target process (i.e. the load address).
  97   std::pair<uint64_t, std::string> getSectionAddr(StringRef FileName,
  98                                                   StringRef SectionName,
  99                                                   bool LocalAddress);
 100
 101   /// If there is a section at the given local address, return its load
 102   ///        address, otherwise return none.
 103   Optional<uint64_t> getSectionLoadAddress(void *LocalAddress) const;
 104
 105 private:
 106   std::unique_ptr<RuntimeDyldCheckerImpl> Impl;
 107 };
 108
 109 } // end namespace llvm
 110
 111 #endif