src/mediactl.h

   1 /*
   2  * Media controller interface library
   3  *
   4  * Copyright (C) 2010-2011 Ideas on board SPRL
   5  *
   6  * Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU Lesser General Public License as published
  10  * by the Free Software Foundation; either version 2.1 of the License, or
  11  * (at your option) any later version.
  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 Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public License
  19  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  20  */
  21
  22 #ifndef __MEDIA_H__
  23 #define __MEDIA_H__
  24
  25 #include <linux/media.h>
  26
  27 struct media_link {
  28         struct media_pad *source;
  29         struct media_pad *sink;
  30         struct media_link *twin;
  31         __u32 flags;
  32         __u32 padding[3];
  33 };
  34
  35 struct media_pad {
  36         struct media_entity *entity;
  37         __u32 index;
  38         __u32 flags;
  39         __u32 padding[3];
  40 };
  41
  42 struct media_entity {
  43         struct media_device *media;
  44         struct media_entity_desc info;
  45         struct media_pad *pads;
  46         struct media_link *links;
  47         unsigned int max_links;
  48         unsigned int num_links;
  49
  50         char devname[32];
  51         int fd;
  52         __u32 padding[6];
  53 };
  54
  55 struct media_device;
  56
  57 /**
  58  * @brief Create a new media device.
  59  * @param devnode - device node path.
  60  *
  61  * Create a media device instance for the given device node and return it. The
  62  * device node is not accessed by this function, device node access errors will
  63  * not be caught and reported here. The media device needs to be enumerated
  64  * before it can be accessed, see media_device_enumerate().
  65  *
  66  * Media devices are reference-counted, see media_device_ref() and
  67  * media_device_unref() for more information.
  68  *
  69  * @return A pointer to the new media device or NULL if memory cannot be
  70  * allocated.
  71  */
  72 struct media_device *media_device_new(const char *devnode);
  73
  74 /**
  75  * @brief Take a reference to the device.
  76  * @param media - device instance.
  77  *
  78  * Media devices are reference-counted. Taking a reference to a device prevents
  79  * it from being freed until all references are released. The reference count is
  80  * initialized to 1 when the device is created.
  81  *
  82  * @return A pointer to @a media.
  83  */
  84 struct media_device *media_device_ref(struct media_device *media);
  85
  86 /**
  87  * @brief Release a reference to the device.
  88  * @param media - device instance.
  89  *
  90  * Release a reference to the media device. When the reference count reaches 0
  91  * this function frees the device.
  92  */
  93 void media_device_unref(struct media_device *media);
  94
  95 /**
  96  * @brief Set a handler for debug messages.
  97  * @param media - device instance.
  98  * @param debug_handler - debug message handler
  99  * @param debug_priv - first argument to debug message handler
 100  *
 101  * Set a handler for debug messages that will be called whenever
 102  * debugging information is to be printed. The handler expects an
 103  * fprintf-like function.
 104  */
 105 void media_debug_set_handler(
 106         struct media_device *media, void (*debug_handler)(void *, ...),
 107         void *debug_priv);
 108
 109 /**
 110  * @brief Enumerate the device topology
 111  * @param media - device instance.
 112  *
 113  * Enumerate the media device entities, pads and links. Calling this function is
 114  * mandatory before accessing the media device contents.
 115  *
 116  * @return Zero on success or a negative error code on failure.
 117  */
 118 int media_device_enumerate(struct media_device *media);
 119
 120 /**
 121  * @brief Locate the pad at the other end of a link.
 122  * @param pad - sink pad at one end of the link.
 123  *
 124  * Locate the source pad connected to @a pad through an enabled link. As only one
 125  * link connected to a sink pad can be enabled at a time, the connected source
 126  * pad is guaranteed to be unique.
 127  *
 128  * @return A pointer to the connected source pad, or NULL if all links connected
 129  * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
 130  */
 131 struct media_pad *media_entity_remote_source(struct media_pad *pad);
 132
 133 /**
 134  * @brief Get the type of an entity.
 135  * @param entity - the entity.
 136  *
 137  * @return The type of @a entity.
 138  */
 139 static inline unsigned int media_entity_type(struct media_entity *entity)
 140 {
 141         return entity->info.type & MEDIA_ENT_TYPE_MASK;
 142 }
 143
 144 /**
 145  * @brief Find an entity by its name.
 146  * @param media - media device.
 147  * @param name - entity name.
 148  * @param length - size of @a name.
 149  *
 150  * Search for an entity with a name equal to @a name.
 151  *
 152  * @return A pointer to the entity if found, or NULL otherwise.
 153  */
 154 struct media_entity *media_get_entity_by_name(struct media_device *media,
 155         const char *name, size_t length);
 156
 157 /**
 158  * @brief Find an entity by its ID.
 159  * @param media - media device.
 160  * @param id - entity ID.
 161  *
 162  * This function searches for an entity based on its ID using an exact match or
 163  * next ID method based on the given @a id. If @a id is ORed with
 164  * MEDIA_ENT_ID_FLAG_NEXT, the function will return the entity with the smallest
 165  * ID larger than @a id. Otherwise it will return the entity with an ID equal to
 166  * @a id.
 167  *
 168  * @return A pointer to the entity if found, or NULL otherwise.
 169  */
 170 struct media_entity *media_get_entity_by_id(struct media_device *media,
 171         __u32 id);
 172
 173 /**
 174  * @brief Get the number of entities
 175  * @param media - media device.
 176  *
 177  * This function returns the total number of entities in the media device. If
 178  * entities haven't been enumerated yet it will return 0.
 179  *
 180  * @return The number of entities in the media device
 181  */
 182 unsigned int media_get_entities_count(struct media_device *media);
 183
 184 /**
 185  * @brief Get the entities
 186  * @param media - media device.
 187  *
 188  * This function returns a pointer to the array of entities for the media
 189  * device. If entities haven't been enumerated yet it will return NULL.
 190  *
 191  * The array of entities is owned by the media device object and will be freed
 192  * when the media object is destroyed.
 193  *
 194  * @return A pointer to an array of entities
 195  */
 196 struct media_entity *media_get_entities(struct media_device *media);
 197
 198 /**
 199  * @brief Get the media device information
 200  * @param media - media device.
 201  *
 202  * The information structure is owned by the media device object and will be freed
 203  * when the media object is destroyed.
 204  *
 205  * @return A pointer to the media device information
 206  */
 207 const struct media_device_info *media_get_info(struct media_device *media);
 208
 209 /**
 210  * @brief Get the media device node name
 211  * @param media - media device.
 212  *
 213  * The device node name string is owned by the media device object and will be
 214  * freed when the media object is destroyed.
 215  *
 216  * @return A pointer to the media device node name
 217  */
 218 const char *media_get_devnode(struct media_device *media);
 219
 220 /**
 221  * @brief Configure a link.
 222  * @param media - media device.
 223  * @param source - source pad at the link origin.
 224  * @param sink - sink pad at the link target.
 225  * @param flags - configuration flags.
 226  *
 227  * Locate the link between @a source and @a sink, and configure it by applying
 228  * the new @a flags.
 229  *
 230  * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
 231  *
 232  * @return 0 on success, -1 on failure:
 233  *         -ENOENT: link not found
 234  *         - other error codes returned by MEDIA_IOC_SETUP_LINK
 235  */
 236 int media_setup_link(struct media_device *media,
 237         struct media_pad *source, struct media_pad *sink,
 238         __u32 flags);
 239
 240 /**
 241  * @brief Reset all links to the disabled state.
 242  * @param media - media device.
 243  *
 244  * Disable all links in the media device. This function is usually used after
 245  * opening a media device to reset all links to a known state.
 246  *
 247  * @return 0 on success, or a negative error code on failure.
 248  */
 249 int media_reset_links(struct media_device *media);
 250
 251 /**
 252  * @brief Parse string to a pad on the media device.
 253  * @param media - media device.
 254  * @param p - input string
 255  * @param endp - pointer to string where parsing ended
 256  *
 257  * Parse NULL terminated string describing a pad and return its struct
 258  * media_pad instance.
 259  *
 260  * @return Pointer to struct media_pad on success, NULL on failure.
 261  */
 262 struct media_pad *media_parse_pad(struct media_device *media,
 263                                   const char *p, char **endp);
 264
 265 /**
 266  * @brief Parse string to a link on the media device.
 267  * @param media - media device.
 268  * @param p - input string
 269  * @param endp - pointer to p where parsing ended
 270  *
 271  * Parse NULL terminated string p describing a link and return its struct
 272  * media_link instance.
 273  *
 274  * @return Pointer to struct media_link on success, NULL on failure.
 275  */
 276 struct media_link *media_parse_link(struct media_device *media,
 277                                     const char *p, char **endp);
 278
 279 /**
 280  * @brief Parse string to a link on the media device and set it up.
 281  * @param media - media device.
 282  * @param p - input string
 283  *
 284  * Parse NULL terminated string p describing a link and its configuration
 285  * and configure the link.
 286  *
 287  * @return 0 on success, or a negative error code on failure.
 288  */
 289 int media_parse_setup_link(struct media_device *media,
 290                            const char *p, char **endp);
 291
 292 /**
 293  * @brief Parse string to link(s) on the media device and set it up.
 294  * @param media - media device.
 295  * @param p - input string
 296  *
 297  * Parse NULL terminated string p describing link(s) separated by
 298  * commas (,) and configure the link(s).
 299  *
 300  * @return 0 on success, or a negative error code on failure.
 301  */
 302 int media_parse_setup_links(struct media_device *media, const char *p);
 303
 304 #endif