[Spice-devel] [PATCH spice-space-pages 2/5] multiple-monitors: Expand section on qxl memory allocation

[Jonathon Jongsma]

Clarify a few minor things and add a suggested memory allocation table
for different guest OSes. These values were based on a document written
by Frediano about QXL memory allocation, and via the recommendations
from oVirt found at http://www.ovirt.org/documentation/draft/video-ram/
---
**Note: one potentially contentious part of this change is the "ram_size_mb"
recommendation for RHEL7. It appears that the Linux KMS driver doesn't really
use this first bar for much (dynamic memory, cursors, commands, images, monitor
configs, etc, but no surfaces), so we don't need to allocate a ton amount of
memory there.  However, for historical reasons, it's not actually possible to
allocate anything less than 2*vgamem_mb for this bar.  I modified qemu locally
to remove this limitation, and things seem to work fine with just 8MB on a
RHEL7 guest. However, I'm not sure exactly how much we really need here.


 multiple-monitors.rst | 44 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/multiple-monitors.rst b/multiple-monitors.rst
index b90fb9e..0d97cdb 100644
--- a/multiple-monitors.rst
+++ b/multiple-monitors.rst
@@ -40,7 +40,7 @@ The QXL driver device has two memory bars. `ram_size`/`ram_size_mb` controls the
 size of the first memory bar, and `vram_size`/`vram_size_mb`/`vram64_size_mb`
 controls the size of the second memory bar. `vgamem_mb` is located within the
 first memory bar, which means that `ram_size_mb` is constrained to be a least 2
-times as large as `vgamem_mb`.
+times as large as `vgamem_mb` (but should be considerably larger for best results).
 
 These memory bars are used in different ways by different QXL drivers. In the
 Windows QXL driver and non-KMS Linux drivers (e.g. RHEL 6), `vgamem_mb`
@@ -49,13 +49,14 @@ maximum resolution of the device. For devices that support
 multiple displays with a single device (i.e. Linux drivers), this primary
 surface must be large enough to contain all displays. This bar is also used for
 dynamic memory such as cursors, commands, and images. The second bar is used
-for offscreen memory.
+for offscreen memory. Offscreen memory is not used in RHEL6 or Windows, so this
+second bar is generally not used at all in these guests.
 
-In KMS-based Linux drivers, all surfaces (including the primary surface) are
-allocated in the second memory bar and the first memory bar is used for dynamic
-memory such as cursors, commands, images, and monitor configs. Therefore,
-devices that support multiple displays will need larger values for `vram_size`
-/ `vram_size_mb`.
+In KMS-based Linux drivers (e.g. RHEL7), all surfaces (including the primary
+surface) are allocated in the second memory bar and the first memory bar is
+used for dynamic memory such as cursors, commands, images, and monitor configs.
+Therefore, devices that support multiple displays will need larger values for
+`vram_size` / `vram_size_mb`.
 
 64 bit drivers support a larger second memory bar that can be configured with
 `vram64_size_mb`. If `vram_size_mb` is configured to 32 and `vram64_size_mb` is
@@ -63,6 +64,35 @@ configured to 128, you will get a 32 bit memory bar of 32 megabytes and a 64
 bit memory bar of 128 megabytes. The first 32 megabytes of the 64 bit memory
 bar will contain the same data as the 32 bit memory bar.
 
+The following table gives some recommended memory values for different guests:
+
++---------------------+----------+-------------+---------------+-------------+----------------+
+| Guest OS            | Monitors | QXL devices | `ram_size_mb` | `vgamem_mb` | `vram_size_mb` |
++=====================+==========+=============+===============+=============+================+
+| Linux w/ UMS driver | 1        | 1           | 64            | 16          | 8              |
+| (e.g. RHEL6)        +----------+-------------+---------------+-------------+----------------+
+|                     | 2        | 1           | 128           | 32          | 8              |
+|                     +----------+-------------+---------------+-------------+----------------+
+|                     | 4        | 1           | 256           | 64          | 8              |
++---------------------+----------+-------------+---------------+-------------+----------------+
+| Linux w/ KMS driver | 1        | 1           | 8 [#note]_    | 16          | 32             |
+| (e.g. RHEL7)        +----------+-------------+---------------+-------------+----------------+
+|                     | 2        | 1           | 8 [#note]_    | 32          | 64             |
+|                     +----------+-------------+---------------+-------------+----------------+
+|                     | 4        | 1           | 8 [#note]_    | 64          | 128            |
++---------------------+----------+-------------+---------------+-------------+----------------+
+| Windows             | 1        | 1           | 64            | 16          | 8              |
+|                     +----------+-------------+---------------+-------------+----------------+
+|                     | 2        | 2           | 64            | 16          | 8              |
+|                     +----------+-------------+---------------+-------------+----------------+
+|                     | 4        | 4           | 64            | 16          | 8              |
++---------------------+----------+-------------+---------------+-------------+----------------+
+
+.. [#note] Note that at the time of writing, qemu does not allow you to
+ configure the first memory bar (specified by `ram_size_mb`) to a value smaller
+ than 2 * `vgamem_mb`, even though the KMS driver does not use the first memory
+ bar for display surfaces.
+
 Spice Protocol
 ++++++++++++++
 Additional displays are enabled and disabled via the spice protocol using agent
-- 
2.9.3