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