fix for automake-1.12
[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         int fd;
57         struct media_device_info info;
58         struct media_entity *entities;
59         unsigned int entities_count;
60         void (*debug_handler)(void *, ...);
61         void *debug_priv;
62         __u32 padding[6];
63 };
64
65 #define media_dbg(media, ...) \
66         (media)->debug_handler((media)->debug_priv, __VA_ARGS__)
67
68 /**
69  * @brief Set a handler for debug messages.
70  * @param media - device instance.
71  * @param debug_handler - debug message handler
72  * @param debug_priv - first argument to debug message handler
73  *
74  * Set a handler for debug messages that will be called whenever
75  * debugging information is to be printed. The handler expects an
76  * fprintf-like function.
77  */
78 void media_debug_set_handler(
79         struct media_device *media, void (*debug_handler)(void *, ...),
80         void *debug_priv);
81
82 /**
83  * @brief Open a media device with debugging enabled.
84  * @param name - name (including path) of the device node.
85  * @param debug_handler - debug message handler
86  * @param debug_priv - first argument to debug message handler
87  *
88  * Open the media device referenced by @a name and enumerate entities, pads and
89  * links.
90  *
91  * Calling media_open_debug() instead of media_open() is equivalent to
92  * media_open() and media_debug_set_handler() except that debugging is
93  * also enabled during media_open().
94  *
95  * @return A pointer to a newly allocated media_device structure instance on
96  * success and NULL on failure. The returned pointer must be freed with
97  * media_close when the device isn't needed anymore.
98  */
99 struct media_device *media_open_debug(
100         const char *name, void (*debug_handler)(void *, ...),
101         void *debug_priv);
102
103 /**
104  * @brief Open a media device.
105  * @param name - name (including path) of the device node.
106  *
107  * Open the media device referenced by @a name and enumerate entities, pads and
108  * links.
109  *
110  * @return A pointer to a newly allocated media_device structure instance on
111  * success and NULL on failure. The returned pointer must be freed with
112  * media_close when the device isn't needed anymore.
113  */
114 struct media_device *media_open(const char *name);
115
116 /**
117  * @brief Close a media device.
118  * @param media - device instance.
119  *
120  * Close the @a media device instance and free allocated resources. Access to the
121  * device instance is forbidden after this function returns.
122  */
123 void media_close(struct media_device *media);
124
125 /**
126  * @brief Locate the pad at the other end of a link.
127  * @param pad - sink pad at one end of the link.
128  *
129  * Locate the source pad connected to @a pad through an enabled link. As only one
130  * link connected to a sink pad can be enabled at a time, the connected source
131  * pad is guaranteed to be unique.
132  *
133  * @return A pointer to the connected source pad, or NULL if all links connected
134  * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
135  */
136 struct media_pad *media_entity_remote_source(struct media_pad *pad);
137
138 /**
139  * @brief Get the type of an entity.
140  * @param entity - the entity.
141  *
142  * @return The type of @a entity.
143  */
144 static inline unsigned int media_entity_type(struct media_entity *entity)
145 {
146         return entity->info.type & MEDIA_ENT_TYPE_MASK;
147 }
148
149 /**
150  * @brief Find an entity by its name.
151  * @param media - media device.
152  * @param name - entity name.
153  * @param length - size of @a name.
154  *
155  * Search for an entity with a name equal to @a name.
156  *
157  * @return A pointer to the entity if found, or NULL otherwise.
158  */
159 struct media_entity *media_get_entity_by_name(struct media_device *media,
160         const char *name, size_t length);
161
162 /**
163  * @brief Find an entity by its ID.
164  * @param media - media device.
165  * @param id - entity ID.
166  *
167  * This function searches for an entity based on its ID using an exact match or
168  * next ID method based on the given @a id. If @a id is ORed with
169  * MEDIA_ENT_ID_FLAG_NEXT, the function will return the entity with the smallest
170  * ID larger than @a id. Otherwise it will return the entity with an ID equal to
171  * @a id.
172  *
173  * @return A pointer to the entity if found, or NULL otherwise.
174  */
175 struct media_entity *media_get_entity_by_id(struct media_device *media,
176         __u32 id);
177
178 /**
179  * @brief Configure a link.
180  * @param media - media device.
181  * @param source - source pad at the link origin.
182  * @param sink - sink pad at the link target.
183  * @param flags - configuration flags.
184  *
185  * Locate the link between @a source and @a sink, and configure it by applying
186  * the new @a flags.
187  *
188  * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
189  *
190  * @return 0 on success, -1 on failure:
191  *         -ENOENT: link not found
192  *         - other error codes returned by MEDIA_IOC_SETUP_LINK
193  */
194 int media_setup_link(struct media_device *media,
195         struct media_pad *source, struct media_pad *sink,
196         __u32 flags);
197
198 /**
199  * @brief Reset all links to the disabled state.
200  * @param media - media device.
201  *
202  * Disable all links in the media device. This function is usually used after
203  * opening a media device to reset all links to a known state.
204  *
205  * @return 0 on success, or a negative error code on failure.
206  */
207 int media_reset_links(struct media_device *media);
208
209 /**
210  * @brief Parse string to a pad on the media device.
211  * @param media - media device.
212  * @param p - input string
213  * @param endp - pointer to string where parsing ended
214  *
215  * Parse NULL terminated string describing a pad and return its struct
216  * media_pad instance.
217  *
218  * @return Pointer to struct media_pad on success, NULL on failure.
219  */
220 struct media_pad *media_parse_pad(struct media_device *media,
221                                   const char *p, char **endp);
222
223 /**
224  * @brief Parse string to a link on the media device.
225  * @param media - media device.
226  * @param p - input string
227  * @param endp - pointer to p where parsing ended
228  *
229  * Parse NULL terminated string p describing a link and return its struct
230  * media_link instance.
231  *
232  * @return Pointer to struct media_link on success, NULL on failure.
233  */
234 struct media_link *media_parse_link(struct media_device *media,
235                                     const char *p, char **endp);
236
237 /**
238  * @brief Parse string to a link on the media device and set it up.
239  * @param media - media device.
240  * @param p - input string
241  *
242  * Parse NULL terminated string p describing a link and its configuration
243  * and configure the link.
244  *
245  * @return 0 on success, or a negative error code on failure.
246  */
247 int media_parse_setup_link(struct media_device *media,
248                            const char *p, char **endp);
249
250 /**
251  * @brief Parse string to link(s) on the media device and set it up.
252  * @param media - media device.
253  * @param p - input string
254  *
255  * Parse NULL terminated string p describing link(s) separated by
256  * commas (,) and configure the link(s).
257  *
258  * @return 0 on success, or a negative error code on failure.
259  */
260 int media_parse_setup_links(struct media_device *media, const char *p);
261
262 #endif