Make the media_device 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_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
57 /**
58  * @brief Create a new media device.
59  * @param devnode - device node path.
60  *
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().
65  *
66  * Media devices are reference-counted, see media_device_ref() and
67  * media_device_unref() for more information.
68  *
69  * @return A pointer to the new media device or NULL if memory cannot be
70  * allocated.
71  */
72 struct media_device *media_device_new(const char *devnode);
73
74 /**
75  * @brief Take a reference to the device.
76  * @param media - device instance.
77  *
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.
81  *
82  * @return A pointer to @a media.
83  */
84 struct media_device *media_device_ref(struct media_device *media);
85
86 /**
87  * @brief Release a reference to the device.
88  * @param media - device instance.
89  *
90  * Release a reference to the media device. When the reference count reaches 0
91  * this function frees the device.
92  */
93 void media_device_unref(struct media_device *media);
94
95 /**
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
100  *
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.
104  */
105 void media_debug_set_handler(
106         struct media_device *media, void (*debug_handler)(void *, ...),
107         void *debug_priv);
108
109 /**
110  * @brief Enumerate the device topology
111  * @param media - device instance.
112  *
113  * Enumerate the media device entities, pads and links. Calling this function is
114  * mandatory before accessing the media device contents.
115  *
116  * @return Zero on success or a negative error code on failure.
117  */
118 int media_device_enumerate(struct media_device *media);
119
120 /**
121  * @brief Locate the pad at the other end of a link.
122  * @param pad - sink pad at one end of the link.
123  *
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.
127  *
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.
130  */
131 struct media_pad *media_entity_remote_source(struct media_pad *pad);
132
133 /**
134  * @brief Get the type of an entity.
135  * @param entity - the entity.
136  *
137  * @return The type of @a entity.
138  */
139 static inline unsigned int media_entity_type(struct media_entity *entity)
140 {
141         return entity->info.type & MEDIA_ENT_TYPE_MASK;
142 }
143
144 /**
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.
149  *
150  * Search for an entity with a name equal to @a name.
151  *
152  * @return A pointer to the entity if found, or NULL otherwise.
153  */
154 struct media_entity *media_get_entity_by_name(struct media_device *media,
155         const char *name, size_t length);
156
157 /**
158  * @brief Find an entity by its ID.
159  * @param media - media device.
160  * @param id - entity ID.
161  *
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
166  * @a id.
167  *
168  * @return A pointer to the entity if found, or NULL otherwise.
169  */
170 struct media_entity *media_get_entity_by_id(struct media_device *media,
171         __u32 id);
172
173 /**
174  * @brief Get the number of entities
175  * @param media - media device.
176  *
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.
179  *
180  * @return The number of entities in the media device
181  */
182 unsigned int media_get_entities_count(struct media_device *media);
183
184 /**
185  * @brief Get the entities
186  * @param media - media device.
187  *
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.
190  *
191  * The array of entities is owned by the media device object and will be freed
192  * when the media object is destroyed.
193  *
194  * @return A pointer to an array of entities
195  */
196 struct media_entity *media_get_entities(struct media_device *media);
197
198 /**
199  * @brief Get the media device information
200  * @param media - media device.
201  *
202  * The information structure is owned by the media device object and will be freed
203  * when the media object is destroyed.
204  *
205  * @return A pointer to the media device information
206  */
207 const struct media_device_info *media_get_info(struct media_device *media);
208
209 /**
210  * @brief Get the media device node name
211  * @param media - media device.
212  *
213  * The device node name string is owned by the media device object and will be
214  * freed when the media object is destroyed.
215  *
216  * @return A pointer to the media device node name
217  */
218 const char *media_get_devnode(struct media_device *media);
219
220 /**
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.
226  *
227  * Locate the link between @a source and @a sink, and configure it by applying
228  * the new @a flags.
229  *
230  * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
231  *
232  * @return 0 on success, -1 on failure:
233  *         -ENOENT: link not found
234  *         - other error codes returned by MEDIA_IOC_SETUP_LINK
235  */
236 int media_setup_link(struct media_device *media,
237         struct media_pad *source, struct media_pad *sink,
238         __u32 flags);
239
240 /**
241  * @brief Reset all links to the disabled state.
242  * @param media - media device.
243  *
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.
246  *
247  * @return 0 on success, or a negative error code on failure.
248  */
249 int media_reset_links(struct media_device *media);
250
251 /**
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
256  *
257  * Parse NULL terminated string describing a pad and return its struct
258  * media_pad instance.
259  *
260  * @return Pointer to struct media_pad on success, NULL on failure.
261  */
262 struct media_pad *media_parse_pad(struct media_device *media,
263                                   const char *p, char **endp);
264
265 /**
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
270  *
271  * Parse NULL terminated string p describing a link and return its struct
272  * media_link instance.
273  *
274  * @return Pointer to struct media_link on success, NULL on failure.
275  */
276 struct media_link *media_parse_link(struct media_device *media,
277                                     const char *p, char **endp);
278
279 /**
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
283  *
284  * Parse NULL terminated string p describing a link and its configuration
285  * and configure the link.
286  *
287  * @return 0 on success, or a negative error code on failure.
288  */
289 int media_parse_setup_link(struct media_device *media,
290                            const char *p, char **endp);
291
292 /**
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
296  *
297  * Parse NULL terminated string p describing link(s) separated by
298  * commas (,) and configure the link(s).
299  *
300  * @return 0 on success, or a negative error code on failure.
301  */
302 int media_parse_setup_links(struct media_device *media, const char *p);
303
304 #endif