Commit | Line | Data |
---|---|---|
53e269c1 LP |
1 | /* |
2 | * Media entity | |
3 | * | |
4 | * Copyright (C) 2010 Nokia Corporation | |
5 | * | |
6 | * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com> | |
7 | * Sakari Ailus <sakari.ailus@iki.fi> | |
8 | * | |
9 | * This program is free software; you can redistribute it and/or modify | |
10 | * it under the terms of the GNU General Public License version 2 as | |
11 | * published by the Free Software Foundation. | |
12 | * | |
13 | * This program is distributed in the hope that it will be useful, | |
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
16 | * GNU General Public License for more details. | |
17 | * | |
18 | * You should have received a copy of the GNU General Public License | |
19 | * along with this program; if not, write to the Free Software | |
20 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
21 | */ | |
22 | ||
23 | #ifndef _MEDIA_ENTITY_H | |
24 | #define _MEDIA_ENTITY_H | |
25 | ||
c8d54cd5 | 26 | #include <linux/bitmap.h> |
2899d35d | 27 | #include <linux/bug.h> |
0149a2e1 | 28 | #include <linux/kernel.h> |
53e269c1 | 29 | #include <linux/list.h> |
1651333b | 30 | #include <linux/media.h> |
53e269c1 | 31 | |
ec6e4c95 MCC |
32 | /* Enums used internally at the media controller to represent graphs */ |
33 | ||
34 | /** | |
35 | * enum media_gobj_type - type of a graph object | |
36 | * | |
bfab2aac | 37 | * @MEDIA_GRAPH_ENTITY: Identify a media entity |
18710dc6 | 38 | * @MEDIA_GRAPH_PAD: Identify a media pad |
6b6a4278 | 39 | * @MEDIA_GRAPH_LINK: Identify a media link |
27e543fa MCC |
40 | * @MEDIA_GRAPH_INTF_DEVNODE: Identify a media Kernel API interface via |
41 | * a device node | |
ec6e4c95 MCC |
42 | */ |
43 | enum media_gobj_type { | |
bfab2aac | 44 | MEDIA_GRAPH_ENTITY, |
18710dc6 | 45 | MEDIA_GRAPH_PAD, |
6b6a4278 | 46 | MEDIA_GRAPH_LINK, |
27e543fa | 47 | MEDIA_GRAPH_INTF_DEVNODE, |
ec6e4c95 MCC |
48 | }; |
49 | ||
50 | #define MEDIA_BITS_PER_TYPE 8 | |
05b3b77c MCC |
51 | #define MEDIA_BITS_PER_ID (32 - MEDIA_BITS_PER_TYPE) |
52 | #define MEDIA_ID_MASK GENMASK_ULL(MEDIA_BITS_PER_ID - 1, 0) | |
ec6e4c95 MCC |
53 | |
54 | /* Structs to represent the objects that belong to a media graph */ | |
55 | ||
56 | /** | |
57 | * struct media_gobj - Define a graph object. | |
58 | * | |
c358e80d | 59 | * @mdev: Pointer to the struct media_device that owns the object |
ec6e4c95 MCC |
60 | * @id: Non-zero object ID identifier. The ID should be unique |
61 | * inside a media_device, as it is composed by | |
05b3b77c MCC |
62 | * %MEDIA_BITS_PER_TYPE to store the type plus |
63 | * %MEDIA_BITS_PER_ID to store the ID | |
c358e80d | 64 | * @list: List entry stored in one of the per-type mdev object lists |
ec6e4c95 MCC |
65 | * |
66 | * All objects on the media graph should have this struct embedded | |
67 | */ | |
68 | struct media_gobj { | |
39a956c4 | 69 | struct media_device *mdev; |
ec6e4c95 | 70 | u32 id; |
05bfa9fa | 71 | struct list_head list; |
ec6e4c95 MCC |
72 | }; |
73 | ||
c8d54cd5 | 74 | #define MEDIA_ENTITY_ENUM_MAX_DEPTH 16 |
c8d54cd5 | 75 | |
c8d54cd5 SA |
76 | /** |
77 | * struct media_entity_enum - An enumeration of media entities. | |
78 | * | |
c8d54cd5 SA |
79 | * @bmap: Bit map in which each bit represents one entity at struct |
80 | * media_entity->internal_idx. | |
81 | * @idx_max: Number of bits in bmap | |
82 | */ | |
83 | struct media_entity_enum { | |
c8d54cd5 SA |
84 | unsigned long *bmap; |
85 | int idx_max; | |
86 | }; | |
87 | ||
434257f1 SA |
88 | /** |
89 | * struct media_entity_graph - Media graph traversal state | |
90 | * | |
91 | * @stack: Graph traversal stack; the stack contains information | |
92 | * on the path the media entities to be walked and the | |
93 | * links through which they were reached. | |
29d8da02 | 94 | * @ent_enum: Visited entities |
434257f1 SA |
95 | * @top: The top of the stack |
96 | */ | |
82c68290 SA |
97 | struct media_entity_graph { |
98 | struct { | |
99 | struct media_entity *entity; | |
100 | struct list_head *link; | |
101 | } stack[MEDIA_ENTITY_ENUM_MAX_DEPTH]; | |
102 | ||
29d8da02 | 103 | struct media_entity_enum ent_enum; |
82c68290 SA |
104 | int top; |
105 | }; | |
106 | ||
5dd8775d SA |
107 | /* |
108 | * struct media_pipeline - Media pipeline related information | |
109 | * | |
74a41330 SA |
110 | * @streaming_count: Streaming start count - streaming stop count |
111 | * @graph: Media graph walk during pipeline start / stop | |
5dd8775d | 112 | */ |
e02188c9 | 113 | struct media_pipeline { |
74a41330 | 114 | int streaming_count; |
5dd8775d | 115 | struct media_entity_graph graph; |
e02188c9 LP |
116 | }; |
117 | ||
c358e80d MCC |
118 | /** |
119 | * struct media_link - A link object part of a media graph. | |
120 | * | |
121 | * @graph_obj: Embedded structure containing the media object common data | |
122 | * @list: Linked list associated with an entity or an interface that | |
123 | * owns the link. | |
124 | * @gobj0: Part of a union. Used to get the pointer for the first | |
125 | * graph_object of the link. | |
126 | * @source: Part of a union. Used only if the first object (gobj0) is | |
127 | * a pad. In that case, it represents the source pad. | |
128 | * @intf: Part of a union. Used only if the first object (gobj0) is | |
129 | * an interface. | |
130 | * @gobj1: Part of a union. Used to get the pointer for the second | |
131 | * graph_object of the link. | |
132 | * @source: Part of a union. Used only if the second object (gobj1) is | |
133 | * a pad. In that case, it represents the sink pad. | |
134 | * @entity: Part of a union. Used only if the second object (gobj1) is | |
135 | * an entity. | |
136 | * @reverse: Pointer to the link for the reverse direction of a pad to pad | |
137 | * link. | |
138 | * @flags: Link flags, as defined in uapi/media.h (MEDIA_LNK_FL_*) | |
39d1ebc6 | 139 | * @is_backlink: Indicate if the link is a backlink. |
c358e80d | 140 | */ |
53e269c1 | 141 | struct media_link { |
6b6a4278 | 142 | struct media_gobj graph_obj; |
57208e5e | 143 | struct list_head list; |
4b8a3c08 MCC |
144 | union { |
145 | struct media_gobj *gobj0; | |
146 | struct media_pad *source; | |
86e26620 | 147 | struct media_interface *intf; |
4b8a3c08 MCC |
148 | }; |
149 | union { | |
150 | struct media_gobj *gobj1; | |
151 | struct media_pad *sink; | |
86e26620 | 152 | struct media_entity *entity; |
4b8a3c08 | 153 | }; |
c358e80d MCC |
154 | struct media_link *reverse; |
155 | unsigned long flags; | |
39d1ebc6 | 156 | bool is_backlink; |
53e269c1 LP |
157 | }; |
158 | ||
c358e80d MCC |
159 | /** |
160 | * struct media_pad - A media pad graph object. | |
161 | * | |
162 | * @graph_obj: Embedded structure containing the media object common data | |
163 | * @entity: Entity this pad belongs to | |
164 | * @index: Pad index in the entity pads array, numbered from 0 to n | |
165 | * @flags: Pad flags, as defined in uapi/media.h (MEDIA_PAD_FL_*) | |
166 | */ | |
53e269c1 | 167 | struct media_pad { |
4b8a3c08 | 168 | struct media_gobj graph_obj; /* must be first field in struct */ |
c358e80d MCC |
169 | struct media_entity *entity; |
170 | u16 index; | |
171 | unsigned long flags; | |
53e269c1 LP |
172 | }; |
173 | ||
5a5394be LP |
174 | /** |
175 | * struct media_entity_operations - Media entity operations | |
176 | * @link_setup: Notify the entity of link changes. The operation can | |
177 | * return an error, in which case link setup will be | |
178 | * cancelled. Optional. | |
179 | * @link_validate: Return whether a link is valid from the entity point of | |
180 | * view. The media_entity_pipeline_start() function | |
181 | * validates all links by calling this operation. Optional. | |
182 | */ | |
97548ed4 LP |
183 | struct media_entity_operations { |
184 | int (*link_setup)(struct media_entity *entity, | |
185 | const struct media_pad *local, | |
186 | const struct media_pad *remote, u32 flags); | |
af88be38 | 187 | int (*link_validate)(struct media_link *link); |
97548ed4 LP |
188 | }; |
189 | ||
c358e80d MCC |
190 | /** |
191 | * struct media_entity - A media entity graph object. | |
192 | * | |
193 | * @graph_obj: Embedded structure containing the media object common data. | |
194 | * @name: Entity name. | |
0e576b76 MCC |
195 | * @function: Entity main function, as defined in uapi/media.h |
196 | * (MEDIA_ENT_F_*) | |
c358e80d | 197 | * @flags: Entity flags, as defined in uapi/media.h (MEDIA_ENT_FL_*) |
c358e80d MCC |
198 | * @num_pads: Number of sink and source pads. |
199 | * @num_links: Total number of links, forward and back, enabled and disabled. | |
200 | * @num_backlinks: Number of backlinks | |
665faa97 SA |
201 | * @internal_idx: An unique internal entity specific number. The numbers are |
202 | * re-used if entities are unregistered or registered again. | |
c358e80d MCC |
203 | * @pads: Pads array with the size defined by @num_pads. |
204 | * @links: List of data links. | |
205 | * @ops: Entity operations. | |
206 | * @stream_count: Stream count for the entity. | |
207 | * @use_count: Use count for the entity. | |
208 | * @pipe: Pipeline this entity belongs to. | |
209 | * @info: Union with devnode information. Kept just for backward | |
210 | * compatibility. | |
211 | * @major: Devnode major number (zero if not applicable). Kept just | |
212 | * for backward compatibility. | |
213 | * @minor: Devnode minor number (zero if not applicable). Kept just | |
214 | * for backward compatibility. | |
215 | * | |
216 | * NOTE: @stream_count and @use_count reference counts must never be | |
217 | * negative, but are signed integers on purpose: a simple WARN_ON(<0) check | |
218 | * can be used to detect reference count bugs that would make them negative. | |
219 | */ | |
53e269c1 | 220 | struct media_entity { |
4b8a3c08 | 221 | struct media_gobj graph_obj; /* must be first field in struct */ |
c358e80d | 222 | const char *name; |
0e576b76 | 223 | u32 function; |
c358e80d | 224 | unsigned long flags; |
53e269c1 | 225 | |
c358e80d MCC |
226 | u16 num_pads; |
227 | u16 num_links; | |
228 | u16 num_backlinks; | |
665faa97 | 229 | int internal_idx; |
53e269c1 | 230 | |
c358e80d MCC |
231 | struct media_pad *pads; |
232 | struct list_head links; | |
53e269c1 | 233 | |
c358e80d | 234 | const struct media_entity_operations *ops; |
97548ed4 | 235 | |
503c3d82 LP |
236 | /* Reference counts must never be negative, but are signed integers on |
237 | * purpose: a simple WARN_ON(<0) check can be used to detect reference | |
238 | * count bugs that would make them negative. | |
239 | */ | |
c358e80d MCC |
240 | int stream_count; |
241 | int use_count; | |
503c3d82 | 242 | |
c358e80d | 243 | struct media_pipeline *pipe; |
e02188c9 | 244 | |
53e269c1 | 245 | union { |
53e269c1 LP |
246 | struct { |
247 | u32 major; | |
248 | u32 minor; | |
e31a0ba7 | 249 | } dev; |
fa5034c6 | 250 | } info; |
53e269c1 LP |
251 | }; |
252 | ||
27e543fa | 253 | /** |
c358e80d | 254 | * struct media_interface - A media interface graph object. |
27e543fa MCC |
255 | * |
256 | * @graph_obj: embedded graph object | |
86e26620 | 257 | * @links: List of links pointing to graph entities |
c358e80d | 258 | * @type: Type of the interface as defined in the |
27e543fa MCC |
259 | * uapi/media/media.h header, e. g. |
260 | * MEDIA_INTF_T_* | |
c358e80d | 261 | * @flags: Interface flags as defined in uapi/media/media.h |
27e543fa MCC |
262 | */ |
263 | struct media_interface { | |
264 | struct media_gobj graph_obj; | |
86e26620 | 265 | struct list_head links; |
27e543fa MCC |
266 | u32 type; |
267 | u32 flags; | |
268 | }; | |
269 | ||
270 | /** | |
c358e80d | 271 | * struct media_intf_devnode - A media interface via a device node. |
27e543fa MCC |
272 | * |
273 | * @intf: embedded interface object | |
274 | * @major: Major number of a device node | |
275 | * @minor: Minor number of a device node | |
276 | */ | |
277 | struct media_intf_devnode { | |
278 | struct media_interface intf; | |
c398bb64 MCC |
279 | |
280 | /* Should match the fields at media_v2_intf_devnode */ | |
27e543fa MCC |
281 | u32 major; |
282 | u32 minor; | |
283 | }; | |
284 | ||
60266185 MCC |
285 | /** |
286 | * media_entity_id() - return the media entity graph object id | |
287 | * | |
288 | * @entity: pointer to entity | |
289 | */ | |
fa762394 MCC |
290 | static inline u32 media_entity_id(struct media_entity *entity) |
291 | { | |
bfab2aac | 292 | return entity->graph_obj.id; |
fa762394 MCC |
293 | } |
294 | ||
60266185 MCC |
295 | /** |
296 | * media_type() - return the media object type | |
297 | * | |
298 | * @gobj: pointer to the media graph object | |
299 | */ | |
ec6e4c95 MCC |
300 | static inline enum media_gobj_type media_type(struct media_gobj *gobj) |
301 | { | |
05b3b77c | 302 | return gobj->id >> MEDIA_BITS_PER_ID; |
ec6e4c95 MCC |
303 | } |
304 | ||
630c0e80 MCC |
305 | /** |
306 | * media_id() - return the media object ID | |
307 | * | |
308 | * @gobj: pointer to the media graph object | |
309 | */ | |
05b3b77c | 310 | static inline u32 media_id(struct media_gobj *gobj) |
ec6e4c95 | 311 | { |
05b3b77c | 312 | return gobj->id & MEDIA_ID_MASK; |
ec6e4c95 MCC |
313 | } |
314 | ||
630c0e80 MCC |
315 | /** |
316 | * media_gobj_gen_id() - encapsulates type and ID on at the object ID | |
317 | * | |
318 | * @type: object type as define at enum &media_gobj_type. | |
319 | * @local_id: next ID, from struct &media_device.@id. | |
320 | */ | |
05b3b77c | 321 | static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id) |
ec6e4c95 MCC |
322 | { |
323 | u32 id; | |
324 | ||
05b3b77c MCC |
325 | id = type << MEDIA_BITS_PER_ID; |
326 | id |= local_id & MEDIA_ID_MASK; | |
ec6e4c95 MCC |
327 | |
328 | return id; | |
329 | } | |
330 | ||
60266185 MCC |
331 | /** |
332 | * is_media_entity_v4l2_io() - identify if the entity main function | |
333 | * is a V4L2 I/O | |
334 | * | |
335 | * @entity: pointer to entity | |
336 | * | |
337 | * Return: true if the entity main function is one of the V4L2 I/O types | |
338 | * (video, VBI or SDR radio); false otherwise. | |
339 | */ | |
fa17b46a MCC |
340 | static inline bool is_media_entity_v4l2_io(struct media_entity *entity) |
341 | { | |
342 | if (!entity) | |
343 | return false; | |
344 | ||
0e576b76 | 345 | switch (entity->function) { |
4ca72efa MCC |
346 | case MEDIA_ENT_F_IO_V4L: |
347 | case MEDIA_ENT_F_IO_VBI: | |
348 | case MEDIA_ENT_F_IO_SWRADIO: | |
fa17b46a MCC |
349 | return true; |
350 | default: | |
351 | return false; | |
352 | } | |
353 | } | |
354 | ||
60266185 MCC |
355 | /** |
356 | * is_media_entity_v4l2_subdev - return true if the entity main function is | |
357 | * associated with the V4L2 API subdev usage | |
358 | * | |
359 | * @entity: pointer to entity | |
360 | * | |
361 | * This is an ancillary function used by subdev-based V4L2 drivers. | |
362 | * It checks if the entity function is one of functions used by a V4L2 subdev, | |
363 | * e. g. camera-relatef functions, analog TV decoder, TV tuner, V4L2 DSPs. | |
364 | */ | |
fa17b46a MCC |
365 | static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity) |
366 | { | |
367 | if (!entity) | |
368 | return false; | |
369 | ||
0e576b76 | 370 | switch (entity->function) { |
4ca72efa MCC |
371 | case MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN: |
372 | case MEDIA_ENT_F_CAM_SENSOR: | |
373 | case MEDIA_ENT_F_FLASH: | |
374 | case MEDIA_ENT_F_LENS: | |
375 | case MEDIA_ENT_F_ATV_DECODER: | |
376 | case MEDIA_ENT_F_TUNER: | |
fa17b46a MCC |
377 | return true; |
378 | ||
379 | default: | |
380 | return false; | |
381 | } | |
382 | } | |
383 | ||
92777994 MCC |
384 | /** |
385 | * __media_entity_enum_init - Initialise an entity enumeration | |
386 | * | |
387 | * @ent_enum: Entity enumeration to be initialised | |
388 | * @idx_max: Maximum number of entities in the enumeration | |
389 | * | |
390 | * Return: Returns zero on success or a negative error code. | |
391 | */ | |
c8d54cd5 SA |
392 | __must_check int __media_entity_enum_init(struct media_entity_enum *ent_enum, |
393 | int idx_max); | |
92777994 MCC |
394 | |
395 | /** | |
396 | * media_entity_enum_cleanup - Release resources of an entity enumeration | |
397 | * | |
398 | * @ent_enum: Entity enumeration to be released | |
399 | */ | |
400 | void media_entity_enum_cleanup(struct media_entity_enum *ent_enum); | |
a5ccc48a | 401 | |
c8d54cd5 SA |
402 | /** |
403 | * media_entity_enum_zero - Clear the entire enum | |
404 | * | |
03e49338 | 405 | * @ent_enum: Entity enumeration to be cleared |
ef69ee1b | 406 | */ |
c8d54cd5 SA |
407 | static inline void media_entity_enum_zero(struct media_entity_enum *ent_enum) |
408 | { | |
409 | bitmap_zero(ent_enum->bmap, ent_enum->idx_max); | |
410 | } | |
411 | ||
412 | /** | |
413 | * media_entity_enum_set - Mark a single entity in the enum | |
414 | * | |
03e49338 | 415 | * @ent_enum: Entity enumeration |
c8d54cd5 SA |
416 | * @entity: Entity to be marked |
417 | */ | |
418 | static inline void media_entity_enum_set(struct media_entity_enum *ent_enum, | |
419 | struct media_entity *entity) | |
420 | { | |
421 | if (WARN_ON(entity->internal_idx >= ent_enum->idx_max)) | |
422 | return; | |
423 | ||
424 | __set_bit(entity->internal_idx, ent_enum->bmap); | |
425 | } | |
426 | ||
427 | /** | |
428 | * media_entity_enum_clear - Unmark a single entity in the enum | |
429 | * | |
03e49338 | 430 | * @ent_enum: Entity enumeration |
c8d54cd5 SA |
431 | * @entity: Entity to be unmarked |
432 | */ | |
433 | static inline void media_entity_enum_clear(struct media_entity_enum *ent_enum, | |
434 | struct media_entity *entity) | |
435 | { | |
436 | if (WARN_ON(entity->internal_idx >= ent_enum->idx_max)) | |
437 | return; | |
438 | ||
439 | __clear_bit(entity->internal_idx, ent_enum->bmap); | |
440 | } | |
441 | ||
442 | /** | |
443 | * media_entity_enum_test - Test whether the entity is marked | |
444 | * | |
03e49338 | 445 | * @ent_enum: Entity enumeration |
c8d54cd5 SA |
446 | * @entity: Entity to be tested |
447 | * | |
448 | * Returns true if the entity was marked. | |
449 | */ | |
450 | static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum, | |
451 | struct media_entity *entity) | |
452 | { | |
453 | if (WARN_ON(entity->internal_idx >= ent_enum->idx_max)) | |
454 | return true; | |
455 | ||
456 | return test_bit(entity->internal_idx, ent_enum->bmap); | |
457 | } | |
458 | ||
459 | /** | |
460 | * media_entity_enum_test - Test whether the entity is marked, and mark it | |
461 | * | |
03e49338 | 462 | * @ent_enum: Entity enumeration |
c8d54cd5 SA |
463 | * @entity: Entity to be tested |
464 | * | |
465 | * Returns true if the entity was marked, and mark it before doing so. | |
466 | */ | |
03e49338 MCC |
467 | static inline bool |
468 | media_entity_enum_test_and_set(struct media_entity_enum *ent_enum, | |
469 | struct media_entity *entity) | |
c8d54cd5 SA |
470 | { |
471 | if (WARN_ON(entity->internal_idx >= ent_enum->idx_max)) | |
472 | return true; | |
473 | ||
474 | return __test_and_set_bit(entity->internal_idx, ent_enum->bmap); | |
475 | } | |
476 | ||
477 | /** | |
03e49338 | 478 | * media_entity_enum_empty - Test whether the entire enum is empty |
c8d54cd5 | 479 | * |
03e49338 | 480 | * @ent_enum: Entity enumeration |
c8d54cd5 SA |
481 | * |
482 | * Returns true if the entity was marked. | |
483 | */ | |
484 | static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum) | |
485 | { | |
486 | return bitmap_empty(ent_enum->bmap, ent_enum->idx_max); | |
487 | } | |
488 | ||
489 | /** | |
490 | * media_entity_enum_intersects - Test whether two enums intersect | |
491 | * | |
03e49338 MCC |
492 | * @ent_enum1: First entity enumeration |
493 | * @ent_enum2: Second entity enumeration | |
c8d54cd5 SA |
494 | * |
495 | * Returns true if entity enumerations e and f intersect, otherwise false. | |
496 | */ | |
497 | static inline bool media_entity_enum_intersects( | |
498 | struct media_entity_enum *ent_enum1, | |
499 | struct media_entity_enum *ent_enum2) | |
500 | { | |
501 | WARN_ON(ent_enum1->idx_max != ent_enum2->idx_max); | |
502 | ||
503 | return bitmap_intersects(ent_enum1->bmap, ent_enum2->bmap, | |
504 | min(ent_enum1->idx_max, ent_enum2->idx_max)); | |
505 | } | |
ef69ee1b | 506 | |
ec6e4c95 MCC |
507 | #define gobj_to_entity(gobj) \ |
508 | container_of(gobj, struct media_entity, graph_obj) | |
509 | ||
39a956c4 MCC |
510 | #define gobj_to_pad(gobj) \ |
511 | container_of(gobj, struct media_pad, graph_obj) | |
512 | ||
513 | #define gobj_to_link(gobj) \ | |
514 | container_of(gobj, struct media_link, graph_obj) | |
515 | ||
27e543fa MCC |
516 | #define gobj_to_link(gobj) \ |
517 | container_of(gobj, struct media_link, graph_obj) | |
518 | ||
519 | #define gobj_to_pad(gobj) \ | |
520 | container_of(gobj, struct media_pad, graph_obj) | |
521 | ||
522 | #define gobj_to_intf(gobj) \ | |
523 | container_of(gobj, struct media_interface, graph_obj) | |
524 | ||
525 | #define intf_to_devnode(intf) \ | |
526 | container_of(intf, struct media_intf_devnode, intf) | |
527 | ||
1fc25d30 MCC |
528 | /** |
529 | * media_gobj_create - Initialize a graph object | |
530 | * | |
531 | * @mdev: Pointer to the media_device that contains the object | |
532 | * @type: Type of the object | |
533 | * @gobj: Pointer to the graph object | |
534 | * | |
535 | * This routine initializes the embedded struct media_gobj inside a | |
536 | * media graph object. It is called automatically if media_*_create() | |
537 | * calls are used. However, if the object (entity, link, pad, interface) | |
538 | * is embedded on some other object, this function should be called before | |
539 | * registering the object at the media controller. | |
540 | */ | |
c350ef83 | 541 | void media_gobj_create(struct media_device *mdev, |
ec6e4c95 MCC |
542 | enum media_gobj_type type, |
543 | struct media_gobj *gobj); | |
1fc25d30 MCC |
544 | |
545 | /** | |
546 | * media_gobj_destroy - Stop using a graph object on a media device | |
547 | * | |
548 | * @gobj: Pointer to the graph object | |
549 | * | |
550 | * This should be called by all routines like media_device_unregister() | |
551 | * that remove/destroy media graph objects. | |
552 | */ | |
c350ef83 | 553 | void media_gobj_destroy(struct media_gobj *gobj); |
ec6e4c95 | 554 | |
db7ee32a MCC |
555 | /** |
556 | * media_entity_pads_init() - Initialize the entity pads | |
557 | * | |
558 | * @entity: entity where the pads belong | |
1fc25d30 MCC |
559 | * @num_pads: total number of sink and source pads |
560 | * @pads: Array of @num_pads pads. | |
561 | * | |
562 | * The pads array is managed by the entity driver and passed to | |
563 | * media_entity_pads_init() where its pointer will be stored in the entity | |
564 | * structure. | |
db7ee32a MCC |
565 | * |
566 | * If no pads are needed, drivers could either directly fill | |
567 | * &media_entity->@num_pads with 0 and &media_entity->@pads with NULL or call | |
568 | * this function that will do the same. | |
569 | * | |
570 | * As the number of pads is known in advance, the pads array is not allocated | |
571 | * dynamically but is managed by the entity driver. Most drivers will embed the | |
572 | * pads array in a driver-specific structure, avoiding dynamic allocation. | |
573 | * | |
574 | * Drivers must set the direction of every pad in the pads array before calling | |
575 | * media_entity_pads_init(). The function will initialize the other pads fields. | |
576 | */ | |
ab22e77c | 577 | int media_entity_pads_init(struct media_entity *entity, u16 num_pads, |
57208e5e | 578 | struct media_pad *pads); |
f1fd3289 | 579 | |
db7ee32a MCC |
580 | /** |
581 | * media_entity_cleanup() - free resources associated with an entity | |
582 | * | |
583 | * @entity: entity where the pads belong | |
584 | * | |
585 | * This function must be called during the cleanup phase after unregistering | |
586 | * the entity (currently, it does nothing). | |
587 | */ | |
f1fd3289 | 588 | static inline void media_entity_cleanup(struct media_entity *entity) {}; |
e02188c9 | 589 | |
db7ee32a MCC |
590 | /** |
591 | * media_create_pad_link() - creates a link between two entities. | |
592 | * | |
593 | * @source: pointer to &media_entity of the source pad. | |
594 | * @source_pad: number of the source pad in the pads array | |
595 | * @sink: pointer to &media_entity of the sink pad. | |
596 | * @sink_pad: number of the sink pad in the pads array. | |
597 | * @flags: Link flags, as defined in include/uapi/linux/media.h. | |
598 | * | |
599 | * Valid values for flags: | |
600 | * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be | |
601 | * used to transfer media data. When two or more links target a sink pad, | |
602 | * only one of them can be enabled at a time. | |
603 | * | |
604 | * A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't | |
605 | * be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then | |
606 | * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is | |
607 | * always enabled. | |
608 | * | |
609 | * NOTE: | |
610 | * | |
611 | * Before calling this function, media_entity_pads_init() and | |
612 | * media_device_register_entity() should be called previously for both ends. | |
613 | */ | |
77328043 MCC |
614 | __must_check int media_create_pad_link(struct media_entity *source, |
615 | u16 source_pad, struct media_entity *sink, | |
616 | u16 sink_pad, u32 flags); | |
b01cc9ce MCC |
617 | |
618 | /** | |
619 | * media_create_pad_links() - creates a link between two entities. | |
620 | * | |
621 | * @mdev: Pointer to the media_device that contains the object | |
622 | * @source_function: Function of the source entities. Used only if @source is | |
623 | * NULL. | |
624 | * @source: pointer to &media_entity of the source pad. If NULL, it will use | |
625 | * all entities that matches the @sink_function. | |
626 | * @source_pad: number of the source pad in the pads array | |
627 | * @sink_function: Function of the sink entities. Used only if @sink is NULL. | |
628 | * @sink: pointer to &media_entity of the sink pad. If NULL, it will use | |
629 | * all entities that matches the @sink_function. | |
630 | * @sink_pad: number of the sink pad in the pads array. | |
631 | * @flags: Link flags, as defined in include/uapi/linux/media.h. | |
632 | * @allow_both_undefined: if true, then both @source and @sink can be NULL. | |
633 | * In such case, it will create a crossbar between all entities that | |
634 | * matches @source_function to all entities that matches @sink_function. | |
635 | * If false, it will return 0 and won't create any link if both @source | |
636 | * and @sink are NULL. | |
637 | * | |
638 | * Valid values for flags: | |
639 | * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be | |
640 | * used to transfer media data. If multiple links are created and this | |
641 | * flag is passed as an argument, only the first created link will have | |
642 | * this flag. | |
643 | * | |
644 | * A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't | |
645 | * be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then | |
646 | * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is | |
647 | * always enabled. | |
648 | * | |
649 | * It is common for some devices to have multiple source and/or sink entities | |
650 | * of the same type that should be linked. While media_create_pad_link() | |
651 | * creates link by link, this function is meant to allow 1:n, n:1 and even | |
652 | * cross-bar (n:n) links. | |
653 | * | |
654 | * NOTE: Before calling this function, media_entity_pads_init() and | |
655 | * media_device_register_entity() should be called previously for the entities | |
656 | * to be linked. | |
657 | */ | |
658 | int media_create_pad_links(const struct media_device *mdev, | |
659 | const u32 source_function, | |
660 | struct media_entity *source, | |
661 | const u16 source_pad, | |
662 | const u32 sink_function, | |
663 | struct media_entity *sink, | |
664 | const u16 sink_pad, | |
665 | u32 flags, | |
666 | const bool allow_both_undefined); | |
667 | ||
7349cec1 | 668 | void __media_entity_remove_links(struct media_entity *entity); |
db7ee32a MCC |
669 | |
670 | /** | |
671 | * media_entity_remove_links() - remove all links associated with an entity | |
672 | * | |
673 | * @entity: pointer to &media_entity | |
674 | * | |
675 | * Note: this is called automatically when an entity is unregistered via | |
676 | * media_device_register_entity(). | |
677 | */ | |
7349cec1 SN |
678 | void media_entity_remove_links(struct media_entity *entity); |
679 | ||
1fc25d30 MCC |
680 | /** |
681 | * __media_entity_setup_link - Configure a media link without locking | |
682 | * @link: The link being configured | |
683 | * @flags: Link configuration flags | |
684 | * | |
685 | * The bulk of link setup is handled by the two entities connected through the | |
686 | * link. This function notifies both entities of the link configuration change. | |
687 | * | |
688 | * If the link is immutable or if the current and new configuration are | |
689 | * identical, return immediately. | |
690 | * | |
691 | * The user is expected to hold link->source->parent->mutex. If not, | |
692 | * media_entity_setup_link() should be used instead. | |
693 | */ | |
97548ed4 | 694 | int __media_entity_setup_link(struct media_link *link, u32 flags); |
db7ee32a MCC |
695 | |
696 | /** | |
697 | * media_entity_setup_link() - changes the link flags properties in runtime | |
698 | * | |
699 | * @link: pointer to &media_link | |
700 | * @flags: the requested new link flags | |
701 | * | |
702 | * The only configurable property is the %MEDIA_LNK_FL_ENABLED link flag | |
703 | * flag to enable/disable a link. Links marked with the | |
704 | * %MEDIA_LNK_FL_IMMUTABLE link flag can not be enabled or disabled. | |
705 | * | |
706 | * When a link is enabled or disabled, the media framework calls the | |
707 | * link_setup operation for the two entities at the source and sink of the | |
708 | * link, in that order. If the second link_setup call fails, another | |
709 | * link_setup call is made on the first entity to restore the original link | |
710 | * flags. | |
711 | * | |
712 | * Media device drivers can be notified of link setup operations by setting the | |
713 | * media_device::link_notify pointer to a callback function. If provided, the | |
714 | * notification callback will be called before enabling and after disabling | |
715 | * links. | |
716 | * | |
717 | * Entity drivers must implement the link_setup operation if any of their links | |
718 | * is non-immutable. The operation must either configure the hardware or store | |
719 | * the configuration information to be applied later. | |
720 | * | |
721 | * Link configuration must not have any side effect on other links. If an | |
722 | * enabled link at a sink pad prevents another link at the same pad from | |
723 | * being enabled, the link_setup operation must return -EBUSY and can't | |
724 | * implicitly disable the first enabled link. | |
725 | * | |
726 | * NOTE: the valid values of the flags for the link is the same as described | |
727 | * on media_create_pad_link(), for pad to pad links or the same as described | |
728 | * on media_create_intf_link(), for interface to entity links. | |
729 | */ | |
97548ed4 | 730 | int media_entity_setup_link(struct media_link *link, u32 flags); |
1fc25d30 MCC |
731 | |
732 | /** | |
733 | * media_entity_find_link - Find a link between two pads | |
734 | * @source: Source pad | |
735 | * @sink: Sink pad | |
736 | * | |
737 | * Return a pointer to the link between the two entities. If no such link | |
738 | * exists, return NULL. | |
739 | */ | |
97548ed4 LP |
740 | struct media_link *media_entity_find_link(struct media_pad *source, |
741 | struct media_pad *sink); | |
1fc25d30 MCC |
742 | |
743 | /** | |
744 | * media_entity_remote_pad - Find the pad at the remote end of a link | |
745 | * @pad: Pad at the local end of the link | |
746 | * | |
747 | * Search for a remote pad connected to the given pad by iterating over all | |
748 | * links originating or terminating at that pad until an enabled link is found. | |
749 | * | |
750 | * Return a pointer to the pad at the remote end of the first found enabled | |
751 | * link, or NULL if no enabled link has been found. | |
752 | */ | |
1bddf1b3 | 753 | struct media_pad *media_entity_remote_pad(struct media_pad *pad); |
53e269c1 | 754 | |
1fc25d30 MCC |
755 | /** |
756 | * media_entity_get - Get a reference to the parent module | |
757 | * | |
758 | * @entity: The entity | |
759 | * | |
760 | * Get a reference to the parent media device module. | |
761 | * | |
762 | * The function will return immediately if @entity is NULL. | |
763 | * | |
764 | * Return a pointer to the entity on success or NULL on failure. | |
765 | */ | |
503c3d82 | 766 | struct media_entity *media_entity_get(struct media_entity *entity); |
1fc25d30 | 767 | |
e03d2203 SA |
768 | __must_check int media_entity_graph_walk_init( |
769 | struct media_entity_graph *graph, struct media_device *mdev); | |
aa360d3d MCC |
770 | |
771 | /** | |
772 | * media_entity_graph_walk_cleanup - Release resources used by graph walk. | |
773 | * | |
774 | * @graph: Media graph structure that will be used to walk the graph | |
775 | */ | |
e03d2203 SA |
776 | void media_entity_graph_walk_cleanup(struct media_entity_graph *graph); |
777 | ||
1fc25d30 MCC |
778 | /** |
779 | * media_entity_put - Release the reference to the parent module | |
780 | * | |
781 | * @entity: The entity | |
782 | * | |
783 | * Release the reference count acquired by media_entity_get(). | |
784 | * | |
785 | * The function will return immediately if @entity is NULL. | |
786 | */ | |
503c3d82 LP |
787 | void media_entity_put(struct media_entity *entity); |
788 | ||
1fc25d30 MCC |
789 | /** |
790 | * media_entity_graph_walk_start - Start walking the media graph at a given entity | |
791 | * @graph: Media graph structure that will be used to walk the graph | |
792 | * @entity: Starting entity | |
793 | * | |
e03d2203 SA |
794 | * Before using this function, media_entity_graph_walk_init() must be |
795 | * used to allocate resources used for walking the graph. This | |
796 | * function initializes the graph traversal structure to walk the | |
797 | * entities graph starting at the given entity. The traversal | |
798 | * structure must not be modified by the caller during graph | |
799 | * traversal. After the graph walk, the resources must be released | |
800 | * using media_entity_graph_walk_cleanup(). | |
1fc25d30 | 801 | */ |
a5ccc48a | 802 | void media_entity_graph_walk_start(struct media_entity_graph *graph, |
e03d2203 | 803 | struct media_entity *entity); |
1fc25d30 MCC |
804 | |
805 | /** | |
806 | * media_entity_graph_walk_next - Get the next entity in the graph | |
807 | * @graph: Media graph structure | |
808 | * | |
809 | * Perform a depth-first traversal of the given media entities graph. | |
810 | * | |
811 | * The graph structure must have been previously initialized with a call to | |
812 | * media_entity_graph_walk_start(). | |
813 | * | |
814 | * Return the next entity in the graph or NULL if the whole graph have been | |
815 | * traversed. | |
816 | */ | |
a5ccc48a SA |
817 | struct media_entity * |
818 | media_entity_graph_walk_next(struct media_entity_graph *graph); | |
1fc25d30 MCC |
819 | |
820 | /** | |
821 | * media_entity_pipeline_start - Mark a pipeline as streaming | |
822 | * @entity: Starting entity | |
823 | * @pipe: Media pipeline to be assigned to all entities in the pipeline. | |
824 | * | |
825 | * Mark all entities connected to a given entity through enabled links, either | |
826 | * directly or indirectly, as streaming. The given pipeline object is assigned to | |
827 | * every entity in the pipeline and stored in the media_entity pipe field. | |
828 | * | |
829 | * Calls to this function can be nested, in which case the same number of | |
830 | * media_entity_pipeline_stop() calls will be required to stop streaming. The | |
831 | * pipeline pointer must be identical for all nested calls to | |
832 | * media_entity_pipeline_start(). | |
833 | */ | |
af88be38 SA |
834 | __must_check int media_entity_pipeline_start(struct media_entity *entity, |
835 | struct media_pipeline *pipe); | |
fb49f204 SK |
836 | /** |
837 | * __media_entity_pipeline_start - Mark a pipeline as streaming | |
838 | * | |
839 | * @entity: Starting entity | |
840 | * @pipe: Media pipeline to be assigned to all entities in the pipeline. | |
841 | * | |
842 | * Note: This is the non-locking version of media_entity_pipeline_start() | |
843 | */ | |
844 | __must_check int __media_entity_pipeline_start(struct media_entity *entity, | |
845 | struct media_pipeline *pipe); | |
1fc25d30 MCC |
846 | |
847 | /** | |
848 | * media_entity_pipeline_stop - Mark a pipeline as not streaming | |
849 | * @entity: Starting entity | |
850 | * | |
851 | * Mark all entities connected to a given entity through enabled links, either | |
852 | * directly or indirectly, as not streaming. The media_entity pipe field is | |
853 | * reset to NULL. | |
854 | * | |
855 | * If multiple calls to media_entity_pipeline_start() have been made, the same | |
856 | * number of calls to this function are required to mark the pipeline as not | |
857 | * streaming. | |
858 | */ | |
e02188c9 | 859 | void media_entity_pipeline_stop(struct media_entity *entity); |
a5ccc48a | 860 | |
fb49f204 SK |
861 | /** |
862 | * __media_entity_pipeline_stop - Mark a pipeline as not streaming | |
863 | * | |
864 | * @entity: Starting entity | |
865 | * | |
866 | * Note: This is the non-locking version of media_entity_pipeline_stop() | |
867 | */ | |
868 | void __media_entity_pipeline_stop(struct media_entity *entity); | |
869 | ||
db7ee32a MCC |
870 | /** |
871 | * media_devnode_create() - creates and initializes a device node interface | |
872 | * | |
873 | * @mdev: pointer to struct &media_device | |
874 | * @type: type of the interface, as given by MEDIA_INTF_T_* macros | |
875 | * as defined in the uapi/media/media.h header. | |
876 | * @flags: Interface flags as defined in uapi/media/media.h. | |
877 | * @major: Device node major number. | |
878 | * @minor: Device node minor number. | |
879 | * | |
880 | * Return: if succeeded, returns a pointer to the newly allocated | |
881 | * &media_intf_devnode pointer. | |
882 | */ | |
5e5387df MCC |
883 | struct media_intf_devnode * |
884 | __must_check media_devnode_create(struct media_device *mdev, | |
885 | u32 type, u32 flags, | |
0b3b72df | 886 | u32 major, u32 minor); |
db7ee32a MCC |
887 | /** |
888 | * media_devnode_remove() - removes a device node interface | |
889 | * | |
890 | * @devnode: pointer to &media_intf_devnode to be freed. | |
891 | * | |
892 | * When a device node interface is removed, all links to it are automatically | |
893 | * removed. | |
894 | */ | |
27e543fa | 895 | void media_devnode_remove(struct media_intf_devnode *devnode); |
5e5387df | 896 | struct media_link * |
db7ee32a MCC |
897 | |
898 | /** | |
899 | * media_create_intf_link() - creates a link between an entity and an interface | |
900 | * | |
901 | * @entity: pointer to %media_entity | |
902 | * @intf: pointer to %media_interface | |
903 | * @flags: Link flags, as defined in include/uapi/linux/media.h. | |
904 | * | |
905 | * | |
906 | * Valid values for flags: | |
907 | * The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to | |
908 | * the entity hardware. That's the default value for interfaces. An | |
909 | * interface may be disabled if the hardware is busy due to the usage | |
910 | * of some other interface that it is currently controlling the hardware. | |
911 | * A typical example is an hybrid TV device that handle only one type of | |
912 | * stream on a given time. So, when the digital TV is streaming, | |
913 | * the V4L2 interfaces won't be enabled, as such device is not able to | |
914 | * also stream analog TV or radio. | |
915 | * | |
916 | * Note: | |
917 | * | |
918 | * Before calling this function, media_devnode_create() should be called for | |
919 | * the interface and media_device_register_entity() should be called for the | |
920 | * interface that will be part of the link. | |
921 | */ | |
5e5387df MCC |
922 | __must_check media_create_intf_link(struct media_entity *entity, |
923 | struct media_interface *intf, | |
924 | u32 flags); | |
60266185 MCC |
925 | /** |
926 | * __media_remove_intf_link() - remove a single interface link | |
927 | * | |
928 | * @link: pointer to &media_link. | |
929 | * | |
930 | * Note: this is an unlocked version of media_remove_intf_link() | |
931 | */ | |
d47109fa | 932 | void __media_remove_intf_link(struct media_link *link); |
60266185 MCC |
933 | |
934 | /** | |
935 | * media_remove_intf_link() - remove a single interface link | |
936 | * | |
937 | * @link: pointer to &media_link. | |
938 | * | |
939 | * Note: prefer to use this one, instead of __media_remove_intf_link() | |
940 | */ | |
86e26620 | 941 | void media_remove_intf_link(struct media_link *link); |
60266185 MCC |
942 | |
943 | /** | |
944 | * __media_remove_intf_links() - remove all links associated with an interface | |
945 | * | |
946 | * @intf: pointer to &media_interface | |
947 | * | |
948 | * Note: this is an unlocked version of media_remove_intf_links(). | |
949 | */ | |
7c4696a9 | 950 | void __media_remove_intf_links(struct media_interface *intf); |
92777994 | 951 | |
db7ee32a MCC |
952 | /** |
953 | * media_remove_intf_links() - remove all links associated with an interface | |
954 | * | |
955 | * @intf: pointer to &media_interface | |
956 | * | |
60266185 MCC |
957 | * Notes: |
958 | * | |
959 | * this is called automatically when an entity is unregistered via | |
db7ee32a | 960 | * media_device_register_entity() and by media_devnode_remove(). |
60266185 MCC |
961 | * |
962 | * Prefer to use this one, instead of __media_remove_intf_links(). | |
db7ee32a | 963 | */ |
7c4696a9 MCC |
964 | void media_remove_intf_links(struct media_interface *intf); |
965 | ||
97548ed4 LP |
966 | #define media_entity_call(entity, operation, args...) \ |
967 | (((entity)->ops && (entity)->ops->operation) ? \ | |
968 | (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD) | |
969 | ||
53e269c1 | 970 | #endif |