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