[03/22] gallium: documentation updates for fence->semaphore rename

Submitted by Andres Rodriguez on Dec. 22, 2017, 12:41 a.m.

Details

Message ID 20171222004157.28106-4-andresx7@gmail.com
State New
Headers show
Series "Add support for GL_EXT_semaphore" ( rev: 2 ) in Mesa

Not browsing as part of any series.

Commit Message

Andres Rodriguez Dec. 22, 2017, 12:41 a.m.
Kept separate from the symbol renames for review purposes.

Signed-off-by: Andres Rodriguez <andresx7@gmail.com>
---
 src/gallium/docs/source/context.rst        | 34 +++++++++++++++---------------
 src/gallium/include/pipe/p_context.h       | 33 +++++++++++++++--------------
 src/gallium/include/pipe/p_screen.h        | 24 ++++++++++-----------
 src/gallium/include/state_tracker/st_api.h |  2 +-
 4 files changed, 47 insertions(+), 46 deletions(-)

Patch hide | download patch | download mbox

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index 399b390..a8ff3dc 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -527,33 +527,33 @@  Flushing
 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 semaphore_finish is called with the returned fence
-and the context is still unflushed, and the ctx parameter of semaphore_finish is
-equal to the context where the fence was created, semaphore_finish will flush
-the context.
+to return a valid semaphore. If semaphore_finish is called with the returned
+semaphore and the context is still unflushed, and the ctx parameter of
+semaphore_finish is equal to the context where the semaphore was created,
+semaphore_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::semaphore_server_sync.
+``PIPE_FLUSH_DEFERRED``, the driver must still ensure that the returned
+semaphore 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::semaphore_server_sync.
 
 PIPE_FLUSH_HINT_FINISH: Hints to the driver that the caller will immediately
-wait for the returned fence.
+wait for the returned semaphore.
 
 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:
+finer-grained semaphore. Note that as a general rule, GPU caches may not have
+been flushed yet when these semaphore are signaled. Drivers are free to ignore
+these flags and create normal semaphore 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
+PIPE_FLUSH_TOP_OF_PIPE: The semaphore 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).
+PIPE_FLUSH_BOTTOM_OF_PIPE: The semaphore 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``
diff --git a/src/gallium/include/pipe/p_context.h b/src/gallium/include/pipe/p_context.h
index 750a69a..72e4b9d 100644
--- a/src/gallium/include/pipe/p_context.h
+++ b/src/gallium/include/pipe/p_context.h
@@ -487,43 +487,44 @@  struct pipe_context {
    /**
     * Flush draw commands.
     *
-    * This guarantees that the new fence (if any) will finish in finite time,
-    * unless PIPE_FLUSH_DEFERRED is used.
+    * This guarantees that the new semaphore (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->semaphore_reference() (or equivalent) to transfer
-    * new fence ref to **fence, to ensure that previous fence is unref'd
+    * new semaphore ref to **semaphore, to ensure that previous semaphore 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.
+    * \param semaphore  if not NULL, an old semaphore to unref and transfer a
+    *                   new semaphore reference to
+    * \param flags      bitfield of enum pipe_flush_flags values.
     */
    void (*flush)(struct pipe_context *pipe,
-                 struct pipe_semaphore_handle **fence,
+                 struct pipe_semaphore_handle **semaphore,
                  unsigned flags);
 
    /**
-    * Create a fence from a fd.
+    * Create a semaphore from a fd.
     *
-    * This is used for importing a foreign/external fence fd.
+    * This is used for importing a foreign/external semaphore fd.
     *
-    * \param fence  if not NULL, an old fence to unref and transfer a
-    *    new fence reference to
-    * \param fd     fd representing the fence object
-    * \param type   indicates which fence types backs fd
+    * \param semaphore  if not NULL, an old semaphore to unref and transfer a
+    *                   new semaphore reference to
+    * \param fd         fd representing the semaphore object
+    * \param type       indicates which semaphore types backs fd
     */
    void (*create_semaphore_fd)(struct pipe_context *pipe,
-                               struct pipe_semaphore_handle **fence,
+                               struct pipe_semaphore_handle **semaphore,
                                int fd,
                                enum pipe_fd_type type);
 
    /**
-    * Insert commands to have GPU wait for fence to be signaled.
+    * Insert commands to have GPU wait for semaphore to be signaled.
     */
    void (*semaphore_server_sync)(struct pipe_context *pipe,
-                                 struct pipe_semaphore_handle *fence);
+                                 struct pipe_semaphore_handle *semaphore);
 
    /**
     * Create a view on a texture to be used by a shader stage.
diff --git a/src/gallium/include/pipe/p_screen.h b/src/gallium/include/pipe/p_screen.h
index 57b9357..8231eda 100644
--- a/src/gallium/include/pipe/p_screen.h
+++ b/src/gallium/include/pipe/p_screen.h
@@ -276,18 +276,18 @@  struct pipe_screen {
                               void *winsys_drawable_handle,
                               struct pipe_box *subbox );
 
-   /** Set ptr = fence, with reference counting */
+   /** Set ptr = semaphore, with reference counting */
    void (*semaphore_reference)( struct pipe_screen *screen,
                                 struct pipe_semaphore_handle **ptr,
-                                struct pipe_semaphore_handle *fence );
+                                struct pipe_semaphore_handle *semaphore );
 
    /**
-    * Wait for the fence to finish.
+    * Wait for the semaphore to finish.
     *
-    * If the fence was created with PIPE_FLUSH_DEFERRED, and the context is
+    * If the semaphore was created with PIPE_FLUSH_DEFERRED, and the context is
     * still unflushed, and the ctx parameter of semaphore_finish is equal to
-    * the context where the fence was created, semaphore_finish will flush
-    * the context prior to waiting for the fence.
+    * the context where the semaphore was created, semaphore_finish will flush
+    * the context prior to waiting for the semaphore.
     *
     * In all other cases, the ctx parameter has no effect.
     *
@@ -295,18 +295,18 @@  struct pipe_screen {
     */
    boolean (*semaphore_finish)(struct pipe_screen *screen,
                                struct pipe_context *ctx,
-                               struct pipe_semaphore_handle *fence,
+                               struct pipe_semaphore_handle *semaphore,
                                uint64_t timeout);
 
    /**
-    * For fences created with PIPE_FLUSH_SEMAPHORE_FD (exported fd) or
-    * by create_semaphore_fd() (imported fd), return the native fence fd
-    * associated with the fence.  This may return -1 for fences
-    * created with PIPE_FLUSH_DEFERRED if the fence command has not
+    * For semaphores created with PIPE_FLUSH_SEMAPHORE_FD (exported fd) or
+    * by create_semaphore_fd() (imported fd), return the native semaphore fd
+    * associated with the semaphore.  This may return -1 for semaphores
+    * created with PIPE_FLUSH_DEFERRED if the semaphore command has not
     * been flushed yet.
     */
    int (*semaphore_get_fd)(struct pipe_screen *screen,
-                           struct pipe_semaphore_handle *fence);
+                           struct pipe_semaphore_handle *semaphore);
 
    /**
     * Returns a driver-specific query.
diff --git a/src/gallium/include/state_tracker/st_api.h b/src/gallium/include/state_tracker/st_api.h
index 96ff6da..ff7c29a 100644
--- a/src/gallium/include/state_tracker/st_api.h
+++ b/src/gallium/include/state_tracker/st_api.h
@@ -381,7 +381,7 @@  struct st_context_iface
     * Flush all drawing from context to the pipe also flushes the pipe.
     */
    void (*flush)(struct st_context_iface *stctxi, unsigned flags,
-                 struct pipe_semaphore_handle **fence);
+                 struct pipe_semaphore_handle **semaphore);
 
    /**
     * Replace the texture image of a texture object at the specified level.