diff options
author | Rob Clark <robdclark@gmail.com> | 2016-03-31 16:26:51 -0400 |
---|---|---|
committer | Sumit Semwal <sumit.semwal@linaro.org> | 2016-05-31 12:42:43 -0400 |
commit | dad6c3945fd25384c2b92306a90ba033e1130428 (patch) | |
tree | a31f86b0d66c999262eb3df8547812a3159ace6b | |
parent | e2082e3ab801b989d8d5337b2ecbfc61d09781cb (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.c | 72 | ||||
-rw-r--r-- | include/linux/reservation.h | 53 |
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 | |||
38 | DEFINE_WW_CLASS(reservation_ww_class); | 49 | DEFINE_WW_CLASS(reservation_ww_class); |
39 | EXPORT_SYMBOL(reservation_ww_class); | 50 | EXPORT_SYMBOL(reservation_ww_class); |
40 | 51 | ||
@@ -43,9 +54,17 @@ EXPORT_SYMBOL(reservation_seqcount_class); | |||
43 | 54 | ||
44 | const char reservation_seqcount_string[] = "reservation_seqcount"; | 55 | const char reservation_seqcount_string[] = "reservation_seqcount"; |
45 | EXPORT_SYMBOL(reservation_seqcount_string); | 56 | EXPORT_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 | */ |
50 | int reservation_object_reserve_shared(struct reservation_object *obj) | 69 | int 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 | } |
201 | EXPORT_SYMBOL(reservation_object_add_shared_fence); | 224 | EXPORT_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 | */ | ||
203 | void reservation_object_add_excl_fence(struct reservation_object *obj, | 233 | void 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 | } |
234 | EXPORT_SYMBOL(reservation_object_add_excl_fence); | 264 | EXPORT_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 | */ | ||
236 | int reservation_object_get_fences_rcu(struct reservation_object *obj, | 278 | int 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 | } |
320 | EXPORT_SYMBOL_GPL(reservation_object_get_fences_rcu); | 362 | EXPORT_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 | */ | ||
322 | long reservation_object_wait_timeout_rcu(struct reservation_object *obj, | 376 | long 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 | */ | ||
419 | bool reservation_object_test_signaled_rcu(struct reservation_object *obj, | 483 | bool 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; | |||
49 | extern struct lock_class_key reservation_seqcount_class; | 49 | extern struct lock_class_key reservation_seqcount_class; |
50 | extern const char reservation_seqcount_string[]; | 50 | extern 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 | */ | ||
52 | struct reservation_object_list { | 59 | struct 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 | */ | ||
58 | struct reservation_object { | 73 | struct 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 | */ | ||
71 | static inline void | 90 | static inline void |
72 | reservation_object_init(struct reservation_object *obj) | 91 | reservation_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 | */ | ||
82 | static inline void | 105 | static inline void |
83 | reservation_object_fini(struct reservation_object *obj) | 106 | reservation_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 | */ | ||
109 | static inline struct reservation_object_list * | 140 | static inline struct reservation_object_list * |
110 | reservation_object_get_list(struct reservation_object *obj) | 141 | reservation_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 | */ | ||
116 | static inline struct fence * | 158 | static inline struct fence * |
117 | reservation_object_get_excl(struct reservation_object *obj) | 159 | reservation_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 | */ | ||
123 | static inline struct fence * | 176 | static inline struct fence * |
124 | reservation_object_get_excl_rcu(struct reservation_object *obj) | 177 | reservation_object_get_excl_rcu(struct reservation_object *obj) |
125 | { | 178 | { |