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 #ifndef ANDROID_SYNC_H
18 #define ANDROID_SYNC_H
19
20 #include <stdint.h>
21
22 #include <linux/sync_file.h>
23
24 __BEGIN_DECLS
25
26 #if __ANDROID_API__ >= __ANDROID_API_O__
27
28 /* Fences indicate the status of an asynchronous task. They are initially
29 * in unsignaled state (0), and make a one-time transition to either signaled
30 * (1) or error (< 0) state. A sync file is a collection of one or more fences;
31 * the sync file's status is error if any of its fences are in error state,
32 * signaled if all of the child fences are signaled, or unsignaled otherwise.
33 *
34 * Sync files are created by various device APIs in response to submitting
35 * tasks to the device. Standard file descriptor lifetime syscalls like dup()
36 * and close() are used to manage sync file lifetime.
37 *
38 * The poll(), ppoll(), or select() syscalls can be used to wait for the sync
39 * file to change status, or (with a timeout of zero) to check its status.
40 *
41 * The functions below provide a few additional sync-specific operations.
42 */
43
44 /**
45 * Merge two sync files.
46 *
47 * This produces a new sync file with the given name which has the union of the
48 * two original sync file's fences; redundant fences may be removed.
49 *
50 * If one of the input sync files is signaled or invalid, then this function
51 * may behave like dup(): the new file descriptor refers to the valid/unsignaled
52 * sync file with its original name, rather than a new sync file.
53 *
54 * The original fences remain valid, and the caller is responsible for closing
55 * them.
56 */
57 int32_t sync_merge(const char *name, int32_t fd1, int32_t fd2);
58
59 /**
60 * Retrieve detailed information about a sync file and its fences.
61 *
62 * The returned sync_file_info must be freed by calling sync_file_info_free().
63 */
64 struct sync_file_info *sync_file_info(int32_t fd);
65
66 /**
67 * Get the array of fence infos from the sync file's info.
68 *
69 * The returned array is owned by the parent sync file info, and has
70 * info->num_fences entries.
71 */
sync_get_fence_info(const struct sync_file_info * info)72 static inline struct sync_fence_info* sync_get_fence_info(const struct sync_file_info* info) {
73 // This header should compile in C, but some C++ projects enable
74 // warnings-as-error for C-style casts.
75 #pragma GCC diagnostic push
76 #pragma GCC diagnostic ignored "-Wold-style-cast"
77 return (struct sync_fence_info *)(uintptr_t)(info->sync_fence_info);
78 #pragma GCC diagnostic pop
79 }
80
81 /** Free a struct sync_file_info structure */
82 void sync_file_info_free(struct sync_file_info *info);
83
84 #endif // __ANDROID_API__ >= __ANDROID_API_O__
85
86 __END_DECLS
87
88 #endif /* ANDROID_SYNC_H */
89