From 913f42a3a70d716fa65d639dc4a6dfc9687eec61 Mon Sep 17 00:00:00 2001
From: Fernando Sahmkow <fsahmkow27@gmail.com>
Date: Wed, 8 Apr 2020 13:34:59 -0400
Subject: Memory: Address Feedback.

---
 src/core/memory.h | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

(limited to 'src/core/memory.h')

diff --git a/src/core/memory.h b/src/core/memory.h
index 97750f851..b92d678a4 100644
--- a/src/core/memory.h
+++ b/src/core/memory.h
@@ -294,6 +294,24 @@ public:
     void ReadBlock(const Kernel::Process& process, VAddr src_addr, void* dest_buffer,
                    std::size_t size);
 
+    /**
+     * Reads a contiguous block of bytes from a specified process' address space.
+     * This unsafe version does not trigger GPU flushing.
+     *
+     * @param process     The process to read the data from.
+     * @param src_addr    The virtual address to begin reading from.
+     * @param dest_buffer The buffer to place the read bytes into.
+     * @param size        The amount of data to read, in bytes.
+     *
+     * @note If a size of 0 is specified, then this function reads nothing and
+     *       no attempts to access memory are made at all.
+     *
+     * @pre dest_buffer must be at least size bytes in length, otherwise a
+     *      buffer overrun will occur.
+     *
+     * @post The range [dest_buffer, size) contains the read bytes from the
+     *       process' address space.
+     */
     void ReadBlockUnsafe(const Kernel::Process& process, VAddr src_addr, void* dest_buffer,
                          std::size_t size);
 
@@ -315,6 +333,23 @@ public:
      */
     void ReadBlock(VAddr src_addr, void* dest_buffer, std::size_t size);
 
+    /**
+     * Reads a contiguous block of bytes from the current process' address space.
+     * This unsafe version does not trigger GPU flushing.
+     *
+     * @param src_addr    The virtual address to begin reading from.
+     * @param dest_buffer The buffer to place the read bytes into.
+     * @param size        The amount of data to read, in bytes.
+     *
+     * @note If a size of 0 is specified, then this function reads nothing and
+     *       no attempts to access memory are made at all.
+     *
+     * @pre dest_buffer must be at least size bytes in length, otherwise a
+     *      buffer overrun will occur.
+     *
+     * @post The range [dest_buffer, size) contains the read bytes from the
+     *       current process' address space.
+     */
     void ReadBlockUnsafe(VAddr src_addr, void* dest_buffer, std::size_t size);
 
     /**
@@ -340,6 +375,23 @@ public:
     void WriteBlock(const Kernel::Process& process, VAddr dest_addr, const void* src_buffer,
                     std::size_t size);
 
+    /**
+     * Writes a range of bytes into a given process' address space at the specified
+     * virtual address.
+     * This unsafe version does not invalidate GPU Memory.
+     *
+     * @param process    The process to write data into the address space of.
+     * @param dest_addr  The destination virtual address to begin writing the data at.
+     * @param src_buffer The data to write into the process' address space.
+     * @param size       The size of the data to write, in bytes.
+     *
+     * @post The address range [dest_addr, size) in the process' address space
+     *       contains the data that was within src_buffer.
+     *
+     * @post If an attempt is made to write into an unmapped region of memory, the writes
+     *       will be ignored and an error will be logged.
+     *
+     */
     void WriteBlockUnsafe(const Kernel::Process& process, VAddr dest_addr, const void* src_buffer,
                           std::size_t size);
 
@@ -364,6 +416,22 @@ public:
      */
     void WriteBlock(VAddr dest_addr, const void* src_buffer, std::size_t size);
 
+    /**
+     * Writes a range of bytes into the current process' address space at the specified
+     * virtual address.
+     * This unsafe version does not invalidate GPU Memory.
+     *
+     * @param dest_addr  The destination virtual address to begin writing the data at.
+     * @param src_buffer The data to write into the current process' address space.
+     * @param size       The size of the data to write, in bytes.
+     *
+     * @post The address range [dest_addr, size) in the current process' address space
+     *       contains the data that was within src_buffer.
+     *
+     * @post If an attempt is made to write into an unmapped region of memory, the writes
+     *       will be ignored and an error will be logged.
+     *
+     */
     void WriteBlockUnsafe(VAddr dest_addr, const void* src_buffer, std::size_t size);
 
     /**
-- 
cgit v1.2.3