[Mesa-dev] [PATCH 05/25] gallium: add PIPE_FLUSH_ASYNC and PIPE_FLUSH_HINT_FINISH

[Nicolai Hähnle]

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

Also document some subtleties of pipe_context::flush.
---
 src/gallium/docs/source/context.rst  | 9 +++++++++
 src/gallium/include/pipe/p_context.h | 8 +++++++-
 src/gallium/include/pipe/p_defines.h | 2 ++
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index ba7fef8301d..81822203728 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -514,20 +514,29 @@ Flushing
 ``flush``
 
 PIPE_FLUSH_END_OF_FRAME: Whether the flush marks the end of frame.
 
 PIPE_FLUSH_DEFERRED: It is not required to flush right away, but it is required
 to return a valid fence. If fence_finish is called with the returned fence
 and the context is still unflushed, and the ctx parameter of fence_finish is
 equal to the context where the fence was created, fence_finish will flush
 the context.
 
+PIPE_FLUSH_ASYNC: The flush is allowed to be asynchronous. Unlike
+``PIPE_FLUSH_DEFERRED``, the driver must still ensure that the returned fence
+will finish in finite time. However, subsequent operations in other contexts of
+the same screen are no longer guaranteed to happen after the flush. Drivers
+which use this flag must implement pipe_context::fence_server_sync.
+
+PIPE_FLUSH_HINT_FINISH: Hints to the driver that the caller will immediately
+wait for the returned fence.
+
 
 ``flush_resource``
 
 Flush the resource cache, so that the resource can be used
 by an external client. Possible usage:
 - flushing a resource before presenting it on the screen
 - flushing a resource if some other process or device wants to use it
 This shouldn't be used to flush caches if the resource is only managed
 by a single pipe_screen and is not shared with another process.
 (i.e. you shouldn't use it to flush caches explicitly if you want to e.g.
diff --git a/src/gallium/include/pipe/p_context.h b/src/gallium/include/pipe/p_context.h
index 4609d4dbf23..803569ff317 100644
--- a/src/gallium/include/pipe/p_context.h
+++ b/src/gallium/include/pipe/p_context.h
@@ -462,21 +462,27 @@ struct pipe_context {
     * value passed in through clear_value of size clear_value_size.
     */
    void (*clear_buffer)(struct pipe_context *pipe,
                         struct pipe_resource *res,
                         unsigned offset,
                         unsigned size,
                         const void *clear_value,
                         int clear_value_size);
 
    /**
-    * Flush draw commands
+    * Flush draw commands.
+    *
+    * This guarantees that the new fence (if any) will finish in finite time,
+    * unless PIPE_FLUSH_DEFERRED is used.
+    *
+    * Subsequent operations on other contexts of the same screen are guaranteed
+    * to execute after the flushed commands, unless PIPE_FLUSH_ASYNC is used.
     *
     * NOTE: use screen->fence_reference() (or equivalent) to transfer
     * new fence ref to **fence, to ensure that previous fence is unref'd
     *
     * \param fence  if not NULL, an old fence to unref and transfer a
     *    new fence reference to
     * \param flags  bitfield of enum pipe_flush_flags values.
     */
    void (*flush)(struct pipe_context *pipe,
                  struct pipe_fence_handle **fence,
diff --git a/src/gallium/include/pipe/p_defines.h b/src/gallium/include/pipe/p_defines.h
index 11af6c8d0d8..a6bada1bbc2 100644
--- a/src/gallium/include/pipe/p_defines.h
+++ b/src/gallium/include/pipe/p_defines.h
@@ -345,20 +345,22 @@ enum pipe_transfer_usage
 };
 
 /**
  * Flags for the flush function.
  */
 enum pipe_flush_flags
 {
    PIPE_FLUSH_END_OF_FRAME = (1 << 0),
    PIPE_FLUSH_DEFERRED = (1 << 1),
    PIPE_FLUSH_FENCE_FD = (1 << 2),
+   PIPE_FLUSH_ASYNC = (1 << 3),
+   PIPE_FLUSH_HINT_FINISH = (1 << 4),
 };
 
 /**
  * Flags for pipe_context::dump_debug_state.
  */
 #define PIPE_DUMP_DEVICE_STATUS_REGISTERS    (1 << 0)
 
 /**
  * Create a compute-only context. Use in pipe_screen::context_create.
  * This disables draw, blit, and clear*, render_condition, and other graphics
-- 
2.11.0