man: add android native sync man pagesvm

Maybe not the right package for the man page, but at least it's a start.

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 &lt;sync.h&gt;</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 &lt;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>