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