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