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         int fd;
  57         struct media_device_info info;
  58         struct media_entity *entities;
  59         unsigned int entities_count;
  60         void (*debug_handler)(void *, ...);
  61         void *debug_priv;
  62         __u32 padding[6];
  63 };
  64
  65 #define media_dbg(media, ...) \
  66         (media)->debug_handler((media)->debug_priv, __VA_ARGS__)
  67
  68 /**
  69  * @brief Set a handler for debug messages.
  70  * @param media - device instance.
  71  * @param debug_handler - debug message handler
  72  * @param debug_priv - first argument to debug message handler
  73  *
  74  * Set a handler for debug messages that will be called whenever
  75  * debugging information is to be printed. The handler expects an
  76  * fprintf-like function.
  77  */
  78 void media_debug_set_handler(
  79         struct media_device *media, void (*debug_handler)(void *, ...),
  80         void *debug_priv);
  81
  82 /**
  83  * @brief Open a media device with debugging enabled.
  84  * @param name - name (including path) of the device node.
  85  * @param debug_handler - debug message handler
  86  * @param debug_priv - first argument to debug message handler
  87  *
  88  * Open the media device referenced by @a name and enumerate entities, pads and
  89  * links.
  90  *
  91  * Calling media_open_debug() instead of media_open() is equivalent to
  92  * media_open() and media_debug_set_handler() except that debugging is
  93  * also enabled during media_open().
  94  *
  95  * @return A pointer to a newly allocated media_device structure instance on
  96  * success and NULL on failure. The returned pointer must be freed with
  97  * media_close when the device isn't needed anymore.
  98  */
  99 struct media_device *media_open_debug(
 100         const char *name, void (*debug_handler)(void *, ...),
 101         void *debug_priv);
 102
 103 /**
 104  * @brief Open a media device.
 105  * @param name - name (including path) of the device node.
 106  *
 107  * Open the media device referenced by @a name and enumerate entities, pads and
 108  * links.
 109  *
 110  * @return A pointer to a newly allocated media_device structure instance on
 111  * success and NULL on failure. The returned pointer must be freed with
 112  * media_close when the device isn't needed anymore.
 113  */
 114 struct media_device *media_open(const char *name);
 115
 116 /**
 117  * @brief Close a media device.
 118  * @param media - device instance.
 119  *
 120  * Close the @a media device instance and free allocated resources. Access to the
 121  * device instance is forbidden after this function returns.
 122  */
 123 void media_close(struct media_device *media);
 124
 125 /**
 126  * @brief Locate the pad at the other end of a link.
 127  * @param pad - sink pad at one end of the link.
 128  *
 129  * Locate the source pad connected to @a pad through an enabled link. As only one
 130  * link connected to a sink pad can be enabled at a time, the connected source
 131  * pad is guaranteed to be unique.
 132  *
 133  * @return A pointer to the connected source pad, or NULL if all links connected
 134  * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
 135  */
 136 struct media_pad *media_entity_remote_source(struct media_pad *pad);
 137
 138 /**
 139  * @brief Get the type of an entity.
 140  * @param entity - the entity.
 141  *
 142  * @return The type of @a entity.
 143  */
 144 static inline unsigned int media_entity_type(struct media_entity *entity)
 145 {
 146         return entity->info.type & MEDIA_ENT_TYPE_MASK;
 147 }
 148
 149 /**
 150  * @brief Find an entity by its name.
 151  * @param media - media device.
 152  * @param name - entity name.
 153  * @param length - size of @a name.
 154  *
 155  * Search for an entity with a name equal to @a name.
 156  *
 157  * @return A pointer to the entity if found, or NULL otherwise.
 158  */
 159 struct media_entity *media_get_entity_by_name(struct media_device *media,
 160         const char *name, size_t length);
 161
 162 /**
 163  * @brief Find an entity by its ID.
 164  * @param media - media device.
 165  * @param id - entity ID.
 166  *
 167  * This function searches for an entity based on its ID using an exact match or
 168  * next ID method based on the given @a id. If @a id is ORed with
 169  * MEDIA_ENT_ID_FLAG_NEXT, the function will return the entity with the smallest
 170  * ID larger than @a id. Otherwise it will return the entity with an ID equal to
 171  * @a id.
 172  *
 173  * @return A pointer to the entity if found, or NULL otherwise.
 174  */
 175 struct media_entity *media_get_entity_by_id(struct media_device *media,
 176         __u32 id);
 177
 178 /**
 179  * @brief Configure a link.
 180  * @param media - media device.
 181  * @param source - source pad at the link origin.
 182  * @param sink - sink pad at the link target.
 183  * @param flags - configuration flags.
 184  *
 185  * Locate the link between @a source and @a sink, and configure it by applying
 186  * the new @a flags.
 187  *
 188  * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
 189  *
 190  * @return 0 on success, -1 on failure:
 191  *         -ENOENT: link not found
 192  *         - other error codes returned by MEDIA_IOC_SETUP_LINK
 193  */
 194 int media_setup_link(struct media_device *media,
 195         struct media_pad *source, struct media_pad *sink,
 196         __u32 flags);
 197
 198 /**
 199  * @brief Reset all links to the disabled state.
 200  * @param media - media device.
 201  *
 202  * Disable all links in the media device. This function is usually used after
 203  * opening a media device to reset all links to a known state.
 204  *
 205  * @return 0 on success, or a negative error code on failure.
 206  */
 207 int media_reset_links(struct media_device *media);
 208
 209 /**
 210  * @brief Parse string to a pad on the media device.
 211  * @param media - media device.
 212  * @param p - input string
 213  * @param endp - pointer to string where parsing ended
 214  *
 215  * Parse NULL terminated string describing a pad and return its struct
 216  * media_pad instance.
 217  *
 218  * @return Pointer to struct media_pad on success, NULL on failure.
 219  */
 220 struct media_pad *media_parse_pad(struct media_device *media,
 221                                   const char *p, char **endp);
 222
 223 /**
 224  * @brief Parse string to a link on the media device.
 225  * @param media - media device.
 226  * @param p - input string
 227  * @param endp - pointer to p where parsing ended
 228  *
 229  * Parse NULL terminated string p describing a link and return its struct
 230  * media_link instance.
 231  *
 232  * @return Pointer to struct media_link on success, NULL on failure.
 233  */
 234 struct media_link *media_parse_link(struct media_device *media,
 235                                     const char *p, char **endp);
 236
 237 /**
 238  * @brief Parse string to a link on the media device and set it up.
 239  * @param media - media device.
 240  * @param p - input string
 241  *
 242  * Parse NULL terminated string p describing a link and its configuration
 243  * and configure the link.
 244  *
 245  * @return 0 on success, or a negative error code on failure.
 246  */
 247 int media_parse_setup_link(struct media_device *media,
 248                            const char *p, char **endp);
 249
 250 /**
 251  * @brief Parse string to link(s) on the media device and set it up.
 252  * @param media - media device.
 253  * @param p - input string
 254  *
 255  * Parse NULL terminated string p describing link(s) separated by
 256  * commas (,) and configure the link(s).
 257  *
 258  * @return 0 on success, or a negative error code on failure.
 259  */
 260 int media_parse_setup_links(struct media_device *media, const char *p);
 261
 262 #endif