freezer: Add documentation for methods

src/core/memory/freezer.cpp

@@ -3,18 +3,20 @@
 // Refer to the license.txt file included.
 
 #include "common/assert.h"
+#include "common/logging/log.h"
 #include "core/core.h"
+#include "core/core_timing.h"
 #include "core/core_timing_util.h"
 #include "core/memory.h"
 #include "core/memory/freezer.h"
 
 namespace Memory {
 
-constexpr s64 MEMORY_FREEZER_TICKS = static_cast<s64>(Core::Timing::BASE_CLOCK_RATE / 60);
-
 namespace {
 
-u64 MemoryReadWidth(u8 width, VAddr addr) {
+constexpr s64 MEMORY_FREEZER_TICKS = static_cast<s64>(Core::Timing::BASE_CLOCK_RATE / 60);
+
+u64 MemoryReadWidth(u32 width, VAddr addr) {
     switch (width) {
     case 1:
         return Read8(addr);
@@ -30,7 +32,7 @@ u64 MemoryReadWidth(u8 width, VAddr addr) {
     }
 }
 
-void MemoryWriteWidth(u8 width, VAddr addr, u64 value) {
+void MemoryWriteWidth(u32 width, VAddr addr, u64 value) {
     switch (width) {
     case 1:
         Write8(addr, static_cast<u8>(value));
@@ -73,19 +75,19 @@ void Freezer::SetActive(bool active) {
 }
 
 bool Freezer::IsActive() const {
-    return active.load();
+    return active.load(std::memory_order_relaxed);
 }
 
 void Freezer::Clear() {
-    std::lock_guard<std::recursive_mutex> lock(entries_mutex);
+    std::lock_guard lock{entries_mutex};
 
     LOG_DEBUG(Common_Memory, "Clearing all frozen memory values.");
 
     entries.clear();
 }
 
-u64 Freezer::Freeze(VAddr address, u8 width) {
+u64 Freezer::Freeze(VAddr address, u32 width) {
-    std::lock_guard<std::recursive_mutex> lock(entries_mutex);
+    std::lock_guard lock{entries_mutex};
 
     const auto current_value = MemoryReadWidth(width, address);
     entries.push_back({address, width, current_value});
@@ -98,7 +100,7 @@ u64 Freezer::Freeze(VAddr address, u8 width) {
 }
 
 void Freezer::Unfreeze(VAddr address) {
-    std::lock_guard<std::recursive_mutex> lock(entries_mutex);
+    std::lock_guard lock{entries_mutex};
 
     LOG_DEBUG(Common_Memory, "Unfreezing memory for address={:016X}", address);
 
@@ -108,8 +110,8 @@ void Freezer::Unfreeze(VAddr address) {
         entries.end());
 }
 
-bool Freezer::IsFrozen(VAddr address) {
+bool Freezer::IsFrozen(VAddr address) const {
-    std::lock_guard<std::recursive_mutex> lock(entries_mutex);
+    std::lock_guard lock{entries_mutex};
 
     return std::find_if(entries.begin(), entries.end(), [&address](const Entry& entry) {
                return entry.address == address;
@@ -117,7 +119,7 @@ bool Freezer::IsFrozen(VAddr address) {
 }
 
 void Freezer::SetFrozenValue(VAddr address, u64 value) {
-    std::lock_guard<std::recursive_mutex> lock(entries_mutex);
+    std::lock_guard lock{entries_mutex};
 
     const auto iter = std::find_if(entries.begin(), entries.end(), [&address](const Entry& entry) {
         return entry.address == address;
@@ -135,8 +137,8 @@ void Freezer::SetFrozenValue(VAddr address, u64 value) {
     iter->value = value;
 }
 
-std::optional<Freezer::Entry> Freezer::GetEntry(VAddr address) {
+std::optional<Freezer::Entry> Freezer::GetEntry(VAddr address) const {
-    std::lock_guard<std::recursive_mutex> lock(entries_mutex);
+    std::lock_guard lock{entries_mutex};
 
     const auto iter = std::find_if(entries.begin(), entries.end(), [&address](const Entry& entry) {
         return entry.address == address;
@@ -149,19 +151,19 @@ std::optional<Freezer::Entry> Freezer::GetEntry(VAddr address) {
     return *iter;
 }
 
-std::vector<Freezer::Entry> Freezer::GetEntries() {
+std::vector<Freezer::Entry> Freezer::GetEntries() const {
-    std::lock_guard<std::recursive_mutex> lock(entries_mutex);
+    std::lock_guard lock{entries_mutex};
 
     return entries;
 }
 
 void Freezer::FrameCallback(u64 userdata, s64 cycles_late) {
-    if (!active.load()) {
+    if (!IsActive()) {
         LOG_DEBUG(Common_Memory, "Memory freezer has been deactivated, ending callback events.");
         return;
     }
 
-    std::lock_guard<std::recursive_mutex> lock(entries_mutex);
+    std::lock_guard lock{entries_mutex};
 
     for (const auto& entry : entries) {
         LOG_DEBUG(Common_Memory,
@@ -174,7 +176,7 @@ void Freezer::FrameCallback(u64 userdata, s64 cycles_late) {
 }
 
 void Freezer::FillEntryReads() {
-    std::lock_guard<std::recursive_mutex> lock(entries_mutex);
+    std::lock_guard lock{entries_mutex};
 
     LOG_DEBUG(Common_Memory, "Updating memory freeze entries to current values.");
 

src/core/memory/freezer.h

@@ -4,14 +4,16 @@
 
 #pragma once
 
+#include <atomic>
+#include <mutex>
 #include <optional>
 #include <vector>
 #include "common/common_types.h"
-#include "core/core_timing.h"
 
-namespace Core {
+namespace Core::Timing {
-class System;
+class CoreTiming;
-} // namespace Core
+struct EventType;
+} // namespace Core::Timing
 
 namespace Memory {
 
@@ -20,27 +22,42 @@ class Freezer {
 public:
     struct Entry {
         VAddr address;
-        u8 width;
+        u32 width;
         u64 value;
     };
 
-    Freezer(Core::Timing::CoreTiming& core_timing);
+    explicit Freezer(Core::Timing::CoreTiming& core_timing);
     ~Freezer();
 
+    // Enables or disables the entire memory freezer.
     void SetActive(bool active);
+
+    // Returns whether or not the freezer is active.
     bool IsActive() const;
 
+    // Removes all entries from the freezer.
     void Clear();
 
-    u64 Freeze(VAddr address, u8 width);
+    // Freezes a value to its current memory address. The value the memory is kept at will be the
+    // value that is read during this function. Width can be 1, 2, 4, or 8 (in bytes).
+    u64 Freeze(VAddr address, u32 width);
+
+    // Unfreezes the memory value at address. If the address isn't frozen, this is a no-op.
     void Unfreeze(VAddr address);
 
-    bool IsFrozen(VAddr address);
+    // Returns whether or not the address is frozen.
+    bool IsFrozen(VAddr address) const;
+
+    // Sets the value that address should be frozen to. This doesn't change the width set by using
+    // Freeze(). If the value isn't frozen, this will not freeze it and is thus a no-op.
     void SetFrozenValue(VAddr address, u64 value);
 
-    std::optional<Entry> GetEntry(VAddr address);
+    // Returns the entry corresponding to the address if the address is frozen, otherwise
+    // std::nullopt.
+    std::optional<Entry> GetEntry(VAddr address) const;
 
-    std::vector<Entry> GetEntries();
+    // Returns all the entries in the freezer, an empty vector means nothing is frozen.
+    std::vector<Entry> GetEntries() const;
 
 private:
     void FrameCallback(u64 userdata, s64 cycles_late);
@@ -48,7 +65,7 @@ private:
 
     std::atomic_bool active{false};
 
-    std::recursive_mutex entries_mutex;
+    mutable std::mutex entries_mutex;
     std::vector<Entry> entries;
 
     Core::Timing::EventType* event;