1 /*
2 * Copyright 2017 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 /**
18 * @addtogroup Sync
19 * @{
20 */
21
22 /**
23 * @file sync.h
24 */
25
26 #ifndef ANDROID_SYNC_H
27 #define ANDROID_SYNC_H
28
29 #include <android/versioning.h>
30 #include <inttypes.h>
31 #include <sys/cdefs.h>
32
33 // Inlined from Linux sync_file.h
34 struct sync_merge_data {
35 char name[32];
36 int32_t fd2;
37 int32_t fence;
38 uint32_t flags;
39 uint32_t pad;
40 };
41
42 struct sync_fence_info {
43 char obj_name[32];
44 char driver_name[32];
45 int32_t status;
46 uint32_t flags;
47 uint64_t timestamp_ns;
48 };
49 struct sync_file_info {
50 char name[32];
51 int32_t status;
52 uint32_t flags;
53 uint32_t num_fences;
54 uint32_t pad;
55 uint64_t sync_fence_info;
56 };
57
58 __BEGIN_DECLS
59
60 #if __ANDROID_API__ >= 26
61
62 /* Fences indicate the status of an asynchronous task. They are initially
63 * in unsignaled state (0), and make a one-time transition to either signaled
64 * (1) or error (< 0) state. A sync file is a collection of one or more fences;
65 * the sync file's status is error if any of its fences are in error state,
66 * signaled if all of the child fences are signaled, or unsignaled otherwise.
67 *
68 * Sync files are created by various device APIs in response to submitting
69 * tasks to the device. Standard file descriptor lifetime syscalls like dup()
70 * and close() are used to manage sync file lifetime.
71 *
72 * The poll(), ppoll(), or select() syscalls can be used to wait for the sync
73 * file to change status, or (with a timeout of zero) to check its status.
74 *
75 * The functions below provide a few additional sync-specific operations.
76 */
77
78 /**
79 * Merge two sync files.
80 *
81 * This produces a new sync file with the given name which has the union of the
82 * two original sync file's fences; redundant fences may be removed.
83 *
84 * If one of the input sync files is signaled or invalid, then this function
85 * may behave like dup(): the new file descriptor refers to the valid/unsignaled
86 * sync file with its original name, rather than a new sync file.
87 *
88 * The original fences remain valid, and the caller is responsible for closing
89 * them.
90 *
91 * Available since API level 26.
92 */
93 int32_t sync_merge(const char* name, int32_t fd1, int32_t fd2);
94
95 /**
96 * Retrieve detailed information about a sync file and its fences.
97 *
98 * The returned sync_file_info must be freed by calling sync_file_info_free().
99 *
100 * Available since API level 26.
101 */
102 struct sync_file_info* sync_file_info(int32_t fd);
103
104 /**
105 * Get the array of fence infos from the sync file's info.
106 *
107 * The returned array is owned by the parent sync file info, and has
108 * info->num_fences entries.
109 *
110 * Available since API level 26.
111 */
sync_get_fence_info(const struct sync_file_info * info)112 static inline struct sync_fence_info* sync_get_fence_info(const struct sync_file_info* info) {
113 // This header should compile in C, but some C++ projects enable
114 // warnings-as-error for C-style casts.
115 #pragma GCC diagnostic push
116 #pragma GCC diagnostic ignored "-Wold-style-cast"
117 return (struct sync_fence_info *)(uintptr_t)(info->sync_fence_info);
118 #pragma GCC diagnostic pop
119 }
120
121 /**
122 * Free a struct sync_file_info structure
123 *
124 * Available since API level 26.
125 */
126 void sync_file_info_free(struct sync_file_info* info) __INTRODUCED_IN(26);
127
128 #endif /* __ANDROID_API__ >= 26 */
129
130 __END_DECLS
131
132 #endif /* ANDROID_SYNC_H */
133
134 /** @} */
135