Calling this function will emit a semaphore signal operation into the
GPU's command stream.
Signed-off-by: Andres Rodriguez <andre...@gmail.com>
---
src/gallium/docs/source/context.rst | 31 +++++++++++++++++++++++++++++++
src/gallium/include/pipe/p_context.h | 6 ++++++
2 files changed, 37 insertions(+)
diff --git a/src/gallium/docs/source/context.rst
b/src/gallium/docs/source/context.rst
index a8ff3dc..bab9613 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -567,7 +567,38 @@ 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.
use the resource for texturing)
+Semaphores
+^^^^^^^^^^
+``pipe_semaphore_handle``, and related methods, are used to synchronize
+execution between multiple parties. Examples include CPU <-> GPU
syncrhonization,
+rederer <-> windowing system, multiple external APIs, etc.
+
+A ``pipe_semaphore_handle`` can either be 'one time use' or 're-usable'. A
'one time use'
+semaphore behaves like a traditional GPU fence. Once it reaches the signaled
state it
+is forever considered to be signaled.
+
+Once a re-usable ``pipe_semaphore_handle`` becomes signaled, it can be reset
+back into an unsignaled state. The ``pipe_semaphore_handle`` will be reset to
+the unsignaled state by performing a wait operation on said object, i.e.
+``semaphore_server_sync``. As a corollary to this behaviour, a re-usable
+``pipe_semaphore_handle`` can only have one waiter.
+
+This behaviour is useful in producer <-> consumer chains. It helps avoid
+unecessarily sharing a new ``pipe_semaphore_handle`` each time a new frame is
+ready. Instead, the semaphores are exchanged once ahead of time, and access is
synchronized
+through GPU signaling instead of direct producer <-> consumer communication.
+
+``semaphore_server_sync`` inserts a wait command into the GPU's command stream.
+
+``semaphore_server_signal`` inserts a signal command into the GPU's command
stream.
+
+There are no guarantees that the wait/signal commands will be flushed when
+calling ``semaphore_server_sync`` or ``semaphore_server_signal``. An explicit
+call to ``flush`` is required to make sure the commands are emitted to the GPU.
+
+The Gallium implementation may implicitly ``flush`` the command stream during a
+``semaphore_server_sync`` or ``semaphore_server_signal`` call if necessary.
Resource Busy Queries
^^^^^^^^^^^^^^^^^^^^^
diff --git a/src/gallium/include/pipe/p_context.h
b/src/gallium/include/pipe/p_context.h
index 72e4b9d..5827491 100644
--- a/src/gallium/include/pipe/p_context.h
+++ b/src/gallium/include/pipe/p_context.h
@@ -527,6 +527,12 @@ struct pipe_context {
struct pipe_semaphore_handle *semaphore);
/**
+ * Insert commands to have the GPU signal a semaphore.
+ */
+ void (*semaphore_server_signal)(struct pipe_context *pipe,
+ struct pipe_semaphore_handle *semaphore);
+
+ /**
* Create a view on a texture to be used by a shader stage.
*/
struct pipe_sampler_view * (*create_sampler_view)(struct pipe_context *ctx,
--
2.9.3
_______________________________________________
mesa-dev mailing list
mesa-dev@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/mesa-dev
