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