softmmu: Expand comments describing max_bounce_buffer_size

Commit Message

Mattias Nissler Sept. 10, 2024, 9:35 p.m. UTC

Clarify how the parameter gets configured and how it is used when
servicing DMA mapping requests targeting indirect memory regions.

Signed-off-by: Mattias Nissler <[e-mail]>
---
 include/exec/memory.h       | 9 ++++++++-
 include/hw/pci/pci_device.h | 6 +++++-
 2 files changed, 13 insertions(+), 2 deletions(-)

Comments

Peter Xu Sept. 11, 2024, 6:58 p.m. UTC | #1

On Tue, Sep 10, 2024 at 02:35:12PM -0700, Mattias Nissler wrote:
> Clarify how the parameter gets configured and how it is used when
> servicing DMA mapping requests targeting indirect memory regions.
> 
> Signed-off-by: Mattias Nissler <[e-mail]>

Acked-by: Peter Xu <[e-mail]>

Patch

diff --git a/include/exec/memory.h b/include/exec/memory.h
index e5e865d1a9..9458e2801d 100644
--- a/include/exec/memory.h
+++ b/include/exec/memory.h
@@ -1104,7 +1104,14 @@  struct AddressSpace {
     QTAILQ_HEAD(, MemoryListener) listeners;
     QTAILQ_ENTRY(AddressSpace) address_spaces_link;
 
-    /* Maximum DMA bounce buffer size used for indirect memory map requests */
+    /*
+     * Maximum DMA bounce buffer size used for indirect memory map requests.
+     * This limits the total size of bounce buffer allocations made for
+     * DMA requests to indirect memory regions within this AddressSpace. DMA
+     * requests that exceed the limit (e.g. due to overly large requested size
+     * or concurrent DMA requests having claimed too much buffer space) will be
+     * rejected and left to the caller to handle.
+     */
     size_t max_bounce_buffer_size;
     /* Total size of bounce buffers currently allocated, atomically accessed */
     size_t bounce_buffer_size;
diff --git a/include/hw/pci/pci_device.h b/include/hw/pci/pci_device.h
index 91df40f989..8eaf0d58bb 100644
--- a/include/hw/pci/pci_device.h
+++ b/include/hw/pci/pci_device.h
@@ -168,7 +168,11 @@  struct PCIDevice {
     char *failover_pair_id;
     uint32_t acpi_index;
 
-    /* Maximum DMA bounce buffer size used for indirect memory map requests */
+    /*
+     * Indirect DMA region bounce buffer size as configured for the device. This
+     * is a configuration parameter that is reflected into bus_master_as when
+     * realizing the device.
+     */
     uint32_t max_bounce_buffer_size;
 };