aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRob Clark <robdclark@gmail.com>2016-03-31 16:26:51 -0400
committerSumit Semwal <sumit.semwal@linaro.org>2016-05-31 12:42:43 -0400
commitdad6c3945fd25384c2b92306a90ba033e1130428 (patch)
treea31f86b0d66c999262eb3df8547812a3159ace6b
parente2082e3ab801b989d8d5337b2ecbfc61d09781cb (diff)
reservation: add headerdoc comments
Signed-off-by: Rob Clark <robdclark@gmail.com> Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org>
-rw-r--r--drivers/dma-buf/reservation.c72
-rw-r--r--include/linux/reservation.h53
2 files changed, 121 insertions, 4 deletions
diff --git a/drivers/dma-buf/reservation.c b/drivers/dma-buf/reservation.c
index c0bd5722c997..9566a62ad8e3 100644
--- a/drivers/dma-buf/reservation.c
+++ b/drivers/dma-buf/reservation.c
@@ -35,6 +35,17 @@
35#include <linux/reservation.h> 35#include <linux/reservation.h>
36#include <linux/export.h> 36#include <linux/export.h>
37 37
38/**
39 * DOC: Reservation Object Overview
40 *
41 * The reservation object provides a mechanism to manage shared and
42 * exclusive fences associated with a buffer. A reservation object
43 * can have attached one exclusive fence (normally associated with
44 * write operations) or N shared fences (read operations). The RCU
45 * mechanism is used to protect read access to fences from locked
46 * write-side updates.
47 */
48
38DEFINE_WW_CLASS(reservation_ww_class); 49DEFINE_WW_CLASS(reservation_ww_class);
39EXPORT_SYMBOL(reservation_ww_class); 50EXPORT_SYMBOL(reservation_ww_class);
40 51
@@ -43,9 +54,17 @@ EXPORT_SYMBOL(reservation_seqcount_class);
43 54
44const char reservation_seqcount_string[] = "reservation_seqcount"; 55const char reservation_seqcount_string[] = "reservation_seqcount";
45EXPORT_SYMBOL(reservation_seqcount_string); 56EXPORT_SYMBOL(reservation_seqcount_string);
46/* 57
47 * Reserve space to add a shared fence to a reservation_object, 58/**
48 * must be called with obj->lock held. 59 * reservation_object_reserve_shared - Reserve space to add a shared
60 * fence to a reservation_object.
61 * @obj: reservation object
62 *
63 * Should be called before reservation_object_add_shared_fence(). Must
64 * be called with obj->lock held.
65 *
66 * RETURNS
67 * Zero for success, or -errno
49 */ 68 */
50int reservation_object_reserve_shared(struct reservation_object *obj) 69int reservation_object_reserve_shared(struct reservation_object *obj)
51{ 70{
@@ -180,7 +199,11 @@ done:
180 fence_put(old_fence); 199 fence_put(old_fence);
181} 200}
182 201
183/* 202/**
203 * reservation_object_add_shared_fence - Add a fence to a shared slot
204 * @obj: the reservation object
205 * @fence: the shared fence to add
206 *
184 * Add a fence to a shared slot, obj->lock must be held, and 207 * Add a fence to a shared slot, obj->lock must be held, and
185 * reservation_object_reserve_shared_fence has been called. 208 * reservation_object_reserve_shared_fence has been called.
186 */ 209 */
@@ -200,6 +223,13 @@ void reservation_object_add_shared_fence(struct reservation_object *obj,
200} 223}
201EXPORT_SYMBOL(reservation_object_add_shared_fence); 224EXPORT_SYMBOL(reservation_object_add_shared_fence);
202 225
226/**
227 * reservation_object_add_excl_fence - Add an exclusive fence.
228 * @obj: the reservation object
229 * @fence: the shared fence to add
230 *
231 * Add a fence to the exclusive slot. The obj->lock must be held.
232 */
203void reservation_object_add_excl_fence(struct reservation_object *obj, 233void reservation_object_add_excl_fence(struct reservation_object *obj,
204 struct fence *fence) 234 struct fence *fence)
205{ 235{
@@ -233,6 +263,18 @@ void reservation_object_add_excl_fence(struct reservation_object *obj,
233} 263}
234EXPORT_SYMBOL(reservation_object_add_excl_fence); 264EXPORT_SYMBOL(reservation_object_add_excl_fence);
235 265
266/**
267 * reservation_object_get_fences_rcu - Get an object's shared and exclusive
268 * fences without update side lock held
269 * @obj: the reservation object
270 * @pfence_excl: the returned exclusive fence (or NULL)
271 * @pshared_count: the number of shared fences returned
272 * @pshared: the array of shared fence ptrs returned (array is krealloc'd to
273 * the required size, and must be freed by caller)
274 *
275 * RETURNS
276 * Zero or -errno
277 */
236int reservation_object_get_fences_rcu(struct reservation_object *obj, 278int reservation_object_get_fences_rcu(struct reservation_object *obj,
237 struct fence **pfence_excl, 279 struct fence **pfence_excl,
238 unsigned *pshared_count, 280 unsigned *pshared_count,
@@ -319,6 +361,18 @@ unlock:
319} 361}
320EXPORT_SYMBOL_GPL(reservation_object_get_fences_rcu); 362EXPORT_SYMBOL_GPL(reservation_object_get_fences_rcu);
321 363
364/**
365 * reservation_object_wait_timeout_rcu - Wait on reservation's objects
366 * shared and/or exclusive fences.
367 * @obj: the reservation object
368 * @wait_all: if true, wait on all fences, else wait on just exclusive fence
369 * @intr: if true, do interruptible wait
370 * @timeout: timeout value in jiffies or zero to return immediately
371 *
372 * RETURNS
373 * Returns -ERESTARTSYS if interrupted, 0 if the wait timed out, or
374 * greater than zer on success.
375 */
322long reservation_object_wait_timeout_rcu(struct reservation_object *obj, 376long reservation_object_wait_timeout_rcu(struct reservation_object *obj,
323 bool wait_all, bool intr, 377 bool wait_all, bool intr,
324 unsigned long timeout) 378 unsigned long timeout)
@@ -416,6 +470,16 @@ reservation_object_test_signaled_single(struct fence *passed_fence)
416 return ret; 470 return ret;
417} 471}
418 472
473/**
474 * reservation_object_test_signaled_rcu - Test if a reservation object's
475 * fences have been signaled.
476 * @obj: the reservation object
477 * @test_all: if true, test all fences, otherwise only test the exclusive
478 * fence
479 *
480 * RETURNS
481 * true if all fences signaled, else false
482 */
419bool reservation_object_test_signaled_rcu(struct reservation_object *obj, 483bool reservation_object_test_signaled_rcu(struct reservation_object *obj,
420 bool test_all) 484 bool test_all)
421{ 485{
diff --git a/include/linux/reservation.h b/include/linux/reservation.h
index 49d057655d62..b0f305e77b7f 100644
--- a/include/linux/reservation.h
+++ b/include/linux/reservation.h
@@ -49,12 +49,27 @@ extern struct ww_class reservation_ww_class;
49extern struct lock_class_key reservation_seqcount_class; 49extern struct lock_class_key reservation_seqcount_class;
50extern const char reservation_seqcount_string[]; 50extern const char reservation_seqcount_string[];
51 51
52/**
53 * struct reservation_object_list - a list of shared fences
54 * @rcu: for internal use
55 * @shared_count: table of shared fences
56 * @shared_max: for growing shared fence table
57 * @shared: shared fence table
58 */
52struct reservation_object_list { 59struct reservation_object_list {
53 struct rcu_head rcu; 60 struct rcu_head rcu;
54 u32 shared_count, shared_max; 61 u32 shared_count, shared_max;
55 struct fence __rcu *shared[]; 62 struct fence __rcu *shared[];
56}; 63};
57 64
65/**
66 * struct reservation_object - a reservation object manages fences for a buffer
67 * @lock: update side lock
68 * @seq: sequence count for managing RCU read-side synchronization
69 * @fence_excl: the exclusive fence, if there is one currently
70 * @fence: list of current shared fences
71 * @staged: staged copy of shared fences for RCU updates
72 */
58struct reservation_object { 73struct reservation_object {
59 struct ww_mutex lock; 74 struct ww_mutex lock;
60 seqcount_t seq; 75 seqcount_t seq;
@@ -68,6 +83,10 @@ struct reservation_object {
68#define reservation_object_assert_held(obj) \ 83#define reservation_object_assert_held(obj) \
69 lockdep_assert_held(&(obj)->lock.base) 84 lockdep_assert_held(&(obj)->lock.base)
70 85
86/**
87 * reservation_object_init - initialize a reservation object
88 * @obj: the reservation object
89 */
71static inline void 90static inline void
72reservation_object_init(struct reservation_object *obj) 91reservation_object_init(struct reservation_object *obj)
73{ 92{
@@ -79,6 +98,10 @@ reservation_object_init(struct reservation_object *obj)
79 obj->staged = NULL; 98 obj->staged = NULL;
80} 99}
81 100
101/**
102 * reservation_object_fini - destroys a reservation object
103 * @obj: the reservation object
104 */
82static inline void 105static inline void
83reservation_object_fini(struct reservation_object *obj) 106reservation_object_fini(struct reservation_object *obj)
84{ 107{
@@ -106,6 +129,14 @@ reservation_object_fini(struct reservation_object *obj)
106 ww_mutex_destroy(&obj->lock); 129 ww_mutex_destroy(&obj->lock);
107} 130}
108 131
132/**
133 * reservation_object_get_list - get the reservation object's
134 * shared fence list, with update-side lock held
135 * @obj: the reservation object
136 *
137 * Returns the shared fence list. Does NOT take references to
138 * the fence. The obj->lock must be held.
139 */
109static inline struct reservation_object_list * 140static inline struct reservation_object_list *
110reservation_object_get_list(struct reservation_object *obj) 141reservation_object_get_list(struct reservation_object *obj)
111{ 142{
@@ -113,6 +144,17 @@ reservation_object_get_list(struct reservation_object *obj)
113 reservation_object_held(obj)); 144 reservation_object_held(obj));
114} 145}
115 146
147/**
148 * reservation_object_get_excl - get the reservation object's
149 * exclusive fence, with update-side lock held
150 * @obj: the reservation object
151 *
152 * Returns the exclusive fence (if any). Does NOT take a
153 * reference. The obj->lock must be held.
154 *
155 * RETURNS
156 * The exclusive fence or NULL
157 */
116static inline struct fence * 158static inline struct fence *
117reservation_object_get_excl(struct reservation_object *obj) 159reservation_object_get_excl(struct reservation_object *obj)
118{ 160{
@@ -120,6 +162,17 @@ reservation_object_get_excl(struct reservation_object *obj)
120 reservation_object_held(obj)); 162 reservation_object_held(obj));
121} 163}
122 164
165/**
166 * reservation_object_get_excl_rcu - get the reservation object's
167 * exclusive fence, without lock held.
168 * @obj: the reservation object
169 *
170 * If there is an exclusive fence, this atomically increments it's
171 * reference count and returns it.
172 *
173 * RETURNS
174 * The exclusive fence or NULL if none
175 */
123static inline struct fence * 176static inline struct fence *
124reservation_object_get_excl_rcu(struct reservation_object *obj) 177reservation_object_get_excl_rcu(struct reservation_object *obj)
125{ 178{