Use pkg-config
[media-ctl.git] / src / media.h
1 /*
2  * Media controller test application
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_entity_desc info;
42         struct media_pad *pads;
43         struct media_link *links;
44         unsigned int max_links;
45         unsigned int num_links;
46
47         char devname[32];
48         int fd;
49         __u32 padding[6];
50 };
51
52 struct media_device {
53         int fd;
54         struct media_entity *entities;
55         unsigned int entities_count;
56         __u32 padding[6];
57 };
58
59 /**
60  * @brief Open a media device.
61  * @param name - name (including path) of the device node.
62  * @param verbose - whether to print verbose information on the standard output.
63  *
64  * Open the media device referenced by @a name and enumerate entities, pads and
65  * links.
66  *
67  * @return A pointer to a newly allocated media_device structure instance on
68  * success and NULL on failure. The returned pointer must be freed with
69  * media_close when the device isn't needed anymore.
70  */
71 struct media_device *media_open(const char *name, int verbose);
72
73 /**
74  * @brief Close a media device.
75  * @param media - device instance.
76  *
77  * Close the @a media device instance and free allocated resources. Access to the
78  * device instance is forbidden after this function returns.
79  */
80 void media_close(struct media_device *media);
81
82 /**
83  * @brief Locate the pad at the other end of a link.
84  * @param pad - sink pad at one end of the link.
85  *
86  * Locate the source pad connected to @a pad through an enabled link. As only one
87  * link connected to a sink pad can be enabled at a time, the connected source
88  * pad is guaranteed to be unique.
89  *
90  * @return A pointer to the connected source pad, or NULL if all links connected
91  * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
92  */
93 struct media_pad *media_entity_remote_source(struct media_pad *pad);
94
95 /**
96  * @brief Get the type of an entity.
97  * @param entity - the entity.
98  *
99  * @return The type of @a entity.
100  */
101 static inline unsigned int media_entity_type(struct media_entity *entity)
102 {
103         return entity->info.type & MEDIA_ENTITY_TYPE_MASK;
104 }
105
106 /**
107  * @brief Find an entity by its name.
108  * @param media - media device.
109  * @param name - entity name.
110  * @param length - size of @a name.
111  *
112  * Search for an entity with a name equal to @a name.
113  *
114  * @return A pointer to the entity if found, or NULL otherwise.
115  */
116 struct media_entity *media_get_entity_by_name(struct media_device *media,
117         const char *name, size_t length);
118
119 /**
120  * @brief Find an entity by its ID.
121  * @param media - media device.
122  * @param id - entity ID.
123  *
124  * Search for an entity with an ID equal to @a id.
125  *
126  * @return A pointer to the entity if found, or NULL otherwise.
127  */
128 struct media_entity *media_get_entity_by_id(struct media_device *media,
129         __u32 id);
130
131 /**
132  * @brief Configure a link.
133  * @param media - media device.
134  * @param source - source pad at the link origin.
135  * @param sink - sink pad at the link target.
136  * @param flags - configuration flags.
137  *
138  * Locate the link between @a source and @a sink, and configure it by applying
139  * the new @a flags.
140  *
141  * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
142  *
143  * @return 0 on success, or a negative error code on failure.
144  */
145 int media_setup_link(struct media_device *media,
146         struct media_pad *source, struct media_pad *sink,
147         __u32 flags);
148
149 /**
150  * @brief Reset all links to the disabled state.
151  * @param media - media device.
152  *
153  * Disable all links in the media device. This function is usually used after
154  * opening a media device to reset all links to a known state.
155  *
156  * @return 0 on success, or a negative error code on failure.
157  */
158 int media_reset_links(struct media_device *media);
159
160 #endif
161