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