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 #ifndef _MEDIA_ENTITY_H 24 #define _MEDIA_ENTITY_H 25 26 #include <linux/bitmap.h> 27 #include <linux/bug.h> 28 #include <linux/kernel.h> 29 #include <linux/list.h> 30 #include <linux/media.h> 31 32 /* Enums used internally at the media controller to represent graphs */ 33 34 /** 35 * enum media_gobj_type - type of a graph object 36 * 37 * @MEDIA_GRAPH_ENTITY: Identify a media entity 38 * @MEDIA_GRAPH_PAD: Identify a media pad 39 * @MEDIA_GRAPH_LINK: Identify a media link 40 * @MEDIA_GRAPH_INTF_DEVNODE: Identify a media Kernel API interface via 41 * a device node 42 */ 43 enum media_gobj_type { 44 MEDIA_GRAPH_ENTITY, 45 MEDIA_GRAPH_PAD, 46 MEDIA_GRAPH_LINK, 47 MEDIA_GRAPH_INTF_DEVNODE, 48 }; 49 50 #define MEDIA_BITS_PER_TYPE 8 51 #define MEDIA_BITS_PER_ID (32 - MEDIA_BITS_PER_TYPE) 52 #define MEDIA_ID_MASK GENMASK_ULL(MEDIA_BITS_PER_ID - 1, 0) 53 54 /* Structs to represent the objects that belong to a media graph */ 55 56 /** 57 * struct media_gobj - Define a graph object. 58 * 59 * @mdev: Pointer to the struct media_device that owns the object 60 * @id: Non-zero object ID identifier. The ID should be unique 61 * inside a media_device, as it is composed by 62 * %MEDIA_BITS_PER_TYPE to store the type plus 63 * %MEDIA_BITS_PER_ID to store the ID 64 * @list: List entry stored in one of the per-type mdev object lists 65 * 66 * All objects on the media graph should have this struct embedded 67 */ 68 struct media_gobj { 69 struct media_device *mdev; 70 u32 id; 71 struct list_head list; 72 }; 73 74 #define MEDIA_ENTITY_ENUM_MAX_DEPTH 16 75 76 /** 77 * struct media_entity_enum - An enumeration of media entities. 78 * 79 * @bmap: Bit map in which each bit represents one entity at struct 80 * media_entity->internal_idx. 81 * @idx_max: Number of bits in bmap 82 */ 83 struct media_entity_enum { 84 unsigned long *bmap; 85 int idx_max; 86 }; 87 88 /** 89 * struct media_entity_graph - Media graph traversal state 90 * 91 * @stack: Graph traversal stack; the stack contains information 92 * on the path the media entities to be walked and the 93 * links through which they were reached. 94 * @ent_enum: Visited entities 95 * @top: The top of the stack 96 */ 97 struct media_entity_graph { 98 struct { 99 struct media_entity *entity; 100 struct list_head *link; 101 } stack[MEDIA_ENTITY_ENUM_MAX_DEPTH]; 102 103 struct media_entity_enum ent_enum; 104 int top; 105 }; 106 107 /* 108 * struct media_pipeline - Media pipeline related information 109 * 110 * @streaming_count: Streaming start count - streaming stop count 111 * @graph: Media graph walk during pipeline start / stop 112 */ 113 struct media_pipeline { 114 int streaming_count; 115 struct media_entity_graph graph; 116 }; 117 118 /** 119 * struct media_link - A link object part of a media graph. 120 * 121 * @graph_obj: Embedded structure containing the media object common data 122 * @list: Linked list associated with an entity or an interface that 123 * owns the link. 124 * @gobj0: Part of a union. Used to get the pointer for the first 125 * graph_object of the link. 126 * @source: Part of a union. Used only if the first object (gobj0) is 127 * a pad. In that case, it represents the source pad. 128 * @intf: Part of a union. Used only if the first object (gobj0) is 129 * an interface. 130 * @gobj1: Part of a union. Used to get the pointer for the second 131 * graph_object of the link. 132 * @source: Part of a union. Used only if the second object (gobj1) is 133 * a pad. In that case, it represents the sink pad. 134 * @entity: Part of a union. Used only if the second object (gobj1) is 135 * an entity. 136 * @reverse: Pointer to the link for the reverse direction of a pad to pad 137 * link. 138 * @flags: Link flags, as defined in uapi/media.h (MEDIA_LNK_FL_*) 139 * @is_backlink: Indicate if the link is a backlink. 140 */ 141 struct media_link { 142 struct media_gobj graph_obj; 143 struct list_head list; 144 union { 145 struct media_gobj *gobj0; 146 struct media_pad *source; 147 struct media_interface *intf; 148 }; 149 union { 150 struct media_gobj *gobj1; 151 struct media_pad *sink; 152 struct media_entity *entity; 153 }; 154 struct media_link *reverse; 155 unsigned long flags; 156 bool is_backlink; 157 }; 158 159 /** 160 * struct media_pad - A media pad graph object. 161 * 162 * @graph_obj: Embedded structure containing the media object common data 163 * @entity: Entity this pad belongs to 164 * @index: Pad index in the entity pads array, numbered from 0 to n 165 * @flags: Pad flags, as defined in uapi/media.h (MEDIA_PAD_FL_*) 166 */ 167 struct media_pad { 168 struct media_gobj graph_obj; /* must be first field in struct */ 169 struct media_entity *entity; 170 u16 index; 171 unsigned long flags; 172 }; 173 174 /** 175 * struct media_entity_operations - Media entity operations 176 * @link_setup: Notify the entity of link changes. The operation can 177 * return an error, in which case link setup will be 178 * cancelled. Optional. 179 * @link_validate: Return whether a link is valid from the entity point of 180 * view. The media_entity_pipeline_start() function 181 * validates all links by calling this operation. Optional. 182 */ 183 struct media_entity_operations { 184 int (*link_setup)(struct media_entity *entity, 185 const struct media_pad *local, 186 const struct media_pad *remote, u32 flags); 187 int (*link_validate)(struct media_link *link); 188 }; 189 190 /** 191 * struct media_entity - A media entity graph object. 192 * 193 * @graph_obj: Embedded structure containing the media object common data. 194 * @name: Entity name. 195 * @function: Entity main function, as defined in uapi/media.h 196 * (MEDIA_ENT_F_*) 197 * @flags: Entity flags, as defined in uapi/media.h (MEDIA_ENT_FL_*) 198 * @num_pads: Number of sink and source pads. 199 * @num_links: Total number of links, forward and back, enabled and disabled. 200 * @num_backlinks: Number of backlinks 201 * @internal_idx: An unique internal entity specific number. The numbers are 202 * re-used if entities are unregistered or registered again. 203 * @pads: Pads array with the size defined by @num_pads. 204 * @links: List of data links. 205 * @ops: Entity operations. 206 * @stream_count: Stream count for the entity. 207 * @use_count: Use count for the entity. 208 * @pipe: Pipeline this entity belongs to. 209 * @info: Union with devnode information. Kept just for backward 210 * compatibility. 211 * @major: Devnode major number (zero if not applicable). Kept just 212 * for backward compatibility. 213 * @minor: Devnode minor number (zero if not applicable). Kept just 214 * for backward compatibility. 215 * 216 * NOTE: @stream_count and @use_count reference counts must never be 217 * negative, but are signed integers on purpose: a simple WARN_ON(<0) check 218 * can be used to detect reference count bugs that would make them negative. 219 */ 220 struct media_entity { 221 struct media_gobj graph_obj; /* must be first field in struct */ 222 const char *name; 223 u32 function; 224 unsigned long flags; 225 226 u16 num_pads; 227 u16 num_links; 228 u16 num_backlinks; 229 int internal_idx; 230 231 struct media_pad *pads; 232 struct list_head links; 233 234 const struct media_entity_operations *ops; 235 236 /* Reference counts must never be negative, but are signed integers on 237 * purpose: a simple WARN_ON(<0) check can be used to detect reference 238 * count bugs that would make them negative. 239 */ 240 int stream_count; 241 int use_count; 242 243 struct media_pipeline *pipe; 244 245 union { 246 struct { 247 u32 major; 248 u32 minor; 249 } dev; 250 } info; 251 }; 252 253 /** 254 * struct media_interface - A media interface graph object. 255 * 256 * @graph_obj: embedded graph object 257 * @links: List of links pointing to graph entities 258 * @type: Type of the interface as defined in the 259 * uapi/media/media.h header, e. g. 260 * MEDIA_INTF_T_* 261 * @flags: Interface flags as defined in uapi/media/media.h 262 */ 263 struct media_interface { 264 struct media_gobj graph_obj; 265 struct list_head links; 266 u32 type; 267 u32 flags; 268 }; 269 270 /** 271 * struct media_intf_devnode - A media interface via a device node. 272 * 273 * @intf: embedded interface object 274 * @major: Major number of a device node 275 * @minor: Minor number of a device node 276 */ 277 struct media_intf_devnode { 278 struct media_interface intf; 279 280 /* Should match the fields at media_v2_intf_devnode */ 281 u32 major; 282 u32 minor; 283 }; 284 285 /** 286 * media_entity_id() - return the media entity graph object id 287 * 288 * @entity: pointer to entity 289 */ 290 static inline u32 media_entity_id(struct media_entity *entity) 291 { 292 return entity->graph_obj.id; 293 } 294 295 /** 296 * media_type() - return the media object type 297 * 298 * @gobj: pointer to the media graph object 299 */ 300 static inline enum media_gobj_type media_type(struct media_gobj *gobj) 301 { 302 return gobj->id >> MEDIA_BITS_PER_ID; 303 } 304 305 /** 306 * media_id() - return the media object ID 307 * 308 * @gobj: pointer to the media graph object 309 */ 310 static inline u32 media_id(struct media_gobj *gobj) 311 { 312 return gobj->id & MEDIA_ID_MASK; 313 } 314 315 /** 316 * media_gobj_gen_id() - encapsulates type and ID on at the object ID 317 * 318 * @type: object type as define at enum &media_gobj_type. 319 * @local_id: next ID, from struct &media_device.@id. 320 */ 321 static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id) 322 { 323 u32 id; 324 325 id = type << MEDIA_BITS_PER_ID; 326 id |= local_id & MEDIA_ID_MASK; 327 328 return id; 329 } 330 331 /** 332 * is_media_entity_v4l2_io() - identify if the entity main function 333 * is a V4L2 I/O 334 * 335 * @entity: pointer to entity 336 * 337 * Return: true if the entity main function is one of the V4L2 I/O types 338 * (video, VBI or SDR radio); false otherwise. 339 */ 340 static inline bool is_media_entity_v4l2_io(struct media_entity *entity) 341 { 342 if (!entity) 343 return false; 344 345 switch (entity->function) { 346 case MEDIA_ENT_F_IO_V4L: 347 case MEDIA_ENT_F_IO_VBI: 348 case MEDIA_ENT_F_IO_SWRADIO: 349 return true; 350 default: 351 return false; 352 } 353 } 354 355 /** 356 * is_media_entity_v4l2_subdev - return true if the entity main function is 357 * associated with the V4L2 API subdev usage 358 * 359 * @entity: pointer to entity 360 * 361 * This is an ancillary function used by subdev-based V4L2 drivers. 362 * It checks if the entity function is one of functions used by a V4L2 subdev, 363 * e. g. camera-relatef functions, analog TV decoder, TV tuner, V4L2 DSPs. 364 */ 365 static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity) 366 { 367 if (!entity) 368 return false; 369 370 switch (entity->function) { 371 case MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN: 372 case MEDIA_ENT_F_CAM_SENSOR: 373 case MEDIA_ENT_F_FLASH: 374 case MEDIA_ENT_F_LENS: 375 case MEDIA_ENT_F_ATV_DECODER: 376 case MEDIA_ENT_F_TUNER: 377 return true; 378 379 default: 380 return false; 381 } 382 } 383 384 /** 385 * __media_entity_enum_init - Initialise an entity enumeration 386 * 387 * @ent_enum: Entity enumeration to be initialised 388 * @idx_max: Maximum number of entities in the enumeration 389 * 390 * Return: Returns zero on success or a negative error code. 391 */ 392 __must_check int __media_entity_enum_init(struct media_entity_enum *ent_enum, 393 int idx_max); 394 395 /** 396 * media_entity_enum_cleanup - Release resources of an entity enumeration 397 * 398 * @ent_enum: Entity enumeration to be released 399 */ 400 void media_entity_enum_cleanup(struct media_entity_enum *ent_enum); 401 402 /** 403 * media_entity_enum_zero - Clear the entire enum 404 * 405 * @ent_enum: Entity enumeration to be cleared 406 */ 407 static inline void media_entity_enum_zero(struct media_entity_enum *ent_enum) 408 { 409 bitmap_zero(ent_enum->bmap, ent_enum->idx_max); 410 } 411 412 /** 413 * media_entity_enum_set - Mark a single entity in the enum 414 * 415 * @ent_enum: Entity enumeration 416 * @entity: Entity to be marked 417 */ 418 static inline void media_entity_enum_set(struct media_entity_enum *ent_enum, 419 struct media_entity *entity) 420 { 421 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max)) 422 return; 423 424 __set_bit(entity->internal_idx, ent_enum->bmap); 425 } 426 427 /** 428 * media_entity_enum_clear - Unmark a single entity in the enum 429 * 430 * @ent_enum: Entity enumeration 431 * @entity: Entity to be unmarked 432 */ 433 static inline void media_entity_enum_clear(struct media_entity_enum *ent_enum, 434 struct media_entity *entity) 435 { 436 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max)) 437 return; 438 439 __clear_bit(entity->internal_idx, ent_enum->bmap); 440 } 441 442 /** 443 * media_entity_enum_test - Test whether the entity is marked 444 * 445 * @ent_enum: Entity enumeration 446 * @entity: Entity to be tested 447 * 448 * Returns true if the entity was marked. 449 */ 450 static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum, 451 struct media_entity *entity) 452 { 453 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max)) 454 return true; 455 456 return test_bit(entity->internal_idx, ent_enum->bmap); 457 } 458 459 /** 460 * media_entity_enum_test - Test whether the entity is marked, and mark it 461 * 462 * @ent_enum: Entity enumeration 463 * @entity: Entity to be tested 464 * 465 * Returns true if the entity was marked, and mark it before doing so. 466 */ 467 static inline bool 468 media_entity_enum_test_and_set(struct media_entity_enum *ent_enum, 469 struct media_entity *entity) 470 { 471 if (WARN_ON(entity->internal_idx >= ent_enum->idx_max)) 472 return true; 473 474 return __test_and_set_bit(entity->internal_idx, ent_enum->bmap); 475 } 476 477 /** 478 * media_entity_enum_empty - Test whether the entire enum is empty 479 * 480 * @ent_enum: Entity enumeration 481 * 482 * Returns true if the entity was marked. 483 */ 484 static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum) 485 { 486 return bitmap_empty(ent_enum->bmap, ent_enum->idx_max); 487 } 488 489 /** 490 * media_entity_enum_intersects - Test whether two enums intersect 491 * 492 * @ent_enum1: First entity enumeration 493 * @ent_enum2: Second entity enumeration 494 * 495 * Returns true if entity enumerations e and f intersect, otherwise false. 496 */ 497 static inline bool media_entity_enum_intersects( 498 struct media_entity_enum *ent_enum1, 499 struct media_entity_enum *ent_enum2) 500 { 501 WARN_ON(ent_enum1->idx_max != ent_enum2->idx_max); 502 503 return bitmap_intersects(ent_enum1->bmap, ent_enum2->bmap, 504 min(ent_enum1->idx_max, ent_enum2->idx_max)); 505 } 506 507 #define gobj_to_entity(gobj) \ 508 container_of(gobj, struct media_entity, graph_obj) 509 510 #define gobj_to_pad(gobj) \ 511 container_of(gobj, struct media_pad, graph_obj) 512 513 #define gobj_to_link(gobj) \ 514 container_of(gobj, struct media_link, graph_obj) 515 516 #define gobj_to_link(gobj) \ 517 container_of(gobj, struct media_link, graph_obj) 518 519 #define gobj_to_pad(gobj) \ 520 container_of(gobj, struct media_pad, graph_obj) 521 522 #define gobj_to_intf(gobj) \ 523 container_of(gobj, struct media_interface, graph_obj) 524 525 #define intf_to_devnode(intf) \ 526 container_of(intf, struct media_intf_devnode, intf) 527 528 /** 529 * media_gobj_create - Initialize a graph object 530 * 531 * @mdev: Pointer to the media_device that contains the object 532 * @type: Type of the object 533 * @gobj: Pointer to the graph object 534 * 535 * This routine initializes the embedded struct media_gobj inside a 536 * media graph object. It is called automatically if media_*_create() 537 * calls are used. However, if the object (entity, link, pad, interface) 538 * is embedded on some other object, this function should be called before 539 * registering the object at the media controller. 540 */ 541 void media_gobj_create(struct media_device *mdev, 542 enum media_gobj_type type, 543 struct media_gobj *gobj); 544 545 /** 546 * media_gobj_destroy - Stop using a graph object on a media device 547 * 548 * @gobj: Pointer to the graph object 549 * 550 * This should be called by all routines like media_device_unregister() 551 * that remove/destroy media graph objects. 552 */ 553 void media_gobj_destroy(struct media_gobj *gobj); 554 555 /** 556 * media_entity_pads_init() - Initialize the entity pads 557 * 558 * @entity: entity where the pads belong 559 * @num_pads: total number of sink and source pads 560 * @pads: Array of @num_pads pads. 561 * 562 * The pads array is managed by the entity driver and passed to 563 * media_entity_pads_init() where its pointer will be stored in the entity 564 * structure. 565 * 566 * If no pads are needed, drivers could either directly fill 567 * &media_entity->@num_pads with 0 and &media_entity->@pads with NULL or call 568 * this function that will do the same. 569 * 570 * As the number of pads is known in advance, the pads array is not allocated 571 * dynamically but is managed by the entity driver. Most drivers will embed the 572 * pads array in a driver-specific structure, avoiding dynamic allocation. 573 * 574 * Drivers must set the direction of every pad in the pads array before calling 575 * media_entity_pads_init(). The function will initialize the other pads fields. 576 */ 577 int media_entity_pads_init(struct media_entity *entity, u16 num_pads, 578 struct media_pad *pads); 579 580 /** 581 * media_entity_cleanup() - free resources associated with an entity 582 * 583 * @entity: entity where the pads belong 584 * 585 * This function must be called during the cleanup phase after unregistering 586 * the entity (currently, it does nothing). 587 */ 588 static inline void media_entity_cleanup(struct media_entity *entity) {}; 589 590 /** 591 * media_create_pad_link() - creates a link between two entities. 592 * 593 * @source: pointer to &media_entity of the source pad. 594 * @source_pad: number of the source pad in the pads array 595 * @sink: pointer to &media_entity of the sink pad. 596 * @sink_pad: number of the sink pad in the pads array. 597 * @flags: Link flags, as defined in include/uapi/linux/media.h. 598 * 599 * Valid values for flags: 600 * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be 601 * used to transfer media data. When two or more links target a sink pad, 602 * only one of them can be enabled at a time. 603 * 604 * A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't 605 * be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then 606 * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is 607 * always enabled. 608 * 609 * NOTE: 610 * 611 * Before calling this function, media_entity_pads_init() and 612 * media_device_register_entity() should be called previously for both ends. 613 */ 614 __must_check int media_create_pad_link(struct media_entity *source, 615 u16 source_pad, struct media_entity *sink, 616 u16 sink_pad, u32 flags); 617 618 /** 619 * media_create_pad_links() - creates a link between two entities. 620 * 621 * @mdev: Pointer to the media_device that contains the object 622 * @source_function: Function of the source entities. Used only if @source is 623 * NULL. 624 * @source: pointer to &media_entity of the source pad. If NULL, it will use 625 * all entities that matches the @sink_function. 626 * @source_pad: number of the source pad in the pads array 627 * @sink_function: Function of the sink entities. Used only if @sink is NULL. 628 * @sink: pointer to &media_entity of the sink pad. If NULL, it will use 629 * all entities that matches the @sink_function. 630 * @sink_pad: number of the sink pad in the pads array. 631 * @flags: Link flags, as defined in include/uapi/linux/media.h. 632 * @allow_both_undefined: if true, then both @source and @sink can be NULL. 633 * In such case, it will create a crossbar between all entities that 634 * matches @source_function to all entities that matches @sink_function. 635 * If false, it will return 0 and won't create any link if both @source 636 * and @sink are NULL. 637 * 638 * Valid values for flags: 639 * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be 640 * used to transfer media data. If multiple links are created and this 641 * flag is passed as an argument, only the first created link will have 642 * this flag. 643 * 644 * A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't 645 * be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then 646 * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is 647 * always enabled. 648 * 649 * It is common for some devices to have multiple source and/or sink entities 650 * of the same type that should be linked. While media_create_pad_link() 651 * creates link by link, this function is meant to allow 1:n, n:1 and even 652 * cross-bar (n:n) links. 653 * 654 * NOTE: Before calling this function, media_entity_pads_init() and 655 * media_device_register_entity() should be called previously for the entities 656 * to be linked. 657 */ 658 int media_create_pad_links(const struct media_device *mdev, 659 const u32 source_function, 660 struct media_entity *source, 661 const u16 source_pad, 662 const u32 sink_function, 663 struct media_entity *sink, 664 const u16 sink_pad, 665 u32 flags, 666 const bool allow_both_undefined); 667 668 void __media_entity_remove_links(struct media_entity *entity); 669 670 /** 671 * media_entity_remove_links() - remove all links associated with an entity 672 * 673 * @entity: pointer to &media_entity 674 * 675 * Note: this is called automatically when an entity is unregistered via 676 * media_device_register_entity(). 677 */ 678 void media_entity_remove_links(struct media_entity *entity); 679 680 /** 681 * __media_entity_setup_link - Configure a media link without locking 682 * @link: The link being configured 683 * @flags: Link configuration flags 684 * 685 * The bulk of link setup is handled by the two entities connected through the 686 * link. This function notifies both entities of the link configuration change. 687 * 688 * If the link is immutable or if the current and new configuration are 689 * identical, return immediately. 690 * 691 * The user is expected to hold link->source->parent->mutex. If not, 692 * media_entity_setup_link() should be used instead. 693 */ 694 int __media_entity_setup_link(struct media_link *link, u32 flags); 695 696 /** 697 * media_entity_setup_link() - changes the link flags properties in runtime 698 * 699 * @link: pointer to &media_link 700 * @flags: the requested new link flags 701 * 702 * The only configurable property is the %MEDIA_LNK_FL_ENABLED link flag 703 * flag to enable/disable a link. Links marked with the 704 * %MEDIA_LNK_FL_IMMUTABLE link flag can not be enabled or disabled. 705 * 706 * When a link is enabled or disabled, the media framework calls the 707 * link_setup operation for the two entities at the source and sink of the 708 * link, in that order. If the second link_setup call fails, another 709 * link_setup call is made on the first entity to restore the original link 710 * flags. 711 * 712 * Media device drivers can be notified of link setup operations by setting the 713 * media_device::link_notify pointer to a callback function. If provided, the 714 * notification callback will be called before enabling and after disabling 715 * links. 716 * 717 * Entity drivers must implement the link_setup operation if any of their links 718 * is non-immutable. The operation must either configure the hardware or store 719 * the configuration information to be applied later. 720 * 721 * Link configuration must not have any side effect on other links. If an 722 * enabled link at a sink pad prevents another link at the same pad from 723 * being enabled, the link_setup operation must return -EBUSY and can't 724 * implicitly disable the first enabled link. 725 * 726 * NOTE: the valid values of the flags for the link is the same as described 727 * on media_create_pad_link(), for pad to pad links or the same as described 728 * on media_create_intf_link(), for interface to entity links. 729 */ 730 int media_entity_setup_link(struct media_link *link, u32 flags); 731 732 /** 733 * media_entity_find_link - Find a link between two pads 734 * @source: Source pad 735 * @sink: Sink pad 736 * 737 * Return a pointer to the link between the two entities. If no such link 738 * exists, return NULL. 739 */ 740 struct media_link *media_entity_find_link(struct media_pad *source, 741 struct media_pad *sink); 742 743 /** 744 * media_entity_remote_pad - Find the pad at the remote end of a link 745 * @pad: Pad at the local end of the link 746 * 747 * Search for a remote pad connected to the given pad by iterating over all 748 * links originating or terminating at that pad until an enabled link is found. 749 * 750 * Return a pointer to the pad at the remote end of the first found enabled 751 * link, or NULL if no enabled link has been found. 752 */ 753 struct media_pad *media_entity_remote_pad(struct media_pad *pad); 754 755 /** 756 * media_entity_get - Get a reference to the parent module 757 * 758 * @entity: The entity 759 * 760 * Get a reference to the parent media device module. 761 * 762 * The function will return immediately if @entity is NULL. 763 * 764 * Return a pointer to the entity on success or NULL on failure. 765 */ 766 struct media_entity *media_entity_get(struct media_entity *entity); 767 768 __must_check int media_entity_graph_walk_init( 769 struct media_entity_graph *graph, struct media_device *mdev); 770 771 /** 772 * media_entity_graph_walk_cleanup - Release resources used by graph walk. 773 * 774 * @graph: Media graph structure that will be used to walk the graph 775 */ 776 void media_entity_graph_walk_cleanup(struct media_entity_graph *graph); 777 778 /** 779 * media_entity_put - Release the reference to the parent module 780 * 781 * @entity: The entity 782 * 783 * Release the reference count acquired by media_entity_get(). 784 * 785 * The function will return immediately if @entity is NULL. 786 */ 787 void media_entity_put(struct media_entity *entity); 788 789 /** 790 * media_entity_graph_walk_start - Start walking the media graph at a given entity 791 * @graph: Media graph structure that will be used to walk the graph 792 * @entity: Starting entity 793 * 794 * Before using this function, media_entity_graph_walk_init() must be 795 * used to allocate resources used for walking the graph. This 796 * function initializes the graph traversal structure to walk the 797 * entities graph starting at the given entity. The traversal 798 * structure must not be modified by the caller during graph 799 * traversal. After the graph walk, the resources must be released 800 * using media_entity_graph_walk_cleanup(). 801 */ 802 void media_entity_graph_walk_start(struct media_entity_graph *graph, 803 struct media_entity *entity); 804 805 /** 806 * media_entity_graph_walk_next - Get the next entity in the graph 807 * @graph: Media graph structure 808 * 809 * Perform a depth-first traversal of the given media entities graph. 810 * 811 * The graph structure must have been previously initialized with a call to 812 * media_entity_graph_walk_start(). 813 * 814 * Return the next entity in the graph or NULL if the whole graph have been 815 * traversed. 816 */ 817 struct media_entity * 818 media_entity_graph_walk_next(struct media_entity_graph *graph); 819 820 /** 821 * media_entity_pipeline_start - Mark a pipeline as streaming 822 * @entity: Starting entity 823 * @pipe: Media pipeline to be assigned to all entities in the pipeline. 824 * 825 * Mark all entities connected to a given entity through enabled links, either 826 * directly or indirectly, as streaming. The given pipeline object is assigned to 827 * every entity in the pipeline and stored in the media_entity pipe field. 828 * 829 * Calls to this function can be nested, in which case the same number of 830 * media_entity_pipeline_stop() calls will be required to stop streaming. The 831 * pipeline pointer must be identical for all nested calls to 832 * media_entity_pipeline_start(). 833 */ 834 __must_check int media_entity_pipeline_start(struct media_entity *entity, 835 struct media_pipeline *pipe); 836 /** 837 * __media_entity_pipeline_start - Mark a pipeline as streaming 838 * 839 * @entity: Starting entity 840 * @pipe: Media pipeline to be assigned to all entities in the pipeline. 841 * 842 * Note: This is the non-locking version of media_entity_pipeline_start() 843 */ 844 __must_check int __media_entity_pipeline_start(struct media_entity *entity, 845 struct media_pipeline *pipe); 846 847 /** 848 * media_entity_pipeline_stop - Mark a pipeline as not streaming 849 * @entity: Starting entity 850 * 851 * Mark all entities connected to a given entity through enabled links, either 852 * directly or indirectly, as not streaming. The media_entity pipe field is 853 * reset to NULL. 854 * 855 * If multiple calls to media_entity_pipeline_start() have been made, the same 856 * number of calls to this function are required to mark the pipeline as not 857 * streaming. 858 */ 859 void media_entity_pipeline_stop(struct media_entity *entity); 860 861 /** 862 * __media_entity_pipeline_stop - Mark a pipeline as not streaming 863 * 864 * @entity: Starting entity 865 * 866 * Note: This is the non-locking version of media_entity_pipeline_stop() 867 */ 868 void __media_entity_pipeline_stop(struct media_entity *entity); 869 870 /** 871 * media_devnode_create() - creates and initializes a device node interface 872 * 873 * @mdev: pointer to struct &media_device 874 * @type: type of the interface, as given by MEDIA_INTF_T_* macros 875 * as defined in the uapi/media/media.h header. 876 * @flags: Interface flags as defined in uapi/media/media.h. 877 * @major: Device node major number. 878 * @minor: Device node minor number. 879 * 880 * Return: if succeeded, returns a pointer to the newly allocated 881 * &media_intf_devnode pointer. 882 */ 883 struct media_intf_devnode * 884 __must_check media_devnode_create(struct media_device *mdev, 885 u32 type, u32 flags, 886 u32 major, u32 minor); 887 /** 888 * media_devnode_remove() - removes a device node interface 889 * 890 * @devnode: pointer to &media_intf_devnode to be freed. 891 * 892 * When a device node interface is removed, all links to it are automatically 893 * removed. 894 */ 895 void media_devnode_remove(struct media_intf_devnode *devnode); 896 struct media_link * 897 898 /** 899 * media_create_intf_link() - creates a link between an entity and an interface 900 * 901 * @entity: pointer to %media_entity 902 * @intf: pointer to %media_interface 903 * @flags: Link flags, as defined in include/uapi/linux/media.h. 904 * 905 * 906 * Valid values for flags: 907 * The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to 908 * the entity hardware. That's the default value for interfaces. An 909 * interface may be disabled if the hardware is busy due to the usage 910 * of some other interface that it is currently controlling the hardware. 911 * A typical example is an hybrid TV device that handle only one type of 912 * stream on a given time. So, when the digital TV is streaming, 913 * the V4L2 interfaces won't be enabled, as such device is not able to 914 * also stream analog TV or radio. 915 * 916 * Note: 917 * 918 * Before calling this function, media_devnode_create() should be called for 919 * the interface and media_device_register_entity() should be called for the 920 * interface that will be part of the link. 921 */ 922 __must_check media_create_intf_link(struct media_entity *entity, 923 struct media_interface *intf, 924 u32 flags); 925 /** 926 * __media_remove_intf_link() - remove a single interface link 927 * 928 * @link: pointer to &media_link. 929 * 930 * Note: this is an unlocked version of media_remove_intf_link() 931 */ 932 void __media_remove_intf_link(struct media_link *link); 933 934 /** 935 * media_remove_intf_link() - remove a single interface link 936 * 937 * @link: pointer to &media_link. 938 * 939 * Note: prefer to use this one, instead of __media_remove_intf_link() 940 */ 941 void media_remove_intf_link(struct media_link *link); 942 943 /** 944 * __media_remove_intf_links() - remove all links associated with an interface 945 * 946 * @intf: pointer to &media_interface 947 * 948 * Note: this is an unlocked version of media_remove_intf_links(). 949 */ 950 void __media_remove_intf_links(struct media_interface *intf); 951 952 /** 953 * media_remove_intf_links() - remove all links associated with an interface 954 * 955 * @intf: pointer to &media_interface 956 * 957 * Notes: 958 * 959 * this is called automatically when an entity is unregistered via 960 * media_device_register_entity() and by media_devnode_remove(). 961 * 962 * Prefer to use this one, instead of __media_remove_intf_links(). 963 */ 964 void media_remove_intf_links(struct media_interface *intf); 965 966 #define media_entity_call(entity, operation, args...) \ 967 (((entity)->ops && (entity)->ops->operation) ? \ 968 (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD) 969 970 #endif 971