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  * @revision:   Entity revision - OBSOLETE - should be removed soon.
 157  * @flags:      Entity flags, as defined in uapi/media.h (MEDIA_ENT_FL_*)
 158  * @group_id:   Entity group ID - OBSOLETE - should be removed soon.
 159  * @num_pads:   Number of sink and source pads.
 160  * @num_links:  Total number of links, forward and back, enabled and disabled.
 161  * @num_backlinks: Number of backlinks
 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         u32 revision;
 184         unsigned long flags;
 185         u32 group_id;
 186
 187         u16 num_pads;
 188         u16 num_links;
 189         u16 num_backlinks;
 190
 191         struct media_pad *pads;
 192         struct list_head links;
 193
 194         const struct media_entity_operations *ops;
 195
 196         /* Reference counts must never be negative, but are signed integers on
 197          * purpose: a simple WARN_ON(<0) check can be used to detect reference
 198          * count bugs that would make them negative.
 199          */
 200         int stream_count;
 201         int use_count;
 202
 203         struct media_pipeline *pipe;
 204
 205         union {
 206                 struct {
 207                         u32 major;
 208                         u32 minor;
 209                 } dev;
 210         } info;
 211 };
 212
 213 /**
 214  * struct media_interface - A media interface graph object.
 215  *
 216  * @graph_obj:          embedded graph object
 217  * @links:              List of links pointing to graph entities
 218  * @type:               Type of the interface as defined in the
 219  *                      uapi/media/media.h header, e. g.
 220  *                      MEDIA_INTF_T_*
 221  * @flags:              Interface flags as defined in uapi/media/media.h
 222  */
 223 struct media_interface {
 224         struct media_gobj               graph_obj;
 225         struct list_head                links;
 226         u32                             type;
 227         u32                             flags;
 228 };
 229
 230 /**
 231  * struct media_intf_devnode - A media interface via a device node.
 232  *
 233  * @intf:       embedded interface object
 234  * @major:      Major number of a device node
 235  * @minor:      Minor number of a device node
 236  */
 237 struct media_intf_devnode {
 238         struct media_interface          intf;
 239
 240         /* Should match the fields at media_v2_intf_devnode */
 241         u32                             major;
 242         u32                             minor;
 243 };
 244
 245 static inline u32 media_entity_id(struct media_entity *entity)
 246 {
 247         return entity->graph_obj.id;
 248 }
 249
 250 static inline enum media_gobj_type media_type(struct media_gobj *gobj)
 251 {
 252         return gobj->id >> MEDIA_BITS_PER_LOCAL_ID;
 253 }
 254
 255 static inline u32 media_localid(struct media_gobj *gobj)
 256 {
 257         return gobj->id & MEDIA_LOCAL_ID_MASK;
 258 }
 259
 260 static inline u32 media_gobj_gen_id(enum media_gobj_type type, u32 local_id)
 261 {
 262         u32 id;
 263
 264         id = type << MEDIA_BITS_PER_LOCAL_ID;
 265         id |= local_id & MEDIA_LOCAL_ID_MASK;
 266
 267         return id;
 268 }
 269
 270 static inline bool is_media_entity_v4l2_io(struct media_entity *entity)
 271 {
 272         if (!entity)
 273                 return false;
 274
 275         switch (entity->function) {
 276         case MEDIA_ENT_F_IO_V4L:
 277         case MEDIA_ENT_F_IO_VBI:
 278         case MEDIA_ENT_F_IO_SWRADIO:
 279                 return true;
 280         default:
 281                 return false;
 282         }
 283 }
 284
 285 static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity)
 286 {
 287         if (!entity)
 288                 return false;
 289
 290         switch (entity->function) {
 291         case MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN:
 292         case MEDIA_ENT_F_CAM_SENSOR:
 293         case MEDIA_ENT_F_FLASH:
 294         case MEDIA_ENT_F_LENS:
 295         case MEDIA_ENT_F_ATV_DECODER:
 296         case MEDIA_ENT_F_TUNER:
 297                 return true;
 298
 299         default:
 300                 return false;
 301         }
 302 }
 303
 304 #define MEDIA_ENTITY_ENUM_MAX_DEPTH     16
 305 #define MEDIA_ENTITY_ENUM_MAX_ID        64
 306
 307 /*
 308  * The number of pads can't be bigger than the number of entities,
 309  * as the worse-case scenario is to have one entity linked up to
 310  * MEDIA_ENTITY_ENUM_MAX_ID - 1 entities.
 311  */
 312 #define MEDIA_ENTITY_MAX_PADS           (MEDIA_ENTITY_ENUM_MAX_ID - 1)
 313
 314 struct media_entity_graph {
 315         struct {
 316                 struct media_entity *entity;
 317                 struct list_head *link;
 318         } stack[MEDIA_ENTITY_ENUM_MAX_DEPTH];
 319
 320         DECLARE_BITMAP(entities, MEDIA_ENTITY_ENUM_MAX_ID);
 321         int top;
 322 };
 323
 324 #define gobj_to_entity(gobj) \
 325                 container_of(gobj, struct media_entity, graph_obj)
 326
 327 #define gobj_to_pad(gobj) \
 328                 container_of(gobj, struct media_pad, graph_obj)
 329
 330 #define gobj_to_link(gobj) \
 331                 container_of(gobj, struct media_link, graph_obj)
 332
 333 #define gobj_to_link(gobj) \
 334                 container_of(gobj, struct media_link, graph_obj)
 335
 336 #define gobj_to_pad(gobj) \
 337                 container_of(gobj, struct media_pad, graph_obj)
 338
 339 #define gobj_to_intf(gobj) \
 340                 container_of(gobj, struct media_interface, graph_obj)
 341
 342 #define intf_to_devnode(intf) \
 343                 container_of(intf, struct media_intf_devnode, intf)
 344
 345 void media_gobj_init(struct media_device *mdev,
 346                     enum media_gobj_type type,
 347                     struct media_gobj *gobj);
 348 void media_gobj_remove(struct media_gobj *gobj);
 349
 350 int media_entity_init(struct media_entity *entity, u16 num_pads,
 351                       struct media_pad *pads);
 352 void media_entity_cleanup(struct media_entity *entity);
 353
 354 __must_check int media_create_pad_link(struct media_entity *source,
 355                         u16 source_pad, struct media_entity *sink,
 356                         u16 sink_pad, u32 flags);
 357 void __media_entity_remove_links(struct media_entity *entity);
 358 void media_entity_remove_links(struct media_entity *entity);
 359
 360 int __media_entity_setup_link(struct media_link *link, u32 flags);
 361 int media_entity_setup_link(struct media_link *link, u32 flags);
 362 struct media_link *media_entity_find_link(struct media_pad *source,
 363                 struct media_pad *sink);
 364 struct media_pad *media_entity_remote_pad(struct media_pad *pad);
 365
 366 struct media_entity *media_entity_get(struct media_entity *entity);
 367 void media_entity_put(struct media_entity *entity);
 368
 369 void media_entity_graph_walk_start(struct media_entity_graph *graph,
 370                 struct media_entity *entity);
 371 struct media_entity *
 372 media_entity_graph_walk_next(struct media_entity_graph *graph);
 373 __must_check int media_entity_pipeline_start(struct media_entity *entity,
 374                                              struct media_pipeline *pipe);
 375 void media_entity_pipeline_stop(struct media_entity *entity);
 376
 377 struct media_intf_devnode *
 378 __must_check media_devnode_create(struct media_device *mdev,
 379                                   u32 type, u32 flags,
 380                                   u32 major, u32 minor);
 381 void media_devnode_remove(struct media_intf_devnode *devnode);
 382 struct media_link *
 383 __must_check media_create_intf_link(struct media_entity *entity,
 384                                     struct media_interface *intf,
 385                                     u32 flags);
 386 void __media_remove_intf_link(struct media_link *link);
 387 void media_remove_intf_link(struct media_link *link);
 388 void __media_remove_intf_links(struct media_interface *intf);
 389 void media_remove_intf_links(struct media_interface *intf);
 390
 391
 392 #define media_entity_call(entity, operation, args...)                   \
 393         (((entity)->ops && (entity)->ops->operation) ?                  \
 394          (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)
 395
 396 #endif