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