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