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 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 struct media_link {
32 struct media_pad *source;
33 struct media_pad *sink;
34 struct media_link *twin;
35 __u32 flags;
36 __u32 padding[3];
37 };
38
39 struct media_pad {
40 struct media_entity *entity;
41 __u32 index;
42 __u32 flags;
43 __u32 padding[3];
44 };
45
46 struct media_device;
47 struct media_entity;
48
49 /**
50 * @brief Create a new media device.
51 * @param devnode - device node path.
52 *
53 * Create a media device instance for the given device node and return it. The
54 * device node is not accessed by this function, device node access errors will
55 * not be caught and reported here. The media device needs to be enumerated
56 * before it can be accessed, see media_device_enumerate().
57 *
58 * Media devices are reference-counted, see media_device_ref() and
59 * media_device_unref() for more information.
60 *
61 * @return A pointer to the new media device or NULL if memory cannot be
62 * allocated.
63 */
64 struct media_device *media_device_new(const char *devnode);
65
66 /**
67 * @brief Create a new emulated media device.
68 * @param info - device information.
69 *
70 * Emulated media devices are userspace-only objects not backed by a kernel
71 * media device. They are created for ALSA and V4L2 devices that are not
72 * associated with a media controller device.
73 *
74 * Only device query functions are available for media devices. Enumerating or
75 * setting up links is invalid.
76 *
77 * @return A pointer to the new media device or NULL if memory cannot be
78 * allocated.
79 */
80 struct media_device *media_device_new_emulated(struct media_device_info *info);
81
82 /**
83 * @brief Take a reference to the device.
84 * @param media - device instance.
85 *
86 * Media devices are reference-counted. Taking a reference to a device prevents
87 * it from being freed until all references are released. The reference count is
88 * initialized to 1 when the device is created.
89 *
90 * @return A pointer to @a media.
91 */
92 struct media_device *media_device_ref(struct media_device *media);
93
94 /**
95 * @brief Release a reference to the device.
96 * @param media - device instance.
97 *
98 * Release a reference to the media device. When the reference count reaches 0
99 * this function frees the device.
100 */
101 void media_device_unref(struct media_device *media);
102
103 /**
104 * @brief Add an entity to an existing media device
105 * @param media - device instance.
106 * @param desc - description of the entity to be added
107 * @param devnode - device node corresponding to the entity
108 *
109 * Entities are usually created and added to media devices automatically when
110 * the media device is enumerated through the media controller API. However,
111 * when an emulated media device (thus not backed with a kernel-side media
112 * controller device) is created, entities need to be manually added.
113 *
114 * Entities can also be manually added to a successfully enumerated media device
115 * to group several functions provided by separate kernel devices. The most
116 * common use case is to group the audio and video functions of a USB webcam in
117 * a single media device. Those functions are exposed through separate USB
118 * interfaces and handled through unrelated kernel drivers, they must thus be
119 * manually added to the same media device.
120 *
121 * This function adds a new entity to the given media device and initializes it
122 * from the given entity description and device node name. Only the following
123 * fields of the description are copied over to the new entity:
124 *
125 * - type
126 * - flags (MEDIA_ENT_FL_DEFAULT only)
127 * - name
128 * - v4l, fb, alsa or dvb (depending on the device type)
129 *
130 * All other fields of the newly created entity id are initialized to 0,
131 * including the entity ID.
132 *
133 * @return Zero on success or -ENOMEM if memory cannot be allocated.
134 */
135 int media_device_add_entity(struct media_device *media,
136 const struct media_entity_desc *desc,
137 const char *devnode);
138
139 /**
140 * @brief Set a handler for debug messages.
141 * @param media - device instance.
142 * @param debug_handler - debug message handler
143 * @param debug_priv - first argument to debug message handler
144 *
145 * Set a handler for debug messages that will be called whenever
146 * debugging information is to be printed. The handler expects an
147 * fprintf-like function.
148 */
149 void media_debug_set_handler(
150 struct media_device *media, void (*debug_handler)(void *, ...),
151 void *debug_priv);
152
153 /**
154 * @brief Enumerate the device topology
155 * @param media - device instance.
156 *
157 * Enumerate the media device entities, pads and links. Calling this function is
158 * mandatory before accessing the media device contents.
159 *
160 * @return Zero on success or a negative error code on failure.
161 */
162 int media_device_enumerate(struct media_device *media);
163
164 /**
165 * @brief Locate the pad at the other end of a link.
166 * @param pad - sink pad at one end of the link.
167 *
168 * Locate the source pad connected to @a pad through an enabled link. As only one
169 * link connected to a sink pad can be enabled at a time, the connected source
170 * pad is guaranteed to be unique.
171 *
172 * @return A pointer to the connected source pad, or NULL if all links connected
173 * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
174 */
175 struct media_pad *media_entity_remote_source(struct media_pad *pad);
176
177 /**
178 * @brief Get information about a media entity
179 * @param entity - media entity.
180 *
181 * The information structure is owned by the media entity object and will be
182 * freed when the object is destroyed.
183 *
184 * @return A pointer to the media entity information
185 */
186 const struct media_entity_desc *media_entity_get_info(struct media_entity *entity);
187
188 /**
189 * @brief Get an entity pad
190 * @param entity - media entity.
191 * @param index - pad index.
192 *
193 * This function returns a pointer to the pad object identified by its index
194 * for the given entity. If the pad index is out of bounds it will return NULL.
195 *
196 * @return A pointer to the pad
197 */
198 const struct media_pad *media_entity_get_pad(struct media_entity *entity,
199 unsigned int index);
200
201 /**
202 * @brief Get the number of links
203 * @param entity - media entity.
204 *
205 * This function returns the total number of links that originate from or arrive
206 * at the the media entity.
207 *
208 * @return The number of links for the entity
209 */
210 unsigned int media_entity_get_links_count(struct media_entity *entity);
211
212 /**
213 * @brief Get an entity link
214 * @param entity - media entity.
215 * @param index - link index.
216 *
217 * This function returns a pointer to the link object identified by its index
218 * for the given entity. If the link index is out of bounds it will return NULL.
219 *
220 * @return A pointer to the link
221 */
222 const struct media_link *media_entity_get_link(struct media_entity *entity,
223 unsigned int index);
224
225 /**
226 * @brief Get the device node name for an entity
227 * @param entity - media entity.
228 *
229 * This function returns the full path and name to the device node corresponding
230 * to the given entity.
231 *
232 * @return A pointer to the device node name or NULL if the entity has no
233 * associated device node
234 */
235 const char *media_entity_get_devname(struct media_entity *entity);
236
237 /**
238 * @brief Get the type of an entity.
239 * @param entity - the entity.
240 *
241 * @return The type of @a entity.
242 */
media_entity_type(struct media_entity * entity)243 static inline unsigned int media_entity_type(struct media_entity *entity)
244 {
245 return media_entity_get_info(entity)->type & MEDIA_ENT_TYPE_MASK;
246 }
247
248 /**
249 * @brief Find an entity by its name.
250 * @param media - media device.
251 * @param name - entity name.
252 * @param length - size of @a name.
253 *
254 * Search for an entity with a name equal to @a name.
255 *
256 * @return A pointer to the entity if found, or NULL otherwise.
257 */
258 struct media_entity *media_get_entity_by_name(struct media_device *media,
259 const char *name, size_t length);
260
261 /**
262 * @brief Find an entity by its ID.
263 * @param media - media device.
264 * @param id - entity ID.
265 *
266 * This function searches for an entity based on its ID using an exact match or
267 * next ID method based on the given @a id. If @a id is ORed with
268 * MEDIA_ENT_ID_FLAG_NEXT, the function will return the entity with the smallest
269 * ID larger than @a id. Otherwise it will return the entity with an ID equal to
270 * @a id.
271 *
272 * @return A pointer to the entity if found, or NULL otherwise.
273 */
274 struct media_entity *media_get_entity_by_id(struct media_device *media,
275 __u32 id);
276
277 /**
278 * @brief Get the number of entities
279 * @param media - media device.
280 *
281 * This function returns the total number of entities in the media device. If
282 * entities haven't been enumerated yet it will return 0.
283 *
284 * @return The number of entities in the media device
285 */
286 unsigned int media_get_entities_count(struct media_device *media);
287
288 /**
289 * @brief Get the entities
290 * @param media - media device.
291 *
292 * This function returns a pointer to the array of entities for the media
293 * device. If entities haven't been enumerated yet it will return NULL.
294 *
295 * The array of entities is owned by the media device object and will be freed
296 * when the media object is destroyed.
297 *
298 * @return A pointer to an array of entities
299 */
300 struct media_entity *media_get_entity(struct media_device *media, unsigned int index);
301
302 /**
303 * @brief Get the default entity for a given type
304 * @param media - media device.
305 * @param type - entity type.
306 *
307 * This function returns the default entity of the requested type. @a type must
308 * be one of
309 *
310 * MEDIA_ENT_T_DEVNODE_V4L
311 * MEDIA_ENT_T_DEVNODE_FB
312 * MEDIA_ENT_T_DEVNODE_ALSA
313 * MEDIA_ENT_T_DEVNODE_DVB
314 *
315 * @return A pointer to the default entity for the type if it exists, or NULL
316 * otherwise.
317 */
318 struct media_entity *media_get_default_entity(struct media_device *media,
319 unsigned int type);
320
321 /**
322 * @brief Get the media device information
323 * @param media - media device.
324 *
325 * The information structure is owned by the media device object and will be freed
326 * when the media object is destroyed.
327 *
328 * @return A pointer to the media device information
329 */
330 const struct media_device_info *media_get_info(struct media_device *media);
331
332 /**
333 * @brief Get the media device node name
334 * @param media - media device.
335 *
336 * The device node name string is owned by the media device object and will be
337 * freed when the media object is destroyed.
338 *
339 * @return A pointer to the media device node name
340 */
341 const char *media_get_devnode(struct media_device *media);
342
343 /**
344 * @brief Configure a link.
345 * @param media - media device.
346 * @param source - source pad at the link origin.
347 * @param sink - sink pad at the link target.
348 * @param flags - configuration flags.
349 *
350 * Locate the link between @a source and @a sink, and configure it by applying
351 * the new @a flags.
352 *
353 * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
354 *
355 * @return 0 on success, -1 on failure:
356 * -ENOENT: link not found
357 * - other error codes returned by MEDIA_IOC_SETUP_LINK
358 */
359 int media_setup_link(struct media_device *media,
360 struct media_pad *source, struct media_pad *sink,
361 __u32 flags);
362
363 /**
364 * @brief Reset all links to the disabled state.
365 * @param media - media device.
366 *
367 * Disable all links in the media device. This function is usually used after
368 * opening a media device to reset all links to a known state.
369 *
370 * @return 0 on success, or a negative error code on failure.
371 */
372 int media_reset_links(struct media_device *media);
373
374 /**
375 * @brief Parse string to a pad on the media device.
376 * @param media - media device.
377 * @param p - input string
378 * @param endp - pointer to string where parsing ended
379 *
380 * Parse NULL terminated string describing a pad and return its struct
381 * media_pad instance.
382 *
383 * @return Pointer to struct media_pad on success, NULL on failure.
384 */
385 struct media_pad *media_parse_pad(struct media_device *media,
386 const char *p, char **endp);
387
388 /**
389 * @brief Parse string to a link on the media device.
390 * @param media - media device.
391 * @param p - input string
392 * @param endp - pointer to p where parsing ended
393 *
394 * Parse NULL terminated string p describing a link and return its struct
395 * media_link instance.
396 *
397 * @return Pointer to struct media_link on success, NULL on failure.
398 */
399 struct media_link *media_parse_link(struct media_device *media,
400 const char *p, char **endp);
401
402 /**
403 * @brief Parse string to a link on the media device and set it up.
404 * @param media - media device.
405 * @param p - input string
406 *
407 * Parse NULL terminated string p describing a link and its configuration
408 * and configure the link.
409 *
410 * @return 0 on success, or a negative error code on failure.
411 */
412 int media_parse_setup_link(struct media_device *media,
413 const char *p, char **endp);
414
415 /**
416 * @brief Parse string to link(s) on the media device and set it up.
417 * @param media - media device.
418 * @param p - input string
419 *
420 * Parse NULL terminated string p describing link(s) separated by
421 * commas (,) and configure the link(s).
422 *
423 * @return 0 on success, or a negative error code on failure.
424 */
425 int media_parse_setup_links(struct media_device *media, const char *p);
426
427 #ifdef __cplusplus
428 }
429 #endif // __cplusplus
430
431 #endif
432