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_device;
  43 struct media_entity;
  44
  45 /**
  46  * @brief Create a new media device.
  47  * @param devnode - device node path.
  48  *
  49  * Create a media device instance for the given device node and return it. The
  50  * device node is not accessed by this function, device node access errors will
  51  * not be caught and reported here. The media device needs to be enumerated
  52  * before it can be accessed, see media_device_enumerate().
  53  *
  54  * Media devices are reference-counted, see media_device_ref() and
  55  * media_device_unref() for more information.
  56  *
  57  * @return A pointer to the new media device or NULL if memory cannot be
  58  * allocated.
  59  */
  60 struct media_device *media_device_new(const char *devnode);
  61
  62 /**
  63  * @brief Take a reference to the device.
  64  * @param media - device instance.
  65  *
  66  * Media devices are reference-counted. Taking a reference to a device prevents
  67  * it from being freed until all references are released. The reference count is
  68  * initialized to 1 when the device is created.
  69  *
  70  * @return A pointer to @a media.
  71  */
  72 struct media_device *media_device_ref(struct media_device *media);
  73
  74 /**
  75  * @brief Release a reference to the device.
  76  * @param media - device instance.
  77  *
  78  * Release a reference to the media device. When the reference count reaches 0
  79  * this function frees the device.
  80  */
  81 void media_device_unref(struct media_device *media);
  82
  83 /**
  84  * @brief Set a handler for debug messages.
  85  * @param media - device instance.
  86  * @param debug_handler - debug message handler
  87  * @param debug_priv - first argument to debug message handler
  88  *
  89  * Set a handler for debug messages that will be called whenever
  90  * debugging information is to be printed. The handler expects an
  91  * fprintf-like function.
  92  */
  93 void media_debug_set_handler(
  94         struct media_device *media, void (*debug_handler)(void *, ...),
  95         void *debug_priv);
  96
  97 /**
  98  * @brief Enumerate the device topology
  99  * @param media - device instance.
 100  *
 101  * Enumerate the media device entities, pads and links. Calling this function is
 102  * mandatory before accessing the media device contents.
 103  *
 104  * @return Zero on success or a negative error code on failure.
 105  */
 106 int media_device_enumerate(struct media_device *media);
 107
 108 /**
 109  * @brief Locate the pad at the other end of a link.
 110  * @param pad - sink pad at one end of the link.
 111  *
 112  * Locate the source pad connected to @a pad through an enabled link. As only one
 113  * link connected to a sink pad can be enabled at a time, the connected source
 114  * pad is guaranteed to be unique.
 115  *
 116  * @return A pointer to the connected source pad, or NULL if all links connected
 117  * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
 118  */
 119 struct media_pad *media_entity_remote_source(struct media_pad *pad);
 120
 121 /**
 122  * @brief Get information about a media entity
 123  * @param entity - media entity.
 124  *
 125  * The information structure is owned by the media entity object and will be
 126  * freed when the object is destroyed.
 127  *
 128  * @return A pointer to the media entity information
 129  */
 130 const struct media_entity_desc *media_entity_get_info(struct media_entity *entity);
 131
 132 /**
 133  * @brief Get an entity pad
 134  * @param entity - media entity.
 135  * @param index - pad index.
 136  *
 137  * This function returns a pointer to the pad object identified by its index
 138  * for the given entity. If the pad index is out of bounds it will return NULL.
 139  *
 140  * @return A pointer to the pad
 141  */
 142 const struct media_pad *media_entity_get_pad(struct media_entity *entity,
 143                                              unsigned int index);
 144
 145 /**
 146  * @brief Get the number of links
 147  * @param entity - media entity.
 148  *
 149  * This function returns the total number of links that originate from or arrive
 150  * at the the media entity.
 151  *
 152  * @return The number of links for the entity
 153  */
 154 unsigned int media_entity_get_links_count(struct media_entity *entity);
 155
 156 /**
 157  * @brief Get an entity link
 158  * @param entity - media entity.
 159  * @param index - link index.
 160  *
 161  * This function returns a pointer to the link object identified by its index
 162  * for the given entity. If the link index is out of bounds it will return NULL.
 163  *
 164  * @return A pointer to the link
 165  */
 166 const struct media_link *media_entity_get_link(struct media_entity *entity,
 167                                                unsigned int index);
 168
 169 /**
 170  * @brief Get the device node name for an entity
 171  * @param entity - media entity.
 172  *
 173  * This function returns the full path and name to the device node corresponding
 174  * to the given entity.
 175  *
 176  * @return A pointer to the device node name or NULL if the entity has no
 177  * associated device node
 178  */
 179 const char *media_entity_get_devname(struct media_entity *entity);
 180
 181 /**
 182  * @brief Get the type of an entity.
 183  * @param entity - the entity.
 184  *
 185  * @return The type of @a entity.
 186  */
 187 static inline unsigned int media_entity_type(struct media_entity *entity)
 188 {
 189         return media_entity_get_info(entity)->type & MEDIA_ENT_TYPE_MASK;
 190 }
 191
 192 /**
 193  * @brief Find an entity by its name.
 194  * @param media - media device.
 195  * @param name - entity name.
 196  * @param length - size of @a name.
 197  *
 198  * Search for an entity with a name equal to @a name.
 199  *
 200  * @return A pointer to the entity if found, or NULL otherwise.
 201  */
 202 struct media_entity *media_get_entity_by_name(struct media_device *media,
 203         const char *name, size_t length);
 204
 205 /**
 206  * @brief Find an entity by its ID.
 207  * @param media - media device.
 208  * @param id - entity ID.
 209  *
 210  * This function searches for an entity based on its ID using an exact match or
 211  * next ID method based on the given @a id. If @a id is ORed with
 212  * MEDIA_ENT_ID_FLAG_NEXT, the function will return the entity with the smallest
 213  * ID larger than @a id. Otherwise it will return the entity with an ID equal to
 214  * @a id.
 215  *
 216  * @return A pointer to the entity if found, or NULL otherwise.
 217  */
 218 struct media_entity *media_get_entity_by_id(struct media_device *media,
 219         __u32 id);
 220
 221 /**
 222  * @brief Get the number of entities
 223  * @param media - media device.
 224  *
 225  * This function returns the total number of entities in the media device. If
 226  * entities haven't been enumerated yet it will return 0.
 227  *
 228  * @return The number of entities in the media device
 229  */
 230 unsigned int media_get_entities_count(struct media_device *media);
 231
 232 /**
 233  * @brief Get the entities
 234  * @param media - media device.
 235  *
 236  * This function returns a pointer to the array of entities for the media
 237  * device. If entities haven't been enumerated yet it will return NULL.
 238  *
 239  * The array of entities is owned by the media device object and will be freed
 240  * when the media object is destroyed.
 241  *
 242  * @return A pointer to an array of entities
 243  */
 244 struct media_entity *media_get_entity(struct media_device *media, unsigned int index);
 245
 246 /**
 247  * @brief Get the default entity for a given type
 248  * @param media - media device.
 249  * @param type - entity type.
 250  *
 251  * This function returns the default entity of the requested type. @a type must
 252  * be one of
 253  *
 254  *      MEDIA_ENT_T_DEVNODE_V4L
 255  *      MEDIA_ENT_T_DEVNODE_FB
 256  *      MEDIA_ENT_T_DEVNODE_ALSA
 257  *      MEDIA_ENT_T_DEVNODE_DVB
 258  *
 259  * @return A pointer to the default entity for the type if it exists, or NULL
 260  * otherwise.
 261  */
 262 struct media_entity *media_get_default_entity(struct media_device *media,
 263                                               unsigned int type);
 264
 265 /**
 266  * @brief Get the media device information
 267  * @param media - media device.
 268  *
 269  * The information structure is owned by the media device object and will be freed
 270  * when the media object is destroyed.
 271  *
 272  * @return A pointer to the media device information
 273  */
 274 const struct media_device_info *media_get_info(struct media_device *media);
 275
 276 /**
 277  * @brief Get the media device node name
 278  * @param media - media device.
 279  *
 280  * The device node name string is owned by the media device object and will be
 281  * freed when the media object is destroyed.
 282  *
 283  * @return A pointer to the media device node name
 284  */
 285 const char *media_get_devnode(struct media_device *media);
 286
 287 /**
 288  * @brief Configure a link.
 289  * @param media - media device.
 290  * @param source - source pad at the link origin.
 291  * @param sink - sink pad at the link target.
 292  * @param flags - configuration flags.
 293  *
 294  * Locate the link between @a source and @a sink, and configure it by applying
 295  * the new @a flags.
 296  *
 297  * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
 298  *
 299  * @return 0 on success, -1 on failure:
 300  *         -ENOENT: link not found
 301  *         - other error codes returned by MEDIA_IOC_SETUP_LINK
 302  */
 303 int media_setup_link(struct media_device *media,
 304         struct media_pad *source, struct media_pad *sink,
 305         __u32 flags);
 306
 307 /**
 308  * @brief Reset all links to the disabled state.
 309  * @param media - media device.
 310  *
 311  * Disable all links in the media device. This function is usually used after
 312  * opening a media device to reset all links to a known state.
 313  *
 314  * @return 0 on success, or a negative error code on failure.
 315  */
 316 int media_reset_links(struct media_device *media);
 317
 318 /**
 319  * @brief Parse string to a pad on the media device.
 320  * @param media - media device.
 321  * @param p - input string
 322  * @param endp - pointer to string where parsing ended
 323  *
 324  * Parse NULL terminated string describing a pad and return its struct
 325  * media_pad instance.
 326  *
 327  * @return Pointer to struct media_pad on success, NULL on failure.
 328  */
 329 struct media_pad *media_parse_pad(struct media_device *media,
 330                                   const char *p, char **endp);
 331
 332 /**
 333  * @brief Parse string to a link on the media device.
 334  * @param media - media device.
 335  * @param p - input string
 336  * @param endp - pointer to p where parsing ended
 337  *
 338  * Parse NULL terminated string p describing a link and return its struct
 339  * media_link instance.
 340  *
 341  * @return Pointer to struct media_link on success, NULL on failure.
 342  */
 343 struct media_link *media_parse_link(struct media_device *media,
 344                                     const char *p, char **endp);
 345
 346 /**
 347  * @brief Parse string to a link on the media device and set it up.
 348  * @param media - media device.
 349  * @param p - input string
 350  *
 351  * Parse NULL terminated string p describing a link and its configuration
 352  * and configure the link.
 353  *
 354  * @return 0 on success, or a negative error code on failure.
 355  */
 356 int media_parse_setup_link(struct media_device *media,
 357                            const char *p, char **endp);
 358
 359 /**
 360  * @brief Parse string to link(s) on the media device and set it up.
 361  * @param media - media device.
 362  * @param p - input string
 363  *
 364  * Parse NULL terminated string p describing link(s) separated by
 365  * commas (,) and configure the link(s).
 366  *
 367  * @return 0 on success, or a negative error code on failure.
 368  */
 369 int media_parse_setup_links(struct media_device *media, const char *p);
 370
 371 #endif