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 #include <linux/bitmap.h>
24 #include <linux/module.h>
25 #include <linux/slab.h>
26 #include <media/media-entity.h>
27 #include <media/media-device.h>
30 * media_entity_init - Initialize a media entity
32 * @num_pads: Total number of sink and source pads.
33 * @extra_links: Initial estimate of the number of extra links.
34 * @pads: Array of 'num_pads' pads.
36 * The total number of pads is an intrinsic property of entities known by the
37 * entity driver, while the total number of links depends on hardware design
38 * and is an extrinsic property unknown to the entity driver. However, in most
39 * use cases the entity driver can guess the number of links which can safely
40 * be assumed to be equal to or larger than the number of pads.
42 * For those reasons the links array can be preallocated based on the entity
43 * driver guess and will be reallocated later if extra links need to be
46 * This function allocates a links array with enough space to hold at least
47 * 'num_pads' + 'extra_links' elements. The media_entity::max_links field will
48 * be set to the number of allocated elements.
50 * The pads array is managed by the entity driver and passed to
51 * media_entity_init() where its pointer will be stored in the entity structure.
54 media_entity_init(struct media_entity
*entity
, u16 num_pads
,
55 struct media_pad
*pads
, u16 extra_links
)
57 struct media_link
*links
;
58 unsigned int max_links
= num_pads
+ extra_links
;
61 links
= kzalloc(max_links
* sizeof(links
[0]), GFP_KERNEL
);
66 entity
->max_links
= max_links
;
67 entity
->num_links
= 0;
68 entity
->num_backlinks
= 0;
69 entity
->num_pads
= num_pads
;
71 entity
->links
= links
;
73 for (i
= 0; i
< num_pads
; i
++) {
74 pads
[i
].entity
= entity
;
80 EXPORT_SYMBOL_GPL(media_entity_init
);
83 media_entity_cleanup(struct media_entity
*entity
)
87 EXPORT_SYMBOL_GPL(media_entity_cleanup
);
89 /* -----------------------------------------------------------------------------
93 static struct media_entity
*
94 media_entity_other(struct media_entity
*entity
, struct media_link
*link
)
96 if (link
->source
->entity
== entity
)
97 return link
->sink
->entity
;
99 return link
->source
->entity
;
102 /* push an entity to traversal stack */
103 static void stack_push(struct media_entity_graph
*graph
,
104 struct media_entity
*entity
)
106 if (graph
->top
== MEDIA_ENTITY_ENUM_MAX_DEPTH
- 1) {
111 graph
->stack
[graph
->top
].link
= 0;
112 graph
->stack
[graph
->top
].entity
= entity
;
115 static struct media_entity
*stack_pop(struct media_entity_graph
*graph
)
117 struct media_entity
*entity
;
119 entity
= graph
->stack
[graph
->top
].entity
;
125 #define link_top(en) ((en)->stack[(en)->top].link)
126 #define stack_top(en) ((en)->stack[(en)->top].entity)
129 * media_entity_graph_walk_start - Start walking the media graph at a given entity
130 * @graph: Media graph structure that will be used to walk the graph
131 * @entity: Starting entity
133 * This function initializes the graph traversal structure to walk the entities
134 * graph starting at the given entity. The traversal structure must not be
135 * modified by the caller during graph traversal. When done the structure can
138 void media_entity_graph_walk_start(struct media_entity_graph
*graph
,
139 struct media_entity
*entity
)
142 graph
->stack
[graph
->top
].entity
= NULL
;
143 bitmap_zero(graph
->entities
, MEDIA_ENTITY_ENUM_MAX_ID
);
145 if (WARN_ON(entity
->id
>= MEDIA_ENTITY_ENUM_MAX_ID
))
148 __set_bit(entity
->id
, graph
->entities
);
149 stack_push(graph
, entity
);
151 EXPORT_SYMBOL_GPL(media_entity_graph_walk_start
);
154 * media_entity_graph_walk_next - Get the next entity in the graph
155 * @graph: Media graph structure
157 * Perform a depth-first traversal of the given media entities graph.
159 * The graph structure must have been previously initialized with a call to
160 * media_entity_graph_walk_start().
162 * Return the next entity in the graph or NULL if the whole graph have been
165 struct media_entity
*
166 media_entity_graph_walk_next(struct media_entity_graph
*graph
)
168 if (stack_top(graph
) == NULL
)
172 * Depth first search. Push entity to stack and continue from
173 * top of the stack until no more entities on the level can be
176 while (link_top(graph
) < stack_top(graph
)->num_links
) {
177 struct media_entity
*entity
= stack_top(graph
);
178 struct media_link
*link
= &entity
->links
[link_top(graph
)];
179 struct media_entity
*next
;
181 /* The link is not enabled so we do not follow. */
182 if (!(link
->flags
& MEDIA_LNK_FL_ENABLED
)) {
187 /* Get the entity in the other end of the link . */
188 next
= media_entity_other(entity
, link
);
189 if (WARN_ON(next
->id
>= MEDIA_ENTITY_ENUM_MAX_ID
))
192 /* Has the entity already been visited? */
193 if (__test_and_set_bit(next
->id
, graph
->entities
)) {
198 /* Push the new entity to stack and start over. */
200 stack_push(graph
, next
);
203 return stack_pop(graph
);
205 EXPORT_SYMBOL_GPL(media_entity_graph_walk_next
);
207 /* -----------------------------------------------------------------------------
208 * Pipeline management
212 * media_entity_pipeline_start - Mark a pipeline as streaming
213 * @entity: Starting entity
214 * @pipe: Media pipeline to be assigned to all entities in the pipeline.
216 * Mark all entities connected to a given entity through enabled links, either
217 * directly or indirectly, as streaming. The given pipeline object is assigned to
218 * every entity in the pipeline and stored in the media_entity pipe field.
220 * Calls to this function can be nested, in which case the same number of
221 * media_entity_pipeline_stop() calls will be required to stop streaming. The
222 * pipeline pointer must be identical for all nested calls to
223 * media_entity_pipeline_start().
225 __must_check
int media_entity_pipeline_start(struct media_entity
*entity
,
226 struct media_pipeline
*pipe
)
228 struct media_device
*mdev
= entity
->parent
;
229 struct media_entity_graph graph
;
230 struct media_entity
*entity_err
= entity
;
233 mutex_lock(&mdev
->graph_mutex
);
235 media_entity_graph_walk_start(&graph
, entity
);
237 while ((entity
= media_entity_graph_walk_next(&graph
))) {
238 DECLARE_BITMAP(active
, entity
->num_pads
);
239 DECLARE_BITMAP(has_no_links
, entity
->num_pads
);
242 entity
->stream_count
++;
243 WARN_ON(entity
->pipe
&& entity
->pipe
!= pipe
);
246 /* Already streaming --- no need to check. */
247 if (entity
->stream_count
> 1)
250 if (!entity
->ops
|| !entity
->ops
->link_validate
)
253 bitmap_zero(active
, entity
->num_pads
);
254 bitmap_fill(has_no_links
, entity
->num_pads
);
256 for (i
= 0; i
< entity
->num_links
; i
++) {
257 struct media_link
*link
= &entity
->links
[i
];
258 struct media_pad
*pad
= link
->sink
->entity
== entity
259 ? link
->sink
: link
->source
;
261 /* Mark that a pad is connected by a link. */
262 bitmap_clear(has_no_links
, pad
->index
, 1);
265 * Pads that either do not need to connect or
266 * are connected through an enabled link are
269 if (!(pad
->flags
& MEDIA_PAD_FL_MUST_CONNECT
) ||
270 link
->flags
& MEDIA_LNK_FL_ENABLED
)
271 bitmap_set(active
, pad
->index
, 1);
274 * Link validation will only take place for
275 * sink ends of the link that are enabled.
277 if (link
->sink
!= pad
||
278 !(link
->flags
& MEDIA_LNK_FL_ENABLED
))
281 ret
= entity
->ops
->link_validate(link
);
282 if (ret
< 0 && ret
!= -ENOIOCTLCMD
) {
283 dev_dbg(entity
->parent
->dev
,
284 "link validation failed for \"%s\":%u -> \"%s\":%u, error %d\n",
285 link
->source
->entity
->name
,
287 entity
->name
, link
->sink
->index
, ret
);
292 /* Either no links or validated links are fine. */
293 bitmap_or(active
, active
, has_no_links
, entity
->num_pads
);
295 if (!bitmap_full(active
, entity
->num_pads
)) {
297 dev_dbg(entity
->parent
->dev
,
298 "\"%s\":%u must be connected by an enabled link\n",
300 (unsigned)find_first_zero_bit(
301 active
, entity
->num_pads
));
306 mutex_unlock(&mdev
->graph_mutex
);
312 * Link validation on graph failed. We revert what we did and
315 media_entity_graph_walk_start(&graph
, entity_err
);
317 while ((entity_err
= media_entity_graph_walk_next(&graph
))) {
318 entity_err
->stream_count
--;
319 if (entity_err
->stream_count
== 0)
320 entity_err
->pipe
= NULL
;
323 * We haven't increased stream_count further than this
326 if (entity_err
== entity
)
330 mutex_unlock(&mdev
->graph_mutex
);
334 EXPORT_SYMBOL_GPL(media_entity_pipeline_start
);
337 * media_entity_pipeline_stop - Mark a pipeline as not streaming
338 * @entity: Starting entity
340 * Mark all entities connected to a given entity through enabled links, either
341 * directly or indirectly, as not streaming. The media_entity pipe field is
344 * If multiple calls to media_entity_pipeline_start() have been made, the same
345 * number of calls to this function are required to mark the pipeline as not
348 void media_entity_pipeline_stop(struct media_entity
*entity
)
350 struct media_device
*mdev
= entity
->parent
;
351 struct media_entity_graph graph
;
353 mutex_lock(&mdev
->graph_mutex
);
355 media_entity_graph_walk_start(&graph
, entity
);
357 while ((entity
= media_entity_graph_walk_next(&graph
))) {
358 entity
->stream_count
--;
359 if (entity
->stream_count
== 0)
363 mutex_unlock(&mdev
->graph_mutex
);
365 EXPORT_SYMBOL_GPL(media_entity_pipeline_stop
);
367 /* -----------------------------------------------------------------------------
372 * media_entity_get - Get a reference to the parent module
373 * @entity: The entity
375 * Get a reference to the parent media device module.
377 * The function will return immediately if @entity is NULL.
379 * Return a pointer to the entity on success or NULL on failure.
381 struct media_entity
*media_entity_get(struct media_entity
*entity
)
386 if (entity
->parent
->dev
&&
387 !try_module_get(entity
->parent
->dev
->driver
->owner
))
392 EXPORT_SYMBOL_GPL(media_entity_get
);
395 * media_entity_put - Release the reference to the parent module
396 * @entity: The entity
398 * Release the reference count acquired by media_entity_get().
400 * The function will return immediately if @entity is NULL.
402 void media_entity_put(struct media_entity
*entity
)
407 if (entity
->parent
->dev
)
408 module_put(entity
->parent
->dev
->driver
->owner
);
410 EXPORT_SYMBOL_GPL(media_entity_put
);
412 /* -----------------------------------------------------------------------------
416 static struct media_link
*media_entity_add_link(struct media_entity
*entity
)
418 if (entity
->num_links
>= entity
->max_links
) {
419 struct media_link
*links
= entity
->links
;
420 unsigned int max_links
= entity
->max_links
+ 2;
423 links
= krealloc(links
, max_links
* sizeof(*links
), GFP_KERNEL
);
427 for (i
= 0; i
< entity
->num_links
; i
++)
428 links
[i
].reverse
->reverse
= &links
[i
];
430 entity
->max_links
= max_links
;
431 entity
->links
= links
;
434 return &entity
->links
[entity
->num_links
++];
438 media_entity_create_link(struct media_entity
*source
, u16 source_pad
,
439 struct media_entity
*sink
, u16 sink_pad
, u32 flags
)
441 struct media_link
*link
;
442 struct media_link
*backlink
;
444 BUG_ON(source
== NULL
|| sink
== NULL
);
445 BUG_ON(source_pad
>= source
->num_pads
);
446 BUG_ON(sink_pad
>= sink
->num_pads
);
448 link
= media_entity_add_link(source
);
452 link
->source
= &source
->pads
[source_pad
];
453 link
->sink
= &sink
->pads
[sink_pad
];
456 /* Create the backlink. Backlinks are used to help graph traversal and
457 * are not reported to userspace.
459 backlink
= media_entity_add_link(sink
);
460 if (backlink
== NULL
) {
465 backlink
->source
= &source
->pads
[source_pad
];
466 backlink
->sink
= &sink
->pads
[sink_pad
];
467 backlink
->flags
= flags
;
469 link
->reverse
= backlink
;
470 backlink
->reverse
= link
;
472 sink
->num_backlinks
++;
476 EXPORT_SYMBOL_GPL(media_entity_create_link
);
478 void __media_entity_remove_links(struct media_entity
*entity
)
482 for (i
= 0; i
< entity
->num_links
; i
++) {
483 struct media_link
*link
= &entity
->links
[i
];
484 struct media_entity
*remote
;
487 if (link
->source
->entity
== entity
)
488 remote
= link
->sink
->entity
;
490 remote
= link
->source
->entity
;
492 while (r
< remote
->num_links
) {
493 struct media_link
*rlink
= &remote
->links
[r
];
495 if (rlink
!= link
->reverse
) {
500 if (link
->source
->entity
== entity
)
501 remote
->num_backlinks
--;
503 if (--remote
->num_links
== 0)
506 /* Insert last entry in place of the dropped link. */
507 *rlink
= remote
->links
[remote
->num_links
];
511 entity
->num_links
= 0;
512 entity
->num_backlinks
= 0;
514 EXPORT_SYMBOL_GPL(__media_entity_remove_links
);
516 void media_entity_remove_links(struct media_entity
*entity
)
518 /* Do nothing if the entity is not registered. */
519 if (entity
->parent
== NULL
)
522 mutex_lock(&entity
->parent
->graph_mutex
);
523 __media_entity_remove_links(entity
);
524 mutex_unlock(&entity
->parent
->graph_mutex
);
526 EXPORT_SYMBOL_GPL(media_entity_remove_links
);
528 static int __media_entity_setup_link_notify(struct media_link
*link
, u32 flags
)
532 /* Notify both entities. */
533 ret
= media_entity_call(link
->source
->entity
, link_setup
,
534 link
->source
, link
->sink
, flags
);
535 if (ret
< 0 && ret
!= -ENOIOCTLCMD
)
538 ret
= media_entity_call(link
->sink
->entity
, link_setup
,
539 link
->sink
, link
->source
, flags
);
540 if (ret
< 0 && ret
!= -ENOIOCTLCMD
) {
541 media_entity_call(link
->source
->entity
, link_setup
,
542 link
->source
, link
->sink
, link
->flags
);
547 link
->reverse
->flags
= link
->flags
;
553 * __media_entity_setup_link - Configure a media link
554 * @link: The link being configured
555 * @flags: Link configuration flags
557 * The bulk of link setup is handled by the two entities connected through the
558 * link. This function notifies both entities of the link configuration change.
560 * If the link is immutable or if the current and new configuration are
561 * identical, return immediately.
563 * The user is expected to hold link->source->parent->mutex. If not,
564 * media_entity_setup_link() should be used instead.
566 int __media_entity_setup_link(struct media_link
*link
, u32 flags
)
568 const u32 mask
= MEDIA_LNK_FL_ENABLED
;
569 struct media_device
*mdev
;
570 struct media_entity
*source
, *sink
;
576 /* The non-modifiable link flags must not be modified. */
577 if ((link
->flags
& ~mask
) != (flags
& ~mask
))
580 if (link
->flags
& MEDIA_LNK_FL_IMMUTABLE
)
581 return link
->flags
== flags
? 0 : -EINVAL
;
583 if (link
->flags
== flags
)
586 source
= link
->source
->entity
;
587 sink
= link
->sink
->entity
;
589 if (!(link
->flags
& MEDIA_LNK_FL_DYNAMIC
) &&
590 (source
->stream_count
|| sink
->stream_count
))
593 mdev
= source
->parent
;
595 if (mdev
->link_notify
) {
596 ret
= mdev
->link_notify(link
, flags
,
597 MEDIA_DEV_NOTIFY_PRE_LINK_CH
);
602 ret
= __media_entity_setup_link_notify(link
, flags
);
604 if (mdev
->link_notify
)
605 mdev
->link_notify(link
, flags
, MEDIA_DEV_NOTIFY_POST_LINK_CH
);
610 int media_entity_setup_link(struct media_link
*link
, u32 flags
)
614 mutex_lock(&link
->source
->entity
->parent
->graph_mutex
);
615 ret
= __media_entity_setup_link(link
, flags
);
616 mutex_unlock(&link
->source
->entity
->parent
->graph_mutex
);
620 EXPORT_SYMBOL_GPL(media_entity_setup_link
);
623 * media_entity_find_link - Find a link between two pads
624 * @source: Source pad
627 * Return a pointer to the link between the two entities. If no such link
628 * exists, return NULL.
631 media_entity_find_link(struct media_pad
*source
, struct media_pad
*sink
)
633 struct media_link
*link
;
636 for (i
= 0; i
< source
->entity
->num_links
; ++i
) {
637 link
= &source
->entity
->links
[i
];
639 if (link
->source
->entity
== source
->entity
&&
640 link
->source
->index
== source
->index
&&
641 link
->sink
->entity
== sink
->entity
&&
642 link
->sink
->index
== sink
->index
)
648 EXPORT_SYMBOL_GPL(media_entity_find_link
);
651 * media_entity_remote_pad - Find the pad at the remote end of a link
652 * @pad: Pad at the local end of the link
654 * Search for a remote pad connected to the given pad by iterating over all
655 * links originating or terminating at that pad until an enabled link is found.
657 * Return a pointer to the pad at the remote end of the first found enabled
658 * link, or NULL if no enabled link has been found.
660 struct media_pad
*media_entity_remote_pad(struct media_pad
*pad
)
664 for (i
= 0; i
< pad
->entity
->num_links
; i
++) {
665 struct media_link
*link
= &pad
->entity
->links
[i
];
667 if (!(link
->flags
& MEDIA_LNK_FL_ENABLED
))
670 if (link
->source
== pad
)
673 if (link
->sink
== pad
)
680 EXPORT_SYMBOL_GPL(media_entity_remote_pad
);