2 * Media controller interface library
4 * Copyright (C) 2010-2011 Ideas on board SPRL
6 * Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
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.
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.
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/>.
25 #include <linux/media.h>
28 struct media_pad *source;
29 struct media_pad *sink;
30 struct media_link *twin;
36 struct media_entity *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;
58 * @brief Create a new media device.
59 * @param devnode - device node path.
61 * Create a media device instance for the given device node and return it. The
62 * device node is not accessed by this function, device node access errors will
63 * not be caught and reported here. The media device needs to be enumerated
64 * before it can be accessed, see media_device_enumerate().
66 * Media devices are reference-counted, see media_device_ref() and
67 * media_device_unref() for more information.
69 * @return A pointer to the new media device or NULL if memory cannot be
72 struct media_device *media_device_new(const char *devnode);
75 * @brief Take a reference to the device.
76 * @param media - device instance.
78 * Media devices are reference-counted. Taking a reference to a device prevents
79 * it from being freed until all references are released. The reference count is
80 * initialized to 1 when the device is created.
82 * @return A pointer to @a media.
84 struct media_device *media_device_ref(struct media_device *media);
87 * @brief Release a reference to the device.
88 * @param media - device instance.
90 * Release a reference to the media device. When the reference count reaches 0
91 * this function frees the device.
93 void media_device_unref(struct media_device *media);
96 * @brief Set a handler for debug messages.
97 * @param media - device instance.
98 * @param debug_handler - debug message handler
99 * @param debug_priv - first argument to debug message handler
101 * Set a handler for debug messages that will be called whenever
102 * debugging information is to be printed. The handler expects an
103 * fprintf-like function.
105 void media_debug_set_handler(
106 struct media_device *media, void (*debug_handler)(void *, ...),
110 * @brief Enumerate the device topology
111 * @param media - device instance.
113 * Enumerate the media device entities, pads and links. Calling this function is
114 * mandatory before accessing the media device contents.
116 * @return Zero on success or a negative error code on failure.
118 int media_device_enumerate(struct media_device *media);
121 * @brief Locate the pad at the other end of a link.
122 * @param pad - sink pad at one end of the link.
124 * Locate the source pad connected to @a pad through an enabled link. As only one
125 * link connected to a sink pad can be enabled at a time, the connected source
126 * pad is guaranteed to be unique.
128 * @return A pointer to the connected source pad, or NULL if all links connected
129 * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
131 struct media_pad *media_entity_remote_source(struct media_pad *pad);
134 * @brief Get the type of an entity.
135 * @param entity - the entity.
137 * @return The type of @a entity.
139 static inline unsigned int media_entity_type(struct media_entity *entity)
141 return entity->info.type & MEDIA_ENT_TYPE_MASK;
145 * @brief Find an entity by its name.
146 * @param media - media device.
147 * @param name - entity name.
148 * @param length - size of @a name.
150 * Search for an entity with a name equal to @a name.
152 * @return A pointer to the entity if found, or NULL otherwise.
154 struct media_entity *media_get_entity_by_name(struct media_device *media,
155 const char *name, size_t length);
158 * @brief Find an entity by its ID.
159 * @param media - media device.
160 * @param id - entity ID.
162 * This function searches for an entity based on its ID using an exact match or
163 * next ID method based on the given @a id. If @a id is ORed with
164 * MEDIA_ENT_ID_FLAG_NEXT, the function will return the entity with the smallest
165 * ID larger than @a id. Otherwise it will return the entity with an ID equal to
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 Get the number of entities
175 * @param media - media device.
177 * This function returns the total number of entities in the media device. If
178 * entities haven't been enumerated yet it will return 0.
180 * @return The number of entities in the media device
182 unsigned int media_get_entities_count(struct media_device *media);
185 * @brief Get the entities
186 * @param media - media device.
188 * This function returns a pointer to the array of entities for the media
189 * device. If entities haven't been enumerated yet it will return NULL.
191 * The array of entities is owned by the media device object and will be freed
192 * when the media object is destroyed.
194 * @return A pointer to an array of entities
196 struct media_entity *media_get_entities(struct media_device *media);
199 * @brief Get the media device information
200 * @param media - media device.
202 * The information structure is owned by the media device object and will be freed
203 * when the media object is destroyed.
205 * @return A pointer to the media device information
207 const struct media_device_info *media_get_info(struct media_device *media);
210 * @brief Get the media device node name
211 * @param media - media device.
213 * The device node name string is owned by the media device object and will be
214 * freed when the media object is destroyed.
216 * @return A pointer to the media device node name
218 const char *media_get_devnode(struct media_device *media);
221 * @brief Configure a link.
222 * @param media - media device.
223 * @param source - source pad at the link origin.
224 * @param sink - sink pad at the link target.
225 * @param flags - configuration flags.
227 * Locate the link between @a source and @a sink, and configure it by applying
230 * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
232 * @return 0 on success, -1 on failure:
233 * -ENOENT: link not found
234 * - other error codes returned by MEDIA_IOC_SETUP_LINK
236 int media_setup_link(struct media_device *media,
237 struct media_pad *source, struct media_pad *sink,
241 * @brief Reset all links to the disabled state.
242 * @param media - media device.
244 * Disable all links in the media device. This function is usually used after
245 * opening a media device to reset all links to a known state.
247 * @return 0 on success, or a negative error code on failure.
249 int media_reset_links(struct media_device *media);
252 * @brief Parse string to a pad on the media device.
253 * @param media - media device.
254 * @param p - input string
255 * @param endp - pointer to string where parsing ended
257 * Parse NULL terminated string describing a pad and return its struct
258 * media_pad instance.
260 * @return Pointer to struct media_pad on success, NULL on failure.
262 struct media_pad *media_parse_pad(struct media_device *media,
263 const char *p, char **endp);
266 * @brief Parse string to a link on the media device.
267 * @param media - media device.
268 * @param p - input string
269 * @param endp - pointer to p where parsing ended
271 * Parse NULL terminated string p describing a link and return its struct
272 * media_link instance.
274 * @return Pointer to struct media_link on success, NULL on failure.
276 struct media_link *media_parse_link(struct media_device *media,
277 const char *p, char **endp);
280 * @brief Parse string to a link on the media device and set it up.
281 * @param media - media device.
282 * @param p - input string
284 * Parse NULL terminated string p describing a link and its configuration
285 * and configure the link.
287 * @return 0 on success, or a negative error code on failure.
289 int media_parse_setup_link(struct media_device *media,
290 const char *p, char **endp);
293 * @brief Parse string to link(s) on the media device and set it up.
294 * @param media - media device.
295 * @param p - input string
297 * Parse NULL terminated string p describing link(s) separated by
298 * commas (,) and configure the link(s).
300 * @return 0 on success, or a negative error code on failure.
302 int media_parse_setup_links(struct media_device *media, const char *p);