1/*
2 * Copyright (C) 2013 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef _LIBADF_ADF_H_
18#define _LIBADF_ADF_H_
19
20#include <stdint.h>
21#include <stdbool.h>
22#include <sys/cdefs.h>
23#include <sys/types.h>
24#include <video/adf.h>
25
26typedef __u32 adf_id_t;
27
28struct adf_device {
29    adf_id_t id;
30    int fd;
31};
32
33__BEGIN_DECLS
34
35/**
36 * Enumerates all ADF devices.
37 *
38 * Returns the number of ADF devices, and sets ids to a list of device IDs.
39 * The caller must free() the returned list of device IDs.
40 *
41 * On error, returns -errno.
42 */
43ssize_t adf_devices(adf_id_t **ids);
44
45/**
46 * Opens an ADF device.
47 *
48 * On error, returns -errno.
49 */
50int adf_device_open(adf_id_t id, int flags, struct adf_device *dev);
51/**
52 * Closes an ADF device.
53 */
54void adf_device_close(struct adf_device *dev);
55/**
56 * Reads the ADF device data.
57 *
58 * adf_get_device_data() allocates buffers inside data, which the caller
59 * must free by calling adf_free_device_data().  On error, returns -errno.
60 */
61int adf_get_device_data(struct adf_device *dev, struct adf_device_data *data);
62/**
63 * Frees the device data returned by adf_get_device_data().
64 */
65void adf_free_device_data(struct adf_device_data *data);
66
67/**
68 * Atomically posts a new display configuration to the specified interfaces.
69 *
70 * Returns a sync fence fd that will fire when the configuration is removed
71 * from the screen.  On error, returns -errno.
72 */
73int adf_device_post(struct adf_device *dev,
74        adf_id_t *interfaces, size_t n_interfaces,
75        struct adf_buffer_config *bufs, size_t n_bufs,
76        void *custom_data, size_t custom_data_size);
77/**
78 * Atomically posts a new display configuration to the specified interfaces.
79 *
80 * Compared to adf_device_post(), adf_device_post_v2():
81 *
82 *  (*) allows the client to choose the kind of sync fence returned
83 *      (through complete_fence_type)
84 *
85 *  (*) stores the returned sync fence fd in a provided buffer, so the client
86 *      can distinguish between a permission error (ret = -1) and a successful
87 *      call that returns no fence (*complete_fence = -1)
88 *
89 * On error, returns -errno.
90 *
91 * On devices without the corresponding kernel support, returns -ENOTTY.
92 */
93int adf_device_post_v2(struct adf_device *dev,
94        adf_id_t *interfaces, __u32 n_interfaces,
95        struct adf_buffer_config *bufs, __u32 n_bufs,
96        void *custom_data, __u64 custom_data_size,
97        enum adf_complete_fence_type complete_fence_type,
98        int *complete_fence);
99
100/**
101 * Attaches the specified interface and overlay engine.
102 */
103int adf_device_attach(struct adf_device *dev, adf_id_t overlay_engine,
104                      adf_id_t interface);
105/**
106 * Detaches the specified interface and overlay engine.
107 */
108int adf_device_detach(struct adf_device *dev, adf_id_t overlay_engine,
109                      adf_id_t interface);
110
111/**
112 * Enumerates all interfaces belonging to an ADF device.
113 *
114 * The caller must free() the returned list of interface IDs.
115 */
116ssize_t adf_interfaces(struct adf_device *dev, adf_id_t **interfaces);
117
118/**
119 * Enumerates all interfaces which can be attached to the specified overlay
120 * engine.
121 *
122 * The caller must free() the returned list of interface IDs.
123 */
124ssize_t adf_interfaces_for_overlay_engine(struct adf_device *dev,
125        adf_id_t overlay_engine, adf_id_t **interfaces);
126/**
127 * Filters a list of interfaces by type.
128 *
129 * Returns the number of matching interfaces, and sets out to a list of matching
130 * interface IDs.  The caller must free() the returned list of interface IDs.
131 *
132 * On error, returns -errno.
133 */
134ssize_t adf_interfaces_filter_by_type(struct adf_device *dev,
135        enum adf_interface_type type,
136        adf_id_t *in, size_t n_in, adf_id_t **out);
137/**
138 * Filters a list of interfaces by flag.
139 *
140 * The caller must free() the returned list of interface IDs.
141 */
142ssize_t adf_interfaces_filter_by_flag(struct adf_device *dev, __u32 flag,
143        adf_id_t *in, size_t n_in, adf_id_t **out);
144
145/**
146 * Opens an ADF interface.
147 *
148 * Returns a file descriptor.  The caller must close() the fd when done.
149 * On error, returns -errno.
150 */
151int adf_interface_open(struct adf_device *dev, adf_id_t id, int flags);
152/**
153 * Reads the interface data.
154 *
155 * adf_get_interface_data() allocates buffers inside data, which the caller
156 * must free by calling adf_free_interface_data().  On error, returns -errno.
157 */
158int adf_get_interface_data(int fd, struct adf_interface_data *data);
159/**
160 * Frees the interface data returned by adf_get_interface_data().
161 */
162void adf_free_interface_data(struct adf_interface_data *data);
163
164/**
165 * Sets the interface's DPMS mode.
166 */
167int adf_interface_blank(int fd, __u8 mode);
168/**
169 * Sets the interface's display mode.
170 */
171int adf_interface_set_mode(int fd, struct drm_mode_modeinfo *mode);
172/**
173 * Allocates a single-plane RGB buffer of the specified size and format.
174 *
175 * Returns a dma-buf fd.  On error, returns -errno.
176 */
177int adf_interface_simple_buffer_alloc(int fd, __u32 w, __u32 h,
178        __u32 format, __u32 *offset, __u32 *pitch);
179/**
180 * Posts a single-plane RGB buffer to the display using the specified
181 * overlay engine.
182 *
183 * Returns a sync fence fd that will fire when the buffer is removed
184 * from the screen.  On error, returns -errno.
185 */
186int adf_interface_simple_post(int fd, adf_id_t overlay_engine,
187        __u32 w, __u32 h, __u32 format, int buf_fd, __u32 offset,
188        __u32 pitch, int acquire_fence);
189/**
190 * Posts a single-plane RGB buffer to the display using the specified
191 * overlay engine.
192 *
193 * Compared to adf_interface_simple_post(), adf_interface_simple_post_v2():
194 *
195 *  (*) allows the client to choose the kind of sync fence returned
196 *      (through complete_fence_type)
197 *
198 *  (*) stores the returned sync fence fd in a provided buffer, so the client
199 *      can distinguish between a permission error (ret = -1) and a successful
200 *      call that returns no fence (*complete_fence = -1)
201 *
202 * On error, returns -errno.
203 *
204 * On devices without the corresponding kernel support, returns -ENOTTY.
205 */
206int adf_interface_simple_post_v2(int fd, adf_id_t overlay_engine,
207        __u32 w, __u32 h, __u32 format, int buf_fd, __u32 offset,
208        __u32 pitch, int acquire_fence,
209        enum adf_complete_fence_type complete_fence_type,
210        int *complete_fence);
211
212/**
213 * Enumerates all overlay engines belonging to an ADF device.
214 *
215 * The caller must free() the returned list of overlay engine IDs.
216 */
217ssize_t adf_overlay_engines(struct adf_device *dev, adf_id_t **overlay_engines);
218
219/**
220 * Enumerates all overlay engines which can be attached to the specified
221 * interface.
222 *
223 * The caller must free() the returned list of overlay engine IDs.
224 */
225ssize_t adf_overlay_engines_for_interface(struct adf_device *dev,
226        adf_id_t interface, adf_id_t **overlay_engines);
227/**
228 * Filters a list of overlay engines by supported buffer format.
229 *
230 * Returns the overlay engines which support at least one of the specified
231 * formats.  The caller must free() the returned list of overlay engine IDs.
232 */
233ssize_t adf_overlay_engines_filter_by_format(struct adf_device *dev,
234        const __u32 *formats, size_t n_formats, adf_id_t *in, size_t n_in,
235        adf_id_t **out);
236
237/**
238 * Opens an ADF overlay engine.
239 *
240 * Returns a file descriptor.  The caller must close() the fd when done.
241 * On error, returns -errno.
242 */
243int adf_overlay_engine_open(struct adf_device *dev, adf_id_t id, int flags);
244/**
245 * Reads the overlay engine data.
246 *
247 * adf_get_overlay_engine_data() allocates buffers inside data, which the caller
248 * must free by calling adf_free_overlay_engine_data().  On error, returns
249 * -errno.
250 */
251int adf_get_overlay_engine_data(int fd, struct adf_overlay_engine_data *data);
252/**
253 * Frees the overlay engine data returned by adf_get_overlay_engine_data().
254 */
255void adf_free_overlay_engine_data(struct adf_overlay_engine_data *data);
256
257/**
258 * Returns whether the overlay engine supports the specified format.
259 */
260bool adf_overlay_engine_supports_format(int fd, __u32 format);
261
262/**
263 * Subscribes or unsubscribes from the specified hardware event.
264 */
265int adf_set_event(int fd, enum adf_event_type type, bool enabled);
266/**
267 * Reads one event from the fd, blocking if needed.
268 *
269 * The caller must free() the returned buffer.  On error, returns -errno.
270 */
271int adf_read_event(int fd, struct adf_event **event);
272
273#define ADF_FORMAT_STR_SIZE 5
274/**
275 * Converts an ADF/DRM fourcc format to its string representation.
276 */
277void adf_format_str(__u32 format, char buf[ADF_FORMAT_STR_SIZE]);
278
279/**
280 * Finds an appropriate interface and overlay engine for a simple post.
281 *
282 * Specifically, finds the primary interface, and an overlay engine
283 * that can be attached to the primary interface and supports one of the
284 * specified formats.  The caller may pass a NULL formats list, to indicate that
285 * any RGB format is acceptable.
286 *
287 * On error, returns -errno.
288 */
289int adf_find_simple_post_configuration(struct adf_device *dev,
290        const __u32 *formats, size_t n_formats,
291        adf_id_t *interface, adf_id_t *overlay_engine);
292
293__END_DECLS
294
295#endif /* _LIBADF_ADF_H_ */
296