blob: 8cb2c504a05c7bf41e6e4dc22b894f19b2649a1c [file] [log] [blame]
Thomas Gleixner1802d0b2019-05-27 08:55:21 +02001/* SPDX-License-Identifier: GPL-2.0-only */
Laurent Pinchart53e269c2009-12-09 08:40:00 -03002/*
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>
Laurent Pinchart53e269c2009-12-09 08:40:00 -03009 */
10
11#ifndef _MEDIA_ENTITY_H
12#define _MEDIA_ENTITY_H
13
Sakari Ailusc8d54cd2015-12-16 11:44:32 -020014#include <linux/bitmap.h>
Philipp Zabel2899d352016-02-15 09:08:06 -020015#include <linux/bug.h>
Niklas Söderlundae45cd52017-06-15 06:17:25 -030016#include <linux/fwnode.h>
Sakari Ailus0149a2e2013-12-13 08:58:37 -030017#include <linux/kernel.h>
Laurent Pinchart53e269c2009-12-09 08:40:00 -030018#include <linux/list.h>
Laurent Pinchart16513332009-12-09 08:40:01 -030019#include <linux/media.h>
Laurent Pinchart53e269c2009-12-09 08:40:00 -030020
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -030021/* Enums used internally at the media controller to represent graphs */
22
23/**
24 * enum media_gobj_type - type of a graph object
25 *
Mauro Carvalho Chehabbfab2aac2015-08-14 12:47:48 -030026 * @MEDIA_GRAPH_ENTITY: Identify a media entity
Mauro Carvalho Chehab18710dc2015-08-14 12:50:08 -030027 * @MEDIA_GRAPH_PAD: Identify a media pad
Mauro Carvalho Chehab6b6a4272015-08-14 12:54:36 -030028 * @MEDIA_GRAPH_LINK: Identify a media link
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -030029 * @MEDIA_GRAPH_INTF_DEVNODE: Identify a media Kernel API interface via
30 * a device node
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -030031 */
32enum media_gobj_type {
Mauro Carvalho Chehabbfab2aac2015-08-14 12:47:48 -030033 MEDIA_GRAPH_ENTITY,
Mauro Carvalho Chehab18710dc2015-08-14 12:50:08 -030034 MEDIA_GRAPH_PAD,
Mauro Carvalho Chehab6b6a4272015-08-14 12:54:36 -030035 MEDIA_GRAPH_LINK,
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -030036 MEDIA_GRAPH_INTF_DEVNODE,
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -030037};
38
39#define MEDIA_BITS_PER_TYPE 8
Mauro Carvalho Chehab05b3b772015-12-16 14:28:01 -020040#define MEDIA_BITS_PER_ID (32 - MEDIA_BITS_PER_TYPE)
41#define MEDIA_ID_MASK GENMASK_ULL(MEDIA_BITS_PER_ID - 1, 0)
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -030042
43/* Structs to represent the objects that belong to a media graph */
44
45/**
46 * struct media_gobj - Define a graph object.
47 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -030048 * @mdev: Pointer to the struct &media_device that owns the object
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -030049 * @id: Non-zero object ID identifier. The ID should be unique
50 * inside a media_device, as it is composed by
Mauro Carvalho Chehab05b3b772015-12-16 14:28:01 -020051 * %MEDIA_BITS_PER_TYPE to store the type plus
52 * %MEDIA_BITS_PER_ID to store the ID
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -030053 * @list: List entry stored in one of the per-type mdev object lists
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -030054 *
55 * All objects on the media graph should have this struct embedded
56 */
57struct media_gobj {
Mauro Carvalho Chehab39a956c2015-08-13 14:42:42 -030058 struct media_device *mdev;
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -030059 u32 id;
Mauro Carvalho Chehab05bfa9f2015-08-23 07:51:33 -030060 struct list_head list;
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -030061};
62
Sakari Ailusc8d54cd2015-12-16 11:44:32 -020063#define MEDIA_ENTITY_ENUM_MAX_DEPTH 16
Sakari Ailusc8d54cd2015-12-16 11:44:32 -020064
Sakari Ailusc8d54cd2015-12-16 11:44:32 -020065/**
66 * struct media_entity_enum - An enumeration of media entities.
67 *
Sakari Ailusc8d54cd2015-12-16 11:44:32 -020068 * @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 {
Sakari Ailusc8d54cd2015-12-16 11:44:32 -020073 unsigned long *bmap;
74 int idx_max;
75};
76
Sakari Ailus434257f2015-12-16 11:32:20 -020077/**
Sakari Ailus20b85222016-11-21 14:48:30 -020078 * struct media_graph - Media graph traversal state
Sakari Ailus434257f2015-12-16 11:32:20 -020079 *
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.
Mauro Carvalho Chehabbd945e42017-09-27 15:54:43 -040083 * @stack.entity: pointer to &struct media_entity at the graph.
84 * @stack.link: pointer to &struct list_head.
Sakari Ailus29d8da02015-12-16 11:32:28 -020085 * @ent_enum: Visited entities
Sakari Ailus434257f2015-12-16 11:32:20 -020086 * @top: The top of the stack
87 */
Sakari Ailus20b85222016-11-21 14:48:30 -020088struct media_graph {
Sakari Ailus82c68292015-12-16 11:32:19 -020089 struct {
90 struct media_entity *entity;
91 struct list_head *link;
92 } stack[MEDIA_ENTITY_ENUM_MAX_DEPTH];
93
Sakari Ailus29d8da02015-12-16 11:32:28 -020094 struct media_entity_enum ent_enum;
Sakari Ailus82c68292015-12-16 11:32:19 -020095 int top;
96};
97
Mauro Carvalho Chehab74604b72016-07-17 09:18:03 -030098/**
Sakari Ailus5dd87752015-12-16 11:32:21 -020099 * struct media_pipeline - Media pipeline related information
100 *
Sakari Ailus74a413302015-12-16 11:32:29 -0200101 * @streaming_count: Streaming start count - streaming stop count
102 * @graph: Media graph walk during pipeline start / stop
Sakari Ailus5dd87752015-12-16 11:32:21 -0200103 */
Laurent Pincharte02188c2010-08-25 09:00:41 -0300104struct media_pipeline {
Sakari Ailus74a413302015-12-16 11:32:29 -0200105 int streaming_count;
Sakari Ailus20b85222016-11-21 14:48:30 -0200106 struct media_graph graph;
Laurent Pincharte02188c2010-08-25 09:00:41 -0300107};
108
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300109/**
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.
Mauro Carvalho Chehabe383ce02016-09-22 07:59:03 -0300123 * @sink: Part of a union. Used only if the second object (gobj1) is
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300124 * 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_*)
Mauro Carvalho Chehab39d1ebc62015-08-30 09:53:57 -0300130 * @is_backlink: Indicate if the link is a backlink.
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300131 */
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300132struct media_link {
Mauro Carvalho Chehab6b6a4272015-08-14 12:54:36 -0300133 struct media_gobj graph_obj;
Mauro Carvalho Chehab57208e52015-08-07 06:55:40 -0300134 struct list_head list;
Mauro Carvalho Chehab4b8a3c02015-08-20 09:10:07 -0300135 union {
136 struct media_gobj *gobj0;
137 struct media_pad *source;
Mauro Carvalho Chehab86e26622015-08-07 10:36:25 -0300138 struct media_interface *intf;
Mauro Carvalho Chehab4b8a3c02015-08-20 09:10:07 -0300139 };
140 union {
141 struct media_gobj *gobj1;
142 struct media_pad *sink;
Mauro Carvalho Chehab86e26622015-08-07 10:36:25 -0300143 struct media_entity *entity;
Mauro Carvalho Chehab4b8a3c02015-08-20 09:10:07 -0300144 };
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300145 struct media_link *reverse;
146 unsigned long flags;
Mauro Carvalho Chehab39d1ebc62015-08-30 09:53:57 -0300147 bool is_backlink;
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300148};
149
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300150/**
Mauro Carvalho Chehabc1a37dd2018-07-31 08:03:48 -0400151 * 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/**
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300179 * 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
Mauro Carvalho Chehabc1a37dd2018-07-31 08:03:48 -0400184 * @sig_type: Type of the signal inside a media pad
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300185 * @flags: Pad flags, as defined in
186 * :ref:`include/uapi/linux/media.h <media_header>`
187 * (seek for ``MEDIA_PAD_FL_*``)
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300188 */
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300189struct media_pad {
Mauro Carvalho Chehab4b8a3c02015-08-20 09:10:07 -0300190 struct media_gobj graph_obj; /* must be first field in struct */
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300191 struct media_entity *entity;
192 u16 index;
Mauro Carvalho Chehabc1a37dd2018-07-31 08:03:48 -0400193 enum media_pad_signal_type sig_type;
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300194 unsigned long flags;
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300195};
196
Laurent Pinchart5a5394b2014-03-26 00:01:44 -0300197/**
198 * struct media_entity_operations - Media entity operations
Niklas Söderlundae45cd52017-06-15 06:17:25 -0300199 * @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.
Laurent Pinchart5a5394b2014-03-26 00:01:44 -0300202 * @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
Sakari Ailus20b85222016-11-21 14:48:30 -0200206 * view. The media_pipeline_start() function
Laurent Pinchart5a5394b2014-03-26 00:01:44 -0300207 * validates all links by calling this operation. Optional.
Mauro Carvalho Chehab5ed470f2016-04-06 10:55:25 -0300208 *
Mauro Carvalho Chehab5b8700e2016-07-20 09:22:38 -0300209 * .. note::
210 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300211 * Those these callbacks are called with struct &media_device.graph_mutex
Mauro Carvalho Chehab5b8700e2016-07-20 09:22:38 -0300212 * mutex held.
Laurent Pinchart5a5394b2014-03-26 00:01:44 -0300213 */
Laurent Pinchart97548ed2009-12-09 08:40:03 -0300214struct media_entity_operations {
Niklas Söderlundae45cd52017-06-15 06:17:25 -0300215 int (*get_fwnode_pad)(struct fwnode_endpoint *endpoint);
Laurent Pinchart97548ed2009-12-09 08:40:03 -0300216 int (*link_setup)(struct media_entity *entity,
217 const struct media_pad *local,
218 const struct media_pad *remote, u32 flags);
Sakari Ailusaf88be32012-01-11 06:25:15 -0300219 int (*link_validate)(struct media_link *link);
Laurent Pinchart97548ed2009-12-09 08:40:03 -0300220};
221
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300222/**
Laurent Pinchartb76a2a82016-02-29 08:45:44 -0300223 * 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
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300240 * %MEDIA_ENTITY_TYPE_V4L2_SUBDEV and can safely be cast to a &v4l2_subdev
Laurent Pinchartb76a2a82016-02-29 08:45:44 -0300241 * structure using the container_of() macro.
242 */
243enum media_entity_type {
244 MEDIA_ENTITY_TYPE_BASE,
245 MEDIA_ENTITY_TYPE_VIDEO_DEVICE,
246 MEDIA_ENTITY_TYPE_V4L2_SUBDEV,
247};
248
249/**
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300250 * struct media_entity - A media entity graph object.
251 *
252 * @graph_obj: Embedded structure containing the media object common data.
253 * @name: Entity name.
Laurent Pinchartb76a2a82016-02-29 08:45:44 -0300254 * @obj_type: Type of the object that implements the media_entity.
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300255 * @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_*``)
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300261 * @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
Sakari Ailus665faa92015-12-16 11:32:17 -0200264 * @internal_idx: An unique internal entity specific number. The numbers are
265 * re-used if entities are unregistered or registered again.
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300266 * @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.
Mauro Carvalho Chehabbd945e42017-09-27 15:54:43 -0400274 * @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.
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300277 * @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 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300282 * .. 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.
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300288 */
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300289struct media_entity {
Mauro Carvalho Chehab4b8a3c02015-08-20 09:10:07 -0300290 struct media_gobj graph_obj; /* must be first field in struct */
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300291 const char *name;
Laurent Pinchartb76a2a82016-02-29 08:45:44 -0300292 enum media_entity_type obj_type;
Mauro Carvalho Chehab0e576b72015-09-06 09:33:39 -0300293 u32 function;
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300294 unsigned long flags;
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300295
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300296 u16 num_pads;
297 u16 num_links;
298 u16 num_backlinks;
Sakari Ailus665faa92015-12-16 11:32:17 -0200299 int internal_idx;
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300300
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300301 struct media_pad *pads;
302 struct list_head links;
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300303
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300304 const struct media_entity_operations *ops;
Laurent Pinchart97548ed2009-12-09 08:40:03 -0300305
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300306 int stream_count;
307 int use_count;
Laurent Pinchart503c3d822010-03-07 15:04:59 -0300308
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300309 struct media_pipeline *pipe;
Laurent Pincharte02188c2010-08-25 09:00:41 -0300310
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300311 union {
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300312 struct {
313 u32 major;
314 u32 minor;
Mauro Carvalho Chehabe31a0ba2015-01-02 12:18:23 -0300315 } dev;
Clemens Ladischfa5034c2011-11-05 18:42:01 -0300316 } info;
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300317};
318
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -0300319/**
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300320 * struct media_interface - A media interface graph object.
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -0300321 *
322 * @graph_obj: embedded graph object
Mauro Carvalho Chehab86e26622015-08-07 10:36:25 -0300323 * @links: List of links pointing to graph entities
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300324 * @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.
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -0300334 */
335struct media_interface {
336 struct media_gobj graph_obj;
Mauro Carvalho Chehab86e26622015-08-07 10:36:25 -0300337 struct list_head links;
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -0300338 u32 type;
339 u32 flags;
340};
341
342/**
Mauro Carvalho Chehabc358e802015-08-29 23:43:03 -0300343 * struct media_intf_devnode - A media interface via a device node.
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -0300344 *
345 * @intf: embedded interface object
346 * @major: Major number of a device node
347 * @minor: Minor number of a device node
348 */
349struct media_intf_devnode {
350 struct media_interface intf;
Mauro Carvalho Chehabc398bb62015-08-23 08:28:21 -0300351
352 /* Should match the fields at media_v2_intf_devnode */
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -0300353 u32 major;
354 u32 minor;
355};
356
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -0200357/**
358 * media_entity_id() - return the media entity graph object id
359 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300360 * @entity: pointer to &media_entity
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -0200361 */
Mauro Carvalho Chehabfa762392015-08-14 10:42:05 -0300362static inline u32 media_entity_id(struct media_entity *entity)
363{
Mauro Carvalho Chehabbfab2aac2015-08-14 12:47:48 -0300364 return entity->graph_obj.id;
Mauro Carvalho Chehabfa762392015-08-14 10:42:05 -0300365}
366
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -0200367/**
368 * media_type() - return the media object type
369 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300370 * @gobj: Pointer to the struct &media_gobj graph object
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -0200371 */
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -0300372static inline enum media_gobj_type media_type(struct media_gobj *gobj)
373{
Mauro Carvalho Chehab05b3b772015-12-16 14:28:01 -0200374 return gobj->id >> MEDIA_BITS_PER_ID;
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -0300375}
376
Mauro Carvalho Chehab630c0e82015-12-16 15:15:18 -0200377/**
378 * media_id() - return the media object ID
379 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300380 * @gobj: Pointer to the struct &media_gobj graph object
Mauro Carvalho Chehab630c0e82015-12-16 15:15:18 -0200381 */
Mauro Carvalho Chehab05b3b772015-12-16 14:28:01 -0200382static inline u32 media_id(struct media_gobj *gobj)
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -0300383{
Mauro Carvalho Chehab05b3b772015-12-16 14:28:01 -0200384 return gobj->id & MEDIA_ID_MASK;
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -0300385}
386
Mauro Carvalho Chehab630c0e82015-12-16 15:15:18 -0200387/**
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.
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300391 * @local_id: next ID, from struct &media_device.id.
Mauro Carvalho Chehab630c0e82015-12-16 15:15:18 -0200392 */
Mauro Carvalho Chehab05b3b772015-12-16 14:28:01 -0200393static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id)
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -0300394{
395 u32 id;
396
Mauro Carvalho Chehab05b3b772015-12-16 14:28:01 -0200397 id = type << MEDIA_BITS_PER_ID;
398 id |= local_id & MEDIA_ID_MASK;
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -0300399
400 return id;
401}
402
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -0200403/**
Laurent Pinchart45b46872016-02-29 08:45:45 -0300404 * is_media_entity_v4l2_video_device() - Check if the entity is a video_device
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -0200405 * @entity: pointer to entity
406 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300407 * Return: %true if the entity is an instance of a video_device object and can
Laurent Pinchartb76a2a82016-02-29 08:45:44 -0300408 * safely be cast to a struct video_device using the container_of() macro, or
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300409 * %false otherwise.
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -0200410 */
Laurent Pinchart45b46872016-02-29 08:45:45 -0300411static inline bool is_media_entity_v4l2_video_device(struct media_entity *entity)
Mauro Carvalho Chehabfa17b462015-08-21 12:17:40 -0300412{
Laurent Pinchartb76a2a82016-02-29 08:45:44 -0300413 return entity && entity->obj_type == MEDIA_ENTITY_TYPE_VIDEO_DEVICE;
Mauro Carvalho Chehabfa17b462015-08-21 12:17:40 -0300414}
415
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -0200416/**
Laurent Pinchartb76a2a82016-02-29 08:45:44 -0300417 * is_media_entity_v4l2_subdev() - Check if the entity is a v4l2_subdev
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -0200418 * @entity: pointer to entity
419 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300420 * 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.
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -0200423 */
Mauro Carvalho Chehabfa17b462015-08-21 12:17:40 -0300424static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity)
425{
Laurent Pinchartb76a2a82016-02-29 08:45:44 -0300426 return entity && entity->obj_type == MEDIA_ENTITY_TYPE_V4L2_SUBDEV;
Mauro Carvalho Chehabfa17b462015-08-21 12:17:40 -0300427}
428
Mauro Carvalho Chehab92777992015-12-16 13:53:04 -0200429/**
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 */
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200437__must_check int __media_entity_enum_init(struct media_entity_enum *ent_enum,
438 int idx_max);
Mauro Carvalho Chehab92777992015-12-16 13:53:04 -0200439
440/**
441 * media_entity_enum_cleanup - Release resources of an entity enumeration
442 *
443 * @ent_enum: Entity enumeration to be released
444 */
445void media_entity_enum_cleanup(struct media_entity_enum *ent_enum);
Sakari Ailusa5ccc482010-03-07 16:14:14 -0300446
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200447/**
448 * media_entity_enum_zero - Clear the entire enum
449 *
Mauro Carvalho Chehab03e49332015-12-16 13:58:31 -0200450 * @ent_enum: Entity enumeration to be cleared
Mauro Carvalho Chehabef69ee12015-10-01 18:07:53 -0300451 */
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200452static inline void media_entity_enum_zero(struct media_entity_enum *ent_enum)
453{
454 bitmap_zero(ent_enum->bmap, ent_enum->idx_max);
455}
456
457/**
458 * media_entity_enum_set - Mark a single entity in the enum
459 *
Mauro Carvalho Chehab03e49332015-12-16 13:58:31 -0200460 * @ent_enum: Entity enumeration
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200461 * @entity: Entity to be marked
462 */
463static inline void media_entity_enum_set(struct media_entity_enum *ent_enum,
464 struct media_entity *entity)
465{
466 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))
467 return;
468
469 __set_bit(entity->internal_idx, ent_enum->bmap);
470}
471
472/**
473 * media_entity_enum_clear - Unmark a single entity in the enum
474 *
Mauro Carvalho Chehab03e49332015-12-16 13:58:31 -0200475 * @ent_enum: Entity enumeration
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200476 * @entity: Entity to be unmarked
477 */
478static 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 *
Mauro Carvalho Chehab03e49332015-12-16 13:58:31 -0200490 * @ent_enum: Entity enumeration
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200491 * @entity: Entity to be tested
492 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300493 * Returns %true if the entity was marked.
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200494 */
495static 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/**
Mauro Carvalho Chehabe383ce02016-09-22 07:59:03 -0300505 * media_entity_enum_test_and_set - Test whether the entity is marked,
506 * and mark it
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200507 *
Mauro Carvalho Chehab03e49332015-12-16 13:58:31 -0200508 * @ent_enum: Entity enumeration
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200509 * @entity: Entity to be tested
510 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300511 * Returns %true if the entity was marked, and mark it before doing so.
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200512 */
Mauro Carvalho Chehab03e49332015-12-16 13:58:31 -0200513static inline bool
514media_entity_enum_test_and_set(struct media_entity_enum *ent_enum,
515 struct media_entity *entity)
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200516{
517 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))
518 return true;
519
520 return __test_and_set_bit(entity->internal_idx, ent_enum->bmap);
521}
522
523/**
Mauro Carvalho Chehab03e49332015-12-16 13:58:31 -0200524 * media_entity_enum_empty - Test whether the entire enum is empty
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200525 *
Mauro Carvalho Chehab03e49332015-12-16 13:58:31 -0200526 * @ent_enum: Entity enumeration
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200527 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300528 * Return: %true if the entity was empty.
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200529 */
530static 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 *
Mauro Carvalho Chehab03e49332015-12-16 13:58:31 -0200538 * @ent_enum1: First entity enumeration
539 * @ent_enum2: Second entity enumeration
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200540 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300541 * Return: %true if entity enumerations @ent_enum1 and @ent_enum2 intersect,
542 * otherwise %false.
Sakari Ailusc8d54cd2015-12-16 11:44:32 -0200543 */
544static 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}
Mauro Carvalho Chehabef69ee12015-10-01 18:07:53 -0300553
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300554/**
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 */
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -0300560#define gobj_to_entity(gobj) \
561 container_of(gobj, struct media_entity, graph_obj)
562
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300563/**
Mauro Carvalho Chehabe383ce02016-09-22 07:59:03 -0300564 * gobj_to_pad - returns the struct &media_pad pointer from the
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300565 * @gobj contained on it.
566 *
567 * @gobj: Pointer to the struct &media_gobj graph object
568 */
Mauro Carvalho Chehab39a956c2015-08-13 14:42:42 -0300569#define gobj_to_pad(gobj) \
570 container_of(gobj, struct media_pad, graph_obj)
571
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300572/**
Mauro Carvalho Chehabe383ce02016-09-22 07:59:03 -0300573 * gobj_to_link - returns the struct &media_link pointer from the
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300574 * @gobj contained on it.
575 *
576 * @gobj: Pointer to the struct &media_gobj graph object
577 */
Mauro Carvalho Chehab39a956c2015-08-13 14:42:42 -0300578#define gobj_to_link(gobj) \
579 container_of(gobj, struct media_link, graph_obj)
580
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300581/**
Mauro Carvalho Chehabe383ce02016-09-22 07:59:03 -0300582 * gobj_to_intf - returns the struct &media_interface pointer from the
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300583 * @gobj contained on it.
584 *
585 * @gobj: Pointer to the struct &media_gobj graph object
586 */
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -0300587#define gobj_to_intf(gobj) \
588 container_of(gobj, struct media_interface, graph_obj)
589
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300590/**
Mauro Carvalho Chehabe383ce02016-09-22 07:59:03 -0300591 * intf_to_devnode - returns the struct media_intf_devnode pointer from the
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300592 * @intf contained on it.
593 *
594 * @intf: Pointer to struct &media_intf_devnode
595 */
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -0300596#define intf_to_devnode(intf) \
597 container_of(intf, struct media_intf_devnode, intf)
598
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200599/**
600 * media_gobj_create - Initialize a graph object
601 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300602 * @mdev: Pointer to the &media_device that contains the object
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200603 * @type: Type of the object
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300604 * @gobj: Pointer to the struct &media_gobj graph object
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200605 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300606 * 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.
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200611 */
Mauro Carvalho Chehabc350ef82015-12-11 11:55:40 -0200612void media_gobj_create(struct media_device *mdev,
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -0300613 enum media_gobj_type type,
614 struct media_gobj *gobj);
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200615
616/**
617 * media_gobj_destroy - Stop using a graph object on a media device
618 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300619 * @gobj: Pointer to the struct &media_gobj graph object
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200620 *
621 * This should be called by all routines like media_device_unregister()
622 * that remove/destroy media graph objects.
623 */
Mauro Carvalho Chehabc350ef82015-12-11 11:55:40 -0200624void media_gobj_destroy(struct media_gobj *gobj);
Mauro Carvalho Chehabec6e4c92015-08-25 10:28:36 -0300625
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200626/**
627 * media_entity_pads_init() - Initialize the entity pads
628 *
629 * @entity: entity where the pads belong
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200630 * @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
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300634 * media_entity_pads_init() where its pointer will be stored in the
635 * &media_entity structure.
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200636 *
637 * If no pads are needed, drivers could either directly fill
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300638 * &media_entity->num_pads with 0 and &media_entity->pads with %NULL or call
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200639 * 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 */
Mauro Carvalho Chehabab22e772015-12-11 07:44:40 -0200648int media_entity_pads_init(struct media_entity *entity, u16 num_pads,
Mauro Carvalho Chehab57208e52015-08-07 06:55:40 -0300649 struct media_pad *pads);
Mauro Carvalho Chehabf1fd3282015-12-11 09:13:23 -0200650
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200651/**
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 */
Sakari Ailus35801122018-01-09 05:20:34 -0500659#if IS_ENABLED(CONFIG_MEDIA_CONTROLLER)
660static inline void media_entity_cleanup(struct media_entity *entity) {}
661#else
662#define media_entity_cleanup(entity) do { } while (false)
663#endif
Laurent Pincharte02188c2010-08-25 09:00:41 -0300664
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200665/**
Mauro Carvalho Chehab9d6d20e2018-07-31 09:22:40 -0400666 * 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 */
680int media_get_pad_index(struct media_entity *entity, bool is_sink,
681 enum media_pad_signal_type sig_type);
682
683/**
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200684 * 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.
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300690 * @flags: Link flags, as defined in
691 * :ref:`include/uapi/linux/media.h <media_header>`
692 * ( seek for ``MEDIA_LNK_FL_*``)
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200693 *
694 * Valid values for flags:
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200695 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300696 * %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.
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200700 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300701 * %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.
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200705 *
Mauro Carvalho Chehab74604b72016-07-17 09:18:03 -0300706 * .. note::
707 *
708 * Before calling this function, media_entity_pads_init() and
709 * media_device_register_entity() should be called previously for both ends.
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200710 */
Mauro Carvalho Chehab77328042015-09-04 16:08:24 -0300711__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);
Mauro Carvalho Chehabb01cc9c2015-12-30 09:45:48 -0200714
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
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300722 * all entities that matches the @sink_function.
Mauro Carvalho Chehabb01cc9c2015-12-30 09:45:48 -0200723 * @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
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300726 * all entities that matches the @sink_function.
Mauro Carvalho Chehabb01cc9c2015-12-30 09:45:48 -0200727 * @sink_pad: number of the sink pad in the pads array.
728 * @flags: Link flags, as defined in include/uapi/linux/media.h.
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300729 * @allow_both_undefined: if %true, then both @source and @sink can be NULL.
Mauro Carvalho Chehabb01cc9c2015-12-30 09:45:48 -0200730 * In such case, it will create a crossbar between all entities that
731 * matches @source_function to all entities that matches @sink_function.
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300732 * If %false, it will return 0 and won't create any link if both @source
Mauro Carvalho Chehabb01cc9c2015-12-30 09:45:48 -0200733 * and @sink are NULL.
734 *
735 * Valid values for flags:
Mauro Carvalho Chehab74604b72016-07-17 09:18:03 -0300736 *
Mauro Carvalho Chehabb01cc9c2015-12-30 09:45:48 -0200737 * 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 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300752 * .. 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.
Mauro Carvalho Chehabb01cc9c2015-12-30 09:45:48 -0200757 */
758int 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
Sylwester Nawrocki7349cec2013-05-09 08:29:32 -0300768void __media_entity_remove_links(struct media_entity *entity);
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200769
770/**
771 * media_entity_remove_links() - remove all links associated with an entity
772 *
773 * @entity: pointer to &media_entity
774 *
Mauro Carvalho Chehab74604b72016-07-17 09:18:03 -0300775 * .. note::
776 *
777 * This is called automatically when an entity is unregistered via
778 * media_device_register_entity().
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200779 */
Sylwester Nawrocki7349cec2013-05-09 08:29:32 -0300780void media_entity_remove_links(struct media_entity *entity);
781
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200782/**
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 */
Laurent Pinchart97548ed2009-12-09 08:40:03 -0300796int __media_entity_setup_link(struct media_link *link, u32 flags);
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200797
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
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300815 * &media_device.link_notify pointer to a callback function. If provided, the
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200816 * 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
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300825 * being enabled, the link_setup operation must return %-EBUSY and can't
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200826 * implicitly disable the first enabled link.
827 *
Mauro Carvalho Chehab74604b72016-07-17 09:18:03 -0300828 * .. 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.
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200833 */
Laurent Pinchart97548ed2009-12-09 08:40:03 -0300834int media_entity_setup_link(struct media_link *link, u32 flags);
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200835
836/**
837 * media_entity_find_link - Find a link between two pads
838 * @source: Source pad
839 * @sink: Sink pad
840 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300841 * Return: returns a pointer to the link between the two entities. If no
842 * such link exists, return %NULL.
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200843 */
Laurent Pinchart97548ed2009-12-09 08:40:03 -0300844struct media_link *media_entity_find_link(struct media_pad *source,
845 struct media_pad *sink);
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200846
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 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300854 * 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.
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200856 */
Todor Tomov6538b022017-07-03 08:08:11 -0400857struct media_pad *media_entity_remote_pad(const struct media_pad *pad);
Laurent Pinchart53e269c2009-12-09 08:40:00 -0300858
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200859/**
Niklas Söderlundd295c6a2017-06-15 06:17:26 -0300860 * 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 *
Niklas Söderlundf0a3fa22018-04-08 12:11:52 -0400872 * If the entity does not implement the get_fwnode_pad() operation
Niklas Söderlundd295c6a2017-06-15 06:17:26 -0300873 * 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 */
878int media_entity_get_fwnode_pad(struct media_entity *entity,
879 struct fwnode_handle *fwnode,
880 unsigned long direction_flags);
881
882/**
Sakari Ailus20b85222016-11-21 14:48:30 -0200883 * media_graph_walk_init - Allocate resources used by graph walk.
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300884 *
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 */
Sakari Ailus20b85222016-11-21 14:48:30 -0200888__must_check int media_graph_walk_init(
889 struct media_graph *graph, struct media_device *mdev);
Mauro Carvalho Chehabaa360d32015-12-16 13:56:14 -0200890
891/**
Sakari Ailus20b85222016-11-21 14:48:30 -0200892 * media_graph_walk_cleanup - Release resources used by graph walk.
Mauro Carvalho Chehabaa360d32015-12-16 13:56:14 -0200893 *
894 * @graph: Media graph structure that will be used to walk the graph
895 */
Sakari Ailus20b85222016-11-21 14:48:30 -0200896void media_graph_walk_cleanup(struct media_graph *graph);
Sakari Ailuse03d2202015-12-16 11:32:22 -0200897
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200898/**
Sakari Ailus20b85222016-11-21 14:48:30 -0200899 * media_graph_walk_start - Start walking the media graph at a
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300900 * given entity
901 *
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200902 * @graph: Media graph structure that will be used to walk the graph
903 * @entity: Starting entity
904 *
Sakari Ailus20b85222016-11-21 14:48:30 -0200905 * Before using this function, media_graph_walk_init() must be
Sakari Ailuse03d2202015-12-16 11:32:22 -0200906 * 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
Sakari Ailus20b85222016-11-21 14:48:30 -0200911 * using media_graph_walk_cleanup().
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200912 */
Sakari Ailus20b85222016-11-21 14:48:30 -0200913void media_graph_walk_start(struct media_graph *graph,
914 struct media_entity *entity);
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200915
916/**
Sakari Ailus20b85222016-11-21 14:48:30 -0200917 * media_graph_walk_next - Get the next entity in the graph
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200918 * @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
Sakari Ailus20b85222016-11-21 14:48:30 -0200923 * media_graph_walk_start().
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200924 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300925 * Return: returns the next entity in the graph or %NULL if the whole graph
926 * have been traversed.
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200927 */
Sakari Ailus20b85222016-11-21 14:48:30 -0200928struct media_entity *media_graph_walk_next(struct media_graph *graph);
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200929
930/**
Sakari Ailus20b85222016-11-21 14:48:30 -0200931 * media_pipeline_start - Mark a pipeline as streaming
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200932 * @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
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300936 * 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.
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200938 *
939 * Calls to this function can be nested, in which case the same number of
Sakari Ailus20b85222016-11-21 14:48:30 -0200940 * media_pipeline_stop() calls will be required to stop streaming. The
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200941 * pipeline pointer must be identical for all nested calls to
Sakari Ailus20b85222016-11-21 14:48:30 -0200942 * media_pipeline_start().
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200943 */
Sakari Ailus20b85222016-11-21 14:48:30 -0200944__must_check int media_pipeline_start(struct media_entity *entity,
945 struct media_pipeline *pipe);
Shuah Khanfb49f202016-02-11 21:41:24 -0200946/**
Sakari Ailus20b85222016-11-21 14:48:30 -0200947 * __media_pipeline_start - Mark a pipeline as streaming
Shuah Khanfb49f202016-02-11 21:41:24 -0200948 *
949 * @entity: Starting entity
950 * @pipe: Media pipeline to be assigned to all entities in the pipeline.
951 *
Sakari Ailus20b85222016-11-21 14:48:30 -0200952 * ..note:: This is the non-locking version of media_pipeline_start()
Shuah Khanfb49f202016-02-11 21:41:24 -0200953 */
Sakari Ailus20b85222016-11-21 14:48:30 -0200954__must_check int __media_pipeline_start(struct media_entity *entity,
955 struct media_pipeline *pipe);
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200956
957/**
Sakari Ailus20b85222016-11-21 14:48:30 -0200958 * media_pipeline_stop - Mark a pipeline as not streaming
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200959 * @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
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300963 * reset to %NULL.
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200964 *
Sakari Ailus20b85222016-11-21 14:48:30 -0200965 * If multiple calls to media_pipeline_start() have been made, the same
Mauro Carvalho Chehab1fc25d32015-12-11 12:14:58 -0200966 * number of calls to this function are required to mark the pipeline as not
967 * streaming.
968 */
Sakari Ailus20b85222016-11-21 14:48:30 -0200969void media_pipeline_stop(struct media_entity *entity);
Sakari Ailusa5ccc482010-03-07 16:14:14 -0300970
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200971/**
Sakari Ailus20b85222016-11-21 14:48:30 -0200972 * __media_pipeline_stop - Mark a pipeline as not streaming
Shuah Khanfb49f202016-02-11 21:41:24 -0200973 *
974 * @entity: Starting entity
975 *
Sakari Ailus20b85222016-11-21 14:48:30 -0200976 * .. note:: This is the non-locking version of media_pipeline_stop()
Shuah Khanfb49f202016-02-11 21:41:24 -0200977 */
Sakari Ailus20b85222016-11-21 14:48:30 -0200978void __media_pipeline_stop(struct media_entity *entity);
Shuah Khanfb49f202016-02-11 21:41:24 -0200979
980/**
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200981 * media_devnode_create() - creates and initializes a device node interface
982 *
983 * @mdev: pointer to struct &media_device
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300984 * @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_*``)
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200990 * @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.
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -0300995 *
996 * .. note::
997 *
998 * Currently, no flags for &media_interface is defined.
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -0200999 */
Mauro Carvalho Chehab5e5387d2015-09-04 15:34:19 -03001000struct media_intf_devnode *
1001__must_check media_devnode_create(struct media_device *mdev,
1002 u32 type, u32 flags,
Mauro Carvalho Chehab0b3b72df92015-09-09 08:19:25 -03001003 u32 major, u32 minor);
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -02001004/**
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 */
Mauro Carvalho Chehab27e543f2015-08-20 09:07:34 -03001012void media_devnode_remove(struct media_intf_devnode *devnode);
Mauro Carvalho Chehab5e5387d2015-09-04 15:34:19 -03001013struct media_link *
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -02001014
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
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -03001020 * @flags: Link flags, as defined in
1021 * :ref:`include/uapi/linux/media.h <media_header>`
1022 * ( seek for ``MEDIA_LNK_FL_*``)
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -02001023 *
1024 *
1025 * Valid values for flags:
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -02001026 *
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -03001027 * %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 *
Mauro Carvalho Chehab74604b72016-07-17 09:18:03 -03001033 * 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.
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -02001037 *
Mauro Carvalho Chehab74604b72016-07-17 09:18:03 -03001038 * .. 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.
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -02001043 */
Mauro Carvalho Chehab5e5387d2015-09-04 15:34:19 -03001044__must_check media_create_intf_link(struct media_entity *entity,
1045 struct media_interface *intf,
1046 u32 flags);
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -02001047/**
1048 * __media_remove_intf_link() - remove a single interface link
1049 *
1050 * @link: pointer to &media_link.
1051 *
Mauro Carvalho Chehab74604b72016-07-17 09:18:03 -03001052 * .. note:: This is an unlocked version of media_remove_intf_link()
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -02001053 */
Mauro Carvalho Chehabd47109f2015-08-29 21:23:44 -03001054void __media_remove_intf_link(struct media_link *link);
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -02001055
1056/**
1057 * media_remove_intf_link() - remove a single interface link
1058 *
1059 * @link: pointer to &media_link.
1060 *
Mauro Carvalho Chehab74604b72016-07-17 09:18:03 -03001061 * .. note:: Prefer to use this one, instead of __media_remove_intf_link()
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -02001062 */
Mauro Carvalho Chehab86e26622015-08-07 10:36:25 -03001063void media_remove_intf_link(struct media_link *link);
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -02001064
1065/**
1066 * __media_remove_intf_links() - remove all links associated with an interface
1067 *
1068 * @intf: pointer to &media_interface
1069 *
Mauro Carvalho Chehab74604b72016-07-17 09:18:03 -03001070 * .. note:: This is an unlocked version of media_remove_intf_links().
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -02001071 */
Mauro Carvalho Chehab7c4696a2015-08-24 08:46:46 -03001072void __media_remove_intf_links(struct media_interface *intf);
Mauro Carvalho Chehab92777992015-12-16 13:53:04 -02001073
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -02001074/**
1075 * media_remove_intf_links() - remove all links associated with an interface
1076 *
1077 * @intf: pointer to &media_interface
1078 *
Mauro Carvalho Chehabf58cad22016-07-20 11:15:31 -03001079 * .. note::
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -02001080 *
Mauro Carvalho Chehabf58cad22016-07-20 11:15:31 -03001081 * #) This is called automatically when an entity is unregistered via
1082 * media_device_register_entity() and by media_devnode_remove().
Mauro Carvalho Chehab60266182015-12-13 08:20:46 -02001083 *
Mauro Carvalho Chehabf58cad22016-07-20 11:15:31 -03001084 * #) Prefer to use this one, instead of __media_remove_intf_links().
Mauro Carvalho Chehabdb7ee322015-12-11 11:06:08 -02001085 */
Mauro Carvalho Chehab7c4696a2015-08-24 08:46:46 -03001086void media_remove_intf_links(struct media_interface *intf);
1087
Mauro Carvalho Chehab48a7c4b2016-08-29 16:09:11 -03001088/**
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
Laurent Pinchart97548ed2009-12-09 08:40:03 -03001100#define media_entity_call(entity, operation, args...) \
1101 (((entity)->ops && (entity)->ops->operation) ? \
1102 (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)
1103
Laurent Pinchart53e269c2009-12-09 08:40:00 -03001104#endif