src/mediactl.h

   1 /*
   2  * Media controller interface library
   3  *
   4  * Copyright (C) 2010 Ideas on board SPRL <laurent.pinchart@ideasonboard.com>
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  */
  19
  20 #ifndef __MEDIA_H__
  21 #define __MEDIA_H__
  22
  23 #include <linux/media.h>
  24
  25 struct media_link {
  26         struct media_pad *source;
  27         struct media_pad *sink;
  28         struct media_link *twin;
  29         __u32 flags;
  30         __u32 padding[3];
  31 };
  32
  33 struct media_pad {
  34         struct media_entity *entity;
  35         __u32 index;
  36         __u32 flags;
  37         __u32 padding[3];
  38 };
  39
  40 struct media_entity {
  41         struct media_device *media;
  42         struct media_entity_desc info;
  43         struct media_pad *pads;
  44         struct media_link *links;
  45         unsigned int max_links;
  46         unsigned int num_links;
  47
  48         char devname[32];
  49         int fd;
  50         __u32 padding[6];
  51 };
  52
  53 struct media_device {
  54         int fd;
  55         struct media_entity *entities;
  56         unsigned int entities_count;
  57         void (*debug_handler)(void *, ...);
  58         void *debug_priv;
  59         __u32 padding[6];
  60 };
  61
  62 #define media_dbg(media, ...) \
  63         (media)->debug_handler((media)->debug_priv, __VA_ARGS__)
  64
  65 /**
  66  * @brief Set a handler for debug messages.
  67  * @param media - device instance.
  68  * @param debug_handler - debug message handler
  69  * @param debug_priv - first argument to debug message handler
  70  *
  71  * Set a handler for debug messages that will be called whenever
  72  * debugging information is to be printed. The handler expects an
  73  * fprintf-like function.
  74  */
  75 void media_debug_set_handler(
  76         struct media_device *media, void (*debug_handler)(void *, ...),
  77         void *debug_priv);
  78
  79 /**
  80  * @brief Open a media device with debugging enabled.
  81  * @param name - name (including path) of the device node.
  82  * @param verbose - whether to print verbose information on the standard output.
  83  * @param debug_handler - debug message handler
  84  * @param debug_priv - first argument to debug message handler
  85  *
  86  * Open the media device referenced by @a name and enumerate entities, pads and
  87  * links.
  88  *
  89  * Calling media_open_debug() instead of media_open() is equivalent to
  90  * media_open() and media_debug_set_handler() except that debugging is
  91  * also enabled during media_open().
  92  *
  93  * @return A pointer to a newly allocated media_device structure instance on
  94  * success and NULL on failure. The returned pointer must be freed with
  95  * media_close when the device isn't needed anymore.
  96  */
  97 struct media_device *media_open_debug(
  98         const char *name, int verbose, void (*debug_handler)(void *, ...),
  99         void *debug_priv);
 100
 101 /**
 102  * @brief Open a media device.
 103  * @param name - name (including path) of the device node.
 104  * @param verbose - whether to print verbose information on the standard output.
 105  *
 106  * Open the media device referenced by @a name and enumerate entities, pads and
 107  * links.
 108  *
 109  * @return A pointer to a newly allocated media_device structure instance on
 110  * success and NULL on failure. The returned pointer must be freed with
 111  * media_close when the device isn't needed anymore.
 112  */
 113 struct media_device *media_open(const char *name, int verbose);
 114
 115 /**
 116  * @brief Close a media device.
 117  * @param media - device instance.
 118  *
 119  * Close the @a media device instance and free allocated resources. Access to the
 120  * device instance is forbidden after this function returns.
 121  */
 122 void media_close(struct media_device *media);
 123
 124 /**
 125  * @brief Locate the pad at the other end of a link.
 126  * @param pad - sink pad at one end of the link.
 127  *
 128  * Locate the source pad connected to @a pad through an enabled link. As only one
 129  * link connected to a sink pad can be enabled at a time, the connected source
 130  * pad is guaranteed to be unique.
 131  *
 132  * @return A pointer to the connected source pad, or NULL if all links connected
 133  * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
 134  */
 135 struct media_pad *media_entity_remote_source(struct media_pad *pad);
 136
 137 /**
 138  * @brief Get the type of an entity.
 139  * @param entity - the entity.
 140  *
 141  * @return The type of @a entity.
 142  */
 143 static inline unsigned int media_entity_type(struct media_entity *entity)
 144 {
 145         return entity->info.type & MEDIA_ENT_TYPE_MASK;
 146 }
 147
 148 /**
 149  * @brief Find an entity by its name.
 150  * @param media - media device.
 151  * @param name - entity name.
 152  * @param length - size of @a name.
 153  *
 154  * Search for an entity with a name equal to @a name.
 155  *
 156  * @return A pointer to the entity if found, or NULL otherwise.
 157  */
 158 struct media_entity *media_get_entity_by_name(struct media_device *media,
 159         const char *name, size_t length);
 160
 161 /**
 162  * @brief Find an entity by its ID.
 163  * @param media - media device.
 164  * @param id - entity ID.
 165  *
 166  * Search for an entity with an ID equal to @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 Configure a link.
 175  * @param media - media device.
 176  * @param source - source pad at the link origin.
 177  * @param sink - sink pad at the link target.
 178  * @param flags - configuration flags.
 179  *
 180  * Locate the link between @a source and @a sink, and configure it by applying
 181  * the new @a flags.
 182  *
 183  * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
 184  *
 185  * @return 0 on success, -1 on failure:
 186  *         -ENOENT: link not found
 187  *         - other error codes returned by MEDIA_IOC_SETUP_LINK
 188  */
 189 int media_setup_link(struct media_device *media,
 190         struct media_pad *source, struct media_pad *sink,
 191         __u32 flags);
 192
 193 /**
 194  * @brief Reset all links to the disabled state.
 195  * @param media - media device.
 196  *
 197  * Disable all links in the media device. This function is usually used after
 198  * opening a media device to reset all links to a known state.
 199  *
 200  * @return 0 on success, or a negative error code on failure.
 201  */
 202 int media_reset_links(struct media_device *media);
 203
 204 /**
 205  * @brief Parse string to a pad on the media device.
 206  * @param media - media device.
 207  * @param p - input string
 208  * @param endp - pointer to string where parsing ended
 209  *
 210  * Parse NULL terminated string describing a pad and return its struct
 211  * media_pad instance.
 212  *
 213  * @return Pointer to struct media_pad on success, NULL on failure.
 214  */
 215 struct media_pad *media_parse_pad(struct media_device *media,
 216                                   const char *p, char **endp);
 217
 218 /**
 219  * @brief Parse string to a link on the media device.
 220  * @param media - media device.
 221  * @param p - input string
 222  * @param endp - pointer to p where parsing ended
 223  *
 224  * Parse NULL terminated string p describing a link and return its struct
 225  * media_link instance.
 226  *
 227  * @return Pointer to struct media_link on success, NULL on failure.
 228  */
 229 struct media_link *media_parse_link(struct media_device *media,
 230                                     const char *p, char **endp);
 231
 232 /**
 233  * @brief Parse string to a link on the media device and set it up.
 234  * @param media - media device.
 235  * @param p - input string
 236  *
 237  * Parse NULL terminated string p describing a link and its configuration
 238  * and configure the link.
 239  *
 240  * @return 0 on success, or a negative error code on failure.
 241  */
 242 int media_parse_setup_link(struct media_device *media,
 243                            const char *p, char **endp);
 244
 245 /**
 246  * @brief Parse string to link(s) on the media device and set it up.
 247  * @param media - media device.
 248  * @param p - input string
 249  *
 250  * Parse NULL terminated string p describing link(s) separated by
 251  * commas (,) and configure the link(s).
 252  *
 253  * @return 0 on success, or a negative error code on failure.
 254  */
 255 int media_parse_setup_links(struct media_device *media, const char *p);
 256
 257 #endif