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  * @id:         Non-zero object ID identifier. The ID should be unique
  59  *              inside a media_device, as it is composed by
  60  *              MEDIA_BITS_PER_TYPE to store the type plus
  61  *              MEDIA_BITS_PER_LOCAL_ID to store a per-type ID
  62  *              (called as "local ID").
  63  *
  64  * All objects on the media graph should have this struct embedded
  65  */
  66 struct media_gobj {
  67         struct media_device     *mdev;
  68         u32                     id;
  69 };
  70
  71
  72 struct media_pipeline {
  73 };
  74
  75 struct media_link {
  76         struct media_gobj graph_obj;
  77         struct media_pad *source;       /* Source pad */
  78         struct media_pad *sink;         /* Sink pad  */
  79         struct media_link *reverse;     /* Link in the reverse direction */
  80         unsigned long flags;            /* Link flags (MEDIA_LNK_FL_*) */
  81 };
  82
  83 struct media_pad {
  84         struct media_gobj graph_obj;
  85         struct media_entity *entity;    /* Entity this pad belongs to */
  86         u16 index;                      /* Pad index in the entity pads array */
  87         unsigned long flags;            /* Pad flags (MEDIA_PAD_FL_*) */
  88 };
  89
  90 /**
  91  * struct media_entity_operations - Media entity operations
  92  * @link_setup:         Notify the entity of link changes. The operation can
  93  *                      return an error, in which case link setup will be
  94  *                      cancelled. Optional.
  95  * @link_validate:      Return whether a link is valid from the entity point of
  96  *                      view. The media_entity_pipeline_start() function
  97  *                      validates all links by calling this operation. Optional.
  98  */
  99 struct media_entity_operations {
 100         int (*link_setup)(struct media_entity *entity,
 101                           const struct media_pad *local,
 102                           const struct media_pad *remote, u32 flags);
 103         int (*link_validate)(struct media_link *link);
 104 };
 105
 106 struct media_entity {
 107         struct media_gobj graph_obj;
 108         struct list_head list;
 109         const char *name;               /* Entity name */
 110         u32 type;                       /* Entity type (MEDIA_ENT_T_*) */
 111         u32 revision;                   /* Entity revision, driver specific */
 112         unsigned long flags;            /* Entity flags (MEDIA_ENT_FL_*) */
 113         u32 group_id;                   /* Entity group ID */
 114
 115         u16 num_pads;                   /* Number of sink and source pads */
 116         u16 num_links;                  /* Number of existing links, both
 117                                          * enabled and disabled */
 118         u16 num_backlinks;              /* Number of backlinks */
 119         u16 max_links;                  /* Maximum number of links */
 120
 121         struct media_pad *pads;         /* Pads array (num_pads elements) */
 122         struct media_link *links;       /* Links array (max_links elements)*/
 123
 124         const struct media_entity_operations *ops;      /* Entity operations */
 125
 126         /* Reference counts must never be negative, but are signed integers on
 127          * purpose: a simple WARN_ON(<0) check can be used to detect reference
 128          * count bugs that would make them negative.
 129          */
 130         int stream_count;               /* Stream count for the entity. */
 131         int use_count;                  /* Use count for the entity. */
 132
 133         struct media_pipeline *pipe;    /* Pipeline this entity belongs to. */
 134
 135         union {
 136                 /* Node specifications */
 137                 struct {
 138                         u32 major;
 139                         u32 minor;
 140                 } dev;
 141
 142                 /* Sub-device specifications */
 143                 /* Nothing needed yet */
 144         } info;
 145 };
 146
 147 /**
 148  * struct media_intf_devnode - Define a Kernel API interface
 149  *
 150  * @graph_obj:          embedded graph object
 151  * @type:               Type of the interface as defined at the
 152  *                      uapi/media/media.h header, e. g.
 153  *                      MEDIA_INTF_T_*
 154  * @flags:              Interface flags as defined at uapi/media/media.h
 155  */
 156 struct media_interface {
 157         struct media_gobj               graph_obj;
 158         u32                             type;
 159         u32                             flags;
 160 };
 161
 162 /**
 163  * struct media_intf_devnode - Define a Kernel API interface via a device node
 164  *
 165  * @intf:       embedded interface object
 166  * @major:      Major number of a device node
 167  * @minor:      Minor number of a device node
 168  */
 169 struct media_intf_devnode {
 170         struct media_interface          intf;
 171         u32                             major;
 172         u32                             minor;
 173 };
 174
 175 static inline u32 media_entity_type(struct media_entity *entity)
 176 {
 177         return entity->type & MEDIA_ENT_TYPE_MASK;
 178 }
 179
 180 static inline u32 media_entity_subtype(struct media_entity *entity)
 181 {
 182         return entity->type & MEDIA_ENT_SUBTYPE_MASK;
 183 }
 184
 185 static inline u32 media_entity_id(struct media_entity *entity)
 186 {
 187         return entity->graph_obj.id;
 188 }
 189
 190 static inline enum media_gobj_type media_type(struct media_gobj *gobj)
 191 {
 192         return gobj->id >> MEDIA_BITS_PER_LOCAL_ID;
 193 }
 194
 195 static inline u32 media_localid(struct media_gobj *gobj)
 196 {
 197         return gobj->id & MEDIA_LOCAL_ID_MASK;
 198 }
 199
 200 static inline u32 media_gobj_gen_id(enum media_gobj_type type, u32 local_id)
 201 {
 202         u32 id;
 203
 204         id = type << MEDIA_BITS_PER_LOCAL_ID;
 205         id |= local_id & MEDIA_LOCAL_ID_MASK;
 206
 207         return id;
 208 }
 209
 210 #define MEDIA_ENTITY_ENUM_MAX_DEPTH     16
 211 #define MEDIA_ENTITY_ENUM_MAX_ID        64
 212
 213 /*
 214  * The number of pads can't be bigger than the number of entities,
 215  * as the worse-case scenario is to have one entity linked up to
 216  * MEDIA_ENTITY_ENUM_MAX_ID - 1 entities.
 217  */
 218 #define MEDIA_ENTITY_MAX_PADS           (MEDIA_ENTITY_ENUM_MAX_ID - 1)
 219
 220 struct media_entity_graph {
 221         struct {
 222                 struct media_entity *entity;
 223                 int link;
 224         } stack[MEDIA_ENTITY_ENUM_MAX_DEPTH];
 225
 226         DECLARE_BITMAP(entities, MEDIA_ENTITY_ENUM_MAX_ID);
 227         int top;
 228 };
 229
 230 #define gobj_to_entity(gobj) \
 231                 container_of(gobj, struct media_entity, graph_obj)
 232
 233 #define gobj_to_pad(gobj) \
 234                 container_of(gobj, struct media_pad, graph_obj)
 235
 236 #define gobj_to_link(gobj) \
 237                 container_of(gobj, struct media_link, graph_obj)
 238
 239 #define gobj_to_link(gobj) \
 240                 container_of(gobj, struct media_link, graph_obj)
 241
 242 #define gobj_to_pad(gobj) \
 243                 container_of(gobj, struct media_pad, graph_obj)
 244
 245 #define gobj_to_intf(gobj) \
 246                 container_of(gobj, struct media_interface, graph_obj)
 247
 248 #define intf_to_devnode(intf) \
 249                 container_of(intf, struct media_intf_devnode, intf)
 250
 251 void media_gobj_init(struct media_device *mdev,
 252                     enum media_gobj_type type,
 253                     struct media_gobj *gobj);
 254 void media_gobj_remove(struct media_gobj *gobj);
 255
 256 int media_entity_init(struct media_entity *entity, u16 num_pads,
 257                 struct media_pad *pads);
 258 void media_entity_cleanup(struct media_entity *entity);
 259
 260 int media_create_pad_link(struct media_entity *source, u16 source_pad,
 261                 struct media_entity *sink, u16 sink_pad, u32 flags);
 262 void __media_entity_remove_links(struct media_entity *entity);
 263 void media_entity_remove_links(struct media_entity *entity);
 264
 265 int __media_entity_setup_link(struct media_link *link, u32 flags);
 266 int media_entity_setup_link(struct media_link *link, u32 flags);
 267 struct media_link *media_entity_find_link(struct media_pad *source,
 268                 struct media_pad *sink);
 269 struct media_pad *media_entity_remote_pad(struct media_pad *pad);
 270
 271 struct media_entity *media_entity_get(struct media_entity *entity);
 272 void media_entity_put(struct media_entity *entity);
 273
 274 void media_entity_graph_walk_start(struct media_entity_graph *graph,
 275                 struct media_entity *entity);
 276 struct media_entity *
 277 media_entity_graph_walk_next(struct media_entity_graph *graph);
 278 __must_check int media_entity_pipeline_start(struct media_entity *entity,
 279                                              struct media_pipeline *pipe);
 280 void media_entity_pipeline_stop(struct media_entity *entity);
 281
 282 struct media_intf_devnode *media_devnode_create(struct media_device *mdev,
 283                                                 u32 type, u32 flags,
 284                                                 u32 major, u32 minor,
 285                                                 gfp_t gfp_flags);
 286 void media_devnode_remove(struct media_intf_devnode *devnode);
 287 #define media_entity_call(entity, operation, args...)                   \
 288         (((entity)->ops && (entity)->ops->operation) ?                  \
 289          (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)
 290
 291 #endif