diff options
-rw-r--r-- | man/Makefile.am | 3 | ||||
-rw-r--r-- | man/android-native-sync.xml | 133 |
2 files changed, 135 insertions, 1 deletions
diff --git a/man/Makefile.am b/man/Makefile.am index ad0a40d94..0f6d16731 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -8,7 +8,8 @@ libman_PRE = \ drmAvailable.xml \ drmHandleEvent.xml \ drmModeGetResources.xml \ - drm_intel_exec_mm.3 + drm_intel_exec_mm.3 \ + android-native-sync.7 miscman_PRE = \ drm.xml \ diff --git a/man/android-native-sync.xml b/man/android-native-sync.xml new file mode 100644 index 000000000..900bba221 --- /dev/null +++ b/man/android-native-sync.xml @@ -0,0 +1,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> |