[Mesa-dev] [PATCH v2 05/25] gallium: add sparse buffer interface and capability

[Nicolai Hähnle]

From: Nicolai Hähnle <nicolai.haehnle at amd.com>

TODO fill out caps in all drivers

v2:
- explain the resource_commit interface in more detail
---
 src/gallium/docs/source/context.rst  | 25 +++++++++++++++++++++++++
 src/gallium/docs/source/screen.rst   |  3 +++
 src/gallium/include/pipe/p_context.h | 13 +++++++++++++
 src/gallium/include/pipe/p_defines.h |  2 ++
 4 files changed, 43 insertions(+)

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index a053193..5949ff2 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -611,20 +611,45 @@ for both regular textures as well as for framebuffers read via FBFETCH.
 .. _memory_barrier:
 
 memory_barrier
 %%%%%%%%%%%%%%%
 
 This function flushes caches according to which of the PIPE_BARRIER_* flags
 are set.
 
 
 
+.. _resource_commit:
+
+resource_commit
+%%%%%%%%%%%%%%%
+
+This function changes the commit state of a part of a sparse resource. Sparse
+resources are created by setting the ``PIPE_RESOURCE_FLAG_SPARSE`` flag when
+calling ``resource_create``. Initially, sparse resources only reserve a virtual
+memory region that is not backed by memory (i.e., it is uncommitted). The
+``resource_commit`` function can be called to commit or uncommit parts (or all)
+of a resource. The driver manages the underlying backing memory.
+
+The contents of newly committed memory regions are undefined. Calling this
+function to commit an already committed memory region is allowed and leaves its
+content unchanged. Similarly, calling this function to uncommit an already
+uncommitted memory region is allowed.
+
+For buffers, the given box must be aligned to multiples of
+``PIPE_CAP_SPARSE_BUFFER_PAGE_SIZE``. As an exception to this rule, if the size
+of the buffer is not a multiple of the page size, changing the commit state of
+the last (partial) page requires a box that ends at the end of the buffer
+(i.e., box->x + box->width == buffer->width0).
+
+
+
 .. _pipe_transfer:
 
 PIPE_TRANSFER
 ^^^^^^^^^^^^^
 
 These flags control the behavior of a transfer object.
 
 ``PIPE_TRANSFER_READ``
   Resource contents read back (or accessed directly) at transfer create time.
 
diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst
index 00c9503..8759639 100644
--- a/src/gallium/docs/source/screen.rst
+++ b/src/gallium/docs/source/screen.rst
@@ -369,20 +369,23 @@ The integer capabilities:
   opcode to retrieve the current value in the framebuffer.
 * ``PIPE_CAP_TGSI_MUL_ZERO_WINS``: Whether TGSI shaders support the
   ``TGSI_PROPERTY_MUL_ZERO_WINS`` shader property.
 * ``PIPE_CAP_DOUBLES``: Whether double precision floating-point operations
   are supported.
 * ``PIPE_CAP_INT64``: Whether 64-bit integer operations are supported.
 * ``PIPE_CAP_INT64_DIVMOD``: Whether 64-bit integer division/modulo
   operations are supported.
 * ``PIPE_CAP_TGSI_TEX_TXF_LZ``: Whether TEX_LZ and TXF_LZ opcodes are
   supported.
+* ``PIPE_CAP_SPARSE_BUFFER_PAGE_SIZE``: The page size of sparse buffers in
+  bytes, or 0 if sparse buffers are not supported. The page size must be at
+  most 64KB.
 
 
 .. _pipe_capf:
 
 PIPE_CAPF_*
 ^^^^^^^^^^^^^^^^
 
 The floating-point capabilities are:
 
 * ``PIPE_CAPF_MAX_LINE_WIDTH``: The maximum width of a regular line.
diff --git a/src/gallium/include/pipe/p_context.h b/src/gallium/include/pipe/p_context.h
index a29fff5..4d5535b 100644
--- a/src/gallium/include/pipe/p_context.h
+++ b/src/gallium/include/pipe/p_context.h
@@ -578,20 +578,33 @@ struct pipe_context {
     * Flush any pending framebuffer writes and invalidate texture caches.
     */
    void (*texture_barrier)(struct pipe_context *, unsigned flags);
 
    /**
     * Flush caches according to flags.
     */
    void (*memory_barrier)(struct pipe_context *, unsigned flags);
 
    /**
+    * Change the commitment status of a part of the given resource, which must
+    * have been created with the PIPE_RESOURCE_FLAG_SPARSE bit.
+    *
+    * \param level The texture level whose commitment should be changed.
+    * \param box The region of the resource whose commitment should be changed.
+    * \param commit Whether memory should be committed or un-committed.
+    *
+    * \return false if out of memory, true on success.
+    */
+   bool (*resource_commit)(struct pipe_context *, struct pipe_resource *,
+                           unsigned level, struct pipe_box *box, bool commit);
+
+   /**
     * Creates a video codec for a specific video format/profile
     */
    struct pipe_video_codec *(*create_video_codec)( struct pipe_context *context,
                                                    const struct pipe_video_codec *templat );
 
    /**
     * Creates a video buffer as decoding target
     */
    struct pipe_video_buffer *(*create_video_buffer)( struct pipe_context *context,
                                                      const struct pipe_video_buffer *templat );
diff --git a/src/gallium/include/pipe/p_defines.h b/src/gallium/include/pipe/p_defines.h
index 924711d..91ff5b4 100644
--- a/src/gallium/include/pipe/p_defines.h
+++ b/src/gallium/include/pipe/p_defines.h
@@ -451,20 +451,21 @@ enum pipe_flush_flags
 #define PIPE_BIND_SHARED      (1 << 20) /* get_texture_handle ??? */
 #define PIPE_BIND_LINEAR      (1 << 21)
 
 
 /**
  * Flags for the driver about resource behaviour:
  */
 #define PIPE_RESOURCE_FLAG_MAP_PERSISTENT (1 << 0)
 #define PIPE_RESOURCE_FLAG_MAP_COHERENT   (1 << 1)
 #define PIPE_RESOURCE_FLAG_TEXTURING_MORE_LIKELY (1 << 2)
+#define PIPE_RESOURCE_FLAG_SPARSE                (1 << 3)
 #define PIPE_RESOURCE_FLAG_DRV_PRIV    (1 << 16) /* driver/winsys private */
 #define PIPE_RESOURCE_FLAG_ST_PRIV     (1 << 24) /* state-tracker/winsys private */
 
 /**
  * Hint about the expected lifecycle of a resource.
  * Sorted according to GPU vs CPU access.
  */
 enum pipe_resource_usage {
    PIPE_USAGE_DEFAULT,        /* fast GPU access */
    PIPE_USAGE_IMMUTABLE,      /* fast GPU access, immutable */
@@ -748,20 +749,21 @@ enum pipe_cap
    PIPE_CAP_STREAM_OUTPUT_INTERLEAVE_BUFFERS,
    PIPE_CAP_TGSI_CAN_READ_OUTPUTS,
    PIPE_CAP_NATIVE_FENCE_FD,
    PIPE_CAP_GLSL_OPTIMIZE_CONSERVATIVELY,
    PIPE_CAP_TGSI_FS_FBFETCH,
    PIPE_CAP_TGSI_MUL_ZERO_WINS,
    PIPE_CAP_DOUBLES,
    PIPE_CAP_INT64,
    PIPE_CAP_INT64_DIVMOD,
    PIPE_CAP_TGSI_TEX_TXF_LZ,
+   PIPE_CAP_SPARSE_BUFFER_PAGE_SIZE,
 };
 
 #define PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_NV50 (1 << 0)
 #define PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_R600 (1 << 1)
 
 enum pipe_endian
 {
    PIPE_ENDIAN_LITTLE = 0,
    PIPE_ENDIAN_BIG = 1,
 #if defined(PIPE_ARCH_LITTLE_ENDIAN)
-- 
2.9.3