[mc] Document/clean DwarfExpression

diff --git a/src/mc/DwarfExpression.cpp b/src/mc/DwarfExpression.cpp
index ecedcb2..6c90f31 100644 (file)
--- a/src/mc/DwarfExpression.cpp
+++ b/src/mc/DwarfExpression.cpp
@@ -70,11 +70,12 @@ void execute(
     case DW_OP_breg29:
     case DW_OP_breg30:
     case DW_OP_breg31:{
     case DW_OP_breg29:
     case DW_OP_breg30:
     case DW_OP_breg31:{

+        // Push register + constant:

         int register_id = simgrid::dwarf::dwarf_register_to_libunwind(
           op->atom - DW_OP_breg0);
         unw_word_t res;
         if (!context.cursor)
         int register_id = simgrid::dwarf::dwarf_register_to_libunwind(
           op->atom - DW_OP_breg0);
         unw_word_t res;
         if (!context.cursor)

-          throw evaluation_error("Missin stack context");
+          throw evaluation_error("Missing stack context");

         unw_get_reg(context.cursor, register_id, &res);
         stack.push(res + op->number);
         break;
         unw_get_reg(context.cursor, register_id, &res);
         stack.push(res + op->number);
         break;


@@ -117,7 +118,6 @@ void execute(
       // ***** Constants:
 
       // Short constant literals:
       // ***** Constants:
 
       // Short constant literals:

-      // DW_OP_lit15 pushed the 15 on the stack.

     case DW_OP_lit0:
     case DW_OP_lit1:
     case DW_OP_lit2:
     case DW_OP_lit0:
     case DW_OP_lit1:
     case DW_OP_lit2:


@@ -150,6 +150,7 @@ void execute(
     case DW_OP_lit29:
     case DW_OP_lit30:
     case DW_OP_lit31:
     case DW_OP_lit29:
     case DW_OP_lit30:
     case DW_OP_lit31:

+      // Push a literal/constant on the stack:

       stack.push(atom - DW_OP_lit0);
       break;
 
       stack.push(atom - DW_OP_lit0);
       break;
 


@@ -191,9 +192,8 @@ void execute(
       stack.pop();
       break;
 
       stack.pop();
       break;
 

-      // Swap the two top-most value of the stack:

     case DW_OP_swap:
     case DW_OP_swap:

-      std::swap(stack.top(), stack.top(1));
+      stack.swap();

       break;
 
       // Duplicate the value under the top of the stack:
       break;
 
       // Duplicate the value under the top of the stack:

diff --git a/src/mc/DwarfExpression.hpp b/src/mc/DwarfExpression.hpp
index aa6d888..fda5c6a 100644 (file)
--- a/src/mc/DwarfExpression.hpp
+++ b/src/mc/DwarfExpression.hpp
@@ -8,34 +8,58 @@
 #define SIMGRID_MC_DWARF_EXPRESSION_HPP
 
 #include <cstdint>
 #define SIMGRID_MC_DWARF_EXPRESSION_HPP
 
 #include <cstdint>

-
+#include <cstdlib>

 #include <stdexcept>
 
 #include "src/mc/AddressSpace.hpp"
 
 #include <stdexcept>
 
 #include "src/mc/AddressSpace.hpp"
 

+/** @file DwarfExession.hpp
+ *
+ *  Evaluation of DWARF location expressions
+ */
+

 namespace simgrid {
 namespace dwarf {
 
 namespace simgrid {
 namespace dwarf {
 

-class evaluation_error : std::runtime_error {
-public:
-  evaluation_error(const char* what): std::runtime_error(what) {}
-  ~evaluation_error() noexcept(true);
-};
+/** A DWARF expression
+ *
+ *  DWARF defines a simple stack-based VM for evaluating expressions
+ *  (such as locations of variables, etc.): A DWARF expressions is
+ *  just a sequence of dwarf instructions. We currently directly use
+ *  `Dwarf_Op` from `dwarf.h` for dwarf instructions.
+ */
+typedef std::vector<Dwarf_Op> DwarfExpression;

 
 

+/** Context of evaluation of a DWARF expression
+ *
+ *  Some DWARF instructions need to read the CPU registers,
+ *  the process memory, etc. All those informations are gathered in
+ *  the evaluation context.
+ */

 struct ExpressionContext {
   ExpressionContext() :
     cursor(nullptr), frame_base(nullptr), address_space(nullptr),
     object_info(nullptr), process_index(simgrid::mc::ProcessIndexMissing) {}
 struct ExpressionContext {
   ExpressionContext() :
     cursor(nullptr), frame_base(nullptr), address_space(nullptr),
     object_info(nullptr), process_index(simgrid::mc::ProcessIndexMissing) {}

-    
+  /** CPU state (registers) */

   unw_cursor_t* cursor;
   void* frame_base;
   unw_cursor_t* cursor;
   void* frame_base;

+  /** Address space used to read memory */

   simgrid::mc::AddressSpace* address_space;
   simgrid::mc::ObjectInformation* object_info;
   int process_index;
 };
 
   simgrid::mc::AddressSpace* address_space;
   simgrid::mc::ObjectInformation* object_info;
   int process_index;
 };
 

-typedef std::vector<Dwarf_Op> DwarfExpression;
+/** When an error happens in the execution of a DWARF expression */
+class evaluation_error : std::runtime_error {
+public:
+  evaluation_error(const char* what): std::runtime_error(what) {}
+  ~evaluation_error() noexcept(true);
+};

 
 

+/** A stack for evaluating a DWARF expression
+ *
+ *  DWARF expressions work by manipulating a stack of integer values.
+ */

 class ExpressionStack {
 public:
   typedef std::uintptr_t value_type;
 class ExpressionStack {
 public:
   typedef std::uintptr_t value_type;


@@ -52,12 +76,16 @@ public:
   void clear()             { size_ = 0; }
   uintptr_t&       operator[](int i)       { return stack_[i]; }
   uintptr_t const& operator[](int i) const { return stack_[i]; }
   void clear()             { size_ = 0; }
   uintptr_t&       operator[](int i)       { return stack_[i]; }
   uintptr_t const& operator[](int i) const { return stack_[i]; }

+
+  /** Top of the stack */

   value_type& top()
   {
     if (size_ == 0)
       throw evaluation_error("Empty stack");
     return stack_[size_ - 1];
   }
   value_type& top()
   {
     if (size_ == 0)
       throw evaluation_error("Empty stack");
     return stack_[size_ - 1];
   }

+
+  /** Access the i-th element from the top of the stack */

   value_type& top(unsigned i)
   {
     if (size_ < i)
   value_type& top(unsigned i)
   {
     if (size_ < i)


@@ -65,13 +93,15 @@ public:
     return stack_[size_ - 1 - i];
   }
 
     return stack_[size_ - 1 - i];
   }
 

-  // Push/pop:
+  /** Push a value on the top of the stack */

   void push(value_type value)
   {
     if (size_ == max_size)
       throw evaluation_error("Dwarf stack overflow");
     stack_[size_++] = value;
   }
   void push(value_type value)
   {
     if (size_ == max_size)
       throw evaluation_error("Dwarf stack overflow");
     stack_[size_++] = value;
   }

+
+  /* Pop a value from the top of the stack */

   value_type pop()
   {
     if (size_ == 0)
   value_type pop()
   {
     if (size_ == 0)


@@ -79,13 +109,31 @@ public:
     return stack_[--size_];
   }
 
     return stack_[--size_];
   }
 

-  // Other operations:
+  // These are DWARF operations (DW_OP_foo):
+
+  /* Push a copy of the top-value (DW_OP_dup) */

   void dup() { push(top()); }
   void dup() { push(top()); }

+
+  /* Swap the two top-most values */
+  void swap() { std::swap(top(), top(1)); }

 };
 
 };
 

+/** Executes a DWARF expression
+ *
+ *  @param ops     DWARF expression instructions
+ *  @param n       number of instructions
+ *  @param context evaluation context (registers, memory, etc.)
+ *  @param stack   DWARf stack where the operations are executed
+ */

 void execute(const Dwarf_Op* ops, std::size_t n,
   ExpressionContext const& context, ExpressionStack& stack);
 
 void execute(const Dwarf_Op* ops, std::size_t n,
   ExpressionContext const& context, ExpressionStack& stack);
 

+/** Executes/evaluates a DWARF expression
+ *
+ *  @param expression DWARF expression to execute
+ *  @param context    evaluation context (registers, memory, etc.)
+ *  @param stack      DWARf stack where the operations are executed
+ */

 inline
 void execute(simgrid::dwarf::DwarfExpression const& expression,
   ExpressionContext const& context, ExpressionStack& stack)
 inline
 void execute(simgrid::dwarf::DwarfExpression const& expression,
   ExpressionContext const& context, ExpressionStack& stack)