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