1/* 2 * Media entity 3 * 4 * Copyright (C) 2010 Nokia Corporation 5 * 6 * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com> 7 * Sakari Ailus <sakari.ailus@iki.fi> 8 * 9 * This program is free software; you can redistribute it and/or modify 10 * it under the terms of the GNU General Public License version 2 as 11 * published by the Free Software Foundation. 12 * 13 * This program is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 * GNU General Public License for more details. 17 * 18 * You should have received a copy of the GNU General Public License 19 * along with this program; if not, write to the Free Software 20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 21 */ 22 23#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> 28 29/** 30 * media_entity_init - Initialize a media entity 31 * 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. 35 * 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. 41 * 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 44 * created. 45 * 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. 49 * 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. 52 */ 53int 54media_entity_init(struct media_entity *entity, u16 num_pads, 55 struct media_pad *pads, u16 extra_links) 56{ 57 struct media_link *links; 58 unsigned int max_links = num_pads + extra_links; 59 unsigned int i; 60 61 links = kzalloc(max_links * sizeof(links[0]), GFP_KERNEL); 62 if (links == NULL) 63 return -ENOMEM; 64 65 entity->group_id = 0; 66 entity->max_links = max_links; 67 entity->num_links = 0; 68 entity->num_backlinks = 0; 69 entity->num_pads = num_pads; 70 entity->pads = pads; 71 entity->links = links; 72 73 for (i = 0; i < num_pads; i++) { 74 pads[i].entity = entity; 75 pads[i].index = i; 76 } 77 78 return 0; 79} 80EXPORT_SYMBOL_GPL(media_entity_init); 81 82void 83media_entity_cleanup(struct media_entity *entity) 84{ 85 kfree(entity->links); 86} 87EXPORT_SYMBOL_GPL(media_entity_cleanup); 88 89/* ----------------------------------------------------------------------------- 90 * Graph traversal 91 */ 92 93static struct media_entity * 94media_entity_other(struct media_entity *entity, struct media_link *link) 95{ 96 if (link->source->entity == entity) 97 return link->sink->entity; 98 else 99 return link->source->entity; 100} 101 102/* push an entity to traversal stack */ 103static void stack_push(struct media_entity_graph *graph, 104 struct media_entity *entity) 105{ 106 if (graph->top == MEDIA_ENTITY_ENUM_MAX_DEPTH - 1) { 107 WARN_ON(1); 108 return; 109 } 110 graph->top++; 111 graph->stack[graph->top].link = 0; 112 graph->stack[graph->top].entity = entity; 113} 114 115static struct media_entity *stack_pop(struct media_entity_graph *graph) 116{ 117 struct media_entity *entity; 118 119 entity = graph->stack[graph->top].entity; 120 graph->top--; 121 122 return entity; 123} 124 125#define link_top(en) ((en)->stack[(en)->top].link) 126#define stack_top(en) ((en)->stack[(en)->top].entity) 127 128/** 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 132 * 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 136 * safely be freed. 137 */ 138void media_entity_graph_walk_start(struct media_entity_graph *graph, 139 struct media_entity *entity) 140{ 141 graph->top = 0; 142 graph->stack[graph->top].entity = NULL; 143 bitmap_zero(graph->entities, MEDIA_ENTITY_ENUM_MAX_ID); 144 145 if (WARN_ON(entity->id >= MEDIA_ENTITY_ENUM_MAX_ID)) 146 return; 147 148 __set_bit(entity->id, graph->entities); 149 stack_push(graph, entity); 150} 151EXPORT_SYMBOL_GPL(media_entity_graph_walk_start); 152 153/** 154 * media_entity_graph_walk_next - Get the next entity in the graph 155 * @graph: Media graph structure 156 * 157 * Perform a depth-first traversal of the given media entities graph. 158 * 159 * The graph structure must have been previously initialized with a call to 160 * media_entity_graph_walk_start(). 161 * 162 * Return the next entity in the graph or NULL if the whole graph have been 163 * traversed. 164 */ 165struct media_entity * 166media_entity_graph_walk_next(struct media_entity_graph *graph) 167{ 168 if (stack_top(graph) == NULL) 169 return NULL; 170 171 /* 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 174 * found. 175 */ 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; 180 181 /* The link is not enabled so we do not follow. */ 182 if (!(link->flags & MEDIA_LNK_FL_ENABLED)) { 183 link_top(graph)++; 184 continue; 185 } 186 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)) 190 return NULL; 191 192 /* Has the entity already been visited? */ 193 if (__test_and_set_bit(next->id, graph->entities)) { 194 link_top(graph)++; 195 continue; 196 } 197 198 /* Push the new entity to stack and start over. */ 199 link_top(graph)++; 200 stack_push(graph, next); 201 } 202 203 return stack_pop(graph); 204} 205EXPORT_SYMBOL_GPL(media_entity_graph_walk_next); 206 207/* ----------------------------------------------------------------------------- 208 * Pipeline management 209 */ 210 211/** 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. 215 * 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. 219 * 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(). 224 */ 225__must_check int media_entity_pipeline_start(struct media_entity *entity, 226 struct media_pipeline *pipe) 227{ 228 struct media_device *mdev = entity->parent; 229 struct media_entity_graph graph; 230 struct media_entity *entity_err = entity; 231 int ret; 232 233 mutex_lock(&mdev->graph_mutex); 234 235 media_entity_graph_walk_start(&graph, entity); 236 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); 240 unsigned int i; 241 242 entity->stream_count++; 243 WARN_ON(entity->pipe && entity->pipe != pipe); 244 entity->pipe = pipe; 245 246 /* Already streaming --- no need to check. */ 247 if (entity->stream_count > 1) 248 continue; 249 250 if (!entity->ops || !entity->ops->link_validate) 251 continue; 252 253 bitmap_zero(active, entity->num_pads); 254 bitmap_fill(has_no_links, entity->num_pads); 255 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; 260 261 /* Mark that a pad is connected by a link. */ 262 bitmap_clear(has_no_links, pad->index, 1); 263 264 /* 265 * Pads that either do not need to connect or 266 * are connected through an enabled link are 267 * fine. 268 */ 269 if (!(pad->flags & MEDIA_PAD_FL_MUST_CONNECT) || 270 link->flags & MEDIA_LNK_FL_ENABLED) 271 bitmap_set(active, pad->index, 1); 272 273 /* 274 * Link validation will only take place for 275 * sink ends of the link that are enabled. 276 */ 277 if (link->sink != pad || 278 !(link->flags & MEDIA_LNK_FL_ENABLED)) 279 continue; 280 281 ret = entity->ops->link_validate(link); 282 if (ret < 0 && ret != -ENOIOCTLCMD) 283 goto error; 284 } 285 286 /* Either no links or validated links are fine. */ 287 bitmap_or(active, active, has_no_links, entity->num_pads); 288 289 if (!bitmap_full(active, entity->num_pads)) { 290 ret = -EPIPE; 291 goto error; 292 } 293 } 294 295 mutex_unlock(&mdev->graph_mutex); 296 297 return 0; 298 299error: 300 /* 301 * Link validation on graph failed. We revert what we did and 302 * return the error. 303 */ 304 media_entity_graph_walk_start(&graph, entity_err); 305 306 while ((entity_err = media_entity_graph_walk_next(&graph))) { 307 entity_err->stream_count--; 308 if (entity_err->stream_count == 0) 309 entity_err->pipe = NULL; 310 311 /* 312 * We haven't increased stream_count further than this 313 * so we quit here. 314 */ 315 if (entity_err == entity) 316 break; 317 } 318 319 mutex_unlock(&mdev->graph_mutex); 320 321 return ret; 322} 323EXPORT_SYMBOL_GPL(media_entity_pipeline_start); 324 325/** 326 * media_entity_pipeline_stop - Mark a pipeline as not streaming 327 * @entity: Starting entity 328 * 329 * Mark all entities connected to a given entity through enabled links, either 330 * directly or indirectly, as not streaming. The media_entity pipe field is 331 * reset to NULL. 332 * 333 * If multiple calls to media_entity_pipeline_start() have been made, the same 334 * number of calls to this function are required to mark the pipeline as not 335 * streaming. 336 */ 337void media_entity_pipeline_stop(struct media_entity *entity) 338{ 339 struct media_device *mdev = entity->parent; 340 struct media_entity_graph graph; 341 342 mutex_lock(&mdev->graph_mutex); 343 344 media_entity_graph_walk_start(&graph, entity); 345 346 while ((entity = media_entity_graph_walk_next(&graph))) { 347 entity->stream_count--; 348 if (entity->stream_count == 0) 349 entity->pipe = NULL; 350 } 351 352 mutex_unlock(&mdev->graph_mutex); 353} 354EXPORT_SYMBOL_GPL(media_entity_pipeline_stop); 355 356/* ----------------------------------------------------------------------------- 357 * Module use count 358 */ 359 360/* 361 * media_entity_get - Get a reference to the parent module 362 * @entity: The entity 363 * 364 * Get a reference to the parent media device module. 365 * 366 * The function will return immediately if @entity is NULL. 367 * 368 * Return a pointer to the entity on success or NULL on failure. 369 */ 370struct media_entity *media_entity_get(struct media_entity *entity) 371{ 372 if (entity == NULL) 373 return NULL; 374 375 if (entity->parent->dev && 376 !try_module_get(entity->parent->dev->driver->owner)) 377 return NULL; 378 379 return entity; 380} 381EXPORT_SYMBOL_GPL(media_entity_get); 382 383/* 384 * media_entity_put - Release the reference to the parent module 385 * @entity: The entity 386 * 387 * Release the reference count acquired by media_entity_get(). 388 * 389 * The function will return immediately if @entity is NULL. 390 */ 391void media_entity_put(struct media_entity *entity) 392{ 393 if (entity == NULL) 394 return; 395 396 if (entity->parent->dev) 397 module_put(entity->parent->dev->driver->owner); 398} 399EXPORT_SYMBOL_GPL(media_entity_put); 400 401/* ----------------------------------------------------------------------------- 402 * Links management 403 */ 404 405static struct media_link *media_entity_add_link(struct media_entity *entity) 406{ 407 if (entity->num_links >= entity->max_links) { 408 struct media_link *links = entity->links; 409 unsigned int max_links = entity->max_links + 2; 410 unsigned int i; 411 412 links = krealloc(links, max_links * sizeof(*links), GFP_KERNEL); 413 if (links == NULL) 414 return NULL; 415 416 for (i = 0; i < entity->num_links; i++) 417 links[i].reverse->reverse = &links[i]; 418 419 entity->max_links = max_links; 420 entity->links = links; 421 } 422 423 return &entity->links[entity->num_links++]; 424} 425 426int 427media_entity_create_link(struct media_entity *source, u16 source_pad, 428 struct media_entity *sink, u16 sink_pad, u32 flags) 429{ 430 struct media_link *link; 431 struct media_link *backlink; 432 433 BUG_ON(source == NULL || sink == NULL); 434 BUG_ON(source_pad >= source->num_pads); 435 BUG_ON(sink_pad >= sink->num_pads); 436 437 link = media_entity_add_link(source); 438 if (link == NULL) 439 return -ENOMEM; 440 441 link->source = &source->pads[source_pad]; 442 link->sink = &sink->pads[sink_pad]; 443 link->flags = flags; 444 445 /* Create the backlink. Backlinks are used to help graph traversal and 446 * are not reported to userspace. 447 */ 448 backlink = media_entity_add_link(sink); 449 if (backlink == NULL) { 450 source->num_links--; 451 return -ENOMEM; 452 } 453 454 backlink->source = &source->pads[source_pad]; 455 backlink->sink = &sink->pads[sink_pad]; 456 backlink->flags = flags; 457 458 link->reverse = backlink; 459 backlink->reverse = link; 460 461 sink->num_backlinks++; 462 463 return 0; 464} 465EXPORT_SYMBOL_GPL(media_entity_create_link); 466 467void __media_entity_remove_links(struct media_entity *entity) 468{ 469 unsigned int i; 470 471 for (i = 0; i < entity->num_links; i++) { 472 struct media_link *link = &entity->links[i]; 473 struct media_entity *remote; 474 unsigned int r = 0; 475 476 if (link->source->entity == entity) 477 remote = link->sink->entity; 478 else 479 remote = link->source->entity; 480 481 while (r < remote->num_links) { 482 struct media_link *rlink = &remote->links[r]; 483 484 if (rlink != link->reverse) { 485 r++; 486 continue; 487 } 488 489 if (link->source->entity == entity) 490 remote->num_backlinks--; 491 492 if (--remote->num_links == 0) 493 break; 494 495 /* Insert last entry in place of the dropped link. */ 496 *rlink = remote->links[remote->num_links]; 497 } 498 } 499 500 entity->num_links = 0; 501 entity->num_backlinks = 0; 502} 503EXPORT_SYMBOL_GPL(__media_entity_remove_links); 504 505void media_entity_remove_links(struct media_entity *entity) 506{ 507 /* Do nothing if the entity is not registered. */ 508 if (entity->parent == NULL) 509 return; 510 511 mutex_lock(&entity->parent->graph_mutex); 512 __media_entity_remove_links(entity); 513 mutex_unlock(&entity->parent->graph_mutex); 514} 515EXPORT_SYMBOL_GPL(media_entity_remove_links); 516 517static int __media_entity_setup_link_notify(struct media_link *link, u32 flags) 518{ 519 int ret; 520 521 /* Notify both entities. */ 522 ret = media_entity_call(link->source->entity, link_setup, 523 link->source, link->sink, flags); 524 if (ret < 0 && ret != -ENOIOCTLCMD) 525 return ret; 526 527 ret = media_entity_call(link->sink->entity, link_setup, 528 link->sink, link->source, flags); 529 if (ret < 0 && ret != -ENOIOCTLCMD) { 530 media_entity_call(link->source->entity, link_setup, 531 link->source, link->sink, link->flags); 532 return ret; 533 } 534 535 link->flags = flags; 536 link->reverse->flags = link->flags; 537 538 return 0; 539} 540 541/** 542 * __media_entity_setup_link - Configure a media link 543 * @link: The link being configured 544 * @flags: Link configuration flags 545 * 546 * The bulk of link setup is handled by the two entities connected through the 547 * link. This function notifies both entities of the link configuration change. 548 * 549 * If the link is immutable or if the current and new configuration are 550 * identical, return immediately. 551 * 552 * The user is expected to hold link->source->parent->mutex. If not, 553 * media_entity_setup_link() should be used instead. 554 */ 555int __media_entity_setup_link(struct media_link *link, u32 flags) 556{ 557 const u32 mask = MEDIA_LNK_FL_ENABLED; 558 struct media_device *mdev; 559 struct media_entity *source, *sink; 560 int ret = -EBUSY; 561 562 if (link == NULL) 563 return -EINVAL; 564 565 /* The non-modifiable link flags must not be modified. */ 566 if ((link->flags & ~mask) != (flags & ~mask)) 567 return -EINVAL; 568 569 if (link->flags & MEDIA_LNK_FL_IMMUTABLE) 570 return link->flags == flags ? 0 : -EINVAL; 571 572 if (link->flags == flags) 573 return 0; 574 575 source = link->source->entity; 576 sink = link->sink->entity; 577 578 if (!(link->flags & MEDIA_LNK_FL_DYNAMIC) && 579 (source->stream_count || sink->stream_count)) 580 return -EBUSY; 581 582 mdev = source->parent; 583 584 if (mdev->link_notify) { 585 ret = mdev->link_notify(link, flags, 586 MEDIA_DEV_NOTIFY_PRE_LINK_CH); 587 if (ret < 0) 588 return ret; 589 } 590 591 ret = __media_entity_setup_link_notify(link, flags); 592 593 if (mdev->link_notify) 594 mdev->link_notify(link, flags, MEDIA_DEV_NOTIFY_POST_LINK_CH); 595 596 return ret; 597} 598 599int media_entity_setup_link(struct media_link *link, u32 flags) 600{ 601 int ret; 602 603 mutex_lock(&link->source->entity->parent->graph_mutex); 604 ret = __media_entity_setup_link(link, flags); 605 mutex_unlock(&link->source->entity->parent->graph_mutex); 606 607 return ret; 608} 609EXPORT_SYMBOL_GPL(media_entity_setup_link); 610 611/** 612 * media_entity_find_link - Find a link between two pads 613 * @source: Source pad 614 * @sink: Sink pad 615 * 616 * Return a pointer to the link between the two entities. If no such link 617 * exists, return NULL. 618 */ 619struct media_link * 620media_entity_find_link(struct media_pad *source, struct media_pad *sink) 621{ 622 struct media_link *link; 623 unsigned int i; 624 625 for (i = 0; i < source->entity->num_links; ++i) { 626 link = &source->entity->links[i]; 627 628 if (link->source->entity == source->entity && 629 link->source->index == source->index && 630 link->sink->entity == sink->entity && 631 link->sink->index == sink->index) 632 return link; 633 } 634 635 return NULL; 636} 637EXPORT_SYMBOL_GPL(media_entity_find_link); 638 639/** 640 * media_entity_remote_pad - Find the pad at the remote end of a link 641 * @pad: Pad at the local end of the link 642 * 643 * Search for a remote pad connected to the given pad by iterating over all 644 * links originating or terminating at that pad until an enabled link is found. 645 * 646 * Return a pointer to the pad at the remote end of the first found enabled 647 * link, or NULL if no enabled link has been found. 648 */ 649struct media_pad *media_entity_remote_pad(struct media_pad *pad) 650{ 651 unsigned int i; 652 653 for (i = 0; i < pad->entity->num_links; i++) { 654 struct media_link *link = &pad->entity->links[i]; 655 656 if (!(link->flags & MEDIA_LNK_FL_ENABLED)) 657 continue; 658 659 if (link->source == pad) 660 return link->sink; 661 662 if (link->sink == pad) 663 return link->source; 664 } 665 666 return NULL; 667 668} 669EXPORT_SYMBOL_GPL(media_entity_remote_pad); 670