summaryrefslogtreecommitdiffstats
path: root/include/media/media-request.h
blob: bd36d74316984161bd7e1828b60c189affdf8af3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
// SPDX-License-Identifier: GPL-2.0
/*
 * Media device request objects
 *
 * Copyright 2018 Cisco Systems, Inc. and/or its affiliates. All rights reserved.
 * Copyright (C) 2018 Intel Corporation
 *
 * Author: Hans Verkuil <hans.verkuil@cisco.com>
 * Author: Sakari Ailus <sakari.ailus@linux.intel.com>
 */

#ifndef MEDIA_REQUEST_H
#define MEDIA_REQUEST_H

#include <linux/list.h>
#include <linux/slab.h>
#include <linux/spinlock.h>
#include <linux/refcount.h>

#include <media/media-device.h>

/**
 * enum media_request_state - media request state
 *
 * @MEDIA_REQUEST_STATE_IDLE:		Idle
 * @MEDIA_REQUEST_STATE_VALIDATING:	Validating the request, no state changes
 *					allowed
 * @MEDIA_REQUEST_STATE_QUEUED:		Queued
 * @MEDIA_REQUEST_STATE_COMPLETE:	Completed, the request is done
 * @MEDIA_REQUEST_STATE_CLEANING:	Cleaning, the request is being re-inited
 * @MEDIA_REQUEST_STATE_UPDATING:	The request is being updated, i.e.
 *					request objects are being added,
 *					modified or removed
 * @NR_OF_MEDIA_REQUEST_STATE:		The number of media request states, used
 *					internally for sanity check purposes
 */
enum media_request_state {
	MEDIA_REQUEST_STATE_IDLE,
	MEDIA_REQUEST_STATE_VALIDATING,
	MEDIA_REQUEST_STATE_QUEUED,
	MEDIA_REQUEST_STATE_COMPLETE,
	MEDIA_REQUEST_STATE_CLEANING,
	MEDIA_REQUEST_STATE_UPDATING,
	NR_OF_MEDIA_REQUEST_STATE,
};

struct media_request_object;

/**
 * struct media_request - Media device request
 * @mdev: Media device this request belongs to
 * @kref: Reference count
 * @debug_str: Prefix for debug messages (process name:fd)
 * @state: The state of the request
 * @updating_count: count the number of request updates that are in progress
 * @access_count: count the number of request accesses that are in progress
 * @objects: List of @struct media_request_object request objects
 * @num_incomplete_objects: The number of incomplete objects in the request
 * @poll_wait: Wait queue for poll
 * @lock: Serializes access to this struct
 */
struct media_request {
	struct media_device *mdev;
	struct kref kref;
	char debug_str[TASK_COMM_LEN + 11];
	enum media_request_state state;
	unsigned int updating_count;
	unsigned int access_count;
	struct list_head objects;
	unsigned int num_incomplete_objects;
	wait_queue_head_t poll_wait;
	spinlock_t lock;
};

#ifdef CONFIG_MEDIA_CONTROLLER

/**
 * media_request_lock_for_access - Lock the request to access its objects
 *
 * @req: The media request
 *
 * Use before accessing a completed request. A reference to the request must
 * be held during the access. This usually takes place automatically through
 * a file handle. Use @media_request_unlock_for_access when done.
 */
static inline int __must_check
media_request_lock_for_access(struct media_request *req)
{
	unsigned long flags;
	int ret = -EBUSY;

	spin_lock_irqsave(&req->lock, flags);
	if (req->state == MEDIA_REQUEST_STATE_COMPLETE) {
		req->access_count++;
		ret = 0;
	}
	spin_unlock_irqrestore(&req->lock, flags);

	return ret;
}

/**
 * media_request_unlock_for_access - Unlock a request previously locked for
 *				     access
 *
 * @req: The media request
 *
 * Unlock a request that has previously been locked using
 * @media_request_lock_for_access.
 */
static inline void media_request_unlock_for_access(struct media_request *req)
{
	unsigned long flags;

	spin_lock_irqsave(&req->lock, flags);
	if (!WARN_ON(!req->access_count))
		req->access_count--;
	spin_unlock_irqrestore(&req->lock, flags);
}

/**
 * media_request_lock_for_update - Lock the request for updating its objects
 *
 * @req: The media request
 *
 * Use before updating a request, i.e. adding, modifying or removing a request
 * object in it. A reference to the request must be held during the update. This
 * usually takes place automatically through a file handle. Use
 * @media_request_unlock_for_update when done.
 */
static inline int __must_check
media_request_lock_for_update(struct media_request *req)
{
	unsigned long flags;
	int ret = 0;

	spin_lock_irqsave(&req->lock, flags);
	if (req->state == MEDIA_REQUEST_STATE_IDLE ||
	    req->state == MEDIA_REQUEST_STATE_UPDATING) {
		req->state = MEDIA_REQUEST_STATE_UPDATING;
		req->updating_count++;
	} else {
		ret = -EBUSY;
	}
	spin_unlock_irqrestore(&req->lock, flags);

	return ret;
}

/**
 * media_request_unlock_for_update - Unlock a request previously locked for
 *				     update
 *
 * @req: The media request
 *
 * Unlock a request that has previously been locked using
 * @media_request_lock_for_update.
 */
static inline void media_request_unlock_for_update(struct media_request *req)
{
	unsigned long flags;

	spin_lock_irqsave(&req->lock, flags);
	WARN_ON(req->updating_count <= 0);
	if (!--req->updating_count)
		req->state = MEDIA_REQUEST_STATE_IDLE;
	spin_unlock_irqrestore(&req->lock, flags);
}

/**
 * media_request_get - Get the media request
 *
 * @req: The media request
 *
 * Get the media request.
 */
static inline void media_request_get(struct media_request *req)
{
	kref_get(&req->kref);
}

/**
 * media_request_put - Put the media request
 *
 * @req: The media request
 *
 * Put the media request. The media request will be released
 * when the refcount reaches 0.
 */
void media_request_put(struct media_request *req);

/**
 * media_request_get_by_fd - Get a media request by fd
 *
 * @mdev: Media device this request belongs to
 * @request_fd: The file descriptor of the request
 *
 * Get the request represented by @request_fd that is owned
 * by the media device.
 *
 * Return a -EACCES error pointer if requests are not supported
 * by this driver. Return -EINVAL if the request was not found.
 * Return the pointer to the request if found: the caller will
 * have to call @media_request_put when it finished using the
 * request.
 */
struct media_request *
media_request_get_by_fd(struct media_device *mdev, int request_fd);

/**
 * media_request_alloc - Allocate the media request
 *
 * @mdev: Media device this request belongs to
 * @alloc_fd: Store the request's file descriptor in this int
 *
 * Allocated the media request and put the fd in @alloc_fd.
 */
int media_request_alloc(struct media_device *mdev,
			int *alloc_fd);

#else

static inline void media_request_get(struct media_request *req)
{
}

static inline void media_request_put(struct media_request *req)
{
}

static inline struct media_request *
media_request_get_by_fd(struct media_device *mdev, int request_fd)
{
	return ERR_PTR(-EACCES);
}

#endif

/**
 * struct media_request_object_ops - Media request object operations
 * @prepare: Validate and prepare the request object, optional.
 * @unprepare: Unprepare the request object, optional.
 * @queue: Queue the request object, optional.
 * @unbind: Unbind the request object, optional.
 * @release: Release the request object, required.
 */
struct media_request_object_ops {
	int (*prepare)(struct media_request_object *object);
	void (*unprepare)(struct media_request_object *object);
	void (*queue)(struct media_request_object *object);
	void (*unbind)(struct media_request_object *object);
	void (*release)(struct media_request_object *object);
};

/**
 * struct media_request_object - An opaque object that belongs to a media
 *				 request
 *
 * @ops: object's operations
 * @priv: object's priv pointer
 * @req: the request this object belongs to (can be NULL)
 * @list: List entry of the object for @struct media_request
 * @kref: Reference count of the object, acquire before releasing req->lock
 * @completed: If true, then this object was completed.
 *
 * An object related to the request. This struct is always embedded in
 * another struct that contains the actual data for this request object.
 */
struct media_request_object {
	const struct media_request_object_ops *ops;
	void *priv;
	struct media_request *req;
	struct list_head list;
	struct kref kref;
	bool completed;
};

#ifdef CONFIG_MEDIA_CONTROLLER

/**
 * media_request_object_get - Get a media request object
 *
 * @obj: The object
 *
 * Get a media request object.
 */
static inline void media_request_object_get(struct media_request_object *obj)
{
	kref_get(&obj->kref);
}

/**
 * media_request_object_put - Put a media request object
 *
 * @obj: The object
 *
 * Put a media request object. Once all references are gone, the
 * object's memory is released.
 */
void media_request_object_put(struct media_request_object *obj);

/**
 * media_request_object_find - Find an object in a request
 *
 * @req: The media request
 * @ops: Find an object with this ops value
 * @priv: Find an object with this priv value
 *
 * Both @ops and @priv must be non-NULL.
 *
 * Returns the object pointer or NULL if not found. The caller must
 * call media_request_object_put() once it finished using the object.
 *
 * Since this function needs to walk the list of objects it takes
 * the @req->lock spin lock to make this safe.
 */
struct media_request_object *
media_request_object_find(struct media_request *req,
			  const struct media_request_object_ops *ops,
			  void *priv);

/**
 * media_request_object_init - Initialise a media request object
 *
 * @obj: The object
 *
 * Initialise a media request object. The object will be released using the
 * release callback of the ops once it has no references (this function
 * initialises references to one).
 */
void media_request_object_init(struct media_request_object *obj);

/**
 * media_request_object_bind - Bind a media request object to a request
 *
 * @req: The media request
 * @ops: The object ops for this object
 * @priv: A driver-specific priv pointer associated with this object
 * @is_buffer: Set to true if the object a buffer object.
 * @obj: The object
 *
 * Bind this object to the request and set the ops and priv values of
 * the object so it can be found later with media_request_object_find().
 *
 * Every bound object must be unbound or completed by the kernel at some
 * point in time, otherwise the request will never complete. When the
 * request is released all completed objects will be unbound by the
 * request core code.
 *
 * Buffer objects will be added to the end of the request's object
 * list, non-buffer objects will be added to the front of the list.
 * This ensures that all buffer objects are at the end of the list
 * and that all non-buffer objects that they depend on are processed
 * first.
 */
int media_request_object_bind(struct media_request *req,
			      const struct media_request_object_ops *ops,
			      void *priv, bool is_buffer,
			      struct media_request_object *obj);

/**
 * media_request_object_unbind - Unbind a media request object
 *
 * @obj: The object
 *
 * Unbind the media request object from the request.
 */
void media_request_object_unbind(struct media_request_object *obj);

/**
 * media_request_object_complete - Mark the media request object as complete
 *
 * @obj: The object
 *
 * Mark the media request object as complete. Only bound objects can
 * be completed.
 */
void media_request_object_complete(struct media_request_object *obj);

#else

static inline int __must_check
media_request_lock_for_access(struct media_request *req)
{
	return -EINVAL;
}

static inline void media_request_unlock_for_access(struct media_request *req)
{
}

static inline int __must_check
media_request_lock_for_update(struct media_request *req)
{
	return -EINVAL;
}

static inline void media_request_unlock_for_update(struct media_request *req)
{
}

static inline void media_request_object_get(struct media_request_object *obj)
{
}

static inline void media_request_object_put(struct media_request_object *obj)
{
}

static inline struct media_request_object *
media_request_object_find(struct media_request *req,
			  const struct media_request_object_ops *ops,
			  void *priv)
{
	return NULL;
}

static inline void media_request_object_init(struct media_request_object *obj)
{
	obj->ops = NULL;
	obj->req = NULL;
}

static inline int media_request_object_bind(struct media_request *req,
			       const struct media_request_object_ops *ops,
			       void *priv, bool is_buffer,
			       struct media_request_object *obj)
{
	return 0;
}

static inline void media_request_object_unbind(struct media_request_object *obj)
{
}

static inline void media_request_object_complete(struct media_request_object *obj)
{
}

#endif

#endif