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_gobj_init - Initialize a graph object
32 * @mdev: Pointer to the media_device that contains the object
33 * @type: Type of the object
34 * @gobj: Pointer to the object
36 * This routine initializes the embedded struct media_gobj inside a
37 * media graph object. It is called automatically if media_*_create()
38 * calls are used. However, if the object (entity, link, pad, interface)
39 * is embedded on some other object, this function should be called before
40 * registering the object at the media controller.
42 void media_gobj_init(struct media_device
*mdev
,
43 enum media_gobj_type type
,
44 struct media_gobj
*gobj
)
46 /* Create a per-type unique object ID */
48 case MEDIA_GRAPH_ENTITY
:
49 gobj
->id
= media_gobj_gen_id(type
, ++mdev
->entity_id
);
55 * media_gobj_remove - Stop using a graph object on a media device
57 * @graph_obj: Pointer to the object
59 * This should be called at media_device_unregister_*() routines
61 void media_gobj_remove(struct media_gobj
*gobj
)
63 /* For now, nothing to do */
67 * media_entity_init - Initialize a media entity
69 * @num_pads: Total number of sink and source pads.
70 * @pads: Array of 'num_pads' pads.
72 * The total number of pads is an intrinsic property of entities known by the
73 * entity driver, while the total number of links depends on hardware design
74 * and is an extrinsic property unknown to the entity driver. However, in most
75 * use cases the number of links can safely be assumed to be equal to or
76 * larger than the number of pads.
78 * For those reasons the links array can be preallocated based on the number
79 * of pads and will be reallocated later if extra links need to be created.
81 * This function allocates a links array with enough space to hold at least
82 * 'num_pads' elements. The media_entity::max_links field will be set to the
83 * number of allocated elements.
85 * The pads array is managed by the entity driver and passed to
86 * media_entity_init() where its pointer will be stored in the entity structure.
89 media_entity_init(struct media_entity
*entity
, u16 num_pads
,
90 struct media_pad
*pads
)
92 struct media_link
*links
;
93 unsigned int max_links
= num_pads
;
96 links
= kzalloc(max_links
* sizeof(links
[0]), GFP_KERNEL
);
100 entity
->group_id
= 0;
101 entity
->max_links
= max_links
;
102 entity
->num_links
= 0;
103 entity
->num_backlinks
= 0;
104 entity
->num_pads
= num_pads
;
106 entity
->links
= links
;
108 for (i
= 0; i
< num_pads
; i
++) {
109 pads
[i
].entity
= entity
;
115 EXPORT_SYMBOL_GPL(media_entity_init
);
118 media_entity_cleanup(struct media_entity
*entity
)
120 kfree(entity
->links
);
122 EXPORT_SYMBOL_GPL(media_entity_cleanup
);
124 /* -----------------------------------------------------------------------------
128 static struct media_entity
*
129 media_entity_other(struct media_entity
*entity
, struct media_link
*link
)
131 if (link
->source
->entity
== entity
)
132 return link
->sink
->entity
;
134 return link
->source
->entity
;
137 /* push an entity to traversal stack */
138 static void stack_push(struct media_entity_graph
*graph
,
139 struct media_entity
*entity
)
141 if (graph
->top
== MEDIA_ENTITY_ENUM_MAX_DEPTH
- 1) {
146 graph
->stack
[graph
->top
].link
= 0;
147 graph
->stack
[graph
->top
].entity
= entity
;
150 static struct media_entity
*stack_pop(struct media_entity_graph
*graph
)
152 struct media_entity
*entity
;
154 entity
= graph
->stack
[graph
->top
].entity
;
160 #define link_top(en) ((en)->stack[(en)->top].link)
161 #define stack_top(en) ((en)->stack[(en)->top].entity)
164 * media_entity_graph_walk_start - Start walking the media graph at a given entity
165 * @graph: Media graph structure that will be used to walk the graph
166 * @entity: Starting entity
168 * This function initializes the graph traversal structure to walk the entities
169 * graph starting at the given entity. The traversal structure must not be
170 * modified by the caller during graph traversal. When done the structure can
173 void media_entity_graph_walk_start(struct media_entity_graph
*graph
,
174 struct media_entity
*entity
)
177 graph
->stack
[graph
->top
].entity
= NULL
;
178 bitmap_zero(graph
->entities
, MEDIA_ENTITY_ENUM_MAX_ID
);
180 if (WARN_ON(media_entity_id(entity
) >= MEDIA_ENTITY_ENUM_MAX_ID
))
183 __set_bit(media_entity_id(entity
), graph
->entities
);
184 stack_push(graph
, entity
);
186 EXPORT_SYMBOL_GPL(media_entity_graph_walk_start
);
189 * media_entity_graph_walk_next - Get the next entity in the graph
190 * @graph: Media graph structure
192 * Perform a depth-first traversal of the given media entities graph.
194 * The graph structure must have been previously initialized with a call to
195 * media_entity_graph_walk_start().
197 * Return the next entity in the graph or NULL if the whole graph have been
200 struct media_entity
*
201 media_entity_graph_walk_next(struct media_entity_graph
*graph
)
203 if (stack_top(graph
) == NULL
)
207 * Depth first search. Push entity to stack and continue from
208 * top of the stack until no more entities on the level can be
211 while (link_top(graph
) < stack_top(graph
)->num_links
) {
212 struct media_entity
*entity
= stack_top(graph
);
213 struct media_link
*link
= &entity
->links
[link_top(graph
)];
214 struct media_entity
*next
;
216 /* The link is not enabled so we do not follow. */
217 if (!(link
->flags
& MEDIA_LNK_FL_ENABLED
)) {
222 /* Get the entity in the other end of the link . */
223 next
= media_entity_other(entity
, link
);
224 if (WARN_ON(media_entity_id(next
) >= MEDIA_ENTITY_ENUM_MAX_ID
))
227 /* Has the entity already been visited? */
228 if (__test_and_set_bit(media_entity_id(next
), graph
->entities
)) {
233 /* Push the new entity to stack and start over. */
235 stack_push(graph
, next
);
238 return stack_pop(graph
);
240 EXPORT_SYMBOL_GPL(media_entity_graph_walk_next
);
242 /* -----------------------------------------------------------------------------
243 * Pipeline management
247 * media_entity_pipeline_start - Mark a pipeline as streaming
248 * @entity: Starting entity
249 * @pipe: Media pipeline to be assigned to all entities in the pipeline.
251 * Mark all entities connected to a given entity through enabled links, either
252 * directly or indirectly, as streaming. The given pipeline object is assigned to
253 * every entity in the pipeline and stored in the media_entity pipe field.
255 * Calls to this function can be nested, in which case the same number of
256 * media_entity_pipeline_stop() calls will be required to stop streaming. The
257 * pipeline pointer must be identical for all nested calls to
258 * media_entity_pipeline_start().
260 __must_check
int media_entity_pipeline_start(struct media_entity
*entity
,
261 struct media_pipeline
*pipe
)
263 struct media_device
*mdev
= entity
->parent
;
264 struct media_entity_graph graph
;
265 struct media_entity
*entity_err
= entity
;
268 mutex_lock(&mdev
->graph_mutex
);
270 media_entity_graph_walk_start(&graph
, entity
);
272 while ((entity
= media_entity_graph_walk_next(&graph
))) {
273 DECLARE_BITMAP(active
, MEDIA_ENTITY_MAX_PADS
);
274 DECLARE_BITMAP(has_no_links
, MEDIA_ENTITY_MAX_PADS
);
277 entity
->stream_count
++;
278 WARN_ON(entity
->pipe
&& entity
->pipe
!= pipe
);
281 /* Already streaming --- no need to check. */
282 if (entity
->stream_count
> 1)
285 if (!entity
->ops
|| !entity
->ops
->link_validate
)
288 bitmap_zero(active
, entity
->num_pads
);
289 bitmap_fill(has_no_links
, entity
->num_pads
);
291 for (i
= 0; i
< entity
->num_links
; i
++) {
292 struct media_link
*link
= &entity
->links
[i
];
293 struct media_pad
*pad
= link
->sink
->entity
== entity
294 ? link
->sink
: link
->source
;
296 /* Mark that a pad is connected by a link. */
297 bitmap_clear(has_no_links
, pad
->index
, 1);
300 * Pads that either do not need to connect or
301 * are connected through an enabled link are
304 if (!(pad
->flags
& MEDIA_PAD_FL_MUST_CONNECT
) ||
305 link
->flags
& MEDIA_LNK_FL_ENABLED
)
306 bitmap_set(active
, pad
->index
, 1);
309 * Link validation will only take place for
310 * sink ends of the link that are enabled.
312 if (link
->sink
!= pad
||
313 !(link
->flags
& MEDIA_LNK_FL_ENABLED
))
316 ret
= entity
->ops
->link_validate(link
);
317 if (ret
< 0 && ret
!= -ENOIOCTLCMD
) {
318 dev_dbg(entity
->parent
->dev
,
319 "link validation failed for \"%s\":%u -> \"%s\":%u, error %d\n",
320 link
->source
->entity
->name
,
322 entity
->name
, link
->sink
->index
, ret
);
327 /* Either no links or validated links are fine. */
328 bitmap_or(active
, active
, has_no_links
, entity
->num_pads
);
330 if (!bitmap_full(active
, entity
->num_pads
)) {
332 dev_dbg(entity
->parent
->dev
,
333 "\"%s\":%u must be connected by an enabled link\n",
335 (unsigned)find_first_zero_bit(
336 active
, entity
->num_pads
));
341 mutex_unlock(&mdev
->graph_mutex
);
347 * Link validation on graph failed. We revert what we did and
350 media_entity_graph_walk_start(&graph
, entity_err
);
352 while ((entity_err
= media_entity_graph_walk_next(&graph
))) {
353 entity_err
->stream_count
--;
354 if (entity_err
->stream_count
== 0)
355 entity_err
->pipe
= NULL
;
358 * We haven't increased stream_count further than this
361 if (entity_err
== entity
)
365 mutex_unlock(&mdev
->graph_mutex
);
369 EXPORT_SYMBOL_GPL(media_entity_pipeline_start
);
372 * media_entity_pipeline_stop - Mark a pipeline as not streaming
373 * @entity: Starting entity
375 * Mark all entities connected to a given entity through enabled links, either
376 * directly or indirectly, as not streaming. The media_entity pipe field is
379 * If multiple calls to media_entity_pipeline_start() have been made, the same
380 * number of calls to this function are required to mark the pipeline as not
383 void media_entity_pipeline_stop(struct media_entity
*entity
)
385 struct media_device
*mdev
= entity
->parent
;
386 struct media_entity_graph graph
;
388 mutex_lock(&mdev
->graph_mutex
);
390 media_entity_graph_walk_start(&graph
, entity
);
392 while ((entity
= media_entity_graph_walk_next(&graph
))) {
393 entity
->stream_count
--;
394 if (entity
->stream_count
== 0)
398 mutex_unlock(&mdev
->graph_mutex
);
400 EXPORT_SYMBOL_GPL(media_entity_pipeline_stop
);
402 /* -----------------------------------------------------------------------------
407 * media_entity_get - Get a reference to the parent module
408 * @entity: The entity
410 * Get a reference to the parent media device module.
412 * The function will return immediately if @entity is NULL.
414 * Return a pointer to the entity on success or NULL on failure.
416 struct media_entity
*media_entity_get(struct media_entity
*entity
)
421 if (entity
->parent
->dev
&&
422 !try_module_get(entity
->parent
->dev
->driver
->owner
))
427 EXPORT_SYMBOL_GPL(media_entity_get
);
430 * media_entity_put - Release the reference to the parent module
431 * @entity: The entity
433 * Release the reference count acquired by media_entity_get().
435 * The function will return immediately if @entity is NULL.
437 void media_entity_put(struct media_entity
*entity
)
442 if (entity
->parent
->dev
)
443 module_put(entity
->parent
->dev
->driver
->owner
);
445 EXPORT_SYMBOL_GPL(media_entity_put
);
447 /* -----------------------------------------------------------------------------
451 static struct media_link
*media_entity_add_link(struct media_entity
*entity
)
453 if (entity
->num_links
>= entity
->max_links
) {
454 struct media_link
*links
= entity
->links
;
455 unsigned int max_links
= entity
->max_links
+ 2;
458 links
= krealloc(links
, max_links
* sizeof(*links
), GFP_KERNEL
);
462 for (i
= 0; i
< entity
->num_links
; i
++)
463 links
[i
].reverse
->reverse
= &links
[i
];
465 entity
->max_links
= max_links
;
466 entity
->links
= links
;
469 return &entity
->links
[entity
->num_links
++];
473 media_entity_create_link(struct media_entity
*source
, u16 source_pad
,
474 struct media_entity
*sink
, u16 sink_pad
, u32 flags
)
476 struct media_link
*link
;
477 struct media_link
*backlink
;
479 BUG_ON(source
== NULL
|| sink
== NULL
);
480 BUG_ON(source_pad
>= source
->num_pads
);
481 BUG_ON(sink_pad
>= sink
->num_pads
);
483 link
= media_entity_add_link(source
);
487 link
->source
= &source
->pads
[source_pad
];
488 link
->sink
= &sink
->pads
[sink_pad
];
491 /* Create the backlink. Backlinks are used to help graph traversal and
492 * are not reported to userspace.
494 backlink
= media_entity_add_link(sink
);
495 if (backlink
== NULL
) {
500 backlink
->source
= &source
->pads
[source_pad
];
501 backlink
->sink
= &sink
->pads
[sink_pad
];
502 backlink
->flags
= flags
;
504 link
->reverse
= backlink
;
505 backlink
->reverse
= link
;
507 sink
->num_backlinks
++;
511 EXPORT_SYMBOL_GPL(media_entity_create_link
);
513 void __media_entity_remove_links(struct media_entity
*entity
)
517 for (i
= 0; i
< entity
->num_links
; i
++) {
518 struct media_link
*link
= &entity
->links
[i
];
519 struct media_entity
*remote
;
522 if (link
->source
->entity
== entity
)
523 remote
= link
->sink
->entity
;
525 remote
= link
->source
->entity
;
527 while (r
< remote
->num_links
) {
528 struct media_link
*rlink
= &remote
->links
[r
];
530 if (rlink
!= link
->reverse
) {
535 if (link
->source
->entity
== entity
)
536 remote
->num_backlinks
--;
538 if (--remote
->num_links
== 0)
541 /* Insert last entry in place of the dropped link. */
542 *rlink
= remote
->links
[remote
->num_links
];
546 entity
->num_links
= 0;
547 entity
->num_backlinks
= 0;
549 EXPORT_SYMBOL_GPL(__media_entity_remove_links
);
551 void media_entity_remove_links(struct media_entity
*entity
)
553 /* Do nothing if the entity is not registered. */
554 if (entity
->parent
== NULL
)
557 mutex_lock(&entity
->parent
->graph_mutex
);
558 __media_entity_remove_links(entity
);
559 mutex_unlock(&entity
->parent
->graph_mutex
);
561 EXPORT_SYMBOL_GPL(media_entity_remove_links
);
563 static int __media_entity_setup_link_notify(struct media_link
*link
, u32 flags
)
567 /* Notify both entities. */
568 ret
= media_entity_call(link
->source
->entity
, link_setup
,
569 link
->source
, link
->sink
, flags
);
570 if (ret
< 0 && ret
!= -ENOIOCTLCMD
)
573 ret
= media_entity_call(link
->sink
->entity
, link_setup
,
574 link
->sink
, link
->source
, flags
);
575 if (ret
< 0 && ret
!= -ENOIOCTLCMD
) {
576 media_entity_call(link
->source
->entity
, link_setup
,
577 link
->source
, link
->sink
, link
->flags
);
582 link
->reverse
->flags
= link
->flags
;
588 * __media_entity_setup_link - Configure a media link
589 * @link: The link being configured
590 * @flags: Link configuration flags
592 * The bulk of link setup is handled by the two entities connected through the
593 * link. This function notifies both entities of the link configuration change.
595 * If the link is immutable or if the current and new configuration are
596 * identical, return immediately.
598 * The user is expected to hold link->source->parent->mutex. If not,
599 * media_entity_setup_link() should be used instead.
601 int __media_entity_setup_link(struct media_link
*link
, u32 flags
)
603 const u32 mask
= MEDIA_LNK_FL_ENABLED
;
604 struct media_device
*mdev
;
605 struct media_entity
*source
, *sink
;
611 /* The non-modifiable link flags must not be modified. */
612 if ((link
->flags
& ~mask
) != (flags
& ~mask
))
615 if (link
->flags
& MEDIA_LNK_FL_IMMUTABLE
)
616 return link
->flags
== flags
? 0 : -EINVAL
;
618 if (link
->flags
== flags
)
621 source
= link
->source
->entity
;
622 sink
= link
->sink
->entity
;
624 if (!(link
->flags
& MEDIA_LNK_FL_DYNAMIC
) &&
625 (source
->stream_count
|| sink
->stream_count
))
628 mdev
= source
->parent
;
630 if (mdev
->link_notify
) {
631 ret
= mdev
->link_notify(link
, flags
,
632 MEDIA_DEV_NOTIFY_PRE_LINK_CH
);
637 ret
= __media_entity_setup_link_notify(link
, flags
);
639 if (mdev
->link_notify
)
640 mdev
->link_notify(link
, flags
, MEDIA_DEV_NOTIFY_POST_LINK_CH
);
645 int media_entity_setup_link(struct media_link
*link
, u32 flags
)
649 mutex_lock(&link
->source
->entity
->parent
->graph_mutex
);
650 ret
= __media_entity_setup_link(link
, flags
);
651 mutex_unlock(&link
->source
->entity
->parent
->graph_mutex
);
655 EXPORT_SYMBOL_GPL(media_entity_setup_link
);
658 * media_entity_find_link - Find a link between two pads
659 * @source: Source pad
662 * Return a pointer to the link between the two entities. If no such link
663 * exists, return NULL.
666 media_entity_find_link(struct media_pad
*source
, struct media_pad
*sink
)
668 struct media_link
*link
;
671 for (i
= 0; i
< source
->entity
->num_links
; ++i
) {
672 link
= &source
->entity
->links
[i
];
674 if (link
->source
->entity
== source
->entity
&&
675 link
->source
->index
== source
->index
&&
676 link
->sink
->entity
== sink
->entity
&&
677 link
->sink
->index
== sink
->index
)
683 EXPORT_SYMBOL_GPL(media_entity_find_link
);
686 * media_entity_remote_pad - Find the pad at the remote end of a link
687 * @pad: Pad at the local end of the link
689 * Search for a remote pad connected to the given pad by iterating over all
690 * links originating or terminating at that pad until an enabled link is found.
692 * Return a pointer to the pad at the remote end of the first found enabled
693 * link, or NULL if no enabled link has been found.
695 struct media_pad
*media_entity_remote_pad(struct media_pad
*pad
)
699 for (i
= 0; i
< pad
->entity
->num_links
; i
++) {
700 struct media_link
*link
= &pad
->entity
->links
[i
];
702 if (!(link
->flags
& MEDIA_LNK_FL_ENABLED
))
705 if (link
->source
== pad
)
708 if (link
->sink
== pad
)
715 EXPORT_SYMBOL_GPL(media_entity_remote_pad
);