include/media/media-entity.h

   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/bitops.h>
  27 #include <linux/kernel.h>
  28 #include <linux/list.h>
  29 #include <linux/media.h>
  30
  31 /* Enums used internally at the media controller to represent graphs */
  32
  33 /**
  34  * enum media_gobj_type - type of a graph object
  35  *
  36  * @MEDIA_GRAPH_ENTITY:         Identify a media entity
  37  * @MEDIA_GRAPH_PAD:            Identify a media pad
  38  * @MEDIA_GRAPH_LINK:           Identify a media link
  39  * @MEDIA_GRAPH_INTF_DEVNODE:   Identify a media Kernel API interface via
  40  *                              a device node
  41  */
  42 enum media_gobj_type {
  43         MEDIA_GRAPH_ENTITY,
  44         MEDIA_GRAPH_PAD,
  45         MEDIA_GRAPH_LINK,
  46         MEDIA_GRAPH_INTF_DEVNODE,
  47 };
  48
  49 #define MEDIA_BITS_PER_TYPE             8
  50 #define MEDIA_BITS_PER_LOCAL_ID         (32 - MEDIA_BITS_PER_TYPE)
  51 #define MEDIA_LOCAL_ID_MASK              GENMASK(MEDIA_BITS_PER_LOCAL_ID - 1, 0)
  52
  53 /* Structs to represent the objects that belong to a media graph */
  54
  55 /**
  56  * struct media_gobj - Define a graph object.
  57  *
  58  * @mdev:       Pointer to the struct media_device that owns the object
  59  * @id:         Non-zero object ID identifier. The ID should be unique
  60  *              inside a media_device, as it is composed by
  61  *              MEDIA_BITS_PER_TYPE to store the type plus
  62  *              MEDIA_BITS_PER_LOCAL_ID to store a per-type ID
  63  *              (called as "local 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 struct media_pipeline {
  75 };
  76
  77 /**
  78  * struct media_link - A link object part of a media graph.
  79  *
  80  * @graph_obj:  Embedded structure containing the media object common data
  81  * @list:       Linked list associated with an entity or an interface that
  82  *              owns the link.
  83  * @gobj0:      Part of a union. Used to get the pointer for the first
  84  *              graph_object of the link.
  85  * @source:     Part of a union. Used only if the first object (gobj0) is
  86  *              a pad. In that case, it represents the source pad.
  87  * @intf:       Part of a union. Used only if the first object (gobj0) is
  88  *              an interface.
  89  * @gobj1:      Part of a union. Used to get the pointer for the second
  90  *              graph_object of the link.
  91  * @source:     Part of a union. Used only if the second object (gobj1) is
  92  *              a pad. In that case, it represents the sink pad.
  93  * @entity:     Part of a union. Used only if the second object (gobj1) is
  94  *              an entity.
  95  * @reverse:    Pointer to the link for the reverse direction of a pad to pad
  96  *              link.
  97  * @flags:      Link flags, as defined in uapi/media.h (MEDIA_LNK_FL_*)
  98  * @is_backlink: Indicate if the link is a backlink.
  99  */
 100 struct media_link {
 101         struct media_gobj graph_obj;
 102         struct list_head list;
 103         union {
 104                 struct media_gobj *gobj0;
 105                 struct media_pad *source;
 106                 struct media_interface *intf;
 107         };
 108         union {
 109                 struct media_gobj *gobj1;
 110                 struct media_pad *sink;
 111                 struct media_entity *entity;
 112         };
 113         struct media_link *reverse;
 114         unsigned long flags;
 115         bool is_backlink;
 116 };
 117
 118 /**
 119  * struct media_pad - A media pad graph object.
 120  *
 121  * @graph_obj:  Embedded structure containing the media object common data
 122  * @entity:     Entity this pad belongs to
 123  * @index:      Pad index in the entity pads array, numbered from 0 to n
 124  * @flags:      Pad flags, as defined in uapi/media.h (MEDIA_PAD_FL_*)
 125  */
 126 struct media_pad {
 127         struct media_gobj graph_obj;    /* must be first field in struct */
 128         struct media_entity *entity;
 129         u16 index;
 130         unsigned long flags;
 131 };
 132
 133 /**
 134  * struct media_entity_operations - Media entity operations
 135  * @link_setup:         Notify the entity of link changes. The operation can
 136  *                      return an error, in which case link setup will be
 137  *                      cancelled. Optional.
 138  * @link_validate:      Return whether a link is valid from the entity point of
 139  *                      view. The media_entity_pipeline_start() function
 140  *                      validates all links by calling this operation. Optional.
 141  */
 142 struct media_entity_operations {
 143         int (*link_setup)(struct media_entity *entity,
 144                           const struct media_pad *local,
 145                           const struct media_pad *remote, u32 flags);
 146         int (*link_validate)(struct media_link *link);
 147 };
 148
 149 /**
 150  * struct media_entity - A media entity graph object.
 151  *
 152  * @graph_obj:  Embedded structure containing the media object common data.
 153  * @name:       Entity name.
 154  * @function:   Entity main function, as defined in uapi/media.h
 155  *              (MEDIA_ENT_F_*)
 156  * @flags:      Entity flags, as defined in uapi/media.h (MEDIA_ENT_FL_*)
 157  * @num_pads:   Number of sink and source pads.
 158  * @num_links:  Total number of links, forward and back, enabled and disabled.
 159  * @num_backlinks: Number of backlinks
 160  * @internal_idx: An unique internal entity specific number. The numbers are
 161  *              re-used if entities are unregistered or registered again.
 162  * @pads:       Pads array with the size defined by @num_pads.
 163  * @links:      List of data links.
 164  * @ops:        Entity operations.
 165  * @stream_count: Stream count for the entity.
 166  * @use_count:  Use count for the entity.
 167  * @pipe:       Pipeline this entity belongs to.
 168  * @info:       Union with devnode information.  Kept just for backward
 169  *              compatibility.
 170  * @major:      Devnode major number (zero if not applicable). Kept just
 171  *              for backward compatibility.
 172  * @minor:      Devnode minor number (zero if not applicable). Kept just
 173  *              for backward compatibility.
 174  *
 175  * NOTE: @stream_count and @use_count reference counts must never be
 176  * negative, but are signed integers on purpose: a simple WARN_ON(<0) check
 177  * can be used to detect reference count bugs that would make them negative.
 178  */
 179 struct media_entity {
 180         struct media_gobj graph_obj;    /* must be first field in struct */
 181         const char *name;
 182         u32 function;
 183         unsigned long flags;
 184
 185         u16 num_pads;
 186         u16 num_links;
 187         u16 num_backlinks;
 188         int internal_idx;
 189
 190         struct media_pad *pads;
 191         struct list_head links;
 192
 193         const struct media_entity_operations *ops;
 194
 195         /* Reference counts must never be negative, but are signed integers on
 196          * purpose: a simple WARN_ON(<0) check can be used to detect reference
 197          * count bugs that would make them negative.
 198          */
 199         int stream_count;
 200         int use_count;
 201
 202         struct media_pipeline *pipe;
 203
 204         union {
 205                 struct {
 206                         u32 major;
 207                         u32 minor;
 208                 } dev;
 209         } info;
 210 };
 211
 212 /**
 213  * struct media_interface - A media interface graph object.
 214  *
 215  * @graph_obj:          embedded graph object
 216  * @links:              List of links pointing to graph entities
 217  * @type:               Type of the interface as defined in the
 218  *                      uapi/media/media.h header, e. g.
 219  *                      MEDIA_INTF_T_*
 220  * @flags:              Interface flags as defined in uapi/media/media.h
 221  */
 222 struct media_interface {
 223         struct media_gobj               graph_obj;
 224         struct list_head                links;
 225         u32                             type;
 226         u32                             flags;
 227 };
 228
 229 /**
 230  * struct media_intf_devnode - A media interface via a device node.
 231  *
 232  * @intf:       embedded interface object
 233  * @major:      Major number of a device node
 234  * @minor:      Minor number of a device node
 235  */
 236 struct media_intf_devnode {
 237         struct media_interface          intf;
 238
 239         /* Should match the fields at media_v2_intf_devnode */
 240         u32                             major;
 241         u32                             minor;
 242 };
 243
 244 /**
 245  * media_entity_id() - return the media entity graph object id
 246  *
 247  * @entity:     pointer to entity
 248  */
 249 static inline u32 media_entity_id(struct media_entity *entity)
 250 {
 251         return entity->graph_obj.id;
 252 }
 253
 254 /**
 255  * media_type() - return the media object type
 256  *
 257  * @gobj:       pointer to the media graph object
 258  */
 259 static inline enum media_gobj_type media_type(struct media_gobj *gobj)
 260 {
 261         return gobj->id >> MEDIA_BITS_PER_LOCAL_ID;
 262 }
 263
 264 static inline u32 media_localid(struct media_gobj *gobj)
 265 {
 266         return gobj->id & MEDIA_LOCAL_ID_MASK;
 267 }
 268
 269 static inline u32 media_gobj_gen_id(enum media_gobj_type type, u32 local_id)
 270 {
 271         u32 id;
 272
 273         id = type << MEDIA_BITS_PER_LOCAL_ID;
 274         id |= local_id & MEDIA_LOCAL_ID_MASK;
 275
 276         return id;
 277 }
 278
 279 /**
 280  * is_media_entity_v4l2_io() - identify if the entity main function
 281  *                             is a V4L2 I/O
 282  *
 283  * @entity:     pointer to entity
 284  *
 285  * Return: true if the entity main function is one of the V4L2 I/O types
 286  *      (video, VBI or SDR radio); false otherwise.
 287  */
 288 static inline bool is_media_entity_v4l2_io(struct media_entity *entity)
 289 {
 290         if (!entity)
 291                 return false;
 292
 293         switch (entity->function) {
 294         case MEDIA_ENT_F_IO_V4L:
 295         case MEDIA_ENT_F_IO_VBI:
 296         case MEDIA_ENT_F_IO_SWRADIO:
 297                 return true;
 298         default:
 299                 return false;
 300         }
 301 }
 302
 303 /**
 304  * is_media_entity_v4l2_subdev - return true if the entity main function is
 305  *                               associated with the V4L2 API subdev usage
 306  *
 307  * @entity:     pointer to entity
 308  *
 309  * This is an ancillary function used by subdev-based V4L2 drivers.
 310  * It checks if the entity function is one of functions used by a V4L2 subdev,
 311  * e. g. camera-relatef functions, analog TV decoder, TV tuner, V4L2 DSPs.
 312  */
 313 static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity)
 314 {
 315         if (!entity)
 316                 return false;
 317
 318         switch (entity->function) {
 319         case MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN:
 320         case MEDIA_ENT_F_CAM_SENSOR:
 321         case MEDIA_ENT_F_FLASH:
 322         case MEDIA_ENT_F_LENS:
 323         case MEDIA_ENT_F_ATV_DECODER:
 324         case MEDIA_ENT_F_TUNER:
 325                 return true;
 326
 327         default:
 328                 return false;
 329         }
 330 }
 331
 332 #define MEDIA_ENTITY_ENUM_MAX_DEPTH     16
 333 #define MEDIA_ENTITY_ENUM_MAX_ID        64
 334
 335 /*
 336  * The number of pads can't be bigger than the number of entities,
 337  * as the worse-case scenario is to have one entity linked up to
 338  * MEDIA_ENTITY_ENUM_MAX_ID - 1 entities.
 339  */
 340 #define MEDIA_ENTITY_MAX_PADS           (MEDIA_ENTITY_ENUM_MAX_ID - 1)
 341
 342 struct media_entity_graph {
 343         struct {
 344                 struct media_entity *entity;
 345                 struct list_head *link;
 346         } stack[MEDIA_ENTITY_ENUM_MAX_DEPTH];
 347
 348         DECLARE_BITMAP(entities, MEDIA_ENTITY_ENUM_MAX_ID);
 349         int top;
 350 };
 351
 352 #define gobj_to_entity(gobj) \
 353                 container_of(gobj, struct media_entity, graph_obj)
 354
 355 #define gobj_to_pad(gobj) \
 356                 container_of(gobj, struct media_pad, graph_obj)
 357
 358 #define gobj_to_link(gobj) \
 359                 container_of(gobj, struct media_link, graph_obj)
 360
 361 #define gobj_to_link(gobj) \
 362                 container_of(gobj, struct media_link, graph_obj)
 363
 364 #define gobj_to_pad(gobj) \
 365                 container_of(gobj, struct media_pad, graph_obj)
 366
 367 #define gobj_to_intf(gobj) \
 368                 container_of(gobj, struct media_interface, graph_obj)
 369
 370 #define intf_to_devnode(intf) \
 371                 container_of(intf, struct media_intf_devnode, intf)
 372
 373 /**
 374  *  media_gobj_create - Initialize a graph object
 375  *
 376  * @mdev:       Pointer to the media_device that contains the object
 377  * @type:       Type of the object
 378  * @gobj:       Pointer to the graph object
 379  *
 380  * This routine initializes the embedded struct media_gobj inside a
 381  * media graph object. It is called automatically if media_*_create()
 382  * calls are used. However, if the object (entity, link, pad, interface)
 383  * is embedded on some other object, this function should be called before
 384  * registering the object at the media controller.
 385  */
 386 void media_gobj_create(struct media_device *mdev,
 387                     enum media_gobj_type type,
 388                     struct media_gobj *gobj);
 389
 390 /**
 391  *  media_gobj_destroy - Stop using a graph object on a media device
 392  *
 393  * @gobj:       Pointer to the graph object
 394  *
 395  * This should be called by all routines like media_device_unregister()
 396  * that remove/destroy media graph objects.
 397  */
 398 void media_gobj_destroy(struct media_gobj *gobj);
 399
 400 /**
 401  * media_entity_pads_init() - Initialize the entity pads
 402  *
 403  * @entity:     entity where the pads belong
 404  * @num_pads:   total number of sink and source pads
 405  * @pads:       Array of @num_pads pads.
 406  *
 407  * The pads array is managed by the entity driver and passed to
 408  * media_entity_pads_init() where its pointer will be stored in the entity
 409  * structure.
 410  *
 411  * If no pads are needed, drivers could either directly fill
 412  * &media_entity->@num_pads with 0 and &media_entity->@pads with NULL or call
 413  * this function that will do the same.
 414  *
 415  * As the number of pads is known in advance, the pads array is not allocated
 416  * dynamically but is managed by the entity driver. Most drivers will embed the
 417  * pads array in a driver-specific structure, avoiding dynamic allocation.
 418  *
 419  * Drivers must set the direction of every pad in the pads array before calling
 420  * media_entity_pads_init(). The function will initialize the other pads fields.
 421  */
 422 int media_entity_pads_init(struct media_entity *entity, u16 num_pads,
 423                       struct media_pad *pads);
 424
 425 /**
 426  * media_entity_cleanup() - free resources associated with an entity
 427  *
 428  * @entity:     entity where the pads belong
 429  *
 430  * This function must be called during the cleanup phase after unregistering
 431  * the entity (currently, it does nothing).
 432  */
 433 static inline void media_entity_cleanup(struct media_entity *entity) {};
 434
 435 /**
 436  * media_create_pad_link() - creates a link between two entities.
 437  *
 438  * @source:     pointer to &media_entity of the source pad.
 439  * @source_pad: number of the source pad in the pads array
 440  * @sink:       pointer to &media_entity of the sink pad.
 441  * @sink_pad:   number of the sink pad in the pads array.
 442  * @flags:      Link flags, as defined in include/uapi/linux/media.h.
 443  *
 444  * Valid values for flags:
 445  * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be
 446  *      used to transfer media data. When two or more links target a sink pad,
 447  *      only one of them can be enabled at a time.
 448  *
 449  * A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't
 450  *      be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then
 451  *      %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
 452  *      always enabled.
 453  *
 454  * NOTE:
 455  *
 456  * Before calling this function, media_entity_pads_init() and
 457  * media_device_register_entity() should be called previously for both ends.
 458  */
 459 __must_check int media_create_pad_link(struct media_entity *source,
 460                         u16 source_pad, struct media_entity *sink,
 461                         u16 sink_pad, u32 flags);
 462 void __media_entity_remove_links(struct media_entity *entity);
 463
 464 /**
 465  * media_entity_remove_links() - remove all links associated with an entity
 466  *
 467  * @entity:     pointer to &media_entity
 468  *
 469  * Note: this is called automatically when an entity is unregistered via
 470  * media_device_register_entity().
 471  */
 472 void media_entity_remove_links(struct media_entity *entity);
 473
 474 /**
 475  * __media_entity_setup_link - Configure a media link without locking
 476  * @link: The link being configured
 477  * @flags: Link configuration flags
 478  *
 479  * The bulk of link setup is handled by the two entities connected through the
 480  * link. This function notifies both entities of the link configuration change.
 481  *
 482  * If the link is immutable or if the current and new configuration are
 483  * identical, return immediately.
 484  *
 485  * The user is expected to hold link->source->parent->mutex. If not,
 486  * media_entity_setup_link() should be used instead.
 487  */
 488 int __media_entity_setup_link(struct media_link *link, u32 flags);
 489
 490 /**
 491  * media_entity_setup_link() - changes the link flags properties in runtime
 492  *
 493  * @link:       pointer to &media_link
 494  * @flags:      the requested new link flags
 495  *
 496  * The only configurable property is the %MEDIA_LNK_FL_ENABLED link flag
 497  * flag to enable/disable a link. Links marked with the
 498  * %MEDIA_LNK_FL_IMMUTABLE link flag can not be enabled or disabled.
 499  *
 500  * When a link is enabled or disabled, the media framework calls the
 501  * link_setup operation for the two entities at the source and sink of the
 502  * link, in that order. If the second link_setup call fails, another
 503  * link_setup call is made on the first entity to restore the original link
 504  * flags.
 505  *
 506  * Media device drivers can be notified of link setup operations by setting the
 507  * media_device::link_notify pointer to a callback function. If provided, the
 508  * notification callback will be called before enabling and after disabling
 509  * links.
 510  *
 511  * Entity drivers must implement the link_setup operation if any of their links
 512  * is non-immutable. The operation must either configure the hardware or store
 513  * the configuration information to be applied later.
 514  *
 515  * Link configuration must not have any side effect on other links. If an
 516  * enabled link at a sink pad prevents another link at the same pad from
 517  * being enabled, the link_setup operation must return -EBUSY and can't
 518  * implicitly disable the first enabled link.
 519  *
 520  * NOTE: the valid values of the flags for the link is the same as described
 521  * on media_create_pad_link(), for pad to pad links or the same as described
 522  * on media_create_intf_link(), for interface to entity links.
 523  */
 524 int media_entity_setup_link(struct media_link *link, u32 flags);
 525
 526 /**
 527  * media_entity_find_link - Find a link between two pads
 528  * @source: Source pad
 529  * @sink: Sink pad
 530  *
 531  * Return a pointer to the link between the two entities. If no such link
 532  * exists, return NULL.
 533  */
 534 struct media_link *media_entity_find_link(struct media_pad *source,
 535                 struct media_pad *sink);
 536
 537 /**
 538  * media_entity_remote_pad - Find the pad at the remote end of a link
 539  * @pad: Pad at the local end of the link
 540  *
 541  * Search for a remote pad connected to the given pad by iterating over all
 542  * links originating or terminating at that pad until an enabled link is found.
 543  *
 544  * Return a pointer to the pad at the remote end of the first found enabled
 545  * link, or NULL if no enabled link has been found.
 546  */
 547 struct media_pad *media_entity_remote_pad(struct media_pad *pad);
 548
 549 /**
 550  * media_entity_get - Get a reference to the parent module
 551  *
 552  * @entity: The entity
 553  *
 554  * Get a reference to the parent media device module.
 555  *
 556  * The function will return immediately if @entity is NULL.
 557  *
 558  * Return a pointer to the entity on success or NULL on failure.
 559  */
 560 struct media_entity *media_entity_get(struct media_entity *entity);
 561
 562 /**
 563  * media_entity_put - Release the reference to the parent module
 564  *
 565  * @entity: The entity
 566  *
 567  * Release the reference count acquired by media_entity_get().
 568  *
 569  * The function will return immediately if @entity is NULL.
 570  */
 571 void media_entity_put(struct media_entity *entity);
 572
 573 /**
 574  * media_entity_graph_walk_start - Start walking the media graph at a given entity
 575  * @graph: Media graph structure that will be used to walk the graph
 576  * @entity: Starting entity
 577  *
 578  * This function initializes the graph traversal structure to walk the entities
 579  * graph starting at the given entity. The traversal structure must not be
 580  * modified by the caller during graph traversal. When done the structure can
 581  * safely be freed.
 582  */
 583 void media_entity_graph_walk_start(struct media_entity_graph *graph,
 584                 struct media_entity *entity);
 585
 586 /**
 587  * media_entity_graph_walk_next - Get the next entity in the graph
 588  * @graph: Media graph structure
 589  *
 590  * Perform a depth-first traversal of the given media entities graph.
 591  *
 592  * The graph structure must have been previously initialized with a call to
 593  * media_entity_graph_walk_start().
 594  *
 595  * Return the next entity in the graph or NULL if the whole graph have been
 596  * traversed.
 597  */
 598 struct media_entity *
 599 media_entity_graph_walk_next(struct media_entity_graph *graph);
 600
 601 /**
 602  * media_entity_pipeline_start - Mark a pipeline as streaming
 603  * @entity: Starting entity
 604  * @pipe: Media pipeline to be assigned to all entities in the pipeline.
 605  *
 606  * Mark all entities connected to a given entity through enabled links, either
 607  * directly or indirectly, as streaming. The given pipeline object is assigned to
 608  * every entity in the pipeline and stored in the media_entity pipe field.
 609  *
 610  * Calls to this function can be nested, in which case the same number of
 611  * media_entity_pipeline_stop() calls will be required to stop streaming. The
 612  * pipeline pointer must be identical for all nested calls to
 613  * media_entity_pipeline_start().
 614  */
 615 __must_check int media_entity_pipeline_start(struct media_entity *entity,
 616                                              struct media_pipeline *pipe);
 617
 618 /**
 619  * media_entity_pipeline_stop - Mark a pipeline as not streaming
 620  * @entity: Starting entity
 621  *
 622  * Mark all entities connected to a given entity through enabled links, either
 623  * directly or indirectly, as not streaming. The media_entity pipe field is
 624  * reset to NULL.
 625  *
 626  * If multiple calls to media_entity_pipeline_start() have been made, the same
 627  * number of calls to this function are required to mark the pipeline as not
 628  * streaming.
 629  */
 630 void media_entity_pipeline_stop(struct media_entity *entity);
 631
 632 /**
 633  * media_devnode_create() - creates and initializes a device node interface
 634  *
 635  * @mdev:       pointer to struct &media_device
 636  * @type:       type of the interface, as given by MEDIA_INTF_T_* macros
 637  *              as defined in the uapi/media/media.h header.
 638  * @flags:      Interface flags as defined in uapi/media/media.h.
 639  * @major:      Device node major number.
 640  * @minor:      Device node minor number.
 641  *
 642  * Return: if succeeded, returns a pointer to the newly allocated
 643  *      &media_intf_devnode pointer.
 644  */
 645 struct media_intf_devnode *
 646 __must_check media_devnode_create(struct media_device *mdev,
 647                                   u32 type, u32 flags,
 648                                   u32 major, u32 minor);
 649 /**
 650  * media_devnode_remove() - removes a device node interface
 651  *
 652  * @devnode:    pointer to &media_intf_devnode to be freed.
 653  *
 654  * When a device node interface is removed, all links to it are automatically
 655  * removed.
 656  */
 657 void media_devnode_remove(struct media_intf_devnode *devnode);
 658 struct media_link *
 659
 660 /**
 661  * media_create_intf_link() - creates a link between an entity and an interface
 662  *
 663  * @entity:     pointer to %media_entity
 664  * @intf:       pointer to %media_interface
 665  * @flags:      Link flags, as defined in include/uapi/linux/media.h.
 666  *
 667  *
 668  * Valid values for flags:
 669  * The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to
 670  *      the entity hardware. That's the default value for interfaces. An
 671  *      interface may be disabled if the hardware is busy due to the usage
 672  *      of some other interface that it is currently controlling the hardware.
 673  *      A typical example is an hybrid TV device that handle only one type of
 674  *      stream on a given time. So, when the digital TV is streaming,
 675  *      the V4L2 interfaces won't be enabled, as such device is not able to
 676  *      also stream analog TV or radio.
 677  *
 678  * Note:
 679  *
 680  * Before calling this function, media_devnode_create() should be called for
 681  * the interface and media_device_register_entity() should be called for the
 682  * interface that will be part of the link.
 683  */
 684 __must_check media_create_intf_link(struct media_entity *entity,
 685                                     struct media_interface *intf,
 686                                     u32 flags);
 687 /**
 688  * __media_remove_intf_link() - remove a single interface link
 689  *
 690  * @link:       pointer to &media_link.
 691  *
 692  * Note: this is an unlocked version of media_remove_intf_link()
 693  */
 694 void __media_remove_intf_link(struct media_link *link);
 695
 696 /**
 697  * media_remove_intf_link() - remove a single interface link
 698  *
 699  * @link:       pointer to &media_link.
 700  *
 701  * Note: prefer to use this one, instead of __media_remove_intf_link()
 702  */
 703 void media_remove_intf_link(struct media_link *link);
 704
 705 /**
 706  * __media_remove_intf_links() - remove all links associated with an interface
 707  *
 708  * @intf:       pointer to &media_interface
 709  *
 710  * Note: this is an unlocked version of media_remove_intf_links().
 711  */
 712 void __media_remove_intf_links(struct media_interface *intf);
 713 /**
 714  * media_remove_intf_links() - remove all links associated with an interface
 715  *
 716  * @intf:       pointer to &media_interface
 717  *
 718  * Notes:
 719  *
 720  * this is called automatically when an entity is unregistered via
 721  * media_device_register_entity() and by media_devnode_remove().
 722  *
 723  * Prefer to use this one, instead of __media_remove_intf_links().
 724  */
 725 void media_remove_intf_links(struct media_interface *intf);
 726
 727
 728 #define media_entity_call(entity, operation, args...)                   \
 729         (((entity)->ops && (entity)->ops->operation) ?                  \
 730          (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)
 731
 732 #endif