Add some docs for the CAPI extension

1 files changed, 35 insertions, 0 deletions

diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml
index 678164136b..bf378bfe4c 100644
--- a/docs/users_guide/ffi-chap.xml
+++ b/docs/users_guide/ffi-chap.xml
@@ -160,6 +160,41 @@ foreign import ccall interruptible
           handle <literal>ERROR_OPERATION_ABORTED</literal>.
         </para>
       </sect2>
+
+      <sect2 id="ffi-capi">
+        <title>The CAPI calling convention</title>
+        <para>
+          The <literal>CAPI</literal> extension allows a calling
+          convention of <literal>capi</literal> to be used in foreign
+          declarations, e.g.
+
+<programlisting>
+foreign import capi
+    "header.h f" :: CInt -> IO CInt
+</programlisting>
+
+          Rather than generating code to call <literal>f</literal>
+          according to the platform's ABI, we instead call
+          <literal>f</literal> using the C API defined in the header
+          <literal>header.h</literal>. Thus <literal>f</literal> can be
+          called even if it may be defined as a CPP
+          <literal>#define</literal> rather than a proper function.
+        </para>
+
+        <para>
+          In order to tell GHC the C type that a Haskell type
+          corresponds to when it is used with the CAPI, a
+          <literal>CTYPE</literal> pragma can be used on the type
+          definition. The header which defines the type can optionally
+          also be specified. The syntax looks like:
+
+<programlisting>
+data    {-# CTYPE "unistd.h" "useconds_t" #-} T = ...
+newtype {-# CTYPE            "useconds_t" #-} T = ...
+type    {-# CTYPE "unistd.h" "useconds_t" #-} T = ...
+</programlisting>
+        </para>
+      </sect2>
   </sect1>
 
   <sect1 id="ffi-ghc">