1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
Written 2015 by Jesse Barnes <jbarnes@virtuousgeek.org> based on
drmModeGetResources template from David Herrmann
Dedicated to the Public Domain
-->
<refentry id="android-native-sync">
<refentryinfo>
<title>Android Native Sync</title>
<productname>linux</productname>
<date>June 2015</date>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Erik</firstname>
<surname>Gilling</surname>
<email>konkers@android.com</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>android-native-sync</refentrytitle>
<manvolnum>7</manvolnum>
</refmeta>
<refnamediv>
<refname>android-native-sync</refname>
<refpurpose>Manage inter-device and software synchronization</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <sync.h></funcsynopsisinfo>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>The Android Native Sync framework can be used to monitor and
synchronize activity between multiple devices, logical contexts, or
other events that occur in a monotonic fashion. This is achived through
the use of fence objects and ioctls, in cooperation with device drivers
supporting the interface.
</para>
<para>The fundamental unit of the sync framework is the <parameter>fd</parameter>.
It's generally returned by a device driver as part of an execution request
or specific ioctl. A native sync <parameter>fd</parameter> has several
operations: <constant>SYNC_IOC_WAIT</constant>,
<constant>SYNC_IOC_MERGE</constant>, and
<constant>SYNC_IOC_FENCE_INFO</constant>. In addition, a native sync
<parameter>fd</parameter> can be <citerefentry><refentrytitle>poll()</refentrytitle><manvolnum>2</manvolnum></citerefentry>'d.
</para>
<refsect2>
<title>Polling</title>
<para>Native sync fds can be poll()'d for completion. If the sync
object has been signaled, poll() will return <constant>POLLIN</constant>.
On error, <constant>POLLERR</constant> will be returned. Otherwise,
<literal>0</literal> will be returned.
</para>
</refsect2>
<refsect2>
<title>Ioctls</title>
<para><constant>SYNC_IOC_WAIT</constant> can be used like poll() to block
the caller until the sync object signals. It takes a single argument,
a pointer to a timeout parameter, in milliseconds, which determines how
long the call will block before returning. Passing a variable containing
<literal>-1</literal> (or any <0 number) will use the maximum timeout
possible and <literal>0</literal> will simply return whether the fence
has passed or not. If the fence signals before the timeout has passed,
<literal>0</literal> will be returned. Otherwise,
<constant>ETIME</constant> will be returned, or an appropriate errno.
</para>
<para><constant>SYNC_IOC_MERGE</constant> allows the caller to merge two
sync objects into a single object, which can be useful if the caller
simply needs to monitor the longer of two events that may be occuring
in parallel. The ioctl takes a pointer to a structure as its argument,
describing the objects to merge, and returning the new fd if successful:
<programlisting>
struct sync_merge_data {
__s32 fd2; /* fd of second fence */
char name[32]; /* name of new fence */
__s32 fence; /* fd on newly created fence */
};
</programlisting>
This function returns <literal>0</literal> on success or an appropriate
errno on failure.
</para>
<para><constant>SYNC_IOC_FENCE_INFO</constant> returns information about
a given fence, listing its constituent sync points and other data:
<programlisting>
struct sync_pt_info {
__u32 len;
char obj_name[32];
char driver_name[32];
__s32 status;
__u64 timestamp_ns;
__u8 driver_data[0];
};
struct sync_fence_info_data {
__u32 len;
char name[32];
__s32 status;
__u8 pt_info[0];
};
</programlisting>
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Reporting Bugs</title>
<para>Bugs in this function should be reported to
http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
"libdrm" as the component.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
|
