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