i#6662 public traces, part8: v2p textproto reader (#6926)

Implementation of a simple reader for virtual to
physical address mapping in textproto format.
The reader parses blocks in the following form:
```
address_mapping {
    virtual_address: 0x123
    physical_address: 0x3
}
```
present in the provided textproto file to create a
map in memory from virtual to physical addresses.
The reader also parses the file to obtain the page size,
page count, and number of bytes that were mapped.
All the previous information is saved in a new struct
`v2p_info_t`.

We plan to include this virtual to physical mapping
in textproto format in the release of public traces to
aid users in experimenting with our TLB simulator
using physical addresses.

Adds unit tests and a sample v2p textproto file
to check the correctness of the generated map.

Issue #6662

api/docs/release.dox

@@ -253,6 +253,8 @@ Further non-compatibility-affecting changes include:
    All function markers whose ID is not in the list are removed.
  - Added -skip_to_timestamp and #dynamorio::drmemtrace::scheduler_tmpl_t::
    input_workload_t::times_of_interest to the drmemtrace scheduler.
+ - Added v2p_reader_t to parse a virtual-to-physical mapping in textproto format and
+   v2p_info_t to hold that mapping in memory.
 
 **************************************************
 <hr>

clients/drcachesim/CMakeLists.txt

@@ -266,6 +266,7 @@ set(drcachesim_srcs
   ${client_and_sim_srcs}
   reader/reader.cpp
   reader/config_reader.cpp
+  reader/v2p_reader.cpp
   reader/file_reader.cpp
   reader/record_file_reader.cpp
   ${zlib_reader}
@@ -325,6 +326,7 @@ add_exported_library(drmemtrace_analyzer STATIC
   common/trace_entry.cpp
   reader/reader.cpp
   reader/config_reader.cpp
+  reader/v2p_reader.cpp
   reader/file_reader.cpp
   reader/record_file_reader.cpp
   ${zlib_reader}
@@ -802,7 +804,8 @@ if (BUILD_TESTS)
   set_tests_properties(tool.reuse_distance.unit_tests PROPERTIES TIMEOUT ${test_seconds})
 
   add_executable(tool.drcachesim.unit_tests tests/drcachesim_unit_tests.cpp
-    tests/cache_replacement_policy_unit_test.cpp tests/config_reader_unit_test.cpp)
+    tests/cache_replacement_policy_unit_test.cpp tests/config_reader_unit_test.cpp
+    tests/v2p_reader_unit_test.cpp)
   target_link_libraries(tool.drcachesim.unit_tests drmemtrace_simulator
     # Link test_helpers first, or else the zlib main takes over.
     drmemtrace_static drmemtrace_analyzer test_helpers ${zlib_libs})

clients/drcachesim/reader/v2p_reader.cpp

@@ -0,0 +1,174 @@
+/* **********************************************************
+ * Copyright (c) 2024 Google, LLC  All rights reserved.
+ * **********************************************************/
+
+/*
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * * Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ *   this list of conditions and the following disclaimer in the documentation
+ *   and/or other materials provided with the distribution.
+ *
+ * * Neither the name of Google, LLC nor the names of its contributors may be
+ *   used to endorse or promote products derived from this software without
+ *   specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL GOOGLE, LLC OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+ * DAMAGE.
+ */
+
+#include "v2p_reader.h"
+
+#include <cstdint>
+#include <sstream>
+#include <stdint.h>
+
+#include <cstdlib>
+#include <fstream>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "utils.h"
+
+namespace dynamorio {
+namespace drmemtrace {
+
+std::string
+v2p_reader_t::set_value_or_fail(std::string key_str, uint64_t new_value, uint64_t &value)
+{
+    if (value != 0) {
+        if (value != new_value) {
+            std::stringstream error_ss;
+            error_ss << "ERROR: " << key_str << " mismatch. Current value " << value
+                     << " is different than new value " << new_value << ".";
+            return error_ss.str();
+        }
+    } else {
+        value = new_value;
+    }
+    return "";
+}
+
+std::string
+v2p_reader_t::get_value_from_line(std::string line, uint64_t &value)
+{
+    std::vector<std::string> key_val_pair = split_by(line, ":");
+    if (key_val_pair.size() != 2) {
+        return "ERROR: value not found.";
+    }
+    // base = 0 allows to handle both decimal and hex numbers.
+    value = std::stoull(key_val_pair[1], nullptr, /*base = */ 0);
+    return "";
+}
+
+std::string
+v2p_reader_t::create_v2p_info_from_file(std::string path_to_file, v2p_info_t &v2p_info)
+{
+    if (path_to_file.empty()) {
+        return "ERROR: Path to v2p.textproto is empty.";
+    }
+
+    std::stringstream error_ss;
+    std::ifstream file(path_to_file);
+    if (!file.is_open()) {
+        error_ss << "ERROR: Failed to open " << path_to_file << ".";
+        return error_ss.str();
+    }
+
+    const std::string page_size_key = "page_size";
+    const std::string page_count_key = "page_count";
+    const std::string bytes_mapped_key = "bytes_mapped";
+    const std::string virtual_address_key = "virtual_address";
+    const std::string physical_address_key = "physical_address";
+    // Assumes virtual_address 0 is not in the v2p file.
+    addr_t virtual_address = 0;
+    uint64_t value = 0;
+    std::string error_str;
+    std::string line;
+    while (std::getline(file, line)) {
+        // Ignore comments in v2p.textproto file.
+        if (starts_with(line, "#"))
+            continue;
+
+        std::size_t found = line.find(virtual_address_key);
+        if (found != std::string::npos) {
+            error_str = get_value_from_line(line, value);
+            if (!error_str.empty())
+                return error_str;
+            virtual_address = static_cast<addr_t>(value);
+            continue;
+        }
+
+        found = line.find(physical_address_key);
+        if (found != std::string::npos) {
+            error_str = get_value_from_line(line, value);
+            if (!error_str.empty())
+                return error_str;
+            addr_t physical_address = static_cast<addr_t>(value);
+            if (virtual_address == 0) {
+                error_ss << "ERROR: no corresponding " << virtual_address_key << " for "
+                         << physical_address_key << " " << physical_address << ".";
+                return error_ss.str();
+            }
+            if (v2p_info.v2p_map.count(virtual_address) > 0) {
+                error_ss << "ERROR: " << virtual_address_key << " " << virtual_address
+                         << " is already present in v2p_map.";
+                return error_ss.str();
+            }
+            v2p_info.v2p_map[virtual_address] = physical_address;
+        }
+        virtual_address = 0;
+
+        found = line.find(page_size_key);
+        if (found != std::string::npos) {
+            error_str = get_value_from_line(line, value);
+            if (!error_str.empty())
+                return error_str;
+            error_str = set_value_or_fail(page_size_key, value, v2p_info.page_size);
+            if (!error_str.empty())
+                return error_str;
+            continue;
+        }
+
+        found = line.find(page_count_key);
+        if (found != std::string::npos) {
+            error_str = get_value_from_line(line, value);
+            if (!error_str.empty())
+                return error_str;
+            error_str = set_value_or_fail(page_count_key, value, v2p_info.page_count);
+            if (!error_str.empty())
+                return error_str;
+            continue;
+        }
+
+        found = line.find(bytes_mapped_key);
+        if (found != std::string::npos) {
+            error_str = get_value_from_line(line, value);
+            if (!error_str.empty())
+                return error_str;
+            error_str = set_value_or_fail(bytes_mapped_key, value, v2p_info.bytes_mapped);
+            if (!error_str.empty())
+                return error_str;
+            continue;
+        }
+    }
+
+    return "";
+}
+
+} // namespace drmemtrace
+} // namespace dynamorio

clients/drcachesim/reader/v2p_reader.h

@@ -0,0 +1,84 @@
+/* **********************************************************
+ * Copyright (c) 2024 Google, LLC  All rights reserved.
+ * **********************************************************/
+
+/*
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * * Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ *   this list of conditions and the following disclaimer in the documentation
+ *   and/or other materials provided with the distribution.
+ *
+ * * Neither the name of Google, LLC nor the names of its contributors may be
+ *   used to endorse or promote products derived from this software without
+ *   specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL GOOGLE, LLC OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+ * DAMAGE.
+ */
+
+/* v2p_reader: reads and parses a virtual-to-physical address mapping in textproto format.
+ * Creates a virtual-to-physical address map in memory.
+ * The section of the textproto file that we parse to create the mapping is a sequence of
+ * blocks that follow this format:
+ * address_mapping {
+    virtual_address: 0x123
+    physical_address: 0x3
+ * }
+ * In create_v2p_info_from_file() we rely on the fact that virtual_address and
+ * physical_address are one after the other on two different lines.
+ * The virtual-to-physical mapping along with the page size, page count, and number of
+ * bytes mapped is stored in memory in a v2p_info_t object.
+ */
+
+#ifndef _V2P_READER_H_
+#define _V2P_READER_H_ 1
+
+#include "trace_entry.h"
+
+#include <cstdint>
+#include <string>
+#include <unordered_map>
+
+namespace dynamorio {
+namespace drmemtrace {
+
+struct v2p_info_t {
+    uint64_t page_count = 0;
+    uint64_t bytes_mapped = 0;
+    uint64_t page_size = 0;
+    std::unordered_map<addr_t, addr_t> v2p_map;
+};
+
+class v2p_reader_t {
+public:
+    v2p_reader_t() = default;
+
+    std::string
+    create_v2p_info_from_file(std::string path_to_file, v2p_info_t &v2p_info);
+
+private:
+    std::string
+    get_value_from_line(std::string line, uint64_t &value);
+
+    std::string
+    set_value_or_fail(std::string key_str, uint64_t new_value, uint64_t &value);
+};
+
+} // namespace drmemtrace
+} // namespace dynamorio
+
+#endif /* _V2P_READER_H_ */

clients/drcachesim/tests/drcachesim_unit_tests.cpp

@@ -39,6 +39,7 @@
 #undef NDEBUG
 #include <assert.h>
 #include "config_reader_unit_test.h"
+#include "v2p_reader_unit_test.h"
 #include "cache_replacement_policy_unit_test.h"
 #include "simulator/cache.h"
 #include "simulator/cache_lru.h"
@@ -842,6 +843,7 @@ test_main(int argc, const char *argv[])
     unit_test_exclusive_cache();
     unit_test_cache_accessors();
     unit_test_config_reader(argv[1]);
+    unit_test_v2p_reader(argv[1]);
     unit_test_cache_associativity();
     unit_test_cache_size();
     unit_test_cache_line_size();

clients/drcachesim/tests/v2p_example.textproto

@@ -0,0 +1,26 @@
+# VirtualToPhysical
+# Instance name: vm00_example_v2p
+# Generated: 2024-08-13T23:17:25.138285133+00:00
+address_mapping_group    {
+  page_size: 0x200000
+  address_mapping {
+    virtual_address: 0x123
+    physical_address: 0x3
+  }
+  address_mapping {
+    virtual_address: 0x456
+    physical_address: 0x4
+  }
+  address_mapping {
+    virtual_address: 0x789
+    physical_address: 0x5
+  }
+  information {
+    page_count: 0x1
+    bytes_mapped: 0x18
+  }
+}
+information {
+  page_count: 0x1
+  bytes_mapped: 0x18
+}