1 // clang-format off
2 /*
3 * Copyright 2017 The Android Open Source Project
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 /**
19 * @addtogroup Sync
20 * @{
21 */
22
23 /**
24 * @file sync.h
25 */
26
27 #ifndef ANDROID_SYNC_H
28 #define ANDROID_SYNC_H
29
30 #include <stdint.h>
31 #include <sys/cdefs.h>
32
33 #include <linux/sync_file.h>
34
35 __BEGIN_DECLS
36
37 #if __ANDROID_API__ >= 26
38
39 /* Fences indicate the status of an asynchronous task. They are initially
40 * in unsignaled state (0), and make a one-time transition to either signaled
41 * (1) or error (< 0) state. A sync file is a collection of one or more fences;
42 * the sync file's status is error if any of its fences are in error state,
43 * signaled if all of the child fences are signaled, or unsignaled otherwise.
44 *
45 * Sync files are created by various device APIs in response to submitting
46 * tasks to the device. Standard file descriptor lifetime syscalls like dup()
47 * and close() are used to manage sync file lifetime.
48 *
49 * The poll(), ppoll(), or select() syscalls can be used to wait for the sync
50 * file to change status, or (with a timeout of zero) to check its status.
51 *
52 * The functions below provide a few additional sync-specific operations.
53 */
54
55 /**
56 * Merge two sync files.
57 *
58 * This produces a new sync file with the given name which has the union of the
59 * two original sync file's fences; redundant fences may be removed.
60 *
61 * If one of the input sync files is signaled or invalid, then this function
62 * may behave like dup(): the new file descriptor refers to the valid/unsignaled
63 * sync file with its original name, rather than a new sync file.
64 *
65 * The original fences remain valid, and the caller is responsible for closing
66 * them.
67 *
68 * Available since API level 26.
69 */
70 int32_t sync_merge(const char* name, int32_t fd1, int32_t fd2) /* __INTRODUCED_IN(26) */;
71
72 /**
73 * Retrieve detailed information about a sync file and its fences.
74 *
75 * The returned sync_file_info must be freed by calling sync_file_info_free().
76 *
77 * Available since API level 26.
78 */
79 struct sync_file_info* sync_file_info(int32_t fd) /* __INTRODUCED_IN(26) */;
80
81 /**
82 * Get the array of fence infos from the sync file's info.
83 *
84 * The returned array is owned by the parent sync file info, and has
85 * info->num_fences entries.
86 *
87 * Available since API level 26.
88 */
sync_get_fence_info(const struct sync_file_info * info)89 static inline struct sync_fence_info* sync_get_fence_info(const struct sync_file_info* info) {
90 // This header should compile in C, but some C++ projects enable
91 // warnings-as-error for C-style casts.
92 #pragma GCC diagnostic push
93 #pragma GCC diagnostic ignored "-Wold-style-cast"
94 return (struct sync_fence_info *)(uintptr_t)(info->sync_fence_info);
95 #pragma GCC diagnostic pop
96 }
97
98 /**
99 * Free a struct sync_file_info structure
100 *
101 * Available since API level 26.
102 */
103 void sync_file_info_free(struct sync_file_info* info) /* __INTRODUCED_IN(26) */;
104
105 #endif /* __ANDROID_API__ >= 26 */
106
107 __END_DECLS
108
109 #endif /* ANDROID_SYNC_H */
110
111 /** @} */
112