Remove extra verbosity
[media-ctl.git] / src / mediactl.h
1 /*
2  * Media controller interface library
3  *
4  * Copyright (C) 2010 Ideas on board SPRL <laurent.pinchart@ideasonboard.com>
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License along
17  * with this program; if not, write to the Free Software Foundation, Inc.,
18  */
19
20 #ifndef __MEDIA_H__
21 #define __MEDIA_H__
22
23 #include <linux/media.h>
24
25 struct media_link {
26         struct media_pad *source;
27         struct media_pad *sink;
28         struct media_link *twin;
29         __u32 flags;
30         __u32 padding[3];
31 };
32
33 struct media_pad {
34         struct media_entity *entity;
35         __u32 index;
36         __u32 flags;
37         __u32 padding[3];
38 };
39
40 struct media_entity {
41         struct media_device *media;
42         struct media_entity_desc info;
43         struct media_pad *pads;
44         struct media_link *links;
45         unsigned int max_links;
46         unsigned int num_links;
47
48         char devname[32];
49         int fd;
50         __u32 padding[6];
51 };
52
53 struct media_device {
54         int fd;
55         struct media_entity *entities;
56         unsigned int entities_count;
57         void (*debug_handler)(void *, ...);
58         void *debug_priv;
59         __u32 padding[6];
60 };
61
62 #define media_dbg(media, ...) \
63         (media)->debug_handler((media)->debug_priv, __VA_ARGS__)
64
65 /**
66  * @brief Set a handler for debug messages.
67  * @param media - device instance.
68  * @param debug_handler - debug message handler
69  * @param debug_priv - first argument to debug message handler
70  *
71  * Set a handler for debug messages that will be called whenever
72  * debugging information is to be printed. The handler expects an
73  * fprintf-like function.
74  */
75 void media_debug_set_handler(
76         struct media_device *media, void (*debug_handler)(void *, ...),
77         void *debug_priv);
78
79 /**
80  * @brief Open a media device with debugging enabled.
81  * @param name - name (including path) of the device node.
82  * @param debug_handler - debug message handler
83  * @param debug_priv - first argument to debug message handler
84  *
85  * Open the media device referenced by @a name and enumerate entities, pads and
86  * links.
87  *
88  * Calling media_open_debug() instead of media_open() is equivalent to
89  * media_open() and media_debug_set_handler() except that debugging is
90  * also enabled during media_open().
91  *
92  * @return A pointer to a newly allocated media_device structure instance on
93  * success and NULL on failure. The returned pointer must be freed with
94  * media_close when the device isn't needed anymore.
95  */
96 struct media_device *media_open_debug(
97         const char *name, void (*debug_handler)(void *, ...),
98         void *debug_priv);
99
100 /**
101  * @brief Open a media device.
102  * @param name - name (including path) of the device node.
103  *
104  * Open the media device referenced by @a name and enumerate entities, pads and
105  * links.
106  *
107  * @return A pointer to a newly allocated media_device structure instance on
108  * success and NULL on failure. The returned pointer must be freed with
109  * media_close when the device isn't needed anymore.
110  */
111 struct media_device *media_open(const char *name);
112
113 /**
114  * @brief Close a media device.
115  * @param media - device instance.
116  *
117  * Close the @a media device instance and free allocated resources. Access to the
118  * device instance is forbidden after this function returns.
119  */
120 void media_close(struct media_device *media);
121
122 /**
123  * @brief Locate the pad at the other end of a link.
124  * @param pad - sink pad at one end of the link.
125  *
126  * Locate the source pad connected to @a pad through an enabled link. As only one
127  * link connected to a sink pad can be enabled at a time, the connected source
128  * pad is guaranteed to be unique.
129  *
130  * @return A pointer to the connected source pad, or NULL if all links connected
131  * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
132  */
133 struct media_pad *media_entity_remote_source(struct media_pad *pad);
134
135 /**
136  * @brief Get the type of an entity.
137  * @param entity - the entity.
138  *
139  * @return The type of @a entity.
140  */
141 static inline unsigned int media_entity_type(struct media_entity *entity)
142 {
143         return entity->info.type & MEDIA_ENT_TYPE_MASK;
144 }
145
146 /**
147  * @brief Find an entity by its name.
148  * @param media - media device.
149  * @param name - entity name.
150  * @param length - size of @a name.
151  *
152  * Search for an entity with a name equal to @a name.
153  *
154  * @return A pointer to the entity if found, or NULL otherwise.
155  */
156 struct media_entity *media_get_entity_by_name(struct media_device *media,
157         const char *name, size_t length);
158
159 /**
160  * @brief Find an entity by its ID.
161  * @param media - media device.
162  * @param id - entity ID.
163  *
164  * Search for an entity with an ID equal to @a id.
165  *
166  * @return A pointer to the entity if found, or NULL otherwise.
167  */
168 struct media_entity *media_get_entity_by_id(struct media_device *media,
169         __u32 id);
170
171 /**
172  * @brief Configure a link.
173  * @param media - media device.
174  * @param source - source pad at the link origin.
175  * @param sink - sink pad at the link target.
176  * @param flags - configuration flags.
177  *
178  * Locate the link between @a source and @a sink, and configure it by applying
179  * the new @a flags.
180  *
181  * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
182  *
183  * @return 0 on success, -1 on failure:
184  *         -ENOENT: link not found
185  *         - other error codes returned by MEDIA_IOC_SETUP_LINK
186  */
187 int media_setup_link(struct media_device *media,
188         struct media_pad *source, struct media_pad *sink,
189         __u32 flags);
190
191 /**
192  * @brief Reset all links to the disabled state.
193  * @param media - media device.
194  *
195  * Disable all links in the media device. This function is usually used after
196  * opening a media device to reset all links to a known state.
197  *
198  * @return 0 on success, or a negative error code on failure.
199  */
200 int media_reset_links(struct media_device *media);
201
202 /**
203  * @brief Parse string to a pad on the media device.
204  * @param media - media device.
205  * @param p - input string
206  * @param endp - pointer to string where parsing ended
207  *
208  * Parse NULL terminated string describing a pad and return its struct
209  * media_pad instance.
210  *
211  * @return Pointer to struct media_pad on success, NULL on failure.
212  */
213 struct media_pad *media_parse_pad(struct media_device *media,
214                                   const char *p, char **endp);
215
216 /**
217  * @brief Parse string to a link on the media device.
218  * @param media - media device.
219  * @param p - input string
220  * @param endp - pointer to p where parsing ended
221  *
222  * Parse NULL terminated string p describing a link and return its struct
223  * media_link instance.
224  *
225  * @return Pointer to struct media_link on success, NULL on failure.
226  */
227 struct media_link *media_parse_link(struct media_device *media,
228                                     const char *p, char **endp);
229
230 /**
231  * @brief Parse string to a link on the media device and set it up.
232  * @param media - media device.
233  * @param p - input string
234  *
235  * Parse NULL terminated string p describing a link and its configuration
236  * and configure the link.
237  *
238  * @return 0 on success, or a negative error code on failure.
239  */
240 int media_parse_setup_link(struct media_device *media,
241                            const char *p, char **endp);
242
243 /**
244  * @brief Parse string to link(s) on the media device and set it up.
245  * @param media - media device.
246  * @param p - input string
247  *
248  * Parse NULL terminated string p describing link(s) separated by
249  * commas (,) and configure the link(s).
250  *
251  * @return 0 on success, or a negative error code on failure.
252  */
253 int media_parse_setup_links(struct media_device *media, const char *p);
254
255 #endif