[Mesa-dev] [PATCH 06/25] gallium: add PIPE_FLUSH_{TOP, BOTTOM}_OF_PIPE bits

[Nicolai Hähnle]

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

These bits are intended to be used by the ddebug hang detection and are
named in analogy to the Vulkan stage bits (and the corresponding Radeon
pipeline event).

Hang detection needs fences on the granularity of individual commands,
which nothing else really covers. The closest alternative would have
been PIPE_QUERY_GPU_FINISHED, but (a) queries are a per-context object
and we really want a per-screen object, (b) queries don't offer a
wait with timeout, and (c) in any case, PIPE_QUERY_GPU_FINISHED is
meant to imply that GPU caches are flushed, which the new bits
explicitly aren't.
---
 src/gallium/docs/source/context.rst  | 14 ++++++++++++++
 src/gallium/include/pipe/p_defines.h |  2 ++
 2 files changed, 16 insertions(+)

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index 81822203728..8aee21b2ed4 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -523,20 +523,34 @@ 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.
 
+Additional flags may be set together with ``PIPE_FLUSH_DEFERRED`` for even
+finer-grained fences. Note that as a general rule, GPU caches may not have been
+flushed yet when these fences are signaled. Drivers are free to ignore these
+flags and create normal fences instead. At most one of the following flags can
+be specified:
+
+PIPE_FLUSH_TOP_OF_PIPE: The fence should be signaled as soon as the next
+command is ready to start executing at the top of the pipeline, before any of
+its data is actually read (including indirect draw parameters).
+
+PIPE_FLUSH_BOTTOM_OF_PIPE: The fence should be signaled as soon as the previous
+command has finished executing on the GPU entirely (but data written by the
+command may still be in caches and inaccessible to the CPU).
+
 
 ``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_defines.h b/src/gallium/include/pipe/p_defines.h
index a6bada1bbc2..db9dfb3ae8a 100644
--- a/src/gallium/include/pipe/p_defines.h
+++ b/src/gallium/include/pipe/p_defines.h
@@ -347,20 +347,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),
+   PIPE_FLUSH_TOP_OF_PIPE = (1 << 5),
+   PIPE_FLUSH_BOTTOM_OF_PIPE = (1 << 6),
 };
 
 /**
  * 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