| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-Id: <1452869739-3304-2-git-send-email-gustavo@padovan.org>
Date: Fri, 15 Jan 2016 12:55:11 -0200
From: Gustavo Padovan <gustavo@...ovan.org>
To: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
Cc: linux-kernel@...r.kernel.org, devel@...verdev.osuosl.org,
dri-devel@...ts.freedesktop.org, daniels@...labora.com,
Arve Hjønnevåg <arve@...roid.com>,
Riley Andrews <riandrews@...roid.com>,
Daniel Vetter <daniel.vetter@...ll.ch>,
Rob Clark <robdclark@...il.com>,
Greg Hackmann <ghackmann@...gle.com>,
John Harrison <John.C.Harrison@...el.com>,
Maarten Lankhorst <maarten.lankhorst@...onical.com>,
Gustavo Padovan <gustavo.padovan@...labora.co.uk>
Subject: [RFC 01/29] staging/android: fix sync framework documentation
From: Gustavo Padovan <gustavo.padovan@...labora.co.uk>
Updates comments about functions and structures.
Signed-off-by: Gustavo Padovan <gustavo.padovan@...labora.co.uk>
---
drivers/staging/android/sync.h | 45 ++++++++++++++++++++----------------------
1 file changed, 21 insertions(+), 24 deletions(-)
diff --git a/drivers/staging/android/sync.h b/drivers/staging/android/sync.h
index afa0752..7a4d820 100644
--- a/drivers/staging/android/sync.h
+++ b/drivers/staging/android/sync.h
@@ -110,15 +110,9 @@ struct sync_timeline {
/**
* struct sync_pt - sync point
- * @fence: base fence class
+ * @base: base fence class
* @child_list: membership in sync_timeline.child_list_head
* @active_list: membership in sync_timeline.active_list_head
- * @signaled_list: membership in temporary signaled_list on stack
- * @fence: sync_fence to which the sync_pt belongs
- * @pt_list: membership in sync_fence.pt_list_head
- * @status: 1: signaled, 0:active, <0: error
- * @timestamp: time which sync_pt status transitioned from active to
- * signaled or error.
*/
struct sync_pt {
struct fence base;
@@ -144,12 +138,11 @@ struct sync_fence_cb {
* @file: file representing this fence
* @kref: reference count on fence.
* @name: name of sync_fence. Useful for debugging
- * @pt_list_head: list of sync_pts in the fence. immutable once fence
- * is created
- * @status: 0: signaled, >0:active, <0: error
- *
- * @wq: wait queue for fence signaling
* @sync_fence_list: membership in global fence list
+ * @num_fences number of sync_pts in the fence
+ * @wq: wait queue for fence signaling
+ * @status: 0: signaled, >0:active, <0: error
+ * @cbs: sync_pts callback information
*/
struct sync_fence {
struct file *file;
@@ -172,9 +165,8 @@ typedef void (*sync_callback_t)(struct sync_fence *fence,
/**
* struct sync_fence_waiter - metadata for asynchronous waiter on a fence
- * @waiter_list: membership in sync_fence.waiter_list_head
+ * @work: wait_queue for the fence waiter
* @callback: function pointer to call when fence signals
- * @callback_data: pointer to pass to @callback
*/
struct sync_fence_waiter {
wait_queue_t work;
@@ -200,7 +192,8 @@ static inline void sync_fence_waiter_init(struct sync_fence_waiter *waiter,
*
* Creates a new sync_timeline which will use the implementation specified by
* @ops. @size bytes will be allocated allowing for implementation specific
- * data to be kept after the generic sync_timeline struct.
+ * data to be kept after the generic sync_timeline struct. Returns the
+ * sync_timeline object or NULL in case of error.
*/
struct sync_timeline *sync_timeline_create(const struct sync_timeline_ops *ops,
int size, const char *name);
@@ -231,7 +224,8 @@ void sync_timeline_signal(struct sync_timeline *obj);
*
* Creates a new sync_pt as a child of @parent. @size bytes will be
* allocated allowing for implementation specific data to be kept after
- * the generic sync_timeline struct.
+ * the generic sync_timeline struct. Returns the sync_pt object or
+ * NULL in case of error.
*/
struct sync_pt *sync_pt_create(struct sync_timeline *parent, int size);
@@ -275,7 +269,8 @@ struct sync_fence *sync_fence_create_dma(const char *name, struct fence *pt);
* @b: fence b
*
* Creates a new fence which contains copies of all the sync_pts in both
- * @a and @b. @a and @b remain valid, independent fences.
+ * @a and @b. @a and @b remain valid, independent fences. Returns the
+ * new merged fence or NULL in case of error.
*/
struct sync_fence *sync_fence_merge(const char *name,
struct sync_fence *a, struct sync_fence *b);
@@ -285,7 +280,7 @@ struct sync_fence *sync_fence_merge(const char *name,
* @fd: fd referencing a fence
*
* Ensures @fd references a valid fence, increments the refcount of the backing
- * file, and returns the fence.
+ * file, and returns the fence. Returns the fence or NULL in case of error.
*/
struct sync_fence *sync_fence_fdget(int fd);
@@ -313,10 +308,10 @@ void sync_fence_install(struct sync_fence *fence, int fd);
* @fence: fence to wait on
* @waiter: waiter callback struck
*
- * Returns 1 if @fence has already signaled.
- *
* Registers a callback to be called when @fence signals or has an error.
* @waiter should be initialized with sync_fence_waiter_init().
+ *
+ * Returns 1 if @fence has already signaled, 0 if not or <0 if error.
*/
int sync_fence_wait_async(struct sync_fence *fence,
struct sync_fence_waiter *waiter);
@@ -326,11 +321,11 @@ int sync_fence_wait_async(struct sync_fence *fence,
* @fence: fence to wait on
* @waiter: waiter callback struck
*
- * returns 0 if waiter was removed from fence's async waiter list.
- * returns -ENOENT if waiter was not found on fence's async waiter list.
- *
* Cancels a previously registered async wait. Will fail gracefully if
* @waiter was never registered or if @fence has already signaled @waiter.
+ *
+ * Returns 0 if waiter was removed from fence's async waiter list.
+ * Returns -ENOENT if waiter was not found on fence's async waiter list.
*/
int sync_fence_cancel_async(struct sync_fence *fence,
struct sync_fence_waiter *waiter);
@@ -341,7 +336,9 @@ int sync_fence_cancel_async(struct sync_fence *fence,
* @tiemout: timeout in ms
*
* Wait for @fence to be signaled or have an error. Waits indefinitely
- * if @timeout < 0
+ * if @timeout < 0.
+ *
+ * Returns 0 if fence signaled, > 0 if it is still active and <0 on error
*/
int sync_fence_wait(struct sync_fence *fence, long timeout);
--
2.5.0
Powered by blists - more mailing lists