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