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
  75 struct media_pipeline {
  76 };
  77
  78 /**
  79  * struct media_link - A link object part of a media graph.
  80  *
  81  * @graph_obj:  Embedded structure containing the media object common data
  82  * @list:       Linked list associated with an entity or an interface that
  83  *              owns the link.
  84  * @gobj0:      Part of a union. Used to get the pointer for the first
  85  *              graph_object of the link.
  86  * @source:     Part of a union. Used only if the first object (gobj0) is
  87  *              a pad. In that case, it represents the source pad.
  88  * @intf:       Part of a union. Used only if the first object (gobj0) is
  89  *              an interface.
  90  * @gobj1:      Part of a union. Used to get the pointer for the second
  91  *              graph_object of the link.
  92  * @source:     Part of a union. Used only if the second object (gobj1) is
  93  *              a pad. In that case, it represents the sink pad.
  94  * @entity:     Part of a union. Used only if the second object (gobj1) is
  95  *              an entity.
  96  * @reverse:    Pointer to the link for the reverse direction of a pad to pad
  97  *              link.
  98  * @flags:      Link flags, as defined in uapi/media.h (MEDIA_LNK_FL_*)
  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 };
 116
 117 /**
 118  * struct media_pad - A media pad graph object.
 119  *
 120  * @graph_obj:  Embedded structure containing the media object common data
 121  * @entity:     Entity this pad belongs to
 122  * @index:      Pad index in the entity pads array, numbered from 0 to n
 123  * @flags:      Pad flags, as defined in uapi/media.h (MEDIA_PAD_FL_*)
 124  */
 125 struct media_pad {
 126         struct media_gobj graph_obj;    /* must be first field in struct */
 127         struct media_entity *entity;
 128         u16 index;
 129         unsigned long flags;
 130 };
 131
 132 /**
 133  * struct media_entity_operations - Media entity operations
 134  * @link_setup:         Notify the entity of link changes. The operation can
 135  *                      return an error, in which case link setup will be
 136  *                      cancelled. Optional.
 137  * @link_validate:      Return whether a link is valid from the entity point of
 138  *                      view. The media_entity_pipeline_start() function
 139  *                      validates all links by calling this operation. Optional.
 140  */
 141 struct media_entity_operations {
 142         int (*link_setup)(struct media_entity *entity,
 143                           const struct media_pad *local,
 144                           const struct media_pad *remote, u32 flags);
 145         int (*link_validate)(struct media_link *link);
 146 };
 147
 148 /**
 149  * struct media_entity - A media entity graph object.
 150  *
 151  * @graph_obj:  Embedded structure containing the media object common data.
 152  * @name:       Entity name.
 153  * @type:       Entity type, as defined in uapi/media.h (MEDIA_ENT_T_*)
 154  * @revision:   Entity revision - OBSOLETE - should be removed soon.
 155  * @flags:      Entity flags, as defined in uapi/media.h (MEDIA_ENT_FL_*)
 156  * @group_id:   Entity group ID - OBSOLETE - should be removed soon.
 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  * @pads:       Pads array with the size defined by @num_pads.
 161  * @links:      List of data links.
 162  * @ops:        Entity operations.
 163  * @stream_count: Stream count for the entity.
 164  * @use_count:  Use count for the entity.
 165  * @pipe:       Pipeline this entity belongs to.
 166  * @info:       Union with devnode information.  Kept just for backward
 167  *              compatibility.
 168  * @major:      Devnode major number (zero if not applicable). Kept just
 169  *              for backward compatibility.
 170  * @minor:      Devnode minor number (zero if not applicable). Kept just
 171  *              for backward compatibility.
 172  *
 173  * NOTE: @stream_count and @use_count reference counts must never be
 174  * negative, but are signed integers on purpose: a simple WARN_ON(<0) check
 175  * can be used to detect reference count bugs that would make them negative.
 176  */
 177 struct media_entity {
 178         struct media_gobj graph_obj;    /* must be first field in struct */
 179         const char *name;
 180         u32 type;
 181         u32 revision;
 182         unsigned long flags;
 183         u32 group_id;
 184
 185         u16 num_pads;
 186         u16 num_links;
 187         u16 num_backlinks;
 188
 189         struct media_pad *pads;
 190         struct list_head links;
 191
 192         const struct media_entity_operations *ops;
 193
 194         /* Reference counts must never be negative, but are signed integers on
 195          * purpose: a simple WARN_ON(<0) check can be used to detect reference
 196          * count bugs that would make them negative.
 197          */
 198         int stream_count;
 199         int use_count;
 200
 201         struct media_pipeline *pipe;
 202
 203         union {
 204                 struct {
 205                         u32 major;
 206                         u32 minor;
 207                 } dev;
 208         } info;
 209 };
 210
 211 /**
 212  * struct media_interface - A media interface graph object.
 213  *
 214  * @graph_obj:          embedded graph object
 215  * @links:              List of links pointing to graph entities
 216  * @type:               Type of the interface as defined in the
 217  *                      uapi/media/media.h header, e. g.
 218  *                      MEDIA_INTF_T_*
 219  * @flags:              Interface flags as defined in uapi/media/media.h
 220  */
 221 struct media_interface {
 222         struct media_gobj               graph_obj;
 223         struct list_head                links;
 224         u32                             type;
 225         u32                             flags;
 226 };
 227
 228 /**
 229  * struct media_intf_devnode - A media interface via a device node.
 230  *
 231  * @intf:       embedded interface object
 232  * @major:      Major number of a device node
 233  * @minor:      Minor number of a device node
 234  */
 235 struct media_intf_devnode {
 236         struct media_interface          intf;
 237
 238         /* Should match the fields at media_v2_intf_devnode */
 239         u32                             major;
 240         u32                             minor;
 241 };
 242
 243 static inline u32 media_entity_id(struct media_entity *entity)
 244 {
 245         return entity->graph_obj.id;
 246 }
 247
 248 static inline enum media_gobj_type media_type(struct media_gobj *gobj)
 249 {
 250         return gobj->id >> MEDIA_BITS_PER_LOCAL_ID;
 251 }
 252
 253 static inline u32 media_localid(struct media_gobj *gobj)
 254 {
 255         return gobj->id & MEDIA_LOCAL_ID_MASK;
 256 }
 257
 258 static inline u32 media_gobj_gen_id(enum media_gobj_type type, u32 local_id)
 259 {
 260         u32 id;
 261
 262         id = type << MEDIA_BITS_PER_LOCAL_ID;
 263         id |= local_id & MEDIA_LOCAL_ID_MASK;
 264
 265         return id;
 266 }
 267
 268 static inline bool is_media_entity_v4l2_io(struct media_entity *entity)
 269 {
 270         if (!entity)
 271                 return false;
 272
 273         switch (entity->type) {
 274         case MEDIA_ENT_T_V4L2_VIDEO:
 275         case MEDIA_ENT_T_V4L2_VBI:
 276         case MEDIA_ENT_T_V4L2_SWRADIO:
 277                 return true;
 278         default:
 279                 return false;
 280         }
 281 }
 282
 283 static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity)
 284 {
 285         if (!entity)
 286                 return false;
 287
 288         switch (entity->type) {
 289         case MEDIA_ENT_T_V4L2_SUBDEV_UNKNOWN:
 290         case MEDIA_ENT_T_V4L2_SUBDEV_SENSOR:
 291         case MEDIA_ENT_T_V4L2_SUBDEV_FLASH:
 292         case MEDIA_ENT_T_V4L2_SUBDEV_LENS:
 293         case MEDIA_ENT_T_V4L2_SUBDEV_DECODER:
 294         case MEDIA_ENT_T_V4L2_SUBDEV_TUNER:
 295                 return true;
 296
 297         default:
 298                 return false;
 299         }
 300 }
 301
 302 #define MEDIA_ENTITY_ENUM_MAX_DEPTH     16
 303 #define MEDIA_ENTITY_ENUM_MAX_ID        64
 304
 305 /*
 306  * The number of pads can't be bigger than the number of entities,
 307  * as the worse-case scenario is to have one entity linked up to
 308  * MEDIA_ENTITY_ENUM_MAX_ID - 1 entities.
 309  */
 310 #define MEDIA_ENTITY_MAX_PADS           (MEDIA_ENTITY_ENUM_MAX_ID - 1)
 311
 312 struct media_entity_graph {
 313         struct {
 314                 struct media_entity *entity;
 315                 struct list_head *link;
 316         } stack[MEDIA_ENTITY_ENUM_MAX_DEPTH];
 317
 318         DECLARE_BITMAP(entities, MEDIA_ENTITY_ENUM_MAX_ID);
 319         int top;
 320 };
 321
 322 #define gobj_to_entity(gobj) \
 323                 container_of(gobj, struct media_entity, graph_obj)
 324
 325 #define gobj_to_pad(gobj) \
 326                 container_of(gobj, struct media_pad, graph_obj)
 327
 328 #define gobj_to_link(gobj) \
 329                 container_of(gobj, struct media_link, graph_obj)
 330
 331 #define gobj_to_link(gobj) \
 332                 container_of(gobj, struct media_link, graph_obj)
 333
 334 #define gobj_to_pad(gobj) \
 335                 container_of(gobj, struct media_pad, graph_obj)
 336
 337 #define gobj_to_intf(gobj) \
 338                 container_of(gobj, struct media_interface, graph_obj)
 339
 340 #define intf_to_devnode(intf) \
 341                 container_of(intf, struct media_intf_devnode, intf)
 342
 343 void media_gobj_init(struct media_device *mdev,
 344                     enum media_gobj_type type,
 345                     struct media_gobj *gobj);
 346 void media_gobj_remove(struct media_gobj *gobj);
 347
 348 int media_entity_init(struct media_entity *entity, u16 num_pads,
 349                       struct media_pad *pads);
 350 void media_entity_cleanup(struct media_entity *entity);
 351
 352 int media_create_pad_link(struct media_entity *source, u16 source_pad,
 353                 struct media_entity *sink, u16 sink_pad, u32 flags);
 354 void __media_entity_remove_links(struct media_entity *entity);
 355 void media_entity_remove_links(struct media_entity *entity);
 356
 357 int __media_entity_setup_link(struct media_link *link, u32 flags);
 358 int media_entity_setup_link(struct media_link *link, u32 flags);
 359 struct media_link *media_entity_find_link(struct media_pad *source,
 360                 struct media_pad *sink);
 361 struct media_pad *media_entity_remote_pad(struct media_pad *pad);
 362
 363 struct media_entity *media_entity_get(struct media_entity *entity);
 364 void media_entity_put(struct media_entity *entity);
 365
 366 void media_entity_graph_walk_start(struct media_entity_graph *graph,
 367                 struct media_entity *entity);
 368 struct media_entity *
 369 media_entity_graph_walk_next(struct media_entity_graph *graph);
 370 __must_check int media_entity_pipeline_start(struct media_entity *entity,
 371                                              struct media_pipeline *pipe);
 372 void media_entity_pipeline_stop(struct media_entity *entity);
 373
 374 struct media_intf_devnode *media_devnode_create(struct media_device *mdev,
 375                                                 u32 type, u32 flags,
 376                                                 u32 major, u32 minor,
 377                                                 gfp_t gfp_flags);
 378 void media_devnode_remove(struct media_intf_devnode *devnode);
 379 struct media_link *media_create_intf_link(struct media_entity *entity,
 380                                             struct media_interface *intf,
 381                                             u32 flags);
 382 void __media_remove_intf_link(struct media_link *link);
 383 void media_remove_intf_link(struct media_link *link);
 384 void __media_remove_intf_links(struct media_interface *intf);
 385 void media_remove_intf_links(struct media_interface *intf);
 386
 387
 388 #define media_entity_call(entity, operation, args...)                   \
 389         (((entity)->ops && (entity)->ops->operation) ?                  \
 390          (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)
 391
 392 #endif