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