From e58b540c4e2a8df460e0e357e3f341842dd59a71 Mon Sep 17 00:00:00 2001 From: gdkchan Date: Tue, 31 Dec 2019 00:22:58 -0300 Subject: [PATCH] Add XML documentation to Ryujinx.Graphics.Gpu.Memory --- Ryujinx.Graphics.Gpu/Memory/Buffer.cs | 61 ++++++- Ryujinx.Graphics.Gpu/Memory/BufferBounds.cs | 3 + Ryujinx.Graphics.Gpu/Memory/BufferManager.cs | 156 ++++++++++++++++++ Ryujinx.Graphics.Gpu/Memory/IRange.cs | 4 + Ryujinx.Graphics.Gpu/Memory/IndexBuffer.cs | 3 + Ryujinx.Graphics.Gpu/Memory/MemoryAccessor.cs | 35 ++++ Ryujinx.Graphics.Gpu/Memory/MemoryManager.cs | 111 +++++++++++-- Ryujinx.Graphics.Gpu/Memory/PhysicalMemory.cs | 26 +++ Ryujinx.Graphics.Gpu/Memory/RangeList.cs | 82 ++++++++- Ryujinx.Graphics.Gpu/Memory/ResourceName.cs | 3 + Ryujinx.Graphics.Gpu/Memory/VertexBuffer.cs | 3 + 11 files changed, 471 insertions(+), 16 deletions(-) diff --git a/Ryujinx.Graphics.Gpu/Memory/Buffer.cs b/Ryujinx.Graphics.Gpu/Memory/Buffer.cs index e37fbc0fc2..99818bc864 100644 --- a/Ryujinx.Graphics.Gpu/Memory/Buffer.cs +++ b/Ryujinx.Graphics.Gpu/Memory/Buffer.cs @@ -3,21 +3,43 @@ using System; namespace Ryujinx.Graphics.Gpu.Memory { + /// + /// Buffer, used to store vertex and index data, uniform and storage buffers, and others. + /// class Buffer : IRange, IDisposable { private GpuContext _context; private IBuffer _buffer; + /// + /// Host buffer object. + /// public IBuffer HostBuffer => _buffer; + /// + /// Start address of the buffer in guest memory. + /// public ulong Address { get; } - public ulong Size { get; } + /// + /// Size of the buffer in bytes. + /// + public ulong Size { get; } + + /// + /// End address of the buffer in guest memory. + /// public ulong EndAddress => Address + Size; private int[] _sequenceNumbers; + /// + /// Creates a new instance of the buffer. + /// + /// GPU context that the buffer belongs to + /// Start address of the buffer + /// Size of the buffer in bytes public Buffer(GpuContext context, ulong address, ulong size) { _context = context; @@ -31,6 +53,13 @@ namespace Ryujinx.Graphics.Gpu.Memory Invalidate(); } + /// + /// Gets a sub-range from the buffer. + /// This can be used to bind and use sub-ranges of the buffer on the host API. + /// + /// Start address of the sub-range, must be greater or equal to the buffer address + /// Size in bytes of the sub-range, must be less than or equal to the buffer size + /// The buffer sub-range public BufferRange GetRange(ulong address, ulong size) { int offset = (int)(address - Address); @@ -38,11 +67,24 @@ namespace Ryujinx.Graphics.Gpu.Memory return new BufferRange(_buffer, offset, (int)size); } + /// + /// Checks if a given range overlaps with the buffer. + /// + /// Start address of the range + /// Size in bytes of the range + /// True if the range overlaps, false otherwise public bool OverlapsWith(ulong address, ulong size) { return Address < address + size && address < EndAddress; } + /// + /// Performs guest to host memory synchronization of the buffer data. + /// This causes the buffer data to be overwritten if a write was detected from the CPU, + /// since the last call to this method. + /// + /// Start address of the range to synchronize + /// Size in bytes of the range to synchronize public void SynchronizeMemory(ulong address, ulong size) { int currentSequenceNumber = _context.SequenceNumber; @@ -83,11 +125,22 @@ namespace Ryujinx.Graphics.Gpu.Memory } } + /// + /// Performs copy of all the buffer data from one buffer to another. + /// + /// The destination buffer to copy the data into + /// The offset of the destination buffer to copy into public void CopyTo(Buffer destination, int dstOffset) { _buffer.CopyTo(destination._buffer, 0, dstOffset, (int)Size); } + /// + /// Flushes a range of the buffer. + /// This writes the range data back into guest memory. + /// + /// Start address of the range + /// Size in bytes of the range public void Flush(ulong address, ulong size) { int offset = (int)(address - Address); @@ -97,11 +150,17 @@ namespace Ryujinx.Graphics.Gpu.Memory _context.PhysicalMemory.Write(address, data); } + /// + /// Invalidates all the buffer data, causing it to be read from guest memory. + /// public void Invalidate() { _buffer.SetData(0, _context.PhysicalMemory.Read(Address, Size)); } + /// + /// Disposes the host buffer. + /// public void Dispose() { _buffer.Dispose(); diff --git a/Ryujinx.Graphics.Gpu/Memory/BufferBounds.cs b/Ryujinx.Graphics.Gpu/Memory/BufferBounds.cs index 2a074bd3dd..42500342fc 100644 --- a/Ryujinx.Graphics.Gpu/Memory/BufferBounds.cs +++ b/Ryujinx.Graphics.Gpu/Memory/BufferBounds.cs @@ -1,5 +1,8 @@ namespace Ryujinx.Graphics.Gpu.Memory { + /// + /// Memory range used for buffers. + /// struct BufferBounds { public ulong Address; diff --git a/Ryujinx.Graphics.Gpu/Memory/BufferManager.cs b/Ryujinx.Graphics.Gpu/Memory/BufferManager.cs index d02146b427..1d27bc7e3c 100644 --- a/Ryujinx.Graphics.Gpu/Memory/BufferManager.cs +++ b/Ryujinx.Graphics.Gpu/Memory/BufferManager.cs @@ -6,6 +6,9 @@ using System; namespace Ryujinx.Graphics.Gpu.Memory { + /// + /// Buffer manager. + /// class BufferManager { private const int OverlapsBufferInitialCapacity = 10; @@ -56,6 +59,10 @@ namespace Ryujinx.Graphics.Gpu.Memory private bool _rebind; + /// + /// Creates a new instance of the buffer manager. + /// + /// The GPU context that the buffer manager belongs to public BufferManager(GpuContext context) { _context = context; @@ -79,6 +86,12 @@ namespace Ryujinx.Graphics.Gpu.Memory } } + /// + /// Sets the memory range with the index buffer data, to be used for subsequent draw calls. + /// + /// Start GPU virtual address of the index buffer + /// Size, in bytes, of the index buffer + /// Type of each index buffer element public void SetIndexBuffer(ulong gpuVa, ulong size, IndexType type) { ulong address = TranslateAndCreateBuffer(gpuVa, size); @@ -90,6 +103,14 @@ namespace Ryujinx.Graphics.Gpu.Memory _indexBufferDirty = true; } + /// + /// Sets the memory range with vertex buffer data, to be used for subsequent draw calls. + /// + /// Index of the vertex buffer (up to 16) + /// GPU virtual address of the buffer + /// Size in bytes of the buffer + /// Stride of the buffer, defined as the number of bytes of each vertex + /// Vertex divisor of the buffer, for instanced draws public void SetVertexBuffer(int index, ulong gpuVa, ulong size, int stride, int divisor) { ulong address = TranslateAndCreateBuffer(gpuVa, size); @@ -111,6 +132,13 @@ namespace Ryujinx.Graphics.Gpu.Memory } } + /// + /// Sets a storage buffer on the compute pipeline. + /// Storage buffers can be read and written to on shaders. + /// + /// Index of the storage buffer + /// Start GPU virtual address of the buffer + /// Size in bytes of the storage buffer public void SetComputeStorageBuffer(int index, ulong gpuVa, ulong size) { size += gpuVa & ((ulong)_context.Capabilities.StorageBufferOffsetAlignment - 1); @@ -122,6 +150,14 @@ namespace Ryujinx.Graphics.Gpu.Memory _cpStorageBuffers.Bind(index, address, size); } + /// + /// Sets a storage buffer on the graphics pipeline. + /// Storage buffers can be read and written to on shaders. + /// + /// Index of the shader stage + /// Index of the storage buffer + /// Start GPU virtual address of the buffer + /// Size in bytes of the storage buffer public void SetGraphicsStorageBuffer(int stage, int index, ulong gpuVa, ulong size) { size += gpuVa & ((ulong)_context.Capabilities.StorageBufferOffsetAlignment - 1); @@ -139,6 +175,13 @@ namespace Ryujinx.Graphics.Gpu.Memory _gpStorageBuffers[stage].Bind(index, address, size); } + /// + /// Sets a uniform buffer on the compute pipeline. + /// Uniform buffers are read-only from shaders, and have a small capacity. + /// + /// Index of the uniform buffer + /// Start GPU virtual address of the buffer + /// Size in bytes of the storage buffer public void SetComputeUniformBuffer(int index, ulong gpuVa, ulong size) { ulong address = TranslateAndCreateBuffer(gpuVa, size); @@ -146,6 +189,14 @@ namespace Ryujinx.Graphics.Gpu.Memory _cpUniformBuffers.Bind(index, address, size); } + /// + /// Sets a uniform buffer on the graphics pipeline. + /// Uniform buffers are read-only from shaders, and have a small capacity. + /// + /// Index of the shader stage + /// Index of the uniform buffer + /// Start GPU virtual address of the buffer + /// Size in bytes of the storage buffer public void SetGraphicsUniformBuffer(int stage, int index, ulong gpuVa, ulong size) { ulong address = TranslateAndCreateBuffer(gpuVa, size); @@ -155,11 +206,22 @@ namespace Ryujinx.Graphics.Gpu.Memory _gpUniformBuffersDirty = true; } + /// + /// Sets the enabled storage buffers mask on the compute pipeline. + /// Each bit set on the mask indicates that the respective buffer index is enabled. + /// + /// Buffer enable mask public void SetComputeStorageBufferEnableMask(uint mask) { _cpStorageBuffers.EnableMask = mask; } + /// + /// Sets the enabled storage buffers mask on the graphics pipeline. + /// Each bit set on the mask indicates that the respective buffer index is enabled. + /// + /// Index of the shader stage + /// Buffer enable mask public void SetGraphicsStorageBufferEnableMask(int stage, uint mask) { _gpStorageBuffers[stage].EnableMask = mask; @@ -167,11 +229,22 @@ namespace Ryujinx.Graphics.Gpu.Memory _gpStorageBuffersDirty = true; } + /// + /// Sets the enabled uniform buffers mask on the compute pipeline. + /// Each bit set on the mask indicates that the respective buffer index is enabled. + /// + /// Buffer enable mask public void SetComputeUniformBufferEnableMask(uint mask) { _cpUniformBuffers.EnableMask = mask; } + /// + /// Sets the enabled uniform buffers mask on the graphics pipeline. + /// Each bit set on the mask indicates that the respective buffer index is enabled. + /// + /// Index of the shader stage + /// Buffer enable mask public void SetGraphicsUniformBufferEnableMask(int stage, uint mask) { _gpUniformBuffers[stage].EnableMask = mask; @@ -179,6 +252,13 @@ namespace Ryujinx.Graphics.Gpu.Memory _gpUniformBuffersDirty = true; } + /// + /// Performs address translation of the GPU virtual address, and creates a + /// new buffer, if needed, for the specified range. + /// + /// Start GPU virtual address of the buffer + /// Size in bytes of the buffer + /// CPU virtual address of the buffer, after address translation private ulong TranslateAndCreateBuffer(ulong gpuVa, ulong size) { if (gpuVa == 0) @@ -210,6 +290,13 @@ namespace Ryujinx.Graphics.Gpu.Memory return address; } + /// + /// Creates a new buffer for the specified range, if needed. + /// If a buffer where this range can be fully contained already exists, + /// then the creation of a new buffer is not necessary. + /// + /// Address of the buffer in guest memory + /// Size in bytes of the buffer private void CreateBuffer(ulong address, ulong size) { int overlapsCount = _buffers.FindOverlapsNonOverlapping(address, size, ref _bufferOverlaps); @@ -266,6 +353,9 @@ namespace Ryujinx.Graphics.Gpu.Memory ShrinkOverlapsBufferIfNeeded(); } + /// + /// Resizes the temporary buffer used for range list intersection results, if it has grown too much. + /// private void ShrinkOverlapsBufferIfNeeded() { if (_bufferOverlaps.Length > OverlapsBufferMaxCapacity) @@ -274,16 +364,31 @@ namespace Ryujinx.Graphics.Gpu.Memory } } + /// + /// Gets the address of the compute uniform buffer currently bound at the given index. + /// + /// Index of the uniform buffer binding + /// The uniform buffer address, or a undefined value if the buffer is not currently bound public ulong GetComputeUniformBufferAddress(int index) { return _cpUniformBuffers.Buffers[index].Address; } + /// + /// Gets the address of the graphics uniform buffer currently bound at the given index. + /// + /// Index of the shader stage + /// Index of the uniform buffer binding + /// The uniform buffer address, or a undefined value if the buffer is not currently bound public ulong GetGraphicsUniformBufferAddress(int stage, int index) { return _gpUniformBuffers[stage].Buffers[index].Address; } + /// + /// Ensures that the compute engine bindings are visible to the host GPU. + /// This actually performs the binding using the host graphics API. + /// public void CommitComputeBindings() { uint enableMask = _cpStorageBuffers.EnableMask; @@ -332,6 +437,10 @@ namespace Ryujinx.Graphics.Gpu.Memory _rebind = true; } + /// + /// Ensures that the graphics engine bindings are visible to the host GPU. + /// This actually performs the binding using the host graphics API. + /// public void CommitBindings() { if (_indexBufferDirty || _rebind) @@ -414,16 +523,31 @@ namespace Ryujinx.Graphics.Gpu.Memory _rebind = false; } + /// + /// Bind respective buffer bindings on the host API. + /// + /// Bindings to bind + /// True to bind as storage buffer, false to bind as uniform buffers private void BindBuffers(BuffersPerStage[] bindings, bool isStorage) { BindOrUpdateBuffers(bindings, bind: true, isStorage); } + /// + /// Updates data for the already bound buffer bindings. + /// + /// Bindings to update private void UpdateBuffers(BuffersPerStage[] bindings) { BindOrUpdateBuffers(bindings, bind: false); } + /// + /// This binds buffer into the host API, or updates data for already bound buffers. + /// + /// Bindings to bind or update + /// True to bind, false to update + /// True to bind as storage buffer, false to bind as uniform buffers private void BindOrUpdateBuffers(BuffersPerStage[] bindings, bool bind, bool isStorage = false) { for (ShaderStage stage = ShaderStage.Vertex; stage <= ShaderStage.Fragment; stage++) @@ -461,6 +585,13 @@ namespace Ryujinx.Graphics.Gpu.Memory } } + /// + /// Binds a buffer on the host API. + /// + /// Index to bind the buffer into + /// Shader stage to bind the buffer into + /// Buffer address and size + /// True to bind as storage buffer, false to bind as uniform buffer private void BindBuffer(int index, ShaderStage stage, BufferBounds bounds, bool isStorage) { BufferRange buffer = GetBufferRange(bounds.Address, bounds.Size); @@ -475,6 +606,13 @@ namespace Ryujinx.Graphics.Gpu.Memory } } + /// + /// Copy a buffer data from a given address to another. + /// This does a GPU side copy. + /// + /// GPU virtual address of the copy source + /// GPU virtual address of the copy destination + /// Size in bytes of the copy public void CopyBuffer(GpuVa srcVa, GpuVa dstVa, ulong size) { ulong srcAddress = TranslateAndCreateBuffer(srcVa.Pack(), size); @@ -495,11 +633,24 @@ namespace Ryujinx.Graphics.Gpu.Memory dstBuffer.Flush(dstAddress, size); } + /// + /// Gets a buffer sub-range for a given memory range. + /// + /// Start address of the memory range + /// Size in bytes of the memory range + /// The buffer sub-range for the given range private BufferRange GetBufferRange(ulong address, ulong size) { return GetBuffer(address, size).GetRange(address, size); } + /// + /// Gets a buffer for a given memory range. + /// A buffer overlapping with the specified range is assumed to already exist on the cache. + /// + /// Start address of the memory range + /// Size in bytes of the memory range + /// The buffer where the range is fully contained private Buffer GetBuffer(ulong address, ulong size) { Buffer buffer; @@ -518,6 +669,11 @@ namespace Ryujinx.Graphics.Gpu.Memory return buffer; } + /// + /// Performs guest to host memory synchronization of a given memory range. + /// + /// Start address of the memory range + /// Size in bytes of the memory range private void SynchronizeBufferRange(ulong address, ulong size) { if (size != 0) diff --git a/Ryujinx.Graphics.Gpu/Memory/IRange.cs b/Ryujinx.Graphics.Gpu/Memory/IRange.cs index ee3d5c0bee..6d275d3fb9 100644 --- a/Ryujinx.Graphics.Gpu/Memory/IRange.cs +++ b/Ryujinx.Graphics.Gpu/Memory/IRange.cs @@ -1,5 +1,9 @@ namespace Ryujinx.Graphics.Gpu.Memory { + /// + /// Range of memory. + /// + /// GPU resource type interface IRange { ulong Address { get; } diff --git a/Ryujinx.Graphics.Gpu/Memory/IndexBuffer.cs b/Ryujinx.Graphics.Gpu/Memory/IndexBuffer.cs index ce2a2c7441..7765e89943 100644 --- a/Ryujinx.Graphics.Gpu/Memory/IndexBuffer.cs +++ b/Ryujinx.Graphics.Gpu/Memory/IndexBuffer.cs @@ -2,6 +2,9 @@ using Ryujinx.Graphics.GAL; namespace Ryujinx.Graphics.Gpu.Memory { + /// + /// GPU Index Buffer information. + /// struct IndexBuffer { public ulong Address; diff --git a/Ryujinx.Graphics.Gpu/Memory/MemoryAccessor.cs b/Ryujinx.Graphics.Gpu/Memory/MemoryAccessor.cs index 500c36e509..a0247acfeb 100644 --- a/Ryujinx.Graphics.Gpu/Memory/MemoryAccessor.cs +++ b/Ryujinx.Graphics.Gpu/Memory/MemoryAccessor.cs @@ -3,15 +3,29 @@ using System.Runtime.InteropServices; namespace Ryujinx.Graphics.Gpu.Memory { + /// + /// GPU mapped memory accessor. + /// class MemoryAccessor { private GpuContext _context; + /// + /// Creates a new instance of the GPU memory accessor. + /// + /// GPU context that the memory accessor belongs to public MemoryAccessor(GpuContext context) { _context = context; } + /// + /// Reads data from GPU mapped memory. + /// This reads as much data as possible, up to the specified maximum size. + /// + /// GPU virtual address where the data is located + /// Maximum size of the data + /// The data at the specified memory location public Span Read(ulong gpuVa, ulong maxSize) { ulong processVa = _context.MemoryManager.Translate(gpuVa); @@ -21,6 +35,12 @@ namespace Ryujinx.Graphics.Gpu.Memory return _context.PhysicalMemory.Read(processVa, size); } + /// + /// Reads a structure from GPU mapped memory. + /// + /// Type of the structure + /// GPU virtual address where the strcture is located + /// The structure at the specified memory location public T Read(ulong gpuVa) where T : struct { ulong processVa = _context.MemoryManager.Translate(gpuVa); @@ -30,6 +50,11 @@ namespace Ryujinx.Graphics.Gpu.Memory return MemoryMarshal.Cast(_context.PhysicalMemory.Read(processVa, size))[0]; } + /// + /// Reads a 32-bits signed integer from GPU mapped memory. + /// + /// GPU virtual address where the value is located + /// The value at the specified memory location public int ReadInt32(ulong gpuVa) { ulong processVa = _context.MemoryManager.Translate(gpuVa); @@ -37,6 +62,11 @@ namespace Ryujinx.Graphics.Gpu.Memory return BitConverter.ToInt32(_context.PhysicalMemory.Read(processVa, 4)); } + /// + /// Writes a 32-bits signed integer to GPU mapped memory. + /// + /// GPU virtual address to write the value into + /// The value to be written public void Write(ulong gpuVa, int value) { ulong processVa = _context.MemoryManager.Translate(gpuVa); @@ -44,6 +74,11 @@ namespace Ryujinx.Graphics.Gpu.Memory _context.PhysicalMemory.Write(processVa, BitConverter.GetBytes(value)); } + /// + /// Writes data to GPU mapped memory. + /// + /// GPU virtual address to write the data into + /// The data to be written public void Write(ulong gpuVa, Span data) { ulong processVa = _context.MemoryManager.Translate(gpuVa); diff --git a/Ryujinx.Graphics.Gpu/Memory/MemoryManager.cs b/Ryujinx.Graphics.Gpu/Memory/MemoryManager.cs index 59319a47f8..d4d9b48a0b 100644 --- a/Ryujinx.Graphics.Gpu/Memory/MemoryManager.cs +++ b/Ryujinx.Graphics.Gpu/Memory/MemoryManager.cs @@ -1,5 +1,8 @@ namespace Ryujinx.Graphics.Gpu.Memory { + /// + /// GPU memory manager. + /// public class MemoryManager { private const ulong AddressSpaceSize = 1UL << 40; @@ -26,11 +29,22 @@ namespace Ryujinx.Graphics.Gpu.Memory private ulong[][] _pageTable; + /// + /// Creates a new instance of the GPU memory manager. + /// public MemoryManager() { _pageTable = new ulong[PtLvl0Size][]; } + /// + /// Maps a given range of pages to the specified CPU virtual address. + /// All addresses and sizes must be page aligned. + /// + /// CPU virtual address to map into + /// GPU virtual address to be mapped + /// Size in bytes of the mapping + /// The GPU virtual address of the mapping public ulong Map(ulong pa, ulong va, ulong size) { lock (_pageTable) @@ -44,6 +58,13 @@ namespace Ryujinx.Graphics.Gpu.Memory return va; } + /// + /// Maps a given range of pages to a allocated GPU virtual address. + /// The memory is automatically allocated by the memory manager. + /// + /// CPU virtual address to map into + /// Mapping size in bytes + /// GPU virtual address where the range was mapped, or an all ones mask in case of failure public ulong Map(ulong pa, ulong size) { lock (_pageTable) @@ -62,6 +83,14 @@ namespace Ryujinx.Graphics.Gpu.Memory } } + /// + /// Maps a given range of pages to a allocated GPU virtual address. + /// The memory is automatically allocated by the memory manager. + /// This also ensures that the mapping is always done in the first 4GB of GPU address space. + /// + /// CPU virtual address to map into + /// Mapping size in bytes + /// GPU virtual address where the range was mapped, or an all ones mask in case of failure public ulong MapLow(ulong pa, ulong size) { lock (_pageTable) @@ -84,6 +113,13 @@ namespace Ryujinx.Graphics.Gpu.Memory } } + /// + /// Reserves memory at a fixed GPU memory location. + /// This prevents the reserved region from being used for memory allocation for map. + /// + /// CPU virtual address to reserve + /// Reservation size in bytes + /// GPU virtual address of the reservation, or an all ones mask in case of failure public ulong ReserveFixed(ulong va, ulong size) { lock (_pageTable) @@ -105,6 +141,12 @@ namespace Ryujinx.Graphics.Gpu.Memory return va; } + /// + /// Reserves memory at any GPU memory location. + /// + /// Reservation size in bytes + /// Reservation address alignment in bytes + /// GPU virtual address of the reservation, or an all ones mask in case of failure public ulong Reserve(ulong size, ulong alignment) { lock (_pageTable) @@ -123,6 +165,11 @@ namespace Ryujinx.Graphics.Gpu.Memory } } + /// + /// Frees memory that was previously allocated by a map or reserved. + /// + /// GPU virtual address to free + /// Size in bytes of the region being freed public void Free(ulong va, ulong size) { lock (_pageTable) @@ -134,6 +181,13 @@ namespace Ryujinx.Graphics.Gpu.Memory } } + /// + /// Gets the address of a unused (free) region of the specified size. + /// + /// Size of the region in bytes + /// Required alignment of the region address in bytes + /// Start address of the search on the address space + /// GPU virtual address of the allocation, or an all ones mask in case of failure private ulong GetFreePosition(ulong size, ulong alignment = 1, ulong start = 1UL << 32) { // Note: Address 0 is not considered valid by the driver, @@ -176,6 +230,11 @@ namespace Ryujinx.Graphics.Gpu.Memory return PteUnmapped; } + /// + /// Gets the number of mapped or reserved pages on a given region. + /// + /// Start GPU virtual address of the region + /// Mapped size in bytes of the specified region internal ulong GetSubSize(ulong gpuVa) { ulong size = 0; @@ -188,6 +247,11 @@ namespace Ryujinx.Graphics.Gpu.Memory return size; } + /// + /// Translated a GPU virtual address to a CPU virtual address. + /// + /// GPU virtual address to be translated + /// CPU virtual address internal ulong Translate(ulong gpuVa) { ulong baseAddress = GetPte(gpuVa); @@ -200,11 +264,17 @@ namespace Ryujinx.Graphics.Gpu.Memory return baseAddress + (gpuVa & PageMask); } - public bool IsRegionFree(ulong va, ulong size) + /// + /// Checks if a given memory region is currently unmapped. + /// + /// Start GPU virtual address of the region + /// Size in bytes of the region + /// True if the region is unmapped (free), false otherwise + public bool IsRegionFree(ulong gpuVa, ulong size) { for (ulong offset = 0; offset < size; offset += PageSize) { - if (IsPageInUse(va + offset)) + if (IsPageInUse(gpuVa + offset)) { return false; } @@ -213,15 +283,20 @@ namespace Ryujinx.Graphics.Gpu.Memory return true; } - private bool IsPageInUse(ulong va) + /// + /// Checks if a given memory page is mapped or reserved. + /// + /// GPU virtual address of the page + /// True if the page is mapped or reserved, false otherwise + private bool IsPageInUse(ulong gpuVa) { - if (va >> PtLvl0Bits + PtLvl1Bits + PtPageBits != 0) + if (gpuVa >> PtLvl0Bits + PtLvl1Bits + PtPageBits != 0) { return false; } - ulong l0 = (va >> PtLvl0Bit) & PtLvl0Mask; - ulong l1 = (va >> PtLvl1Bit) & PtLvl1Mask; + ulong l0 = (gpuVa >> PtLvl0Bit) & PtLvl0Mask; + ulong l1 = (gpuVa >> PtLvl1Bit) & PtLvl1Mask; if (_pageTable[l0] == null) { @@ -231,10 +306,15 @@ namespace Ryujinx.Graphics.Gpu.Memory return _pageTable[l0][l1] != PteUnmapped; } - private ulong GetPte(ulong address) + /// + /// Gets the Page Table entry for a given GPU virtual address. + /// + /// GPU virtual address + /// Page table entry (CPU virtual address) + private ulong GetPte(ulong gpuVa) { - ulong l0 = (address >> PtLvl0Bit) & PtLvl0Mask; - ulong l1 = (address >> PtLvl1Bit) & PtLvl1Mask; + ulong l0 = (gpuVa >> PtLvl0Bit) & PtLvl0Mask; + ulong l1 = (gpuVa >> PtLvl1Bit) & PtLvl1Mask; if (_pageTable[l0] == null) { @@ -244,10 +324,15 @@ namespace Ryujinx.Graphics.Gpu.Memory return _pageTable[l0][l1]; } - private void SetPte(ulong address, ulong tgtAddr) + /// + /// Sets a Page Table entry at a given GPU virtual address. + /// + /// GPU virtual address + /// Page table entry (CPU virtual address) + private void SetPte(ulong gpuVa, ulong pte) { - ulong l0 = (address >> PtLvl0Bit) & PtLvl0Mask; - ulong l1 = (address >> PtLvl1Bit) & PtLvl1Mask; + ulong l0 = (gpuVa >> PtLvl0Bit) & PtLvl0Mask; + ulong l1 = (gpuVa >> PtLvl1Bit) & PtLvl1Mask; if (_pageTable[l0] == null) { @@ -259,7 +344,7 @@ namespace Ryujinx.Graphics.Gpu.Memory } } - _pageTable[l0][l1] = tgtAddr; + _pageTable[l0][l1] = pte; } } } \ No newline at end of file diff --git a/Ryujinx.Graphics.Gpu/Memory/PhysicalMemory.cs b/Ryujinx.Graphics.Gpu/Memory/PhysicalMemory.cs index 8f585b0f7a..7a6b096347 100644 --- a/Ryujinx.Graphics.Gpu/Memory/PhysicalMemory.cs +++ b/Ryujinx.Graphics.Gpu/Memory/PhysicalMemory.cs @@ -4,25 +4,51 @@ namespace Ryujinx.Graphics.Gpu.Memory { using CpuMemoryManager = ARMeilleure.Memory.MemoryManager; + /// + /// Represents physical memory, accessible from the GPU. + /// This is actually working CPU virtual addresses, of memory mapped on the game process. + /// class PhysicalMemory { private readonly CpuMemoryManager _cpuMemory; + /// + /// Creates a new instance of the physical memory. + /// + /// CPU memory manager of the application process public PhysicalMemory(CpuMemoryManager cpuMemory) { _cpuMemory = cpuMemory; } + /// + /// Reads data from the application process. + /// + /// Address to be read + /// Size in bytes to be read + /// The data at the specified memory location public Span Read(ulong address, ulong size) { return _cpuMemory.ReadBytes((long)address, (long)size); } + /// + /// Writes data to the application process. + /// + /// Address to write into + /// Data to be written public void Write(ulong address, Span data) { _cpuMemory.WriteBytes((long)address, data.ToArray()); } + /// + /// Gets the modified ranges for a given range of the application process mapped memory. + /// + /// Start address of the range + /// Size, in bytes, of the range + /// Name of the GPU resource being checked + /// Ranges, composed of address and size, modified by the application process, form the CPU public (ulong, ulong)[] GetModifiedRanges(ulong address, ulong size, ResourceName name) { return _cpuMemory.GetModifiedRanges(address, size, (int)name); diff --git a/Ryujinx.Graphics.Gpu/Memory/RangeList.cs b/Ryujinx.Graphics.Gpu/Memory/RangeList.cs index 45f23cf325..52bcf9b46f 100644 --- a/Ryujinx.Graphics.Gpu/Memory/RangeList.cs +++ b/Ryujinx.Graphics.Gpu/Memory/RangeList.cs @@ -3,17 +3,28 @@ using System.Collections.Generic; namespace Ryujinx.Graphics.Gpu.Memory { + /// + /// Lists of GPU resources with data on guest memory. + /// + /// Type of the GPU resource class RangeList where T : IRange { private const int ArrayGrowthSize = 32; private List _items; + /// + /// Creates a new GPU resources list. + /// public RangeList() { _items = new List(); } + /// + /// Adds a new item to the list. + /// + /// The item to be added public void Add(T item) { int index = BinarySearch(item.Address); @@ -26,6 +37,11 @@ namespace Ryujinx.Graphics.Gpu.Memory _items.Insert(index, item); } + /// + /// Removes a item from the list. + /// + /// The item to be removed + /// True if the item was removed, or false if it was not found public bool Remove(T item) { int index = BinarySearch(item.Address); @@ -58,11 +74,26 @@ namespace Ryujinx.Graphics.Gpu.Memory return false; } + /// + /// Gets the first item on the list overlapping in memory with the specified item. + /// Despite the name, this has no ordering guarantees of the returned item. + /// It only ensures that the item returned overlaps the specified item. + /// + /// Item to check for overlaps + /// The overlapping item, or the default value for the type if none found public T FindFirstOverlap(T item) { return FindFirstOverlap(item.Address, item.Size); } + /// + /// Gets the first item on the list overlapping the specified memory range. + /// Despite the name, this has no ordering guarantees of the returned item. + /// It only ensures that the item returned overlaps the specified memory range. + /// + /// Start address of the range + /// Size in bytes or the rangee + /// The overlapping item, or the default value for the type if none found public T FindFirstOverlap(ulong address, ulong size) { int index = BinarySearch(address, size); @@ -75,11 +106,24 @@ namespace Ryujinx.Graphics.Gpu.Memory return _items[index]; } + /// + /// Gets all items overlapping with the specified item in memory. + /// + /// Item to check for overlaps + /// Output array where matches will be written. It is automatically resized to fit the results + /// The number of overlapping items found public int FindOverlaps(T item, ref T[] output) { return FindOverlaps(item.Address, item.Size, ref output); } + /// + /// Gets all items on the list overlapping the specified memory range. + /// + /// Start address of the range + /// Size in bytes or the rangee + /// Output array where matches will be written. It is automatically resized to fit the results + /// The number of overlapping items found public int FindOverlaps(ulong address, ulong size, ref T[] output) { int outputIndex = 0; @@ -110,19 +154,36 @@ namespace Ryujinx.Graphics.Gpu.Memory return outputIndex; } + /// + /// Gets all items overlapping with the specified item in memory. + /// This method only returns correct results if none of the items on the list overlaps with + /// each other. If that is not the case, this method should not be used. + /// This method is faster than the regular method to find all overlaps. + /// + /// Item to check for overlaps + /// Output array where matches will be written. It is automatically resized to fit the results + /// The number of overlapping items found public int FindOverlapsNonOverlapping(T item, ref T[] output) { return FindOverlapsNonOverlapping(item.Address, item.Size, ref output); } + /// + /// Gets all items on the list overlapping the specified memory range. + /// This method only returns correct results if none of the items on the list overlaps with + /// each other. If that is not the case, this method should not be used. + /// This method is faster than the regular method to find all overlaps. + /// + /// Start address of the range + /// Size in bytes or the rangee + /// Output array where matches will be written. It is automatically resized to fit the results + /// The number of overlapping items found public int FindOverlapsNonOverlapping(ulong address, ulong size, ref T[] output) { // This is a bit faster than FindOverlaps, but only works // when none of the items on the list overlaps with each other. int outputIndex = 0; - ulong endAddress = address + size; - int index = BinarySearch(address, size); if (index >= 0) @@ -147,6 +208,12 @@ namespace Ryujinx.Graphics.Gpu.Memory return outputIndex; } + /// + /// Gets all items on the list with the specified memory address. + /// + /// Address to find + /// Output array where matches will be written. It is automatically resized to fit the results + /// The number of matches found public int FindOverlaps(ulong address, ref T[] output) { int index = BinarySearch(address); @@ -181,6 +248,11 @@ namespace Ryujinx.Graphics.Gpu.Memory return outputIndex; } + /// + /// Performs binary search on the internal list of items. + /// + /// Address to find + /// List index of the item, or complement index of nearest item with lower value on the list private int BinarySearch(ulong address) { int left = 0; @@ -212,6 +284,12 @@ namespace Ryujinx.Graphics.Gpu.Memory return ~left; } + /// + /// Performs binary search for items overlapping a given memory range. + /// + /// Start address of the range + /// Size of the range in bytes + /// List index of the item, or complement index of nearest item with lower value on the list private int BinarySearch(ulong address, ulong size) { int left = 0; diff --git a/Ryujinx.Graphics.Gpu/Memory/ResourceName.cs b/Ryujinx.Graphics.Gpu/Memory/ResourceName.cs index 9476a384f1..c3d2dc77a1 100644 --- a/Ryujinx.Graphics.Gpu/Memory/ResourceName.cs +++ b/Ryujinx.Graphics.Gpu/Memory/ResourceName.cs @@ -1,5 +1,8 @@ namespace Ryujinx.Graphics.Gpu.Memory { + /// + /// Name of a GPU resource. + /// public enum ResourceName { Buffer, diff --git a/Ryujinx.Graphics.Gpu/Memory/VertexBuffer.cs b/Ryujinx.Graphics.Gpu/Memory/VertexBuffer.cs index 1cb854d636..8f08912513 100644 --- a/Ryujinx.Graphics.Gpu/Memory/VertexBuffer.cs +++ b/Ryujinx.Graphics.Gpu/Memory/VertexBuffer.cs @@ -1,5 +1,8 @@ namespace Ryujinx.Graphics.Gpu.Memory { + /// + /// GPU Vertex Buffer information. + /// struct VertexBuffer { public ulong Address;