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