2 * Media controller interface library
4 * Copyright (C) 2010 Ideas on board SPRL <laurent.pinchart@ideasonboard.com>
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.
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.
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.,
23 #include <linux/media.h>
26 struct media_pad *source;
27 struct media_pad *sink;
28 struct media_link *twin;
34 struct media_entity *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;
55 struct media_entity *entities;
56 unsigned int entities_count;
57 void (*debug_handler)(void *, ...);
62 #define media_dbg(media, ...) \
63 (media)->debug_handler((media)->debug_priv, __VA_ARGS__)
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
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.
75 void media_debug_set_handler(
76 struct media_device *media, void (*debug_handler)(void *, ...),
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
86 * Open the media device referenced by @a name and enumerate entities, pads and
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().
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.
97 struct media_device *media_open_debug(
98 const char *name, int verbose, void (*debug_handler)(void *, ...),
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.
106 * Open the media device referenced by @a name and enumerate entities, pads and
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.
113 struct media_device *media_open(const char *name, int verbose);
116 * @brief Close a media device.
117 * @param media - device instance.
119 * Close the @a media device instance and free allocated resources. Access to the
120 * device instance is forbidden after this function returns.
122 void media_close(struct media_device *media);
125 * @brief Locate the pad at the other end of a link.
126 * @param pad - sink pad at one end of the link.
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.
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.
135 struct media_pad *media_entity_remote_source(struct media_pad *pad);
138 * @brief Get the type of an entity.
139 * @param entity - the entity.
141 * @return The type of @a entity.
143 static inline unsigned int media_entity_type(struct media_entity *entity)
145 return entity->info.type & MEDIA_ENT_TYPE_MASK;
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.
154 * Search for an entity with a name equal to @a name.
156 * @return A pointer to the entity if found, or NULL otherwise.
158 struct media_entity *media_get_entity_by_name(struct media_device *media,
159 const char *name, size_t length);
162 * @brief Find an entity by its ID.
163 * @param media - media device.
164 * @param id - entity ID.
166 * Search for an entity with an ID equal to @a id.
168 * @return A pointer to the entity if found, or NULL otherwise.
170 struct media_entity *media_get_entity_by_id(struct media_device *media,
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.
180 * Locate the link between @a source and @a sink, and configure it by applying
183 * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
185 * @return 0 on success, -1 on failure:
186 * -ENOENT: link not found
187 * - other error codes returned by MEDIA_IOC_SETUP_LINK
189 int media_setup_link(struct media_device *media,
190 struct media_pad *source, struct media_pad *sink,
194 * @brief Reset all links to the disabled state.
195 * @param media - media device.
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.
200 * @return 0 on success, or a negative error code on failure.
202 int media_reset_links(struct media_device *media);
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
210 * Parse NULL terminated string describing a pad and return its struct
211 * media_pad instance.
213 * @return Pointer to struct media_pad on success, NULL on failure.
215 struct media_pad *media_parse_pad(struct media_device *media,
216 const char *p, char **endp);
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
224 * Parse NULL terminated string p describing a link and return its struct
225 * media_link instance.
227 * @return Pointer to struct media_link on success, NULL on failure.
229 struct media_link *media_parse_link(struct media_device *media,
230 const char *p, char **endp);
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
237 * Parse NULL terminated string p describing a link and its configuration
238 * and configure the link.
240 * @return 0 on success, or a negative error code on failure.
242 int media_parse_setup_link(struct media_device *media,
243 const char *p, char **endp);
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
250 * Parse NULL terminated string p describing link(s) separated by
251 * commas (,) and configure the link(s).
253 * @return 0 on success, or a negative error code on failure.
255 int media_parse_setup_links(struct media_device *media, const char *p);