Make the media_entity structure private
[media-ctl.git] / 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_device;
43 struct media_entity;
44
45 /**
46  * @brief Create a new media device.
47  * @param devnode - device node path.
48  *
49  * Create a media device instance for the given device node and return it. The
50  * device node is not accessed by this function, device node access errors will
51  * not be caught and reported here. The media device needs to be enumerated
52  * before it can be accessed, see media_device_enumerate().
53  *
54  * Media devices are reference-counted, see media_device_ref() and
55  * media_device_unref() for more information.
56  *
57  * @return A pointer to the new media device or NULL if memory cannot be
58  * allocated.
59  */
60 struct media_device *media_device_new(const char *devnode);
61
62 /**
63  * @brief Take a reference to the device.
64  * @param media - device instance.
65  *
66  * Media devices are reference-counted. Taking a reference to a device prevents
67  * it from being freed until all references are released. The reference count is
68  * initialized to 1 when the device is created.
69  *
70  * @return A pointer to @a media.
71  */
72 struct media_device *media_device_ref(struct media_device *media);
73
74 /**
75  * @brief Release a reference to the device.
76  * @param media - device instance.
77  *
78  * Release a reference to the media device. When the reference count reaches 0
79  * this function frees the device.
80  */
81 void media_device_unref(struct media_device *media);
82
83 /**
84  * @brief Set a handler for debug messages.
85  * @param media - device instance.
86  * @param debug_handler - debug message handler
87  * @param debug_priv - first argument to debug message handler
88  *
89  * Set a handler for debug messages that will be called whenever
90  * debugging information is to be printed. The handler expects an
91  * fprintf-like function.
92  */
93 void media_debug_set_handler(
94         struct media_device *media, void (*debug_handler)(void *, ...),
95         void *debug_priv);
96
97 /**
98  * @brief Enumerate the device topology
99  * @param media - device instance.
100  *
101  * Enumerate the media device entities, pads and links. Calling this function is
102  * mandatory before accessing the media device contents.
103  *
104  * @return Zero on success or a negative error code on failure.
105  */
106 int media_device_enumerate(struct media_device *media);
107
108 /**
109  * @brief Locate the pad at the other end of a link.
110  * @param pad - sink pad at one end of the link.
111  *
112  * Locate the source pad connected to @a pad through an enabled link. As only one
113  * link connected to a sink pad can be enabled at a time, the connected source
114  * pad is guaranteed to be unique.
115  *
116  * @return A pointer to the connected source pad, or NULL if all links connected
117  * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
118  */
119 struct media_pad *media_entity_remote_source(struct media_pad *pad);
120
121 /**
122  * @brief Get information about a media entity
123  * @param entity - media entity.
124  *
125  * The information structure is owned by the media entity object and will be
126  * freed when the object is destroyed.
127  *
128  * @return A pointer to the media entity information
129  */
130 const struct media_entity_desc *media_entity_get_info(struct media_entity *entity);
131
132 /**
133  * @brief Get an entity pad
134  * @param entity - media entity.
135  * @param index - pad index.
136  *
137  * This function returns a pointer to the pad object identified by its index
138  * for the given entity. If the pad index is out of bounds it will return NULL.
139  *
140  * @return A pointer to the pad
141  */
142 const struct media_pad *media_entity_get_pad(struct media_entity *entity,
143                                              unsigned int index);
144
145 /**
146  * @brief Get the number of links
147  * @param entity - media entity.
148  *
149  * This function returns the total number of links that originate from or arrive
150  * at the the media entity.
151  *
152  * @return The number of links for the entity
153  */
154 unsigned int media_entity_get_links_count(struct media_entity *entity);
155
156 /**
157  * @brief Get an entity link
158  * @param entity - media entity.
159  * @param index - link index.
160  *
161  * This function returns a pointer to the link object identified by its index
162  * for the given entity. If the link index is out of bounds it will return NULL.
163  *
164  * @return A pointer to the link
165  */
166 const struct media_link *media_entity_get_link(struct media_entity *entity,
167                                                unsigned int index);
168
169 /**
170  * @brief Get the device node name for an entity
171  * @param entity - media entity.
172  *
173  * This function returns the full path and name to the device node corresponding
174  * to the given entity.
175  *
176  * @return A pointer to the device node name or NULL if the entity has no
177  * associated device node
178  */
179 const char *media_entity_get_devname(struct media_entity *entity);
180
181 /**
182  * @brief Get the type of an entity.
183  * @param entity - the entity.
184  *
185  * @return The type of @a entity.
186  */
187 static inline unsigned int media_entity_type(struct media_entity *entity)
188 {
189         return media_entity_get_info(entity)->type & MEDIA_ENT_TYPE_MASK;
190 }
191
192 /**
193  * @brief Find an entity by its name.
194  * @param media - media device.
195  * @param name - entity name.
196  * @param length - size of @a name.
197  *
198  * Search for an entity with a name equal to @a name.
199  *
200  * @return A pointer to the entity if found, or NULL otherwise.
201  */
202 struct media_entity *media_get_entity_by_name(struct media_device *media,
203         const char *name, size_t length);
204
205 /**
206  * @brief Find an entity by its ID.
207  * @param media - media device.
208  * @param id - entity ID.
209  *
210  * This function searches for an entity based on its ID using an exact match or
211  * next ID method based on the given @a id. If @a id is ORed with
212  * MEDIA_ENT_ID_FLAG_NEXT, the function will return the entity with the smallest
213  * ID larger than @a id. Otherwise it will return the entity with an ID equal to
214  * @a id.
215  *
216  * @return A pointer to the entity if found, or NULL otherwise.
217  */
218 struct media_entity *media_get_entity_by_id(struct media_device *media,
219         __u32 id);
220
221 /**
222  * @brief Get the number of entities
223  * @param media - media device.
224  *
225  * This function returns the total number of entities in the media device. If
226  * entities haven't been enumerated yet it will return 0.
227  *
228  * @return The number of entities in the media device
229  */
230 unsigned int media_get_entities_count(struct media_device *media);
231
232 /**
233  * @brief Get the entities
234  * @param media - media device.
235  *
236  * This function returns a pointer to the array of entities for the media
237  * device. If entities haven't been enumerated yet it will return NULL.
238  *
239  * The array of entities is owned by the media device object and will be freed
240  * when the media object is destroyed.
241  *
242  * @return A pointer to an array of entities
243  */
244 struct media_entity *media_get_entity(struct media_device *media, unsigned int index);
245
246 /**
247  * @brief Get the media device information
248  * @param media - media device.
249  *
250  * The information structure is owned by the media device object and will be freed
251  * when the media object is destroyed.
252  *
253  * @return A pointer to the media device information
254  */
255 const struct media_device_info *media_get_info(struct media_device *media);
256
257 /**
258  * @brief Get the media device node name
259  * @param media - media device.
260  *
261  * The device node name string is owned by the media device object and will be
262  * freed when the media object is destroyed.
263  *
264  * @return A pointer to the media device node name
265  */
266 const char *media_get_devnode(struct media_device *media);
267
268 /**
269  * @brief Configure a link.
270  * @param media - media device.
271  * @param source - source pad at the link origin.
272  * @param sink - sink pad at the link target.
273  * @param flags - configuration flags.
274  *
275  * Locate the link between @a source and @a sink, and configure it by applying
276  * the new @a flags.
277  *
278  * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
279  *
280  * @return 0 on success, -1 on failure:
281  *         -ENOENT: link not found
282  *         - other error codes returned by MEDIA_IOC_SETUP_LINK
283  */
284 int media_setup_link(struct media_device *media,
285         struct media_pad *source, struct media_pad *sink,
286         __u32 flags);
287
288 /**
289  * @brief Reset all links to the disabled state.
290  * @param media - media device.
291  *
292  * Disable all links in the media device. This function is usually used after
293  * opening a media device to reset all links to a known state.
294  *
295  * @return 0 on success, or a negative error code on failure.
296  */
297 int media_reset_links(struct media_device *media);
298
299 /**
300  * @brief Parse string to a pad on the media device.
301  * @param media - media device.
302  * @param p - input string
303  * @param endp - pointer to string where parsing ended
304  *
305  * Parse NULL terminated string describing a pad and return its struct
306  * media_pad instance.
307  *
308  * @return Pointer to struct media_pad on success, NULL on failure.
309  */
310 struct media_pad *media_parse_pad(struct media_device *media,
311                                   const char *p, char **endp);
312
313 /**
314  * @brief Parse string to a link on the media device.
315  * @param media - media device.
316  * @param p - input string
317  * @param endp - pointer to p where parsing ended
318  *
319  * Parse NULL terminated string p describing a link and return its struct
320  * media_link instance.
321  *
322  * @return Pointer to struct media_link on success, NULL on failure.
323  */
324 struct media_link *media_parse_link(struct media_device *media,
325                                     const char *p, char **endp);
326
327 /**
328  * @brief Parse string to a link on the media device and set it up.
329  * @param media - media device.
330  * @param p - input string
331  *
332  * Parse NULL terminated string p describing a link and its configuration
333  * and configure the link.
334  *
335  * @return 0 on success, or a negative error code on failure.
336  */
337 int media_parse_setup_link(struct media_device *media,
338                            const char *p, char **endp);
339
340 /**
341  * @brief Parse string to link(s) on the media device and set it up.
342  * @param media - media device.
343  * @param p - input string
344  *
345  * Parse NULL terminated string p describing link(s) separated by
346  * commas (,) and configure the link(s).
347  *
348  * @return 0 on success, or a negative error code on failure.
349  */
350 int media_parse_setup_links(struct media_device *media, const char *p);
351
352 #endif