4 * Copyright (C) 2010 Nokia Corporation
6 * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
7 * Sakari Ailus <sakari.ailus@iki.fi>
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.
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.
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
23 #ifndef _MEDIA_ENTITY_H
24 #define _MEDIA_ENTITY_H
26 #include <linux/bitmap.h>
27 #include <linux/bug.h>
28 #include <linux/kernel.h>
29 #include <linux/list.h>
30 #include <linux/media.h>
32 /* Enums used internally at the media controller to represent graphs */
35 * enum media_gobj_type - type of a graph object
37 * @MEDIA_GRAPH_ENTITY: Identify a media entity
38 * @MEDIA_GRAPH_PAD: Identify a media pad
39 * @MEDIA_GRAPH_LINK: Identify a media link
40 * @MEDIA_GRAPH_INTF_DEVNODE: Identify a media Kernel API interface via
43 enum media_gobj_type {
47 MEDIA_GRAPH_INTF_DEVNODE,
50 #define MEDIA_BITS_PER_TYPE 8
51 #define MEDIA_BITS_PER_ID (32 - MEDIA_BITS_PER_TYPE)
52 #define MEDIA_ID_MASK GENMASK_ULL(MEDIA_BITS_PER_ID - 1, 0)
54 /* Structs to represent the objects that belong to a media graph */
57 * struct media_gobj - Define a graph object.
59 * @mdev: Pointer to the struct &media_device that owns the object
60 * @id: Non-zero object ID identifier. The ID should be unique
61 * inside a media_device, as it is composed by
62 * %MEDIA_BITS_PER_TYPE to store the type plus
63 * %MEDIA_BITS_PER_ID to store the ID
64 * @list: List entry stored in one of the per-type mdev object lists
66 * All objects on the media graph should have this struct embedded
69 struct media_device *mdev;
71 struct list_head list;
74 #define MEDIA_ENTITY_ENUM_MAX_DEPTH 16
77 * struct media_entity_enum - An enumeration of media entities.
79 * @bmap: Bit map in which each bit represents one entity at struct
80 * media_entity->internal_idx.
81 * @idx_max: Number of bits in bmap
83 struct media_entity_enum {
89 * struct media_entity_graph - Media graph traversal state
91 * @stack: Graph traversal stack; the stack contains information
92 * on the path the media entities to be walked and the
93 * links through which they were reached.
94 * @ent_enum: Visited entities
95 * @top: The top of the stack
97 struct media_entity_graph {
99 struct media_entity *entity;
100 struct list_head *link;
101 } stack[MEDIA_ENTITY_ENUM_MAX_DEPTH];
103 struct media_entity_enum ent_enum;
108 * struct media_pipeline - Media pipeline related information
110 * @streaming_count: Streaming start count - streaming stop count
111 * @graph: Media graph walk during pipeline start / stop
113 struct media_pipeline {
115 struct media_entity_graph graph;
119 * struct media_link - A link object part of a media graph.
121 * @graph_obj: Embedded structure containing the media object common data
122 * @list: Linked list associated with an entity or an interface that
124 * @gobj0: Part of a union. Used to get the pointer for the first
125 * graph_object of the link.
126 * @source: Part of a union. Used only if the first object (gobj0) is
127 * a pad. In that case, it represents the source pad.
128 * @intf: Part of a union. Used only if the first object (gobj0) is
130 * @gobj1: Part of a union. Used to get the pointer for the second
131 * graph_object of the link.
132 * @source: Part of a union. Used only if the second object (gobj1) is
133 * a pad. In that case, it represents the sink pad.
134 * @entity: Part of a union. Used only if the second object (gobj1) is
136 * @reverse: Pointer to the link for the reverse direction of a pad to pad
138 * @flags: Link flags, as defined in uapi/media.h (MEDIA_LNK_FL_*)
139 * @is_backlink: Indicate if the link is a backlink.
142 struct media_gobj graph_obj;
143 struct list_head list;
145 struct media_gobj *gobj0;
146 struct media_pad *source;
147 struct media_interface *intf;
150 struct media_gobj *gobj1;
151 struct media_pad *sink;
152 struct media_entity *entity;
154 struct media_link *reverse;
160 * struct media_pad - A media pad graph object.
162 * @graph_obj: Embedded structure containing the media object common data
163 * @entity: Entity this pad belongs to
164 * @index: Pad index in the entity pads array, numbered from 0 to n
165 * @flags: Pad flags, as defined in
166 * :ref:`include/uapi/linux/media.h <media_header>`
167 * (seek for ``MEDIA_PAD_FL_*``)
170 struct media_gobj graph_obj; /* must be first field in struct */
171 struct media_entity *entity;
177 * struct media_entity_operations - Media entity operations
178 * @link_setup: Notify the entity of link changes. The operation can
179 * return an error, in which case link setup will be
180 * cancelled. Optional.
181 * @link_validate: Return whether a link is valid from the entity point of
182 * view. The media_entity_pipeline_start() function
183 * validates all links by calling this operation. Optional.
187 * Those these callbacks are called with struct &media_device.graph_mutex
190 struct media_entity_operations {
191 int (*link_setup)(struct media_entity *entity,
192 const struct media_pad *local,
193 const struct media_pad *remote, u32 flags);
194 int (*link_validate)(struct media_link *link);
198 * enum media_entity_type - Media entity type
200 * @MEDIA_ENTITY_TYPE_BASE:
201 * The entity isn't embedded in another subsystem structure.
202 * @MEDIA_ENTITY_TYPE_VIDEO_DEVICE:
203 * The entity is embedded in a struct video_device instance.
204 * @MEDIA_ENTITY_TYPE_V4L2_SUBDEV:
205 * The entity is embedded in a struct v4l2_subdev instance.
207 * Media entity objects are often not instantiated directly, but the media
208 * entity structure is inherited by (through embedding) other subsystem-specific
209 * structures. The media entity type identifies the type of the subclass
210 * structure that implements a media entity instance.
212 * This allows runtime type identification of media entities and safe casting to
213 * the correct object type. For instance, a media entity structure instance
214 * embedded in a v4l2_subdev structure instance will have the type
215 * %MEDIA_ENTITY_TYPE_V4L2_SUBDEV and can safely be cast to a &v4l2_subdev
216 * structure using the container_of() macro.
218 enum media_entity_type {
219 MEDIA_ENTITY_TYPE_BASE,
220 MEDIA_ENTITY_TYPE_VIDEO_DEVICE,
221 MEDIA_ENTITY_TYPE_V4L2_SUBDEV,
225 * struct media_entity - A media entity graph object.
227 * @graph_obj: Embedded structure containing the media object common data.
228 * @name: Entity name.
229 * @obj_type: Type of the object that implements the media_entity.
230 * @function: Entity main function, as defined in
231 * :ref:`include/uapi/linux/media.h <media_header>`
232 * (seek for ``MEDIA_ENT_F_*``)
233 * @flags: Entity flags, as defined in
234 * :ref:`include/uapi/linux/media.h <media_header>`
235 * (seek for ``MEDIA_ENT_FL_*``)
236 * @num_pads: Number of sink and source pads.
237 * @num_links: Total number of links, forward and back, enabled and disabled.
238 * @num_backlinks: Number of backlinks
239 * @internal_idx: An unique internal entity specific number. The numbers are
240 * re-used if entities are unregistered or registered again.
241 * @pads: Pads array with the size defined by @num_pads.
242 * @links: List of data links.
243 * @ops: Entity operations.
244 * @stream_count: Stream count for the entity.
245 * @use_count: Use count for the entity.
246 * @pipe: Pipeline this entity belongs to.
247 * @info: Union with devnode information. Kept just for backward
249 * @major: Devnode major number (zero if not applicable). Kept just
250 * for backward compatibility.
251 * @minor: Devnode minor number (zero if not applicable). Kept just
252 * for backward compatibility.
256 * @stream_count and @use_count reference counts must never be
257 * negative, but are signed integers on purpose: a simple ``WARN_ON(<0)``
258 * check can be used to detect reference count bugs that would make them
261 struct media_entity {
262 struct media_gobj graph_obj; /* must be first field in struct */
264 enum media_entity_type obj_type;
273 struct media_pad *pads;
274 struct list_head links;
276 const struct media_entity_operations *ops;
281 struct media_pipeline *pipe;
292 * struct media_interface - A media interface graph object.
294 * @graph_obj: embedded graph object
295 * @links: List of links pointing to graph entities
296 * @type: Type of the interface as defined in
297 * :ref:`include/uapi/linux/media.h <media_header>`
298 * (seek for ``MEDIA_INTF_T_*``)
299 * @flags: Interface flags as defined in
300 * :ref:`include/uapi/linux/media.h <media_header>`
301 * (seek for ``MEDIA_INTF_FL_*``)
305 * Currently, no flags for &media_interface is defined.
307 struct media_interface {
308 struct media_gobj graph_obj;
309 struct list_head links;
315 * struct media_intf_devnode - A media interface via a device node.
317 * @intf: embedded interface object
318 * @major: Major number of a device node
319 * @minor: Minor number of a device node
321 struct media_intf_devnode {
322 struct media_interface intf;
324 /* Should match the fields at media_v2_intf_devnode */
330 * media_entity_id() - return the media entity graph object id
332 * @entity: pointer to &media_entity
334 static inline u32 media_entity_id(struct media_entity *entity)
336 return entity->graph_obj.id;
340 * media_type() - return the media object type
342 * @gobj: Pointer to the struct &media_gobj graph object
344 static inline enum media_gobj_type media_type(struct media_gobj *gobj)
346 return gobj->id >> MEDIA_BITS_PER_ID;
350 * media_id() - return the media object ID
352 * @gobj: Pointer to the struct &media_gobj graph object
354 static inline u32 media_id(struct media_gobj *gobj)
356 return gobj->id & MEDIA_ID_MASK;
360 * media_gobj_gen_id() - encapsulates type and ID on at the object ID
362 * @type: object type as define at enum &media_gobj_type.
363 * @local_id: next ID, from struct &media_device.id.
365 static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id)
369 id = type << MEDIA_BITS_PER_ID;
370 id |= local_id & MEDIA_ID_MASK;
376 * is_media_entity_v4l2_video_device() - Check if the entity is a video_device
377 * @entity: pointer to entity
379 * Return: %true if the entity is an instance of a video_device object and can
380 * safely be cast to a struct video_device using the container_of() macro, or
383 static inline bool is_media_entity_v4l2_video_device(struct media_entity *entity)
385 return entity && entity->obj_type == MEDIA_ENTITY_TYPE_VIDEO_DEVICE;
389 * is_media_entity_v4l2_subdev() - Check if the entity is a v4l2_subdev
390 * @entity: pointer to entity
392 * Return: %true if the entity is an instance of a &v4l2_subdev object and can
393 * safely be cast to a struct &v4l2_subdev using the container_of() macro, or
396 static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity)
398 return entity && entity->obj_type == MEDIA_ENTITY_TYPE_V4L2_SUBDEV;
402 * __media_entity_enum_init - Initialise an entity enumeration
404 * @ent_enum: Entity enumeration to be initialised
405 * @idx_max: Maximum number of entities in the enumeration
407 * Return: Returns zero on success or a negative error code.
409 __must_check int __media_entity_enum_init(struct media_entity_enum *ent_enum,
413 * media_entity_enum_cleanup - Release resources of an entity enumeration
415 * @ent_enum: Entity enumeration to be released
417 void media_entity_enum_cleanup(struct media_entity_enum *ent_enum);
420 * media_entity_enum_zero - Clear the entire enum
422 * @ent_enum: Entity enumeration to be cleared
424 static inline void media_entity_enum_zero(struct media_entity_enum *ent_enum)
426 bitmap_zero(ent_enum->bmap, ent_enum->idx_max);
430 * media_entity_enum_set - Mark a single entity in the enum
432 * @ent_enum: Entity enumeration
433 * @entity: Entity to be marked
435 static inline void media_entity_enum_set(struct media_entity_enum *ent_enum,
436 struct media_entity *entity)
438 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))
441 __set_bit(entity->internal_idx, ent_enum->bmap);
445 * media_entity_enum_clear - Unmark a single entity in the enum
447 * @ent_enum: Entity enumeration
448 * @entity: Entity to be unmarked
450 static inline void media_entity_enum_clear(struct media_entity_enum *ent_enum,
451 struct media_entity *entity)
453 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))
456 __clear_bit(entity->internal_idx, ent_enum->bmap);
460 * media_entity_enum_test - Test whether the entity is marked
462 * @ent_enum: Entity enumeration
463 * @entity: Entity to be tested
465 * Returns %true if the entity was marked.
467 static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum,
468 struct media_entity *entity)
470 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))
473 return test_bit(entity->internal_idx, ent_enum->bmap);
477 * media_entity_enum_test - Test whether the entity is marked, and mark it
479 * @ent_enum: Entity enumeration
480 * @entity: Entity to be tested
482 * Returns %true if the entity was marked, and mark it before doing so.
485 media_entity_enum_test_and_set(struct media_entity_enum *ent_enum,
486 struct media_entity *entity)
488 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))
491 return __test_and_set_bit(entity->internal_idx, ent_enum->bmap);
495 * media_entity_enum_empty - Test whether the entire enum is empty
497 * @ent_enum: Entity enumeration
499 * Return: %true if the entity was empty.
501 static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum)
503 return bitmap_empty(ent_enum->bmap, ent_enum->idx_max);
507 * media_entity_enum_intersects - Test whether two enums intersect
509 * @ent_enum1: First entity enumeration
510 * @ent_enum2: Second entity enumeration
512 * Return: %true if entity enumerations @ent_enum1 and @ent_enum2 intersect,
515 static inline bool media_entity_enum_intersects(
516 struct media_entity_enum *ent_enum1,
517 struct media_entity_enum *ent_enum2)
519 WARN_ON(ent_enum1->idx_max != ent_enum2->idx_max);
521 return bitmap_intersects(ent_enum1->bmap, ent_enum2->bmap,
522 min(ent_enum1->idx_max, ent_enum2->idx_max));
526 * gobj_to_entity - returns the struct &media_entity pointer from the
527 * @gobj contained on it.
529 * @gobj: Pointer to the struct &media_gobj graph object
531 #define gobj_to_entity(gobj) \
532 container_of(gobj, struct media_entity, graph_obj)
535 * gobj_to_entity - returns the struct &media_pad pointer from the
536 * @gobj contained on it.
538 * @gobj: Pointer to the struct &media_gobj graph object
540 #define gobj_to_pad(gobj) \
541 container_of(gobj, struct media_pad, graph_obj)
544 * gobj_to_entity - returns the struct &media_link pointer from the
545 * @gobj contained on it.
547 * @gobj: Pointer to the struct &media_gobj graph object
549 #define gobj_to_link(gobj) \
550 container_of(gobj, struct media_link, graph_obj)
553 * gobj_to_entity - returns the struct &media_interface pointer from the
554 * @gobj contained on it.
556 * @gobj: Pointer to the struct &media_gobj graph object
558 #define gobj_to_intf(gobj) \
559 container_of(gobj, struct media_interface, graph_obj)
562 * gobj_to_entity - returns the struct media_intf_devnode pointer from the
563 * @intf contained on it.
565 * @intf: Pointer to struct &media_intf_devnode
567 #define intf_to_devnode(intf) \
568 container_of(intf, struct media_intf_devnode, intf)
571 * media_gobj_create - Initialize a graph object
573 * @mdev: Pointer to the &media_device that contains the object
574 * @type: Type of the object
575 * @gobj: Pointer to the struct &media_gobj graph object
577 * This routine initializes the embedded struct &media_gobj inside a
578 * media graph object. It is called automatically if ``media_*_create``
579 * function calls are used. However, if the object (entity, link, pad,
580 * interface) is embedded on some other object, this function should be
581 * called before registering the object at the media controller.
583 void media_gobj_create(struct media_device *mdev,
584 enum media_gobj_type type,
585 struct media_gobj *gobj);
588 * media_gobj_destroy - Stop using a graph object on a media device
590 * @gobj: Pointer to the struct &media_gobj graph object
592 * This should be called by all routines like media_device_unregister()
593 * that remove/destroy media graph objects.
595 void media_gobj_destroy(struct media_gobj *gobj);
598 * media_entity_pads_init() - Initialize the entity pads
600 * @entity: entity where the pads belong
601 * @num_pads: total number of sink and source pads
602 * @pads: Array of @num_pads pads.
604 * The pads array is managed by the entity driver and passed to
605 * media_entity_pads_init() where its pointer will be stored in the
606 * &media_entity structure.
608 * If no pads are needed, drivers could either directly fill
609 * &media_entity->num_pads with 0 and &media_entity->pads with %NULL or call
610 * this function that will do the same.
612 * As the number of pads is known in advance, the pads array is not allocated
613 * dynamically but is managed by the entity driver. Most drivers will embed the
614 * pads array in a driver-specific structure, avoiding dynamic allocation.
616 * Drivers must set the direction of every pad in the pads array before calling
617 * media_entity_pads_init(). The function will initialize the other pads fields.
619 int media_entity_pads_init(struct media_entity *entity, u16 num_pads,
620 struct media_pad *pads);
623 * media_entity_cleanup() - free resources associated with an entity
625 * @entity: entity where the pads belong
627 * This function must be called during the cleanup phase after unregistering
628 * the entity (currently, it does nothing).
630 static inline void media_entity_cleanup(struct media_entity *entity) {};
633 * media_create_pad_link() - creates a link between two entities.
635 * @source: pointer to &media_entity of the source pad.
636 * @source_pad: number of the source pad in the pads array
637 * @sink: pointer to &media_entity of the sink pad.
638 * @sink_pad: number of the sink pad in the pads array.
639 * @flags: Link flags, as defined in
640 * :ref:`include/uapi/linux/media.h <media_header>`
641 * ( seek for ``MEDIA_LNK_FL_*``)
643 * Valid values for flags:
645 * %MEDIA_LNK_FL_ENABLED
646 * Indicates that the link is enabled and can be used to transfer media data.
647 * When two or more links target a sink pad, only one of them can be
650 * %MEDIA_LNK_FL_IMMUTABLE
651 * Indicates that the link enabled state can't be modified at runtime. If
652 * %MEDIA_LNK_FL_IMMUTABLE is set, then %MEDIA_LNK_FL_ENABLED must also be
653 * set, since an immutable link is always enabled.
657 * Before calling this function, media_entity_pads_init() and
658 * media_device_register_entity() should be called previously for both ends.
660 __must_check int media_create_pad_link(struct media_entity *source,
661 u16 source_pad, struct media_entity *sink,
662 u16 sink_pad, u32 flags);
665 * media_create_pad_links() - creates a link between two entities.
667 * @mdev: Pointer to the media_device that contains the object
668 * @source_function: Function of the source entities. Used only if @source is
670 * @source: pointer to &media_entity of the source pad. If NULL, it will use
671 * all entities that matches the @sink_function.
672 * @source_pad: number of the source pad in the pads array
673 * @sink_function: Function of the sink entities. Used only if @sink is NULL.
674 * @sink: pointer to &media_entity of the sink pad. If NULL, it will use
675 * all entities that matches the @sink_function.
676 * @sink_pad: number of the sink pad in the pads array.
677 * @flags: Link flags, as defined in include/uapi/linux/media.h.
678 * @allow_both_undefined: if %true, then both @source and @sink can be NULL.
679 * In such case, it will create a crossbar between all entities that
680 * matches @source_function to all entities that matches @sink_function.
681 * If %false, it will return 0 and won't create any link if both @source
682 * and @sink are NULL.
684 * Valid values for flags:
686 * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be
687 * used to transfer media data. If multiple links are created and this
688 * flag is passed as an argument, only the first created link will have
691 * A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't
692 * be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then
693 * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
696 * It is common for some devices to have multiple source and/or sink entities
697 * of the same type that should be linked. While media_create_pad_link()
698 * creates link by link, this function is meant to allow 1:n, n:1 and even
699 * cross-bar (n:n) links.
703 * Before calling this function, media_entity_pads_init() and
704 * media_device_register_entity() should be called previously for the
705 * entities to be linked.
707 int media_create_pad_links(const struct media_device *mdev,
708 const u32 source_function,
709 struct media_entity *source,
710 const u16 source_pad,
711 const u32 sink_function,
712 struct media_entity *sink,
715 const bool allow_both_undefined);
717 void __media_entity_remove_links(struct media_entity *entity);
720 * media_entity_remove_links() - remove all links associated with an entity
722 * @entity: pointer to &media_entity
726 * This is called automatically when an entity is unregistered via
727 * media_device_register_entity().
729 void media_entity_remove_links(struct media_entity *entity);
732 * __media_entity_setup_link - Configure a media link without locking
733 * @link: The link being configured
734 * @flags: Link configuration flags
736 * The bulk of link setup is handled by the two entities connected through the
737 * link. This function notifies both entities of the link configuration change.
739 * If the link is immutable or if the current and new configuration are
740 * identical, return immediately.
742 * The user is expected to hold link->source->parent->mutex. If not,
743 * media_entity_setup_link() should be used instead.
745 int __media_entity_setup_link(struct media_link *link, u32 flags);
748 * media_entity_setup_link() - changes the link flags properties in runtime
750 * @link: pointer to &media_link
751 * @flags: the requested new link flags
753 * The only configurable property is the %MEDIA_LNK_FL_ENABLED link flag
754 * flag to enable/disable a link. Links marked with the
755 * %MEDIA_LNK_FL_IMMUTABLE link flag can not be enabled or disabled.
757 * When a link is enabled or disabled, the media framework calls the
758 * link_setup operation for the two entities at the source and sink of the
759 * link, in that order. If the second link_setup call fails, another
760 * link_setup call is made on the first entity to restore the original link
763 * Media device drivers can be notified of link setup operations by setting the
764 * &media_device.link_notify pointer to a callback function. If provided, the
765 * notification callback will be called before enabling and after disabling
768 * Entity drivers must implement the link_setup operation if any of their links
769 * is non-immutable. The operation must either configure the hardware or store
770 * the configuration information to be applied later.
772 * Link configuration must not have any side effect on other links. If an
773 * enabled link at a sink pad prevents another link at the same pad from
774 * being enabled, the link_setup operation must return %-EBUSY and can't
775 * implicitly disable the first enabled link.
779 * The valid values of the flags for the link is the same as described
780 * on media_create_pad_link(), for pad to pad links or the same as described
781 * on media_create_intf_link(), for interface to entity links.
783 int media_entity_setup_link(struct media_link *link, u32 flags);
786 * media_entity_find_link - Find a link between two pads
787 * @source: Source pad
790 * Return: returns a pointer to the link between the two entities. If no
791 * such link exists, return %NULL.
793 struct media_link *media_entity_find_link(struct media_pad *source,
794 struct media_pad *sink);
797 * media_entity_remote_pad - Find the pad at the remote end of a link
798 * @pad: Pad at the local end of the link
800 * Search for a remote pad connected to the given pad by iterating over all
801 * links originating or terminating at that pad until an enabled link is found.
803 * Return: returns a pointer to the pad at the remote end of the first found
804 * enabled link, or %NULL if no enabled link has been found.
806 struct media_pad *media_entity_remote_pad(struct media_pad *pad);
809 * media_entity_get - Get a reference to the parent module
811 * @entity: The entity
813 * Get a reference to the parent media device module.
815 * The function will return immediately if @entity is %NULL.
817 * Return: returns a pointer to the entity on success or %NULL on failure.
819 struct media_entity *media_entity_get(struct media_entity *entity);
822 * media_entity_graph_walk_init - Allocate resources used by graph walk.
824 * @graph: Media graph structure that will be used to walk the graph
825 * @mdev: Pointer to the &media_device that contains the object
827 __must_check int media_entity_graph_walk_init(
828 struct media_entity_graph *graph, struct media_device *mdev);
831 * media_entity_graph_walk_cleanup - Release resources used by graph walk.
833 * @graph: Media graph structure that will be used to walk the graph
835 void media_entity_graph_walk_cleanup(struct media_entity_graph *graph);
838 * media_entity_put - Release the reference to the parent module
840 * @entity: The entity
842 * Release the reference count acquired by media_entity_get().
844 * The function will return immediately if @entity is %NULL.
846 void media_entity_put(struct media_entity *entity);
849 * media_entity_graph_walk_start - Start walking the media graph at a
852 * @graph: Media graph structure that will be used to walk the graph
853 * @entity: Starting entity
855 * Before using this function, media_entity_graph_walk_init() must be
856 * used to allocate resources used for walking the graph. This
857 * function initializes the graph traversal structure to walk the
858 * entities graph starting at the given entity. The traversal
859 * structure must not be modified by the caller during graph
860 * traversal. After the graph walk, the resources must be released
861 * using media_entity_graph_walk_cleanup().
863 void media_entity_graph_walk_start(struct media_entity_graph *graph,
864 struct media_entity *entity);
867 * media_entity_graph_walk_next - Get the next entity in the graph
868 * @graph: Media graph structure
870 * Perform a depth-first traversal of the given media entities graph.
872 * The graph structure must have been previously initialized with a call to
873 * media_entity_graph_walk_start().
875 * Return: returns the next entity in the graph or %NULL if the whole graph
876 * have been traversed.
878 struct media_entity *
879 media_entity_graph_walk_next(struct media_entity_graph *graph);
882 * media_entity_pipeline_start - Mark a pipeline as streaming
883 * @entity: Starting entity
884 * @pipe: Media pipeline to be assigned to all entities in the pipeline.
886 * Mark all entities connected to a given entity through enabled links, either
887 * directly or indirectly, as streaming. The given pipeline object is assigned
888 * to every entity in the pipeline and stored in the media_entity pipe field.
890 * Calls to this function can be nested, in which case the same number of
891 * media_entity_pipeline_stop() calls will be required to stop streaming. The
892 * pipeline pointer must be identical for all nested calls to
893 * media_entity_pipeline_start().
895 __must_check int media_entity_pipeline_start(struct media_entity *entity,
896 struct media_pipeline *pipe);
898 * __media_entity_pipeline_start - Mark a pipeline as streaming
900 * @entity: Starting entity
901 * @pipe: Media pipeline to be assigned to all entities in the pipeline.
903 * ..note:: This is the non-locking version of media_entity_pipeline_start()
905 __must_check int __media_entity_pipeline_start(struct media_entity *entity,
906 struct media_pipeline *pipe);
909 * media_entity_pipeline_stop - Mark a pipeline as not streaming
910 * @entity: Starting entity
912 * Mark all entities connected to a given entity through enabled links, either
913 * directly or indirectly, as not streaming. The media_entity pipe field is
916 * If multiple calls to media_entity_pipeline_start() have been made, the same
917 * number of calls to this function are required to mark the pipeline as not
920 void media_entity_pipeline_stop(struct media_entity *entity);
923 * __media_entity_pipeline_stop - Mark a pipeline as not streaming
925 * @entity: Starting entity
927 * .. note:: This is the non-locking version of media_entity_pipeline_stop()
929 void __media_entity_pipeline_stop(struct media_entity *entity);
932 * media_devnode_create() - creates and initializes a device node interface
934 * @mdev: pointer to struct &media_device
935 * @type: type of the interface, as given by
936 * :ref:`include/uapi/linux/media.h <media_header>`
937 * ( seek for ``MEDIA_INTF_T_*``) macros.
938 * @flags: Interface flags, as defined in
939 * :ref:`include/uapi/linux/media.h <media_header>`
940 * ( seek for ``MEDIA_INTF_FL_*``)
941 * @major: Device node major number.
942 * @minor: Device node minor number.
944 * Return: if succeeded, returns a pointer to the newly allocated
945 * &media_intf_devnode pointer.
949 * Currently, no flags for &media_interface is defined.
951 struct media_intf_devnode *
952 __must_check media_devnode_create(struct media_device *mdev,
954 u32 major, u32 minor);
956 * media_devnode_remove() - removes a device node interface
958 * @devnode: pointer to &media_intf_devnode to be freed.
960 * When a device node interface is removed, all links to it are automatically
963 void media_devnode_remove(struct media_intf_devnode *devnode);
967 * media_create_intf_link() - creates a link between an entity and an interface
969 * @entity: pointer to %media_entity
970 * @intf: pointer to %media_interface
971 * @flags: Link flags, as defined in
972 * :ref:`include/uapi/linux/media.h <media_header>`
973 * ( seek for ``MEDIA_LNK_FL_*``)
976 * Valid values for flags:
978 * %MEDIA_LNK_FL_ENABLED
979 * Indicates that the interface is connected to the entity hardware.
980 * That's the default value for interfaces. An interface may be disabled if
981 * the hardware is busy due to the usage of some other interface that it is
982 * currently controlling the hardware.
984 * A typical example is an hybrid TV device that handle only one type of
985 * stream on a given time. So, when the digital TV is streaming,
986 * the V4L2 interfaces won't be enabled, as such device is not able to
987 * also stream analog TV or radio.
991 * Before calling this function, media_devnode_create() should be called for
992 * the interface and media_device_register_entity() should be called for the
993 * interface that will be part of the link.
995 __must_check media_create_intf_link(struct media_entity *entity,
996 struct media_interface *intf,
999 * __media_remove_intf_link() - remove a single interface link
1001 * @link: pointer to &media_link.
1003 * .. note:: This is an unlocked version of media_remove_intf_link()
1005 void __media_remove_intf_link(struct media_link *link);
1008 * media_remove_intf_link() - remove a single interface link
1010 * @link: pointer to &media_link.
1012 * .. note:: Prefer to use this one, instead of __media_remove_intf_link()
1014 void media_remove_intf_link(struct media_link *link);
1017 * __media_remove_intf_links() - remove all links associated with an interface
1019 * @intf: pointer to &media_interface
1021 * .. note:: This is an unlocked version of media_remove_intf_links().
1023 void __media_remove_intf_links(struct media_interface *intf);
1026 * media_remove_intf_links() - remove all links associated with an interface
1028 * @intf: pointer to &media_interface
1032 * #) This is called automatically when an entity is unregistered via
1033 * media_device_register_entity() and by media_devnode_remove().
1035 * #) Prefer to use this one, instead of __media_remove_intf_links().
1037 void media_remove_intf_links(struct media_interface *intf);
1040 * media_entity_call - Calls a struct media_entity_operations operation on
1043 * @entity: entity where the @operation will be called
1044 * @operation: type of the operation. Should be the name of a member of
1045 * struct &media_entity_operations.
1047 * This helper function will check if @operation is not %NULL. On such case,
1048 * it will issue a call to @operation\(@entity, @args\).
1051 #define media_entity_call(entity, operation, args...) \
1052 (((entity)->ops && (entity)->ops->operation) ? \
1053 (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)