1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3 * Media entity
4 *
5 * Copyright (C) 2010 Nokia Corporation
6 *
7 * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
8 * Sakari Ailus <sakari.ailus@iki.fi>
9 */
10
11 #ifndef _MEDIA_ENTITY_H
12 #define _MEDIA_ENTITY_H
13
14 #include <linux/bitmap.h>
15 #include <linux/bug.h>
16 #include <linux/container_of.h>
17 #include <linux/fwnode.h>
18 #include <linux/list.h>
19 #include <linux/media.h>
20 #include <linux/types.h>
21
22 /* Enums used internally at the media controller to represent graphs */
23
24 /**
25 * enum media_gobj_type - type of a graph object
26 *
27 * @MEDIA_GRAPH_ENTITY: Identify a media entity
28 * @MEDIA_GRAPH_PAD: Identify a media pad
29 * @MEDIA_GRAPH_LINK: Identify a media link
30 * @MEDIA_GRAPH_INTF_DEVNODE: Identify a media Kernel API interface via
31 * a device node
32 */
33 enum media_gobj_type {
34 MEDIA_GRAPH_ENTITY,
35 MEDIA_GRAPH_PAD,
36 MEDIA_GRAPH_LINK,
37 MEDIA_GRAPH_INTF_DEVNODE,
38 };
39
40 #define MEDIA_BITS_PER_TYPE 8
41 #define MEDIA_BITS_PER_ID (32 - MEDIA_BITS_PER_TYPE)
42 #define MEDIA_ID_MASK GENMASK_ULL(MEDIA_BITS_PER_ID - 1, 0)
43
44 /* Structs to represent the objects that belong to a media graph */
45
46 /**
47 * struct media_gobj - Define a graph object.
48 *
49 * @mdev: Pointer to the struct &media_device that owns the object
50 * @id: Non-zero object ID identifier. The ID should be unique
51 * inside a media_device, as it is composed by
52 * %MEDIA_BITS_PER_TYPE to store the type plus
53 * %MEDIA_BITS_PER_ID to store the ID
54 * @list: List entry stored in one of the per-type mdev object lists
55 *
56 * All objects on the media graph should have this struct embedded
57 */
58 struct media_gobj {
59 struct media_device *mdev;
60 u32 id;
61 struct list_head list;
62 };
63
64 #define MEDIA_ENTITY_ENUM_MAX_DEPTH 16
65
66 /**
67 * struct media_entity_enum - An enumeration of media entities.
68 *
69 * @bmap: Bit map in which each bit represents one entity at struct
70 * media_entity->internal_idx.
71 * @idx_max: Number of bits in bmap
72 */
73 struct media_entity_enum {
74 unsigned long *bmap;
75 int idx_max;
76 };
77
78 /**
79 * struct media_graph - Media graph traversal state
80 *
81 * @stack: Graph traversal stack; the stack contains information
82 * on the path the media entities to be walked and the
83 * links through which they were reached.
84 * @stack.entity: pointer to &struct media_entity at the graph.
85 * @stack.link: pointer to &struct list_head.
86 * @ent_enum: Visited entities
87 * @top: The top of the stack
88 */
89 struct media_graph {
90 struct {
91 struct media_entity *entity;
92 struct list_head *link;
93 } stack[MEDIA_ENTITY_ENUM_MAX_DEPTH];
94
95 struct media_entity_enum ent_enum;
96 int top;
97 };
98
99 /**
100 * struct media_pipeline - Media pipeline related information
101 *
102 * @streaming_count: Streaming start count - streaming stop count
103 * @graph: Media graph walk during pipeline start / stop
104 */
105 struct media_pipeline {
106 int streaming_count;
107 struct media_graph graph;
108 };
109
110 /**
111 * struct media_link - A link object part of a media graph.
112 *
113 * @graph_obj: Embedded structure containing the media object common data
114 * @list: Linked list associated with an entity or an interface that
115 * owns the link.
116 * @gobj0: Part of a union. Used to get the pointer for the first
117 * graph_object of the link.
118 * @source: Part of a union. Used only if the first object (gobj0) is
119 * a pad. In that case, it represents the source pad.
120 * @intf: Part of a union. Used only if the first object (gobj0) is
121 * an interface.
122 * @gobj1: Part of a union. Used to get the pointer for the second
123 * graph_object of the link.
124 * @sink: Part of a union. Used only if the second object (gobj1) is
125 * a pad. In that case, it represents the sink pad.
126 * @entity: Part of a union. Used only if the second object (gobj1) is
127 * an entity.
128 * @reverse: Pointer to the link for the reverse direction of a pad to pad
129 * link.
130 * @flags: Link flags, as defined in uapi/media.h (MEDIA_LNK_FL_*)
131 * @is_backlink: Indicate if the link is a backlink.
132 */
133 struct media_link {
134 struct media_gobj graph_obj;
135 struct list_head list;
136 union {
137 struct media_gobj *gobj0;
138 struct media_pad *source;
139 struct media_interface *intf;
140 };
141 union {
142 struct media_gobj *gobj1;
143 struct media_pad *sink;
144 struct media_entity *entity;
145 };
146 struct media_link *reverse;
147 unsigned long flags;
148 bool is_backlink;
149 };
150
151 /**
152 * enum media_pad_signal_type - type of the signal inside a media pad
153 *
154 * @PAD_SIGNAL_DEFAULT:
155 * Default signal. Use this when all inputs or all outputs are
156 * uniquely identified by the pad number.
157 * @PAD_SIGNAL_ANALOG:
158 * The pad contains an analog signal. It can be Radio Frequency,
159 * Intermediate Frequency, a baseband signal or sub-carriers.
160 * Tuner inputs, IF-PLL demodulators, composite and s-video signals
161 * should use it.
162 * @PAD_SIGNAL_DV:
163 * Contains a digital video signal, with can be a bitstream of samples
164 * taken from an analog TV video source. On such case, it usually
165 * contains the VBI data on it.
166 * @PAD_SIGNAL_AUDIO:
167 * Contains an Intermediate Frequency analog signal from an audio
168 * sub-carrier or an audio bitstream. IF signals are provided by tuners
169 * and consumed by audio AM/FM decoders. Bitstream audio is provided by
170 * an audio decoder.
171 */
172 enum media_pad_signal_type {
173 PAD_SIGNAL_DEFAULT = 0,
174 PAD_SIGNAL_ANALOG,
175 PAD_SIGNAL_DV,
176 PAD_SIGNAL_AUDIO,
177 };
178
179 /**
180 * struct media_pad - A media pad graph object.
181 *
182 * @graph_obj: Embedded structure containing the media object common data
183 * @entity: Entity this pad belongs to
184 * @index: Pad index in the entity pads array, numbered from 0 to n
185 * @sig_type: Type of the signal inside a media pad
186 * @flags: Pad flags, as defined in
187 * :ref:`include/uapi/linux/media.h <media_header>`
188 * (seek for ``MEDIA_PAD_FL_*``)
189 */
190 struct media_pad {
191 struct media_gobj graph_obj; /* must be first field in struct */
192 struct media_entity *entity;
193 u16 index;
194 enum media_pad_signal_type sig_type;
195 unsigned long flags;
196 };
197
198 /**
199 * struct media_entity_operations - Media entity operations
200 * @get_fwnode_pad: Return the pad number based on a fwnode endpoint or
201 * a negative value on error. This operation can be used
202 * to map a fwnode to a media pad number. Optional.
203 * @link_setup: Notify the entity of link changes. The operation can
204 * return an error, in which case link setup will be
205 * cancelled. Optional.
206 * @link_validate: Return whether a link is valid from the entity point of
207 * view. The media_pipeline_start() function
208 * validates all links by calling this operation. Optional.
209 *
210 * .. note::
211 *
212 * Those these callbacks are called with struct &media_device.graph_mutex
213 * mutex held.
214 */
215 struct media_entity_operations {
216 int (*get_fwnode_pad)(struct media_entity *entity,
217 struct fwnode_endpoint *endpoint);
218 int (*link_setup)(struct media_entity *entity,
219 const struct media_pad *local,
220 const struct media_pad *remote, u32 flags);
221 int (*link_validate)(struct media_link *link);
222 };
223
224 /**
225 * enum media_entity_type - Media entity type
226 *
227 * @MEDIA_ENTITY_TYPE_BASE:
228 * The entity isn't embedded in another subsystem structure.
229 * @MEDIA_ENTITY_TYPE_VIDEO_DEVICE:
230 * The entity is embedded in a struct video_device instance.
231 * @MEDIA_ENTITY_TYPE_V4L2_SUBDEV:
232 * The entity is embedded in a struct v4l2_subdev instance.
233 *
234 * Media entity objects are often not instantiated directly, but the media
235 * entity structure is inherited by (through embedding) other subsystem-specific
236 * structures. The media entity type identifies the type of the subclass
237 * structure that implements a media entity instance.
238 *
239 * This allows runtime type identification of media entities and safe casting to
240 * the correct object type. For instance, a media entity structure instance
241 * embedded in a v4l2_subdev structure instance will have the type
242 * %MEDIA_ENTITY_TYPE_V4L2_SUBDEV and can safely be cast to a &v4l2_subdev
243 * structure using the container_of() macro.
244 */
245 enum media_entity_type {
246 MEDIA_ENTITY_TYPE_BASE,
247 MEDIA_ENTITY_TYPE_VIDEO_DEVICE,
248 MEDIA_ENTITY_TYPE_V4L2_SUBDEV,
249 };
250
251 /**
252 * struct media_entity - A media entity graph object.
253 *
254 * @graph_obj: Embedded structure containing the media object common data.
255 * @name: Entity name.
256 * @obj_type: Type of the object that implements the media_entity.
257 * @function: Entity main function, as defined in
258 * :ref:`include/uapi/linux/media.h <media_header>`
259 * (seek for ``MEDIA_ENT_F_*``)
260 * @flags: Entity flags, as defined in
261 * :ref:`include/uapi/linux/media.h <media_header>`
262 * (seek for ``MEDIA_ENT_FL_*``)
263 * @num_pads: Number of sink and source pads.
264 * @num_links: Total number of links, forward and back, enabled and disabled.
265 * @num_backlinks: Number of backlinks
266 * @internal_idx: An unique internal entity specific number. The numbers are
267 * re-used if entities are unregistered or registered again.
268 * @pads: Pads array with the size defined by @num_pads.
269 * @links: List of data links.
270 * @ops: Entity operations.
271 * @use_count: Use count for the entity.
272 * @pipe: Pipeline this entity belongs to.
273 * @info: Union with devnode information. Kept just for backward
274 * compatibility.
275 * @info.dev: Contains device major and minor info.
276 * @info.dev.major: device node major, if the device is a devnode.
277 * @info.dev.minor: device node minor, if the device is a devnode.
278 * @major: Devnode major number (zero if not applicable). Kept just
279 * for backward compatibility.
280 * @minor: Devnode minor number (zero if not applicable). Kept just
281 * for backward compatibility.
282 *
283 * .. note::
284 *
285 * The @use_count reference count must never be negative, but is a signed
286 * integer on purpose: a simple ``WARN_ON(<0)`` check can be used to detect
287 * reference count bugs that would make it negative.
288 */
289 struct media_entity {
290 struct media_gobj graph_obj; /* must be first field in struct */
291 const char *name;
292 enum media_entity_type obj_type;
293 u32 function;
294 unsigned long flags;
295
296 u16 num_pads;
297 u16 num_links;
298 u16 num_backlinks;
299 int internal_idx;
300
301 struct media_pad *pads;
302 struct list_head links;
303
304 const struct media_entity_operations *ops;
305
306 int use_count;
307
308 struct media_pipeline *pipe;
309
310 union {
311 struct {
312 u32 major;
313 u32 minor;
314 } dev;
315 } info;
316 };
317
318 /**
319 * struct media_interface - A media interface graph object.
320 *
321 * @graph_obj: embedded graph object
322 * @links: List of links pointing to graph entities
323 * @type: Type of the interface as defined in
324 * :ref:`include/uapi/linux/media.h <media_header>`
325 * (seek for ``MEDIA_INTF_T_*``)
326 * @flags: Interface flags as defined in
327 * :ref:`include/uapi/linux/media.h <media_header>`
328 * (seek for ``MEDIA_INTF_FL_*``)
329 *
330 * .. note::
331 *
332 * Currently, no flags for &media_interface is defined.
333 */
334 struct media_interface {
335 struct media_gobj graph_obj;
336 struct list_head links;
337 u32 type;
338 u32 flags;
339 };
340
341 /**
342 * struct media_intf_devnode - A media interface via a device node.
343 *
344 * @intf: embedded interface object
345 * @major: Major number of a device node
346 * @minor: Minor number of a device node
347 */
348 struct media_intf_devnode {
349 struct media_interface intf;
350
351 /* Should match the fields at media_v2_intf_devnode */
352 u32 major;
353 u32 minor;
354 };
355
356 /**
357 * media_entity_id() - return the media entity graph object id
358 *
359 * @entity: pointer to &media_entity
360 */
media_entity_id(struct media_entity * entity)361 static inline u32 media_entity_id(struct media_entity *entity)
362 {
363 return entity->graph_obj.id;
364 }
365
366 /**
367 * media_type() - return the media object type
368 *
369 * @gobj: Pointer to the struct &media_gobj graph object
370 */
media_type(struct media_gobj * gobj)371 static inline enum media_gobj_type media_type(struct media_gobj *gobj)
372 {
373 return gobj->id >> MEDIA_BITS_PER_ID;
374 }
375
376 /**
377 * media_id() - return the media object ID
378 *
379 * @gobj: Pointer to the struct &media_gobj graph object
380 */
media_id(struct media_gobj * gobj)381 static inline u32 media_id(struct media_gobj *gobj)
382 {
383 return gobj->id & MEDIA_ID_MASK;
384 }
385
386 /**
387 * media_gobj_gen_id() - encapsulates type and ID on at the object ID
388 *
389 * @type: object type as define at enum &media_gobj_type.
390 * @local_id: next ID, from struct &media_device.id.
391 */
media_gobj_gen_id(enum media_gobj_type type,u64 local_id)392 static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id)
393 {
394 u32 id;
395
396 id = type << MEDIA_BITS_PER_ID;
397 id |= local_id & MEDIA_ID_MASK;
398
399 return id;
400 }
401
402 /**
403 * is_media_entity_v4l2_video_device() - Check if the entity is a video_device
404 * @entity: pointer to entity
405 *
406 * Return: %true if the entity is an instance of a video_device object and can
407 * safely be cast to a struct video_device using the container_of() macro, or
408 * %false otherwise.
409 */
is_media_entity_v4l2_video_device(struct media_entity * entity)410 static inline bool is_media_entity_v4l2_video_device(struct media_entity *entity)
411 {
412 return entity && entity->obj_type == MEDIA_ENTITY_TYPE_VIDEO_DEVICE;
413 }
414
415 /**
416 * is_media_entity_v4l2_subdev() - Check if the entity is a v4l2_subdev
417 * @entity: pointer to entity
418 *
419 * Return: %true if the entity is an instance of a &v4l2_subdev object and can
420 * safely be cast to a struct &v4l2_subdev using the container_of() macro, or
421 * %false otherwise.
422 */
is_media_entity_v4l2_subdev(struct media_entity * entity)423 static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity)
424 {
425 return entity && entity->obj_type == MEDIA_ENTITY_TYPE_V4L2_SUBDEV;
426 }
427
428 /**
429 * __media_entity_enum_init - Initialise an entity enumeration
430 *
431 * @ent_enum: Entity enumeration to be initialised
432 * @idx_max: Maximum number of entities in the enumeration
433 *
434 * Return: Returns zero on success or a negative error code.
435 */
436 __must_check int __media_entity_enum_init(struct media_entity_enum *ent_enum,
437 int idx_max);
438
439 /**
440 * media_entity_enum_cleanup - Release resources of an entity enumeration
441 *
442 * @ent_enum: Entity enumeration to be released
443 */
444 void media_entity_enum_cleanup(struct media_entity_enum *ent_enum);
445
446 /**
447 * media_entity_enum_zero - Clear the entire enum
448 *
449 * @ent_enum: Entity enumeration to be cleared
450 */
media_entity_enum_zero(struct media_entity_enum * ent_enum)451 static inline void media_entity_enum_zero(struct media_entity_enum *ent_enum)
452 {
453 bitmap_zero(ent_enum->bmap, ent_enum->idx_max);
454 }
455
456 /**
457 * media_entity_enum_set - Mark a single entity in the enum
458 *
459 * @ent_enum: Entity enumeration
460 * @entity: Entity to be marked
461 */
media_entity_enum_set(struct media_entity_enum * ent_enum,struct media_entity * entity)462 static inline void media_entity_enum_set(struct media_entity_enum *ent_enum,
463 struct media_entity *entity)
464 {
465 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))
466 return;
467
468 __set_bit(entity->internal_idx, ent_enum->bmap);
469 }
470
471 /**
472 * media_entity_enum_clear - Unmark a single entity in the enum
473 *
474 * @ent_enum: Entity enumeration
475 * @entity: Entity to be unmarked
476 */
media_entity_enum_clear(struct media_entity_enum * ent_enum,struct media_entity * entity)477 static inline void media_entity_enum_clear(struct media_entity_enum *ent_enum,
478 struct media_entity *entity)
479 {
480 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))
481 return;
482
483 __clear_bit(entity->internal_idx, ent_enum->bmap);
484 }
485
486 /**
487 * media_entity_enum_test - Test whether the entity is marked
488 *
489 * @ent_enum: Entity enumeration
490 * @entity: Entity to be tested
491 *
492 * Returns %true if the entity was marked.
493 */
media_entity_enum_test(struct media_entity_enum * ent_enum,struct media_entity * entity)494 static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum,
495 struct media_entity *entity)
496 {
497 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))
498 return true;
499
500 return test_bit(entity->internal_idx, ent_enum->bmap);
501 }
502
503 /**
504 * media_entity_enum_test_and_set - Test whether the entity is marked,
505 * and mark it
506 *
507 * @ent_enum: Entity enumeration
508 * @entity: Entity to be tested
509 *
510 * Returns %true if the entity was marked, and mark it before doing so.
511 */
512 static inline bool
media_entity_enum_test_and_set(struct media_entity_enum * ent_enum,struct media_entity * entity)513 media_entity_enum_test_and_set(struct media_entity_enum *ent_enum,
514 struct media_entity *entity)
515 {
516 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))
517 return true;
518
519 return __test_and_set_bit(entity->internal_idx, ent_enum->bmap);
520 }
521
522 /**
523 * media_entity_enum_empty - Test whether the entire enum is empty
524 *
525 * @ent_enum: Entity enumeration
526 *
527 * Return: %true if the entity was empty.
528 */
media_entity_enum_empty(struct media_entity_enum * ent_enum)529 static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum)
530 {
531 return bitmap_empty(ent_enum->bmap, ent_enum->idx_max);
532 }
533
534 /**
535 * media_entity_enum_intersects - Test whether two enums intersect
536 *
537 * @ent_enum1: First entity enumeration
538 * @ent_enum2: Second entity enumeration
539 *
540 * Return: %true if entity enumerations @ent_enum1 and @ent_enum2 intersect,
541 * otherwise %false.
542 */
media_entity_enum_intersects(struct media_entity_enum * ent_enum1,struct media_entity_enum * ent_enum2)543 static inline bool media_entity_enum_intersects(
544 struct media_entity_enum *ent_enum1,
545 struct media_entity_enum *ent_enum2)
546 {
547 WARN_ON(ent_enum1->idx_max != ent_enum2->idx_max);
548
549 return bitmap_intersects(ent_enum1->bmap, ent_enum2->bmap,
550 min(ent_enum1->idx_max, ent_enum2->idx_max));
551 }
552
553 /**
554 * gobj_to_entity - returns the struct &media_entity pointer from the
555 * @gobj contained on it.
556 *
557 * @gobj: Pointer to the struct &media_gobj graph object
558 */
559 #define gobj_to_entity(gobj) \
560 container_of(gobj, struct media_entity, graph_obj)
561
562 /**
563 * gobj_to_pad - returns the struct &media_pad pointer from the
564 * @gobj contained on it.
565 *
566 * @gobj: Pointer to the struct &media_gobj graph object
567 */
568 #define gobj_to_pad(gobj) \
569 container_of(gobj, struct media_pad, graph_obj)
570
571 /**
572 * gobj_to_link - returns the struct &media_link pointer from the
573 * @gobj contained on it.
574 *
575 * @gobj: Pointer to the struct &media_gobj graph object
576 */
577 #define gobj_to_link(gobj) \
578 container_of(gobj, struct media_link, graph_obj)
579
580 /**
581 * gobj_to_intf - returns the struct &media_interface pointer from the
582 * @gobj contained on it.
583 *
584 * @gobj: Pointer to the struct &media_gobj graph object
585 */
586 #define gobj_to_intf(gobj) \
587 container_of(gobj, struct media_interface, graph_obj)
588
589 /**
590 * intf_to_devnode - returns the struct media_intf_devnode pointer from the
591 * @intf contained on it.
592 *
593 * @intf: Pointer to struct &media_intf_devnode
594 */
595 #define intf_to_devnode(intf) \
596 container_of(intf, struct media_intf_devnode, intf)
597
598 /**
599 * media_gobj_create - Initialize a graph object
600 *
601 * @mdev: Pointer to the &media_device that contains the object
602 * @type: Type of the object
603 * @gobj: Pointer to the struct &media_gobj graph object
604 *
605 * This routine initializes the embedded struct &media_gobj inside a
606 * media graph object. It is called automatically if ``media_*_create``
607 * function calls are used. However, if the object (entity, link, pad,
608 * interface) is embedded on some other object, this function should be
609 * called before registering the object at the media controller.
610 */
611 void media_gobj_create(struct media_device *mdev,
612 enum media_gobj_type type,
613 struct media_gobj *gobj);
614
615 /**
616 * media_gobj_destroy - Stop using a graph object on a media device
617 *
618 * @gobj: Pointer to the struct &media_gobj graph object
619 *
620 * This should be called by all routines like media_device_unregister()
621 * that remove/destroy media graph objects.
622 */
623 void media_gobj_destroy(struct media_gobj *gobj);
624
625 /**
626 * media_entity_pads_init() - Initialize the entity pads
627 *
628 * @entity: entity where the pads belong
629 * @num_pads: total number of sink and source pads
630 * @pads: Array of @num_pads pads.
631 *
632 * The pads array is managed by the entity driver and passed to
633 * media_entity_pads_init() where its pointer will be stored in the
634 * &media_entity structure.
635 *
636 * If no pads are needed, drivers could either directly fill
637 * &media_entity->num_pads with 0 and &media_entity->pads with %NULL or call
638 * this function that will do the same.
639 *
640 * As the number of pads is known in advance, the pads array is not allocated
641 * dynamically but is managed by the entity driver. Most drivers will embed the
642 * pads array in a driver-specific structure, avoiding dynamic allocation.
643 *
644 * Drivers must set the direction of every pad in the pads array before calling
645 * media_entity_pads_init(). The function will initialize the other pads fields.
646 */
647 int media_entity_pads_init(struct media_entity *entity, u16 num_pads,
648 struct media_pad *pads);
649
650 /**
651 * media_entity_cleanup() - free resources associated with an entity
652 *
653 * @entity: entity where the pads belong
654 *
655 * This function must be called during the cleanup phase after unregistering
656 * the entity (currently, it does nothing).
657 *
658 * Calling media_entity_cleanup() on a media_entity whose memory has been
659 * zeroed but that has not been initialized with media_entity_pad_init() is
660 * valid and is a no-op.
661 */
662 #if IS_ENABLED(CONFIG_MEDIA_CONTROLLER)
media_entity_cleanup(struct media_entity * entity)663 static inline void media_entity_cleanup(struct media_entity *entity) {}
664 #else
665 #define media_entity_cleanup(entity) do { } while (false)
666 #endif
667
668 /**
669 * media_get_pad_index() - retrieves a pad index from an entity
670 *
671 * @entity: entity where the pads belong
672 * @is_sink: true if the pad is a sink, false if it is a source
673 * @sig_type: type of signal of the pad to be search
674 *
675 * This helper function finds the first pad index inside an entity that
676 * satisfies both @is_sink and @sig_type conditions.
677 *
678 * Return:
679 *
680 * On success, return the pad number. If the pad was not found or the media
681 * entity is a NULL pointer, return -EINVAL.
682 */
683 int media_get_pad_index(struct media_entity *entity, bool is_sink,
684 enum media_pad_signal_type sig_type);
685
686 /**
687 * media_create_pad_link() - creates a link between two entities.
688 *
689 * @source: pointer to &media_entity of the source pad.
690 * @source_pad: number of the source pad in the pads array
691 * @sink: pointer to &media_entity of the sink pad.
692 * @sink_pad: number of the sink pad in the pads array.
693 * @flags: Link flags, as defined in
694 * :ref:`include/uapi/linux/media.h <media_header>`
695 * ( seek for ``MEDIA_LNK_FL_*``)
696 *
697 * Valid values for flags:
698 *
699 * %MEDIA_LNK_FL_ENABLED
700 * Indicates that the link is enabled and can be used to transfer media data.
701 * When two or more links target a sink pad, only one of them can be
702 * enabled at a time.
703 *
704 * %MEDIA_LNK_FL_IMMUTABLE
705 * Indicates that the link enabled state can't be modified at runtime. If
706 * %MEDIA_LNK_FL_IMMUTABLE is set, then %MEDIA_LNK_FL_ENABLED must also be
707 * set, since an immutable link is always enabled.
708 *
709 * .. note::
710 *
711 * Before calling this function, media_entity_pads_init() and
712 * media_device_register_entity() should be called previously for both ends.
713 */
714 __must_check int media_create_pad_link(struct media_entity *source,
715 u16 source_pad, struct media_entity *sink,
716 u16 sink_pad, u32 flags);
717
718 /**
719 * media_create_pad_links() - creates a link between two entities.
720 *
721 * @mdev: Pointer to the media_device that contains the object
722 * @source_function: Function of the source entities. Used only if @source is
723 * NULL.
724 * @source: pointer to &media_entity of the source pad. If NULL, it will use
725 * all entities that matches the @sink_function.
726 * @source_pad: number of the source pad in the pads array
727 * @sink_function: Function of the sink entities. Used only if @sink is NULL.
728 * @sink: pointer to &media_entity of the sink pad. If NULL, it will use
729 * all entities that matches the @sink_function.
730 * @sink_pad: number of the sink pad in the pads array.
731 * @flags: Link flags, as defined in include/uapi/linux/media.h.
732 * @allow_both_undefined: if %true, then both @source and @sink can be NULL.
733 * In such case, it will create a crossbar between all entities that
734 * matches @source_function to all entities that matches @sink_function.
735 * If %false, it will return 0 and won't create any link if both @source
736 * and @sink are NULL.
737 *
738 * Valid values for flags:
739 *
740 * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be
741 * used to transfer media data. If multiple links are created and this
742 * flag is passed as an argument, only the first created link will have
743 * this flag.
744 *
745 * A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't
746 * be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then
747 * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
748 * always enabled.
749 *
750 * It is common for some devices to have multiple source and/or sink entities
751 * of the same type that should be linked. While media_create_pad_link()
752 * creates link by link, this function is meant to allow 1:n, n:1 and even
753 * cross-bar (n:n) links.
754 *
755 * .. note::
756 *
757 * Before calling this function, media_entity_pads_init() and
758 * media_device_register_entity() should be called previously for the
759 * entities to be linked.
760 */
761 int media_create_pad_links(const struct media_device *mdev,
762 const u32 source_function,
763 struct media_entity *source,
764 const u16 source_pad,
765 const u32 sink_function,
766 struct media_entity *sink,
767 const u16 sink_pad,
768 u32 flags,
769 const bool allow_both_undefined);
770
771 void __media_entity_remove_links(struct media_entity *entity);
772
773 /**
774 * media_entity_remove_links() - remove all links associated with an entity
775 *
776 * @entity: pointer to &media_entity
777 *
778 * .. note::
779 *
780 * This is called automatically when an entity is unregistered via
781 * media_device_register_entity().
782 */
783 void media_entity_remove_links(struct media_entity *entity);
784
785 /**
786 * __media_entity_setup_link - Configure a media link without locking
787 * @link: The link being configured
788 * @flags: Link configuration flags
789 *
790 * The bulk of link setup is handled by the two entities connected through the
791 * link. This function notifies both entities of the link configuration change.
792 *
793 * If the link is immutable or if the current and new configuration are
794 * identical, return immediately.
795 *
796 * The user is expected to hold link->source->parent->mutex. If not,
797 * media_entity_setup_link() should be used instead.
798 */
799 int __media_entity_setup_link(struct media_link *link, u32 flags);
800
801 /**
802 * media_entity_setup_link() - changes the link flags properties in runtime
803 *
804 * @link: pointer to &media_link
805 * @flags: the requested new link flags
806 *
807 * The only configurable property is the %MEDIA_LNK_FL_ENABLED link flag
808 * to enable/disable a link. Links marked with the
809 * %MEDIA_LNK_FL_IMMUTABLE link flag can not be enabled or disabled.
810 *
811 * When a link is enabled or disabled, the media framework calls the
812 * link_setup operation for the two entities at the source and sink of the
813 * link, in that order. If the second link_setup call fails, another
814 * link_setup call is made on the first entity to restore the original link
815 * flags.
816 *
817 * Media device drivers can be notified of link setup operations by setting the
818 * &media_device.link_notify pointer to a callback function. If provided, the
819 * notification callback will be called before enabling and after disabling
820 * links.
821 *
822 * Entity drivers must implement the link_setup operation if any of their links
823 * is non-immutable. The operation must either configure the hardware or store
824 * the configuration information to be applied later.
825 *
826 * Link configuration must not have any side effect on other links. If an
827 * enabled link at a sink pad prevents another link at the same pad from
828 * being enabled, the link_setup operation must return %-EBUSY and can't
829 * implicitly disable the first enabled link.
830 *
831 * .. note::
832 *
833 * The valid values of the flags for the link is the same as described
834 * on media_create_pad_link(), for pad to pad links or the same as described
835 * on media_create_intf_link(), for interface to entity links.
836 */
837 int media_entity_setup_link(struct media_link *link, u32 flags);
838
839 /**
840 * media_entity_find_link - Find a link between two pads
841 * @source: Source pad
842 * @sink: Sink pad
843 *
844 * Return: returns a pointer to the link between the two entities. If no
845 * such link exists, return %NULL.
846 */
847 struct media_link *media_entity_find_link(struct media_pad *source,
848 struct media_pad *sink);
849
850 /**
851 * media_entity_remote_pad - Find the pad at the remote end of a link
852 * @pad: Pad at the local end of the link
853 *
854 * Search for a remote pad connected to the given pad by iterating over all
855 * links originating or terminating at that pad until an enabled link is found.
856 *
857 * Return: returns a pointer to the pad at the remote end of the first found
858 * enabled link, or %NULL if no enabled link has been found.
859 */
860 struct media_pad *media_entity_remote_pad(const struct media_pad *pad);
861
862 /**
863 * media_entity_is_streaming - Test if an entity is part of a streaming pipeline
864 * @entity: The entity
865 *
866 * Return: True if the entity is part of a pipeline started with the
867 * media_pipeline_start() function, false otherwise.
868 */
media_entity_is_streaming(const struct media_entity * entity)869 static inline bool media_entity_is_streaming(const struct media_entity *entity)
870 {
871 return entity->pipe;
872 }
873
874 /**
875 * media_entity_get_fwnode_pad - Get pad number from fwnode
876 *
877 * @entity: The entity
878 * @fwnode: Pointer to the fwnode_handle which should be used to find the pad
879 * @direction_flags: Expected direction of the pad, as defined in
880 * :ref:`include/uapi/linux/media.h <media_header>`
881 * (seek for ``MEDIA_PAD_FL_*``)
882 *
883 * This function can be used to resolve the media pad number from
884 * a fwnode. This is useful for devices which use more complex
885 * mappings of media pads.
886 *
887 * If the entity does not implement the get_fwnode_pad() operation
888 * then this function searches the entity for the first pad that
889 * matches the @direction_flags.
890 *
891 * Return: returns the pad number on success or a negative error code.
892 */
893 int media_entity_get_fwnode_pad(struct media_entity *entity,
894 struct fwnode_handle *fwnode,
895 unsigned long direction_flags);
896
897 /**
898 * media_graph_walk_init - Allocate resources used by graph walk.
899 *
900 * @graph: Media graph structure that will be used to walk the graph
901 * @mdev: Pointer to the &media_device that contains the object
902 *
903 * The caller is required to hold the media_device graph_mutex during the graph
904 * walk until the graph state is released.
905 *
906 * Returns zero on success or a negative error code otherwise.
907 */
908 __must_check int media_graph_walk_init(
909 struct media_graph *graph, struct media_device *mdev);
910
911 /**
912 * media_graph_walk_cleanup - Release resources used by graph walk.
913 *
914 * @graph: Media graph structure that will be used to walk the graph
915 */
916 void media_graph_walk_cleanup(struct media_graph *graph);
917
918 /**
919 * media_graph_walk_start - Start walking the media graph at a
920 * given entity
921 *
922 * @graph: Media graph structure that will be used to walk the graph
923 * @entity: Starting entity
924 *
925 * Before using this function, media_graph_walk_init() must be
926 * used to allocate resources used for walking the graph. This
927 * function initializes the graph traversal structure to walk the
928 * entities graph starting at the given entity. The traversal
929 * structure must not be modified by the caller during graph
930 * traversal. After the graph walk, the resources must be released
931 * using media_graph_walk_cleanup().
932 */
933 void media_graph_walk_start(struct media_graph *graph,
934 struct media_entity *entity);
935
936 /**
937 * media_graph_walk_next - Get the next entity in the graph
938 * @graph: Media graph structure
939 *
940 * Perform a depth-first traversal of the given media entities graph.
941 *
942 * The graph structure must have been previously initialized with a call to
943 * media_graph_walk_start().
944 *
945 * Return: returns the next entity in the graph or %NULL if the whole graph
946 * have been traversed.
947 */
948 struct media_entity *media_graph_walk_next(struct media_graph *graph);
949
950 /**
951 * media_pipeline_start - Mark a pipeline as streaming
952 * @entity: Starting entity
953 * @pipe: Media pipeline to be assigned to all entities in the pipeline.
954 *
955 * Mark all entities connected to a given entity through enabled links, either
956 * directly or indirectly, as streaming. The given pipeline object is assigned
957 * to every entity in the pipeline and stored in the media_entity pipe field.
958 *
959 * Calls to this function can be nested, in which case the same number of
960 * media_pipeline_stop() calls will be required to stop streaming. The
961 * pipeline pointer must be identical for all nested calls to
962 * media_pipeline_start().
963 */
964 __must_check int media_pipeline_start(struct media_entity *entity,
965 struct media_pipeline *pipe);
966 /**
967 * __media_pipeline_start - Mark a pipeline as streaming
968 *
969 * @entity: Starting entity
970 * @pipe: Media pipeline to be assigned to all entities in the pipeline.
971 *
972 * ..note:: This is the non-locking version of media_pipeline_start()
973 */
974 __must_check int __media_pipeline_start(struct media_entity *entity,
975 struct media_pipeline *pipe);
976
977 /**
978 * media_pipeline_stop - Mark a pipeline as not streaming
979 * @entity: Starting entity
980 *
981 * Mark all entities connected to a given entity through enabled links, either
982 * directly or indirectly, as not streaming. The media_entity pipe field is
983 * reset to %NULL.
984 *
985 * If multiple calls to media_pipeline_start() have been made, the same
986 * number of calls to this function are required to mark the pipeline as not
987 * streaming.
988 */
989 void media_pipeline_stop(struct media_entity *entity);
990
991 /**
992 * __media_pipeline_stop - Mark a pipeline as not streaming
993 *
994 * @entity: Starting entity
995 *
996 * .. note:: This is the non-locking version of media_pipeline_stop()
997 */
998 void __media_pipeline_stop(struct media_entity *entity);
999
1000 /**
1001 * media_devnode_create() - creates and initializes a device node interface
1002 *
1003 * @mdev: pointer to struct &media_device
1004 * @type: type of the interface, as given by
1005 * :ref:`include/uapi/linux/media.h <media_header>`
1006 * ( seek for ``MEDIA_INTF_T_*``) macros.
1007 * @flags: Interface flags, as defined in
1008 * :ref:`include/uapi/linux/media.h <media_header>`
1009 * ( seek for ``MEDIA_INTF_FL_*``)
1010 * @major: Device node major number.
1011 * @minor: Device node minor number.
1012 *
1013 * Return: if succeeded, returns a pointer to the newly allocated
1014 * &media_intf_devnode pointer.
1015 *
1016 * .. note::
1017 *
1018 * Currently, no flags for &media_interface is defined.
1019 */
1020 struct media_intf_devnode *
1021 __must_check media_devnode_create(struct media_device *mdev,
1022 u32 type, u32 flags,
1023 u32 major, u32 minor);
1024 /**
1025 * media_devnode_remove() - removes a device node interface
1026 *
1027 * @devnode: pointer to &media_intf_devnode to be freed.
1028 *
1029 * When a device node interface is removed, all links to it are automatically
1030 * removed.
1031 */
1032 void media_devnode_remove(struct media_intf_devnode *devnode);
1033
1034 /**
1035 * media_create_intf_link() - creates a link between an entity and an interface
1036 *
1037 * @entity: pointer to %media_entity
1038 * @intf: pointer to %media_interface
1039 * @flags: Link flags, as defined in
1040 * :ref:`include/uapi/linux/media.h <media_header>`
1041 * ( seek for ``MEDIA_LNK_FL_*``)
1042 *
1043 *
1044 * Valid values for flags:
1045 *
1046 * %MEDIA_LNK_FL_ENABLED
1047 * Indicates that the interface is connected to the entity hardware.
1048 * That's the default value for interfaces. An interface may be disabled if
1049 * the hardware is busy due to the usage of some other interface that it is
1050 * currently controlling the hardware.
1051 *
1052 * A typical example is an hybrid TV device that handle only one type of
1053 * stream on a given time. So, when the digital TV is streaming,
1054 * the V4L2 interfaces won't be enabled, as such device is not able to
1055 * also stream analog TV or radio.
1056 *
1057 * .. note::
1058 *
1059 * Before calling this function, media_devnode_create() should be called for
1060 * the interface and media_device_register_entity() should be called for the
1061 * interface that will be part of the link.
1062 */
1063 struct media_link *
1064 __must_check media_create_intf_link(struct media_entity *entity,
1065 struct media_interface *intf,
1066 u32 flags);
1067 /**
1068 * __media_remove_intf_link() - remove a single interface link
1069 *
1070 * @link: pointer to &media_link.
1071 *
1072 * .. note:: This is an unlocked version of media_remove_intf_link()
1073 */
1074 void __media_remove_intf_link(struct media_link *link);
1075
1076 /**
1077 * media_remove_intf_link() - remove a single interface link
1078 *
1079 * @link: pointer to &media_link.
1080 *
1081 * .. note:: Prefer to use this one, instead of __media_remove_intf_link()
1082 */
1083 void media_remove_intf_link(struct media_link *link);
1084
1085 /**
1086 * __media_remove_intf_links() - remove all links associated with an interface
1087 *
1088 * @intf: pointer to &media_interface
1089 *
1090 * .. note:: This is an unlocked version of media_remove_intf_links().
1091 */
1092 void __media_remove_intf_links(struct media_interface *intf);
1093
1094 /**
1095 * media_remove_intf_links() - remove all links associated with an interface
1096 *
1097 * @intf: pointer to &media_interface
1098 *
1099 * .. note::
1100 *
1101 * #) This is called automatically when an entity is unregistered via
1102 * media_device_register_entity() and by media_devnode_remove().
1103 *
1104 * #) Prefer to use this one, instead of __media_remove_intf_links().
1105 */
1106 void media_remove_intf_links(struct media_interface *intf);
1107
1108 /**
1109 * media_entity_call - Calls a struct media_entity_operations operation on
1110 * an entity
1111 *
1112 * @entity: entity where the @operation will be called
1113 * @operation: type of the operation. Should be the name of a member of
1114 * struct &media_entity_operations.
1115 *
1116 * This helper function will check if @operation is not %NULL. On such case,
1117 * it will issue a call to @operation\(@entity, @args\).
1118 */
1119
1120 #define media_entity_call(entity, operation, args...) \
1121 (((entity)->ops && (entity)->ops->operation) ? \
1122 (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)
1123
1124 /**
1125 * media_create_ancillary_link() - create an ancillary link between two
1126 * instances of &media_entity
1127 *
1128 * @primary: pointer to the primary &media_entity
1129 * @ancillary: pointer to the ancillary &media_entity
1130 *
1131 * Create an ancillary link between two entities, indicating that they
1132 * represent two connected pieces of hardware that form a single logical unit.
1133 * A typical example is a camera lens controller being linked to the sensor that
1134 * it is supporting.
1135 *
1136 * The function sets both MEDIA_LNK_FL_ENABLED and MEDIA_LNK_FL_IMMUTABLE for
1137 * the new link.
1138 */
1139 struct media_link *
1140 media_create_ancillary_link(struct media_entity *primary,
1141 struct media_entity *ancillary);
1142
1143 #endif
1144