Add some comments + cleanup + using log categories (at least partially)

Author: fabianbs96

include/phasar/PhasarLLVM/ControlFlow/CFGBase.h

@@ -29,37 +29,52 @@ template <typename Derived> class CFGBase {
   using n_t = typename CFGTraits<Derived>::n_t;
   using f_t = typename CFGTraits<Derived>::f_t;
 
+  /// Returns the function where the given instruction is defined
   [[nodiscard]] f_t getFunctionOf(ByConstRef<n_t> Inst) const noexcept {
     return self().getFunctionOfImpl(Inst);
   }
+  /// Returns an iterable range of all predecessor instructions of Inst in the
+  /// CFG
   [[nodiscard]] decltype(auto) getPredsOf(ByConstRef<n_t> Inst) const {
     static_assert(
         is_iterable_over_v<decltype(self().getPredsOfImpl(Inst)), n_t>);
     return self().getPredsOfImpl(Inst);
   }
+  /// Returns an iterable range of all successor instructions of Inst in the
+  /// CFG. NOTE: This function is typically being caled in a hot part of the
+  /// analysis and should therefore be highly optimized for performance
   [[nodiscard]] decltype(auto) getSuccsOf(ByConstRef<n_t> Inst) const {
     static_assert(
         is_iterable_over_v<decltype(self().getSuccsOfImpl(Inst)), n_t>);
     return self().getSuccsOfImpl(Inst);
   }
+  /// Returns an iterable range of all edges in the CFG of the given function
   [[nodiscard]] decltype(auto)
   getAllControlFlowEdges(ByConstRef<f_t> Fun) const {
     static_assert(
         is_iterable_over_v<decltype(self().getAllControlFlowEdgesImpl(Fun)),
                            std::pair<n_t, n_t>>);
     return self().getAllControlFlowEdgesImpl(Fun);
   }
+  /// Returns an iterable range of all instructions of the given function. NOTE:
+  /// even if the CFG is initialized to ignore debugging instructions, they may
+  /// be contained here.
   [[nodiscard]] decltype(auto) getAllInstructionsOf(ByConstRef<f_t> Fun) const {
     static_assert(
         is_iterable_over_v<decltype(self().getAllInstructionsOfImpl(Fun)),
                            n_t>);
     return self().getAllInstructionsOfImpl(Fun);
   }
+  /// Returns an iterable range of all starting instructions of the given
+  /// function. For a forward-CFG, this is typically a singleton range
   [[nodiscard]] decltype(auto) getStartPointsOf(ByConstRef<f_t> Fun) const {
     static_assert(
         is_iterable_over_v<decltype(self().getStartPointsOfImpl(Fun)), n_t>);
     return self().getStartPointsOfImpl(Fun);
   }
+  /// Returns an iterable range of all exit instructions (often return
+  /// instructions) of the given function. For a backward-CFG, this is typically
+  /// a singleton range
   [[nodiscard]] decltype(auto) getExitPointsOf(ByConstRef<f_t> Fun) const {
     static_assert(
         is_iterable_over_v<decltype(self().getExitPointsOfImpl(Fun)), n_t>);

include/phasar/PhasarLLVM/ControlFlow/ICFGBase.h

@@ -31,57 +31,84 @@ template <typename Derived> class ICFGBase {
                   "An ICFG must also be a CFG");
   }
 
+  /// Returns an iterable range of all function definitions or declarations in
+  /// the ICFG
   [[nodiscard]] decltype(auto) getAllFunctions() const {
     return self().getAllFunctionsImpl();
   }
 
+  /// returns the function definition or declaration with the given name. If
+  /// ther eis no such function, returns a default constructed f_t (nullptr for
+  /// pointers).
   [[nodiscard]] f_t getFunction(llvm::StringRef Fun) const {
     return self().getFunctionImpl(Fun);
   }
 
+  /// Returns true, iff the given instruction is a call-site where the callee is
+  /// called via a function-pointer or another kind of virtual call.
+  /// NOTE: Trivial cases where a bitcast of a function is called may still
+  /// count as indirect call.
   [[nodiscard]] bool isIndirectFunctionCall(ByConstRef<n_t> Inst) const {
     return self().isIndirectFunctionCallImpl(Inst);
   }
+  /// Returns true, iff the given instruction is a call-site where the callee is
+  /// called via virtual dispatch. NOTE: Here, a class-hierarchy is required and
+  /// a simple function-pointer is not sufficient.
   [[nodiscard]] bool isVirtualFunctionCall(ByConstRef<n_t> Inst) const {
     return self().isVirtualFunctionCallImpl(Inst);
   }
+  /// Returns an iterable range of all instructions in all functions of the ICFG
+  /// that are neither call-sites nor start-points of a function
   [[nodiscard]] decltype(auto) allNonCallStartNodes() const {
     static_assert(
         is_iterable_over_v<decltype(self().allNonCallStartNodesImpl()), n_t>);
     return self().allNonCallStartNodesImpl();
   }
+  /// Returns an iterable range of all possible callee candidates at the given
+  /// call-site induced by the used call-graph. NOTE: This function is typically
+  /// called in a hot part of the analysis any should therefore be very fast
   [[nodiscard]] decltype(auto) getCalleesOfCallAt(ByConstRef<n_t> Inst) const {
     static_assert(
         is_iterable_over_v<decltype(self().getCalleesOfCallAtImpl(Inst)), f_t>);
     return self().getCalleesOfCallAtImpl(Inst);
   }
+  /// Returns an iterable range of all possible call-site candidates that may
+  /// call the given function induced by the used call-graph.
   [[nodiscard]] decltype(auto) getCallersOf(ByConstRef<f_t> Fun) const {
     static_assert(
         is_iterable_over_v<decltype(self().getCallersOfImpl(Fun)), n_t>);
     return self().getCallersOfImpl(Fun);
   }
+  /// Returns an iterable range of all call-instruction in the given function
   [[nodiscard]] decltype(auto) getCallsFromWithin(ByConstRef<f_t> Fun) const {
     static_assert(
         is_iterable_over_v<decltype(self().getCallsFromWithinImpl(Fun)), n_t>);
     return self().getCallsFromWithinImpl(Fun);
   }
+  /// Returns an iterable range of all return-sites of the given
+  /// call-instruction. Often the same as getSuccsOf. NOTE: This function is
+  /// typically called in a hot part of the analysis and should therefore be
+  /// very fast
   [[nodiscard]] decltype(auto)
   getReturnSitesOfCallAt(ByConstRef<n_t> Inst) const {
     static_assert(
         is_iterable_over_v<decltype(self().getReturnSitesOfCallAtImpl(Inst)),
                            n_t>);
     return self().getReturnSitesOfCallAtImpl(Inst);
   }
+  /// Returns an iterable range of all global initializer functions
   [[nodiscard]] decltype(auto)
   getGlobalInitializers(ByConstRef<f_t> Fun) const {
     static_assert(
         is_iterable_over_v<decltype(self().getGlobalInitializersImpl(Fun)),
                            f_t>);
     return self().getGlobalInitializersImpl(Fun);
   }
+  /// Prints the underlying call-graph as DOT to the given output-stream
   void print(llvm::raw_ostream &OS = llvm::outs()) const {
     self().printImpl(OS);
   }
+  /// Returns the underlying call-graph as JSON
   [[nodiscard]] nlohmann::json getAsJson() const {
     return self().getAsJsonImpl();
   }
@@ -93,7 +120,10 @@ template <typename Derived> class ICFGBase {
   }
 };
 
+/// True, iff ICF is a proper instantiation of ICFGBase with n_t and f_t taken
+/// from the given analysis-Domain
 template <typename ICF, typename Domain>
+// NOLINTNEXTLINE(readability-identifier-naming)
 constexpr bool is_icfg_v = is_crtp_base_of_v<ICFGBase, ICF>
     &&std::is_same_v<typename ICF::n_t, typename Domain::n_t>
         &&std::is_same_v<typename ICF::f_t, typename Domain::f_t>;

include/phasar/PhasarLLVM/ControlFlow/LLVMBasedICFG.h

@@ -69,6 +69,24 @@ class LLVMBasedICFG : public LLVMBasedCFG, public ICFGBase<LLVMBasedICFG> {
   static constexpr llvm::StringLiteral GlobalCRuntimeModelName =
       "__psrCRuntimeGlobalCtorsModel";
 
+  /// Constructs the ICFG based on the given IRDB and the entry-points using a
+  /// fixpoint iteration. This may take a long time.
+  ///
+  /// \param IRDB The IR code where the ICFG should be based on. Must not be
+  /// nullptr.
+  /// \param CGType The analysis kind to use for call-graph resolution
+  /// \param EntryPoints The names of the functions to start with when
+  /// incrementally building up the ICFG. For whole-program analysis of an
+  /// executable use {"main"}.
+  /// \param TH The type-hierarchy implementation to use. Will be constructed
+  /// on-the-fly if nullptr, but required
+  /// \param PT The points-to implementation to use. Will be constructed
+  /// on-the-fly if nullptr, but required
+  /// \param S The soundness level to expect from the analysis. Currently unused
+  /// \param IncludeGlobals Properly include global constructors/destructors
+  /// into the ICFG, if true. Requires to generate artificial functions into the
+  /// IRDB. True by default
+
   explicit LLVMBasedICFG(ProjectIRDB *IRDB, CallGraphAnalysisType CGType,
                          llvm::ArrayRef<std::string> EntryPoints = {},
                          LLVMTypeHierarchy *TH = nullptr,
@@ -84,14 +102,22 @@ class LLVMBasedICFG : public LLVMBasedCFG, public ICFGBase<LLVMBasedICFG> {
   LLVMBasedICFG(LLVMBasedICFG &&) noexcept = delete;
   LLVMBasedICFG &operator=(LLVMBasedICFG &&) noexcept = delete;
 
+  /// Exports the whole ICFG (not only the call-graph) as DOT.
+  ///
+  /// \param WithSourceCodeInfo If true, not only contains the LLVM instructions
+  /// as labels, but source-code information as well (e.g. function name, line
+  /// no, col no, src-line).
   [[nodiscard]] std::string
   exportICFGAsDot(bool WithSourceCodeInfo = true) const;
+  /// Similar to exportICFGAsDot, but exports the ICFG as JSON instead
   [[nodiscard]] nlohmann::json
   exportICFGAsJson(bool WithSourceCodeInfo = true) const;
 
-  [[nodiscard]] const llvm::SmallVectorImpl<f_t> &
-  getAllVertexFunctions() const noexcept;
+  /// Returns all functions from the underlying IRDB that are part of the ICFG,
+  /// i.e. that are reachable from the entry-points
+  [[nodiscard]] llvm::ArrayRef<f_t> getAllVertexFunctions() const noexcept;
 
+  /// Gets the underlying IRDB
   [[nodiscard]] ProjectIRDB *getIRDB() const noexcept { return IRDB; }
 
   using CFGBase::print;
@@ -131,8 +157,6 @@ class LLVMBasedICFG : public LLVMBasedCFG, public ICFGBase<LLVMBasedICFG> {
                    llvm::SmallVector<const llvm::Function *> *Callees,
                    const llvm::Function *Callee);
 
-  /// The call graph.
-
 #if HAS_MEMORY_RESOURCE
   std::pmr::monotonic_buffer_resource MRes;
 #else

include/phasar/PhasarLLVM/Utils/LLVMBasedContainerConfig.h

@@ -11,7 +11,6 @@
 #define PHASAR_PHASARLLVM_UTILS_LLVMBASEDCONTAINERCONFIG_H
 
 #include "llvm/ADT/STLExtras.h"
-#include "llvm/ADT/iterator.h"
 #include "llvm/ADT/iterator_range.h"
 #include "llvm/IR/Module.h"
 

include/phasar/Utils/Logger.h

@@ -17,6 +17,7 @@
 #include <variant>
 
 #include "llvm/ADT/StringMap.h"
+#include "llvm/ADT/StringRef.h"
 #include "llvm/Support/Compiler.h" // LLVM_UNLIKELY
 #include "llvm/Support/ErrorHandling.h"
 #include "llvm/Support/raw_ostream.h"
@@ -29,6 +30,8 @@ enum SeverityLevel {
   INVALID
 };
 
+SeverityLevel parseSeverityLevel(llvm::StringRef Str);
+
 class Logger final {
 public:
   /**

lib/PhasarLLVM/ControlFlow/LLVMBasedCFG.cpp

@@ -108,13 +108,8 @@ auto detail::LLVMBasedCFGImpl<Derived>::getAllControlFlowEdgesImpl(
   for (const auto &I : llvm::instructions(Fun)) {
     if (IgnoreDbgInstructions) {
       // Check for call to intrinsic debug function
-      if (const auto *DbgCallInst = llvm::dyn_cast<llvm::CallInst>(&I)) {
-        if (DbgCallInst->getCalledFunction() &&
-            DbgCallInst->getCalledFunction()->isIntrinsic() &&
-            (DbgCallInst->getCalledFunction()->getName() ==
-             "llvm.dbg.declare")) {
-          continue;
-        }
+      if (llvm::isa<llvm::DbgInfoIntrinsic>(&I)) {
+        continue;
       }
     }