reorganize and update documentation; fix compiler warning

git-svn-id: svn://svn.linux1394.org/libraw1394/trunk@144 53a565d1-3bb7-0310-b661-cf11e63c67ab

14 files changed, 5071 insertions, 1091 deletions

diff --git a/AUTHORS b/AUTHORS
index f30f375..43ff080 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,10 +1,10 @@
-Maintainer: Ben Collins <bcollins@debian.org>
+Maintainer: Dan Dennedy <dan@dennedy.org>
 
 Original author: Andreas Bombe <andreas.bombe@munich.netsurf.de>
-			   or: <bombe@informatik.tu-muenchen.de>
+			 or <bombe@informatik.tu-muenchen.de>
 		  
 Contributors:
 Manfred Weihs <weihs@ict.tuwien.ac.at>
 Christian Toegel <christian.toegel@gmx.at>
 Dan Maas <dmaas@maasdigital.com>
-Dan Dennedy <dan@dennedy.org>
+Ben Collins <bcollins@debian.org>
diff --git a/INSTALL b/INSTALL
index b42a17a..095b1eb 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,27 +1,43 @@
+Installation Instructions
+*************************
+
+Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004 Free
+Software Foundation, Inc.
+
+This file is free documentation; the Free Software Foundation gives
+unlimited permission to copy, distribute and modify it.
+
 Basic Installation
 ==================
 
-   These are generic installation instructions.
+These are generic installation instructions.
 
    The `configure' shell script attempts to guess correct values for
 various system-dependent variables used during compilation.  It uses
 those values to create a `Makefile' in each directory of the package.
 It may also create one or more `.h' files containing system-dependent
 definitions.  Finally, it creates a shell script `config.status' that
-you can run in the future to recreate the current configuration, a file
-`config.cache' that saves the results of its tests to speed up
-reconfiguring, and a file `config.log' containing compiler output
-(useful mainly for debugging `configure').
+you can run in the future to recreate the current configuration, and a
+file `config.log' containing compiler output (useful mainly for
+debugging `configure').
+
+   It can also use an optional file (typically called `config.cache'
+and enabled with `--cache-file=config.cache' or simply `-C') that saves
+the results of its tests to speed up reconfiguring.  (Caching is
+disabled by default to prevent problems with accidental use of stale
+cache files.)
 
    If you need to do unusual things to compile the package, please try
 to figure out how `configure' could check whether to do them, and mail
 diffs or instructions to the address given in the `README' so they can
-be considered for the next release.  If at some point `config.cache'
-contains results you don't want to keep, you may remove or edit it.
+be considered for the next release.  If you are using the cache, and at
+some point `config.cache' contains results you don't want to keep, you
+may remove or edit it.
 
-   The file `configure.in' is used to create `configure' by a program
-called `autoconf'.  You only need `configure.in' if you want to change
-it or regenerate `configure' using a newer version of `autoconf'.
+   The file `configure.ac' (or `configure.in') is used to create
+`configure' by a program called `autoconf'.  You only need
+`configure.ac' if you want to change it or regenerate `configure' using
+a newer version of `autoconf'.
 
 The simplest way to compile this package is:
 
@@ -54,20 +70,22 @@ The simplest way to compile this package is:
 Compilers and Options
 =====================
 
-   Some systems require unusual options for compilation or linking that
-the `configure' script does not know about.  You can give `configure'
-initial values for variables by setting them in the environment.  Using
-a Bourne-compatible shell, you can do that on the command line like
-this:
-     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
+Some systems require unusual options for compilation or linking that the
+`configure' script does not know about.  Run `./configure --help' for
+details on some of the pertinent environment variables.
+
+   You can give `configure' initial values for configuration parameters
+by setting variables in the command line or in the environment.  Here
+is an example:
+
+     ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
 
-Or on systems that have the `env' program, you can do it like this:
-     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
+   *Note Defining Variables::, for more details.
 
 Compiling For Multiple Architectures
 ====================================
 
-   You can compile the package for more than one kind of computer at the
+You can compile the package for more than one kind of computer at the
 same time, by placing the object files for each architecture in their
 own directory.  To do this, you must use a version of `make' that
 supports the `VPATH' variable, such as GNU `make'.  `cd' to the
@@ -75,28 +93,28 @@ directory where you want the object files and executables to go and run
 the `configure' script.  `configure' automatically checks for the
 source code in the directory that `configure' is in and in `..'.
 
-   If you have to use a `make' that does not supports the `VPATH'
-variable, you have to compile the package for one architecture at a time
-in the source code directory.  After you have installed the package for
-one architecture, use `make distclean' before reconfiguring for another
-architecture.
+   If you have to use a `make' that does not support the `VPATH'
+variable, you have to compile the package for one architecture at a
+time in the source code directory.  After you have installed the
+package for one architecture, use `make distclean' before reconfiguring
+for another architecture.
 
 Installation Names
 ==================
 
-   By default, `make install' will install the package's files in
+By default, `make install' will install the package's files in
 `/usr/local/bin', `/usr/local/man', etc.  You can specify an
 installation prefix other than `/usr/local' by giving `configure' the
-option `--prefix=PATH'.
+option `--prefix=PREFIX'.
 
    You can specify separate installation prefixes for
 architecture-specific files and architecture-independent files.  If you
-give `configure' the option `--exec-prefix=PATH', the package will use
-PATH as the prefix for installing programs and libraries.
+give `configure' the option `--exec-prefix=PREFIX', the package will
+use PREFIX as the prefix for installing programs and libraries.
 Documentation and other data files will still use the regular prefix.
 
    In addition, if you use an unusual directory layout you can give
-options like `--bindir=PATH' to specify different values for particular
+options like `--bindir=DIR' to specify different values for particular
 kinds of files.  Run `configure --help' for a list of the directories
 you can set and what kinds of files go in them.
 
@@ -107,7 +125,7 @@ option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
 Optional Features
 =================
 
-   Some packages pay attention to `--enable-FEATURE' options to
+Some packages pay attention to `--enable-FEATURE' options to
 `configure', where FEATURE indicates an optional part of the package.
 They may also pay attention to `--with-PACKAGE' options, where PACKAGE
 is something like `gnu-as' or `x' (for the X Window System).  The
@@ -122,48 +140,81 @@ you can use the `configure' options `--x-includes=DIR' and
 Specifying the System Type
 ==========================
 
-   There may be some features `configure' can not figure out
-automatically, but needs to determine by the type of host the package
-will run on.  Usually `configure' can figure that out, but if it prints
-a message saying it can not guess the host type, give it the
-`--host=TYPE' option.  TYPE can either be a short name for the system
-type, such as `sun4', or a canonical name with three fields:
+There may be some features `configure' cannot figure out automatically,
+but needs to determine by the type of machine the package will run on.
+Usually, assuming the package is built to be run on the _same_
+architectures, `configure' can figure that out, but if it prints a
+message saying it cannot guess the machine type, give it the
+`--build=TYPE' option.  TYPE can either be a short name for the system
+type, such as `sun4', or a canonical name which has the form:
+
      CPU-COMPANY-SYSTEM
 
-See the file `config.sub' for the possible values of each field.  If
+where SYSTEM can have one of these forms:
+
+     OS KERNEL-OS
+
+   See the file `config.sub' for the possible values of each field.  If
 `config.sub' isn't included in this package, then this package doesn't
-need to know the host type.
+need to know the machine type.
 
-   If you are building compiler tools for cross-compiling, you can also
+   If you are _building_ compiler tools for cross-compiling, you should
 use the `--target=TYPE' option to select the type of system they will
-produce code for and the `--build=TYPE' option to select the type of
-system on which you are compiling the package.
+produce code for.
+
+   If you want to _use_ a cross compiler, that generates code for a
+platform different from the build platform, you should specify the
+"host" platform (i.e., that on which the generated programs will
+eventually be run) with `--host=TYPE'.
 
 Sharing Defaults
 ================
 
-   If you want to set default values for `configure' scripts to share,
-you can create a site shell script called `config.site' that gives
-default values for variables like `CC', `cache_file', and `prefix'.
+If you want to set default values for `configure' scripts to share, you
+can create a site shell script called `config.site' that gives default
+values for variables like `CC', `cache_file', and `prefix'.
 `configure' looks for `PREFIX/share/config.site' if it exists, then
 `PREFIX/etc/config.site' if it exists.  Or, you can set the
 `CONFIG_SITE' environment variable to the location of the site script.
 A warning: not all `configure' scripts look for a site script.
 
-Operation Controls
+Defining Variables
 ==================
 
-   `configure' recognizes the following options to control how it
-operates.
+Variables not defined in a site shell script can be set in the
+environment passed to `configure'.  However, some packages may run
+configure again during the build, and the customized values of these
+variables may be lost.  In order to avoid this problem, you should set
+them in the `configure' command line, using `VAR=value'.  For example:
 
-`--cache-file=FILE'
-     Use and save the results of the tests in FILE instead of
-     `./config.cache'.  Set FILE to `/dev/null' to disable caching, for
-     debugging `configure'.
+     ./configure CC=/usr/local2/bin/gcc
+
+will cause the specified gcc to be used as the C compiler (unless it is
+overridden in the site shell script).
+
+`configure' Invocation
+======================
+
+`configure' recognizes the following options to control how it operates.
 
 `--help'
+`-h'
      Print a summary of the options to `configure', and exit.
 
+`--version'
+`-V'
+     Print the version of Autoconf used to generate the `configure'
+     script, and exit.
+
+`--cache-file=FILE'
+     Enable the cache: use and save the results of the tests in FILE,
+     traditionally `config.cache'.  FILE defaults to `/dev/null' to
+     disable caching.
+
+`--config-cache'
+`-C'
+     Alias for `--cache-file=config.cache'.
+
 `--quiet'
 `--silent'
 `-q'
@@ -175,8 +226,6 @@ operates.
      Look for the package's source code in directory DIR.  Usually
      `configure' can determine that directory automatically.
 
-`--version'
-     Print the version of Autoconf used to generate the `configure'
-     script, and exit.
+`configure' also accepts some other, not widely useful, options.  Run
+`configure --help' for more details.
 
-`configure' also accepts some other, not widely useful, options.
diff --git a/NEWS b/NEWS
index c971bec..34aa442 100644
--- a/NEWS
+++ b/NEWS
@@ -5,12 +5,15 @@ Version 1.1.0:
   numbers changed to reflect a new interface that is not backwards compatible!
 - added raw1394_arm_set_buf() and raw1394_arm_get_buf() functions.
 - added raw1394_new_handle_on_port() to make initialization simpler.
-- new, consistent versioning scheme. 1.0.0 was reported by pkg-config in 0.10
-  series; hence, 1.1.0 in this release.
+- make versioning consistent and updated. 1.0.0 was reported by pkg-config in 
+  0.10 series; hence, 1.1.0 in this release.
 - removed outdated, bogus "linking required only" version symbols in 
   version.c - use pkg-config now.
 - dropped libraw1394.m4 - use pkg-config now.
 - added RPM spec file.
+- deprecate old isochronous API.
+- move API comment documentation to header and reformat header comments as
+  kernel-doc (use linux/scripts/kernel-doc to extract and format them).
 
 Version 0.10:
 
diff --git a/README b/README
index eb0d756..65aad01 100644
--- a/README
+++ b/README
@@ -56,7 +56,7 @@ correctly links with libraw1394.
 
 6. Maintainer
 
-	Maintainers of libraw1394 are currently Ben Collins and Dan Dennedy.  Send 
+	Maintainer of libraw1394 is currently Dan Dennedy.  Send 
 suggestions, bug reports and fixes to linux1394-devel@lists.sourceforge.net.  
 See the file AUTHORS for a complete list of contributors to libraw1394.
 
diff --git a/doc/libraw1394.sgml b/doc/libraw1394.sgml
index fc54c91..da0109c 100644
--- a/doc/libraw1394.sgml
+++ b/doc/libraw1394.sgml
@@ -880,359 +880,4163 @@
   <chapter id="functions">
     <title>Function Reference</title>
 
-    <refentry>
-      <refmeta>
-	<refentrytitle>raw1394_new_handle</refentrytitle>
-	<manvolnum>3</manvolnum>
-      </refmeta>
-
-      <refnamediv>
-	<refname>raw1394_new_handle</refname>
-	<refpurpose>create new handle</refpurpose>
-      </refnamediv>
-
-      <refsynopsisdiv>
-	<funcsynopsis>
-	  <funcprototype>
-	    <funcdef>raw1394handle_t <function>raw1394_new_handle</function></funcdef>
-	    <void>
-	  </funcprototype>
-	</funcsynopsis>
-      </refsynopsisdiv>
-
-      <refsect1>
-	<title>Description</title>
-
-	<para>
-	  Creates and returns a new handle.  It is not allowed to use the same
-	  handle in multiple threads or forked processes.  It is allowed to
-	  create and use multiple handles, however.  Use one handle per thread
-	  which needs it in the multithreaded case.
-	</para>
-      </refsect1>
-
-      <refsect1>
-	<title>Return Value</title>
-
-	<para>
-	  Returns the created handle or <constant>NULL</constant> when
-	  initialization fails.  In the latter case <varname>errno</varname>
-	  either contains some OS specific error code or <constant>0</constant>
-	  if the error is that libraw1394 and raw1394 don't support each other's
-	  protocol versions.
-	</para>
-      </refsect1>
-    </refentry>
-
-    <refentry>
-      <refmeta>
-	<refentrytitle>raw1394_destroy_handle</refentrytitle>
-	<manvolnum>3</manvolnum>
-      </refmeta>
-
-      <refnamediv>
-	<refname>raw1394_destroy_handle</refname>
-	<refpurpose>deallocate handle</refpurpose>
-      </refnamediv>
-
-      <refsynopsisdiv>
-	<funcsynopsis>
-	  <funcprototype>
-	    <funcdef>void <function>raw1394_destroy_handle</function></funcdef>
-	    <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
-	  </funcprototype>
-	</funcsynopsis>
-      </refsynopsisdiv>
-
-      <refsect1>
-	<title>Arguments</title>
-
-	<variablelist>
-	  <varlistentry>
-	    <term><parameter>handle</parameter></term>
-	    <listitem>
-	      <para>handle to be deallocated</para>
-	    </listitem>
-	  </varlistentry>
-	</variablelist>
-      </refsect1>
-
-      <refsect1>
-	<title>Description</title>
-
-	<para>
-	  Closes connection with raw1394 on this handle and deallocates
-	  everything associated with it.  It is safe to pass
-	  <constant>NULL</constant> as handle, nothing is done in this case.
-	</para>
-      </refsect1>
-    </refentry>
-
-    <refentry>
-      <refmeta>
-	<refentrytitle>raw1394_get_port_info</refentrytitle>
-	<manvolnum>3</manvolnum>
-      </refmeta>
-
-      <refnamediv>
-	<refname>raw1394_get_port_info</refname>
-	<refpurpose>get information about connected ports</refpurpose>
-      </refnamediv>
-
-      <refsynopsisdiv>
-	<funcsynopsis>
-	  <funcprototype>
-	    <funcdef>int <function>raw1394_get_port_info</function></funcdef>
-	    <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
-	    <paramdef>struct raw1394_port_info *<parameter>pinf</parameter></paramdef>
-	    <paramdef>int <parameter>maxports</parameter></paramdef>
-	  </funcprototype>
-	</funcsynopsis>
-      </refsynopsisdiv>
-
-      <refsect1>
-	<title>Arguments</title>
-
-	<variablelist>
-	  <varlistentry>
-	    <term><parameter>pinf</parameter></term>
-	    <listitem>
-	      <para>Pointer to an array of structure of type
-	      <structname>raw1394_port_info</structname> which will be filled in
-	      by the function.</para>
-	    </listitem>
-	  </varlistentry>
-	  <varlistentry>
-	    <term><parameter>maxports</parameter></term>
-	    <listitem>
-	      <para>Maximum number of <parameter>pinf</parameter> structures to
-	      fill in.  Zero is valid.</para>
-	    </listitem>
-	  </varlistentry>
-	</variablelist>
-      </refsect1>
-
-      <refsect1>
-	<title>Return Value</title>
-
-	<para>
-	  The number of ports currently existing.
-	</para>
-      </refsect1>
-
-      <refsect1>
-	<title>Description</title>
-
-	<para>
-	  Before you can set which port to use, you use this function to find
-	  out which ports exist. The <structname>raw1394_port_info</structname>
-	  structure looks like this:
-
-	  <programlisting>
-struct <structname>raw1394_portinfo</structname> {
-        int <structfield>nodes</structfield>;
-        char <structfield>name</structfield>[32];
-};
-	  </programlisting>
-	</para>
-
-	<para>
-	  The field <structfield>nodes</structfield> contains the number of
-	  nodes that are currently connected to that port, the field
-	  <structfield>name</structfield> contains the name of the hardware
-	  type.  If your program is interactive, you should present the user
-	  with this list to let them decide which port to use.  A
-	  non-interactive program (and probably interactive ones, too) should
-	  provide a command line option to choose the port.
-	</para>
-      </refsect1>
-    </refentry>
-
-
-    <refentry>
-      <refmeta>
-	<refentrytitle>raw1394_get_fd</refentrytitle>
-	<manvolnum>3</manvolnum>
-      </refmeta>
-
-      <refnamediv>
-	<refname>raw1394_get_fd</refname>
-	<refpurpose>get the communication file descriptor</refpurpose>
-      </refnamediv>
-
-      <refsynopsisdiv>
-	<funcsynopsis>
-	  <funcprototype>
-	    <funcdef>int <function>raw1394_get_fd</function></funcdef>
-	    <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
-	  </funcprototype>
-	</funcsynopsis>
-      </refsynopsisdiv>
-
-      <refsect1>
-	<title>Arguments</title>
-
-	<variablelist>
-	  <varlistentry>
-	    <term><parameter>handle</parameter></term>
-	    <listitem>
-	      <para>handle of which the fd is to be returned from</para>
-	    </listitem>
-	  </varlistentry>
-	</variablelist>
-      </refsect1>
-
-      <refsect1>
-	<title>Description</title>
-
-	<para>
-	  Returns the fd used for communication with the raw1394 kernel module.
-	  This can be used for
-	  <function>select()</function>/<function>poll()</function> calls if you
-	  wait on other fds or can be integrated into another event loop
-	  (e.g. from a GUI application framework).  It can also be used to
-	  set/remove the <constant>O_NONBLOCK</constant> flag using
-	  <function>fcntl()</function> to modify the block behaviour in
-	  <function>raw1394_loop_iterate()</function>.  It must not be used for
-	  anything else.
-	</para>
-      </refsect1>
-
-      <refsect1>
-	<title>Return Value</title>
-
-	<para>
-	  The fd of the communication stream.  Invalid fds may be returned
-	  before a port was set using <function>raw1394_set_port()</function>.
-	</para>
-      </refsect1>
-    </refentry>
-
-    <refentry>
-      <refmeta>
-	<refentrytitle>raw1394_(get|set)_userdata</refentrytitle>
-	<manvolnum>3</manvolnum>
-      </refmeta>
-
-      <refnamediv>
-	<refname>raw1394_get_userdata</refname>
-	<refname>raw1394_set_userdata</refname>
-	<refpurpose>associate user data with a handle</refpurpose>
-      </refnamediv>
-
-      <refsynopsisdiv>
-	<funcsynopsis>
-	  <funcprototype>
-	    <funcdef>void *<function>raw1394_get_userdata</function></funcdef>
-	    <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
-	  </funcprototype>
-	  <funcprototype>
-	    <funcdef>void <function>raw1394_set_userdata</function></funcdef>
-	    <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
-	  </funcprototype>
-	</funcsynopsis>
-      </refsynopsisdiv>
-
-      <refsect1>
-	<title>Arguments</title>
-
-	<variablelist>
-	  <varlistentry>
-	    <term><parameter>handle</parameter></term>
-	    <listitem>
-	      <para>handle associated with the user data</para>
-	    </listitem>
-	  </varlistentry>
-	</variablelist>
-      </refsect1>
-
-      <refsect1>
-	<title>Description</title>
-
-	<para>
-	  Allows to associate one void pointer with a handle.  libraw1394 does
-	  not care about the data, it just stores it in the handle allowing it
-	  to be retrieved at any time.  This can be useful when multiple handles
-	  are used, so that callbacks can identify the handle.
-	</para>
-      </refsect1>
-
-      <refsect1>
-	<title>Return Value</title>
-
-	<para>
-	  <function>raw1394_get_userdata()</function> returns the void pointer
-	  associated with the handle.
-	</para>
-      </refsect1>
-    </refentry>
-
-    <refentry>
-      <refmeta>
-	<refentrytitle>raw1394_get_(local_id|irm_id|nodecount)</refentrytitle>
-	<manvolnum>3</manvolnum>
-      </refmeta>
-
-      <refnamediv>
-	<refname>raw1394_get_local_id</refname>
-	<refname>raw1394_get_irm_id</refname>
-	<refname>raw1394_get_nodecount</refname>
-	<refpurpose>return basic information about the bus</refpurpose>
-      </refnamediv>
-
-      <refsynopsisdiv>
-	<funcsynopsis>
-	  <funcprototype>
-	    <funcdef>nodeid_t <function>raw1394_get_local_id</function></funcdef>
-	    <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
-	  </funcprototype>
-	  <funcprototype>
-	    <funcdef>nodeid_t <function>raw1394_get_irm_id</function></funcdef>
-	    <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
-	  </funcprototype>
-	  <funcprototype>
-	    <funcdef>int <function>raw1394_get_nodecount</function></funcdef>
-	    <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
-	  </funcprototype>
-	</funcsynopsis>
-      </refsynopsisdiv>
-
-      <refsect1>
-	<title>Arguments</title>
-
-	<variablelist>
-	  <varlistentry>
-	    <term><parameter>handle</parameter></term>
-	    <listitem>
-	      <para>handle associated with a 1394 bus</para>
-	    </listitem>
-	  </varlistentry>
-	</variablelist>
-      </refsect1>
-
-      <refsect1>
-	<title>Description</title>
-
-	<para>
-	  These functions return information about the 1394 bus the handle is
-	  associated with.  The values that can be queried through these
-	  functions can change with every bus reset.
-	</para>
-      </refsect1>
-
-      <refsect1>
-	<title>Return Value</title>
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-xmit-init">raw1394_iso_xmit_init</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_xmit_init</refname>
+ <refpurpose>
+   initialize isochronous transmission
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_xmit_init </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>raw1394_iso_xmit_handler_t <parameter>handler</parameter></paramdef>
+   <paramdef>unsigned int <parameter>buf_packets</parameter></paramdef>
+   <paramdef>unsigned int <parameter>max_packet_size</parameter></paramdef>
+   <paramdef>unsigned char <parameter>channel</parameter></paramdef>
+   <paramdef>enum raw1394_iso_speed <parameter>speed</parameter></paramdef>
+   <paramdef>int <parameter>irq_interval</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>handler</parameter></term>
+   <listitem>
+    <para>
+      handler function for queueing packets
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>buf_packets</parameter></term>
+   <listitem>
+    <para>
+      number of isochronous packets to buffer
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>max_packet_size</parameter></term>
+   <listitem>
+    <para>
+      largest packet you need to handle, in bytes
+     (not including the isochronous header)
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+      isochronous channel on which to transmit
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>speed</parameter></term>
+   <listitem>
+    <para>
+      speed at which to transmit
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>irq_interval</parameter></term>
+   <listitem>
+    <para>
+      maximum latency of wake-ups, in packets (-1 if you don't care)
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Allocates all user and kernel resources necessary for isochronous transmission.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-recv-init">raw1394_iso_recv_init</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_recv_init</refname>
+ <refpurpose>
+      initialize isochronous reception
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_recv_init </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>raw1394_iso_recv_handler_t <parameter>handler</parameter></paramdef>
+   <paramdef>unsigned int <parameter>buf_packets</parameter></paramdef>
+   <paramdef>unsigned int <parameter>max_packet_size</parameter></paramdef>
+   <paramdef>unsigned char <parameter>channel</parameter></paramdef>
+   <paramdef>enum raw1394_iso_dma_recv_mode <parameter>mode</parameter></paramdef>
+   <paramdef>int <parameter>irq_interval</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>handler</parameter></term>
+   <listitem>
+    <para>
+      handler function for receiving packets
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>buf_packets</parameter></term>
+   <listitem>
+    <para>
+      number of isochronous packets to buffer
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>max_packet_size</parameter></term>
+   <listitem>
+    <para>
+      largest packet you need to handle, in bytes (not including
+     the isochronous header)
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+      isochronous channel to receive
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>mode</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>irq_interval</parameter></term>
+   <listitem>
+    <para>
+      maximum latency of wake-ups, in packets
+     (-1 if you don't care)
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Allocates all user and kernel resources necessary for isochronous reception.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-multichannel-recv-init">raw1394_iso_multichannel_recv_init</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_multichannel_recv_init</refname>
+ <refpurpose>
+      initialize multi-channel iso reception
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_multichannel_recv_init </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>raw1394_iso_recv_handler_t <parameter>handler</parameter></paramdef>
+   <paramdef>unsigned int <parameter>buf_packets</parameter></paramdef>
+   <paramdef>unsigned int <parameter>max_packet_size</parameter></paramdef>
+   <paramdef>int <parameter>irq_interval</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>handler</parameter></term>
+   <listitem>
+    <para>
+      handler function for receiving packets
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>buf_packets</parameter></term>
+   <listitem>
+    <para>
+      number of isochronous packets to buffer
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>max_packet_size</parameter></term>
+   <listitem>
+    <para>
+      largest packet you need to handle, in bytes (not including
+     the isochronous header)
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>irq_interval</parameter></term>
+   <listitem>
+    <para>
+      maximum latency of wake-ups, in packets (-1 if you don't care)
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Allocates all user and kernel resources necessary for isochronous reception.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-recv-listen-channel">raw1394_iso_recv_listen_channel</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_recv_listen_channel</refname>
+ <refpurpose>
+      listen to a specific channel in multi-channel mode
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_recv_listen_channel </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned char <parameter>channel</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   listen/unlisten on a specific channel (multi-channel mode ONLY)	
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-recv-unlisten-channel">raw1394_iso_recv_unlisten_channel</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_recv_unlisten_channel</refname>
+ <refpurpose>
+      stop listening  to a specific channel in multi-channel mode
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_recv_unlisten_channel </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned char <parameter>channel</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-recv-set-channel-mask">raw1394_iso_recv_set_channel_mask</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_recv_set_channel_mask</refname>
+ <refpurpose>
+      listen or unlisten to a whole bunch of channels at once
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_recv_set_channel_mask </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>u_int64_t <parameter>mask</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>mask</parameter></term>
+   <listitem>
+    <para>
+      64-bit mask of channels, 1 means listen, 0 means unlisten,
+     channel 0 is LSB, channel 63 is MSB
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   for multi-channel reception mode only
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-xmit-start">raw1394_iso_xmit_start</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_xmit_start</refname>
+ <refpurpose>
+      begin isochronous transmission
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_xmit_start </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>int <parameter>start_on_cycle</parameter></paramdef>
+   <paramdef>int <parameter>prebuffer_packets</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>start_on_cycle</parameter></term>
+   <listitem>
+    <para>
+      isochronous cycle number on which to start 
+     (-1 if you don't care)
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>prebuffer_packets</parameter></term>
+   <listitem>
+    <para>
+      number of packets to queue up before starting transmission
+     (-1 if you don't care)
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-recv-start">raw1394_iso_recv_start</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_recv_start</refname>
+ <refpurpose>
+      begin isochronous reception
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_recv_start </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>int <parameter>start_on_cycle</parameter></paramdef>
+   <paramdef>int <parameter>tag_mask</parameter></paramdef>
+   <paramdef>int <parameter>sync</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>start_on_cycle</parameter></term>
+   <listitem>
+    <para>
+      isochronous cycle number on which to start 
+     (-1 if you don't care)
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag_mask</parameter></term>
+   <listitem>
+    <para>
+      mask of tag fields to match (-1 to receive all packets)
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>sync</parameter></term>
+   <listitem>
+    <para>
+      not used, reserved for future implementation
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-xmit-write">raw1394_iso_xmit_write</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_xmit_write</refname>
+ <refpurpose>
+      alternative blocking-write API for ISO transmission
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_xmit_write </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned char * <parameter>data</parameter></paramdef>
+   <paramdef>unsigned int <parameter>len</parameter></paramdef>
+   <paramdef>unsigned char <parameter>tag</parameter></paramdef>
+   <paramdef>unsigned char <parameter>sy</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+      pointer to packet data buffer
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>len</parameter></term>
+   <listitem>
+    <para>
+      length of packet, in bytes
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag</parameter></term>
+   <listitem>
+    <para>
+      tag field
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>sy</parameter></term>
+   <listitem>
+    <para>
+      sync field
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   <function>write</function> style API - do NOT use this if you have set an xmit_handler
+   if buffer is full, waits for more space UNLESS the file descriptor is
+   set to non-blocking, in which case <function>xmit_write</function> will return -1 with
+   errno = EAGAIN
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-xmit-sync">raw1394_iso_xmit_sync</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_xmit_sync</refname>
+ <refpurpose>
+      wait until all queued packets have been sent
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_xmit_sync </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-recv-flush">raw1394_iso_recv_flush</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_recv_flush</refname>
+ <refpurpose>
+      flush all already received iso packets from kernel into user space
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_recv_flush </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   If you specified an irq_interval &gt; 1 in
+   iso_recv_init, you won't be notified for every single iso packet, but
+   for groups of them. Now e.g. if irq_interval is 100, and you were just
+   notified about iso packets and after them only 20 more packets arrived,
+   no notification will be generated (20 &lt; 100). In the case that you know
+   that there should be more packets at this moment, you can call this
+   function and all iso packets which are already received by the kernel
+   will be flushed out to user space.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-stop">raw1394_iso_stop</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_stop</refname>
+ <refpurpose>
+      halt isochronous transmission or reception
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>void <function>raw1394_iso_stop </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-shutdown">raw1394_iso_shutdown</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_shutdown</refname>
+ <refpurpose>
+      clean up and deallocate all resources for isochronous transmission or reception
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>void <function>raw1394_iso_shutdown </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-get-errcode">raw1394_get_errcode</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_get_errcode</refname>
+ <refpurpose>
+      return error code of async transaction
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>raw1394_errcode_t <function>raw1394_get_errcode </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Returns the error code of the last <function>raw1394_read</function>, <function>raw1394_write</function>,
+   <function>raw1394_lock</function> or <function>raw1394_iso_write</function>.  The error code is either an internal
+   error (i.e. not a bus error) or a combination of acknowledge code and
+   response code, as appropriate.
+   </para><para>
+
+   Some macros are available to extract information from the error code,
+   <function>raw1394_errcode_to_errno</function> can be used to convert it to an errno number of
+   roughly the same meaning.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-errcode-to-errno">raw1394_errcode_to_errno</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_errcode_to_errno</refname>
+ <refpurpose>
+      convert libraw1394 errcode to errno
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_errcode_to_errno </function></funcdef>
+   <paramdef>raw1394_errcode_t <parameter>errcode</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>errcode</parameter></term>
+   <listitem>
+    <para>
+      the error code to convert
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   The error code as retrieved by <function>raw1394_get_errcode</function> is converted into a
+   roughly equivalent errno number and returned.  <constant>0xdead</constant> is returned for an
+   illegal errcode.
+   </para><para>
+
+   It is intended to be used to decide what to do (retry, give up, report error)
+   for those programs that aren't interested in details, since these get lost in
+   the conversion.  However the returned errnos are equivalent in source code
+   meaning only, the associated text of e.g. <function>perror</function> is not necessarily
+   meaningful.
+   </para><para>
+
+   Returned values are <constant>EAGAIN</constant> (retrying might succeed, also generation number
+   mismatch), <constant>EREMOTEIO</constant> (other node had internal problems), <constant>EPERM</constant> (operation
+   not allowed on this address, e.g. write on read-only location), <constant>EINVAL</constant>
+   (invalid argument) and <constant>EFAULT</constant> (invalid pointer).
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-new-handle">raw1394_new_handle</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_new_handle</refname>
+ <refpurpose>
+      create new handle
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>raw1394handle_t <function>raw1394_new_handle </function></funcdef>
+   <paramdef> <parameter>void</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>void</parameter></term>
+   <listitem>
+    <para>
+     no arguments
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   </para><para>
+
+   Creates and returns a new handle which can (after being set up) control one
+   port.  It is not allowed to use the same handle in multiple threads or forked
+   processes.  It is allowed to create and use multiple handles, however.  Use
+   one handle per thread which needs it in the multithreaded case.
+   </para><para>
+
+   Returns the created handle or <constant>NULL</constant> when initialization fails.  In the latter
+   case errno either contains some OS specific error code or <constant>0</constant> if the error is
+   that libraw1394 and raw1394 don't support each other's protocol versions.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-destroy-handle">raw1394_destroy_handle</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_destroy_handle</refname>
+ <refpurpose>
+      deallocate handle
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>void <function>raw1394_destroy_handle </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      handle to deallocate
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Closes connection with raw1394 on this handle and deallocates everything
+   associated with it.  It is safe to pass <constant>NULL</constant> as handle, nothing is done in
+   this case.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-new-handle-on-port">raw1394_new_handle_on_port</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_new_handle_on_port</refname>
+ <refpurpose>
+      create a new handle and bind it to a port
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>raw1394handle_t <function>raw1394_new_handle_on_port </function></funcdef>
+   <paramdef>int <parameter>port</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>port</parameter></term>
+   <listitem>
+    <para>
+      port to connect to (same as argument to <function>raw1394_set_port</function>)
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Same as <function>raw1394_new_handle</function>, but also binds the handle to the
+   specified 1394 port. Equivalent to <function>raw1394_new_handle</function> followed by
+   <function>raw1394_get_port_info</function> and <function>raw1394_set_port</function>. Useful for
+   command-line programs that already know what port they want. If
+   <function>raw1394_set_port</function> returns ESTALE, retries automatically.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-busreset-notify">raw1394_busreset_notify</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_busreset_notify</refname>
+ <refpurpose>
+      Switch off/on busreset-notification for handle
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_busreset_notify </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>int <parameter>off_on_switch</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>off_on_switch</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>returns</title>
+ <para>
+   ==0 success 
+   !=0 failure
+   off_on_switch .... RAW1394_NOTIFY_OFF or RAW1394_NOTIFY_ON
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-get-fd">raw1394_get_fd</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_get_fd</refname>
+ <refpurpose>
+      get the communication file descriptor
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_get_fd </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Returns the fd used for communication with the raw1394 kernel module.  This
+   can be used for <function>select</function>/<function>poll</function> calls if you wait on other fds or can be
+   integrated into another event loop (e.g. from a GUI application framework).
+   It can also be used to set/remove the O_NONBLOCK flag using <function>fcntl</function> to modify
+   the blocking behaviour in <function>raw1394_loop_iterate</function>.  It must not be used for
+   anything else.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-set-userdata">raw1394_set_userdata</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_set_userdata</refname>
+ <refpurpose>
+      associate user data with a handle
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>void <function>raw1394_set_userdata </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>void * <parameter>data</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+      user data (pointer)
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Allows to associate one void pointer with a handle.  libraw1394 does not care
+   about the data, it just stores it in the handle allowing it to be retrieved
+   at any time with <function>raw1394_get_userdata</function>.  This can be useful when multiple
+   handles are used, so that callbacks can identify the handle.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-get-userdata">raw1394_get_userdata</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_get_userdata</refname>
+ <refpurpose>
+      retrieve user data from handle
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>void * <function>raw1394_get_userdata </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Returns the user data pointer associated with the handle using
+   <function>raw1394_set_userdata</function>.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-get-local-id">raw1394_get_local_id</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_get_local_id</refname>
+ <refpurpose>
+      get node ID of the current port
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>nodeid_t <function>raw1394_get_local_id </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Returns the node ID of the local node connected to which the handle is
+   connected.  This value can change with every bus reset.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-get-irm-id">raw1394_get_irm_id</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_get_irm_id</refname>
+ <refpurpose>
+      get node ID of isochronous resource manager
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>nodeid_t <function>raw1394_get_irm_id </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Returns the node ID of the isochronous resource manager of the bus the handle
+   is connected to.  This value may change with every bus reset.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-get-nodecount">raw1394_get_nodecount</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_get_nodecount</refname>
+ <refpurpose>
+      get number of nodes on the bus
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_get_nodecount </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Returns the number of nodes on the bus to which the handle is connected.
+   This value can change with every bus reset.  Since the root node always has
+   the highest node ID, this number can be used to determine that ID (it's
+   LOCAL_BUS|(count-1)).
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-get-port-info">raw1394_get_port_info</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_get_port_info</refname>
+ <refpurpose>
+      get information about available ports
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_get_port_info </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>struct raw1394_portinfo * <parameter>pinf</parameter></paramdef>
+   <paramdef>int <parameter>maxports</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>pinf</parameter></term>
+   <listitem>
+    <para>
+      pointer to an array of struct raw1394_portinfo
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>maxports</parameter></term>
+   <listitem>
+    <para>
+      number of elements in <parameter>pinf</parameter>
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Before you can set which port to use, you have to use this function to find
+   out which ports exist.
+   </para><para>
+
+   If your program is interactive, you should present the user with this list to
+   let them decide which port to use if there is more than one.  A
+   non-interactive program (and probably interactive ones, too) should provide a
+   command line option to choose the port.
+   </para><para>
+
+   Returns the number of ports and writes information about them into <parameter>pinf</parameter>, but
+   not into more than <parameter>maxports</parameter> elements.  If <parameter>maxports</parameter> is <constant>0</constant>, <parameter>pinf</parameter> can be
+   <constant>NULL</constant>, too.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-set-port">raw1394_set_port</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_set_port</refname>
+ <refpurpose>
+      choose port for handle
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_set_port </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>int <parameter>port</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>port</parameter></term>
+   <listitem>
+    <para>
+      port to connect to (corresponds to index of struct raw1394_portinfo)
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This function connects the handle to the port given (as queried with
+   <function>raw1394_get_port_info</function>).  If successful, <function>raw1394_get_port_info</function> and
+   <function>raw1394_set_port</function> are not allowed to be called afterwards on this handle.
+   To make up for this, all the other functions (those handling asynchronous and
+   isochronous transmissions) can now be called.
+   </para><para>
+
+   Returns <constant>0</constant> for success and -1 for failure with errno set appropriately.  A
+   possible failure mode is with errno = <constant>ESTALE</constant>, in this case the configuration
+   has changed since the call to <function>raw1394_get_port_info</function> and it has to be called
+   again to update your view of the available ports.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-reset-bus">raw1394_reset_bus</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_reset_bus</refname>
+ <refpurpose>
+      initiate bus reset
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_reset_bus </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This function initiates a bus reset on the connected port.  Usually this is
+   not necessary and should be avoided, this function is here for low level bus
+   control and debugging.
+ </para>
+</refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    <constant>0</constant> for success and -1 for failure with errno set appropriately.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-reset-bus-new">raw1394_reset_bus_new</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_reset_bus_new</refname>
+ <refpurpose>
+      Reset the connected bus (with certain type). 
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_reset_bus_new </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>int <parameter>type</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>type</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>returns</title>
+ <para>
+   -1 failure 
+   0  success
+   type .... RAW1394_SHORT_RESET or RAW1394_LONG_RESET
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-loop-iterate">raw1394_loop_iterate</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_loop_iterate</refname>
+ <refpurpose>
+      get and process one event message
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_loop_iterate </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Get one new message through handle and process it with the registered message
+   handler.  This function will return <constant>-1</constant> for an error or the return value of
+   the handler which got executed.  The default handlers always return zero.
+   </para><para>
+
+   Note that some other library functions may call this function multiple times
+   to wait for their completion, some handler return values may get lost if you
+   use these.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-set-bus-reset-handler">raw1394_set_bus_reset_handler</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_set_bus_reset_handler</refname>
+ <refpurpose>
+      set bus reset handler
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>bus_reset_handler_t <function>raw1394_set_bus_reset_handler </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>bus_reset_handler_t <parameter>new_h</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>new_h</parameter></term>
+   <listitem>
+    <para>
+      pointer to new handler
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Sets the handler to be called on every bus reset to <parameter>new_h</parameter> and returns the
+   old handler. The default handler just calls <function>raw1394_update_generation</function>.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-get-generation">raw1394_get_generation</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_get_generation</refname>
+ <refpurpose>
+      get generation number of handle
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>unsigned int <function>raw1394_get_generation </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This function returns the generation number associated with the handle.  The
+   generation number is incremented on every bus reset, and every transaction
+   started by raw1394 is tagged with the stored generation number.  If these
+   don't match, the transaction will abort with an error.
+   </para><para>
+
+   The generation number of the handle is not automatically updated,
+   <function>raw1394_update_generation</function> has to be used for this.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-update-generation">raw1394_update_generation</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_update_generation</refname>
+ <refpurpose>
+      set generation number of handle
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>void <function>raw1394_update_generation </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned int <parameter>generation</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>generation</parameter></term>
+   <listitem>
+    <para>
+      new generation number
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This function sets the generation number of the handle to <parameter>gen</parameter>.  All requests
+   that apply to a single node ID are tagged with this number and abort with an
+   error if that is different from the generation number kept in the kernel.
+   This avoids acting on the wrong node which may have changed its ID in a bus
+   reset.
+   </para><para>
+
+   You should call this within your bus reset handler with an incremented value.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-set-tag-handler">raw1394_set_tag_handler</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_set_tag_handler</refname>
+ <refpurpose>
+      set request completion handler
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>tag_handler_t <function>raw1394_set_tag_handler </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>tag_handler_t <parameter>new_h</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>new_h</parameter></term>
+   <listitem>
+    <para>
+      pointer to new handler
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Sets the handler to be called whenever a request completes to <parameter>new_h</parameter> and
+   returns the old handler.  The default handler interprets the tag as a pointer
+   to a &amp;struct raw1394_reqhandle and calls the callback in there.
+   </para><para>
+
+   Care must be taken when replacing the tag handler and calling the synchronous
+   versions of the transaction functions (i.e. <function>raw1394_read</function>, <function>raw1394_write</function>,
+   <function>raw1394_lock</function>, <function>raw1394_iso_write</function>) since these do pass pointers to &amp;struct
+   raw1394_reqhandle as the tag and expect the callback to be invoked.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-set-arm-tag-handler">raw1394_set_arm_tag_handler</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_set_arm_tag_handler</refname>
+ <refpurpose>
+      set the async request handler
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>arm_tag_handler_t <function>raw1394_set_arm_tag_handler </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>arm_tag_handler_t <parameter>new_h</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>new_h</parameter></term>
+   <listitem>
+    <para>
+      pointer to new handler
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Set the handler that will be called when an async read/write/lock arm_request
+   arrived. The default action is to call the arm_callback in the 
+   raw1394_arm_reqhandle pointed to by arm_tag.  Returns old handler.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-set-fcp-handler">raw1394_set_fcp_handler</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_set_fcp_handler</refname>
+ <refpurpose>
+      set FCP handler
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>fcp_handler_t <function>raw1394_set_fcp_handler </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>fcp_handler_t <parameter>new_h</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>new_h</parameter></term>
+   <listitem>
+    <para>
+      pointer to new handler
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Function Control Protocol is defined in IEC 61883-1.
+   </para><para>
+
+   Sets the handler to be called when either FCP command or FCP response
+   registers get written to <parameter>new_h</parameter> and returns the old handler.  The default
+   handler does nothing.
+   </para><para>
+
+   In order to actually get FCP events, you have to enable it with
+   <function>raw1394_start_fcp_listen</function> and can stop it with <function>raw1394_stop_fcp_listen</function>.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-int">int</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>int</refname>
+ <refpurpose>
+      This is the general request handler
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>typedef <function>int </function></funcdef>
+   <paramdef>* <parameter>req_callback_t</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>req_callback_t</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   </para><para>
+
+   It is used by the default tag handler
+   when a request completes, it calls the callback and passes it the data
+   pointer and the error code of the request.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-int">int</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>int</refname>
+ <refpurpose>
+      This is the general arm-request handle
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>typedef <function>int </function></funcdef>
+   <paramdef>* <parameter>arm_req_callback_t</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>arm_req_callback_t</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   (arm = address range mapping)
+   It is used by the default arm-tag handler when a request has been 
+   received, it calls the arm_callback.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-arm-register">raw1394_arm_register</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_arm_register</refname>
+ <refpurpose>
+      register an AddressRangeMapping
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_arm_register </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>start</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>byte_t * <parameter>initial_value</parameter></paramdef>
+   <paramdef>octlet_t <parameter>arm_tag</parameter></paramdef>
+   <paramdef>arm_options_t <parameter>access_rights</parameter></paramdef>
+   <paramdef>arm_options_t <parameter>notification_options</parameter></paramdef>
+   <paramdef>arm_options_t <parameter>client_transactions</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>start</parameter></term>
+   <listitem>
+    <para>
+                 identifies addressrange
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+                identifies addressrange
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>initial_value</parameter></term>
+   <listitem>
+    <para>
+         pointer to buffer containing (if necessary) initial value
+     NULL means undefined
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>arm_tag</parameter></term>
+   <listitem>
+    <para>
+               identifier for arm_tag_handler 
+     (usually pointer to raw1394_arm_reqhandle)
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>access_rights</parameter></term>
+   <listitem>
+    <para>
+         access-rights for registered addressrange handled 
+     by kernel-part. Value is one or more binary or of the 
+     following flags - ARM_READ, ARM_WRITE, ARM_LOCK
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>notification_options</parameter></term>
+   <listitem>
+    <para>
+      identifies for which type of request you want
+     to be notified. Value is one or more binary or of the 
+     following flags - ARM_READ, ARM_WRITE, ARM_LOCK
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>client_transactions</parameter></term>
+   <listitem>
+    <para>
+      identifies for which type of request you want
+     to handle the request by the client application.
+     for those requests no response will be generated, but
+     has to be generated by the application.
+     Value is one or more binary or of the 
+     following flags - ARM_READ, ARM_WRITE, ARM_LOCK
+     For each bit set here, notification_options and
+     access_rights will be ignored.
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   ARM = Adress Range Mapping
+ </para>
+</refsect1>
+<refsect1>
+ <title>returns</title>
+ <para>
+               0  ... success
+   &lt;0 ... failure
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-arm-unregister">raw1394_arm_unregister</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_arm_unregister</refname>
+ <refpurpose>
+      unregister an AddressRangeMapping
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_arm_unregister </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>start</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>start</parameter></term>
+   <listitem>
+    <para>
+                 identifies addressrange for unregistering 
+     (value of start have to be the same value 
+     used for registering this adressrange)
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>returns</title>
+ <para>
+              0  ... success
+   &lt;0 ... failure
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-arm-set-buf">raw1394_arm_set_buf</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_arm_set_buf</refname>
+ <refpurpose>
+      set the buffer of an AdressRangeMapping
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_arm_set_buf </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>start</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>void * <parameter>buf</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>start</parameter></term>
+   <listitem>
+    <para>
+      identifies addressrange
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+      identifies addressrange
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>buf</parameter></term>
+   <listitem>
+    <para>
+      pointer to buffer
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This function copies <parameter>length</parameter> bytes from user memory area <parameter>buf</parameter>
+   to one ARM block in kernel memory area
+   with start offset <parameter>start</parameter>.
+ </para>
+</refsect1>
+<refsect1>
+ <title>returns</title>
+ <para>
+          0  ... success
+   &lt;0 ... failure, and errno - error code
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-arm-get-buf">raw1394_arm_get_buf</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_arm_get_buf</refname>
+ <refpurpose>
+      get the buffer of an AdressRangeMapping
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_arm_get_buf </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>start</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>void * <parameter>buf</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>start</parameter></term>
+   <listitem>
+    <para>
+      identifies addressrange
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+      identifies addressrange
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>buf</parameter></term>
+   <listitem>
+    <para>
+      pointer to buffer
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This function copies <parameter>length</parameter> bytes from one
+   ARM block in kernel memory area with start offset <parameter>start</parameter>
+   to user memory area <parameter>buf</parameter>
+ </para>
+</refsect1>
+<refsect1>
+ <title>returns</title>
+ <para>
+          0  ... success
+   &lt;0 ... failure, and errno - error code
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-echo-request">raw1394_echo_request</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_echo_request</refname>
+ <refpurpose>
+      send an echo request to the driver
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_echo_request </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>quadlet_t <parameter>data</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+                   arbitrary data; raw1394_loop_iterate will return it
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   the driver then send back the
+   same request. raw1394_loop_iterate will return data as return value,
+   when it processes the echo. 
+ </para>
+</refsect1>
+<refsect1>
+ <title>returns</title>
+ <para>
+          0 .... success
+   &lt;0 ... failure
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-wake-up">raw1394_wake_up</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_wake_up</refname>
+ <refpurpose>
+      wake up raw1394_loop_iterate
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_wake_up </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   (or a blocking read from the device
+   file). actually this calls raw1394_echo_request with 0 as data. 
+ </para>
+</refsect1>
+<refsect1>
+ <title>returns</title>
+ <para>
+          0 .... success
+   &lt;0 ... failure
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-phy-packet-write">raw1394_phy_packet_write</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_phy_packet_write</refname>
+ <refpurpose>
+      send physical request
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_phy_packet_write </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>quadlet_t <parameter>data</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   examples of physical requests are linkon, physicalconfigurationpacket, etc.
+ </para>
+</refsect1>
+<refsect1>
+ <title>returns</title>
+ <para>
+          0 .... success
+   &lt;0 ... failure
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-start-read">raw1394_start_read</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_start_read</refname>
+ <refpurpose>
+      initiate a read transaction
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_start_read </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeid_t <parameter>node</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>addr</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>buffer</parameter></paramdef>
+   <paramdef>unsigned long <parameter>tag</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>node</parameter></term>
+   <listitem>
+    <para>
+      target node
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>addr</parameter></term>
+   <listitem>
+    <para>
+      address to read from
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+      amount of data to read
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>buffer</parameter></term>
+   <listitem>
+    <para>
+      pointer to buffer where data will be saved
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag</parameter></term>
+   <listitem>
+    <para>
+      data to identify the request to completion handler
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This function starts the specified read request and returns <constant>0</constant> for success
+   and a negative number for an error, in which case errno will be set.  If
+   <parameter>length</parameter> is <constant>4</constant> a quadlet read is initiated and a block read otherwise.
+   </para><para>
+
+   The transaction is only started, no success of the transaction is implied
+   with a successful return of this function.  When the transaction completes, a
+   <function>raw1394_loop_iterate</function> will call the tag handler and pass it the tag and
+   error code of the transaction.  <parameter>tag</parameter> should therefore be set to something
+   that uniquely identifies this transaction (e.g. a struct pointer casted to
+   unsigned long).
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-start-write">raw1394_start_write</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_start_write</refname>
+ <refpurpose>
+      initiate a write transaction
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_start_write </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeid_t <parameter>node</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>addr</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>data</parameter></paramdef>
+   <paramdef>unsigned long <parameter>tag</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>node</parameter></term>
+   <listitem>
+    <para>
+      target node
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>addr</parameter></term>
+   <listitem>
+    <para>
+      address to write to
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+      amount of data to write
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+      pointer to data to be sent
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag</parameter></term>
+   <listitem>
+    <para>
+      data to identify the request to completion handler
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This function starts the specified write request and returns <constant>0</constant> for success
+   and a negative number for an error, in which case errno will be set.  If
+   <parameter>length</parameter> is <constant>4</constant> a quadlet write is initiated and a block write otherwise.
+   </para><para>
+
+   The transaction is only started, no success of the transaction is implied
+   with a successful return of this function.  When the transaction completes, a
+   <function>raw1394_loop_iterate</function> will call the tag handler and pass it the tag and
+   error code of the transaction.  <parameter>tag</parameter> should therefore be set to something
+   that uniquely identifies this transaction (e.g. a struct pointer casted to
+   unsigned long).
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-start-lock">raw1394_start_lock</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_start_lock</refname>
+ <refpurpose>
+      initiate a 32-bit compare-swap lock transaction
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_start_lock </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeid_t <parameter>node</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>addr</parameter></paramdef>
+   <paramdef>unsigned int <parameter>extcode</parameter></paramdef>
+   <paramdef>quadlet_t <parameter>data</parameter></paramdef>
+   <paramdef>quadlet_t <parameter>arg</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>result</parameter></paramdef>
+   <paramdef>unsigned long <parameter>tag</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>node</parameter></term>
+   <listitem>
+    <para>
+      target node
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>addr</parameter></term>
+   <listitem>
+    <para>
+      address to read from
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>extcode</parameter></term>
+   <listitem>
+    <para>
+      extended transaction code determining the lock operation
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+      data part of lock parameters
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>arg</parameter></term>
+   <listitem>
+    <para>
+      arg part of lock parameters
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>result</parameter></term>
+   <listitem>
+    <para>
+      address where return value will be written
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag</parameter></term>
+   <listitem>
+    <para>
+      data to identify the request to completion handler
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This function starts the specified lock request and returns <constant>0</constant> for success
+   and a negative number for an error, in which case errno will be set.
+   </para><para>
+
+   The transaction is only started, no success of the transaction is implied
+   with a successful return of this function.  When the transaction completes, a
+   <function>raw1394_loop_iterate</function> will call the tag handler and pass it the tag and
+   error code of the transaction.  <parameter>tag</parameter> should therefore be set to something
+   that uniquely identifies this transaction (e.g. a struct pointer casted to
+   unsigned long).
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-start-lock64">raw1394_start_lock64</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_start_lock64</refname>
+ <refpurpose>
+      initiate a 64-bit compare-swap lock transaction
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_start_lock64 </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeid_t <parameter>node</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>addr</parameter></paramdef>
+   <paramdef>unsigned int <parameter>extcode</parameter></paramdef>
+   <paramdef>octlet_t <parameter>data</parameter></paramdef>
+   <paramdef>octlet_t <parameter>arg</parameter></paramdef>
+   <paramdef>octlet_t * <parameter>result</parameter></paramdef>
+   <paramdef>unsigned long <parameter>tag</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>node</parameter></term>
+   <listitem>
+    <para>
+      target node
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>addr</parameter></term>
+   <listitem>
+    <para>
+      address to read from
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>extcode</parameter></term>
+   <listitem>
+    <para>
+      extended transaction code determining the lock operation
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+      data part of lock parameters
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>arg</parameter></term>
+   <listitem>
+    <para>
+      arg part of lock parameters
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>result</parameter></term>
+   <listitem>
+    <para>
+      address where return value will be written
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag</parameter></term>
+   <listitem>
+    <para>
+      data to identify the request to completion handler
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This function starts the specified lock request and returns <constant>0</constant> for success
+   and a negative number for an error, in which case errno will be set.
+   </para><para>
+
+   The transaction is only started, no success of the transaction is implied
+   with a successful return of this function.  When the transaction completes, a
+   <function>raw1394_loop_iterate</function> will call the tag handler and pass it the tag and
+   error code of the transaction.  <parameter>tag</parameter> should therefore be set to something
+   that uniquely identifies this transaction (e.g. a struct pointer casted to
+   unsigned long).
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-start-async-stream">raw1394_start_async_stream</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_start_async_stream</refname>
+ <refpurpose>
+      initiate asynchronous stream
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_start_async_stream </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned int <parameter>channel</parameter></paramdef>
+   <paramdef>unsigned int <parameter>tag</parameter></paramdef>
+   <paramdef>unsigned int <parameter>sy</parameter></paramdef>
+   <paramdef>unsigned int <parameter>speed</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>data</parameter></paramdef>
+   <paramdef>unsigned long <parameter>rawtag</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>sy</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>speed</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>rawtag</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Passes custom tag.  Use pointer to raw1394_reqhandle if you use the standard
+   tag handler.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-start-async-send">raw1394_start_async_send</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_start_async_send</refname>
+ <refpurpose>
+      send an asynchronous packet
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_start_async_send </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>size_t <parameter>header_length</parameter></paramdef>
+   <paramdef>unsigned int <parameter>expect_response</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>data</parameter></paramdef>
+   <paramdef>unsigned long <parameter>rawtag</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>header_length</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>expect_response</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>rawtag</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This starts sending an arbitrary async packet. It gets an array of quadlets 
+   consisting of header and data (without CRC in between). Header information 
+   is always in machine byte order, data (data block as well as quadlet data 
+   in a read response for data quadlet) shall be in big endian byte order. 
+   expect_response indicates, if we expect a response (i.e. if we will get the 
+   tag back after the packet was sent or after a response arrived). length is 
+   the length of the complete packet (header_length + length of the data block).
+   The main purpose of this function is to send responses for incoming 
+   transactions, that are handled by the application.
+   Do not use that function, unless you really know, what you do! Sending 
+   corrupt packet may lead to weird results.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-read">raw1394_read</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_read</refname>
+ <refpurpose>
+      send async read request to a node and wait for response.
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_read </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeid_t <parameter>node</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>addr</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>buffer</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>node</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>addr</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>buffer</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This does the complete transaction and will return when it's finished.  It
+   will call <function>raw1394_loop_iterate</function> as often as necessary, return values of
+   handlers called will be therefore lost.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-write">raw1394_write</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_write</refname>
+ <refpurpose>
+      send async write request to a node and wait for response.
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_write </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeid_t <parameter>node</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>addr</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>data</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>node</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>addr</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This does the complete transaction and will return when it's finished.  It
+   will call <function>raw1394_loop_iterate</function> as often as necessary, return values of
+   handlers called will be therefore lost.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-lock">raw1394_lock</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_lock</refname>
+ <refpurpose>
+      send 32-bit compare-swap lock request and wait for response.
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_lock </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeid_t <parameter>node</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>addr</parameter></paramdef>
+   <paramdef>unsigned int <parameter>extcode</parameter></paramdef>
+   <paramdef>quadlet_t <parameter>data</parameter></paramdef>
+   <paramdef>quadlet_t <parameter>arg</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>result</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>node</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>addr</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>extcode</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>arg</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>result</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This does the complete transaction and will return when it's finished.  It
+   will call <function>raw1394_loop_iterate</function> as often as necessary, return values of
+   handlers called will be therefore lost.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-lock64">raw1394_lock64</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_lock64</refname>
+ <refpurpose>
+      send 64-bit compare-swap lock request and wait for response.
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_lock64 </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>nodeid_t <parameter>node</parameter></paramdef>
+   <paramdef>nodeaddr_t <parameter>addr</parameter></paramdef>
+   <paramdef>unsigned int <parameter>extcode</parameter></paramdef>
+   <paramdef>octlet_t <parameter>data</parameter></paramdef>
+   <paramdef>octlet_t <parameter>arg</parameter></paramdef>
+   <paramdef>octlet_t * <parameter>result</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>node</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>addr</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>extcode</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>arg</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>result</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   This does the complete transaction and will return when it's finished.  It
+   will call <function>raw1394_loop_iterate</function> as often as necessary, return values of
+   handlers called will be therefore lost.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-async-stream">raw1394_async_stream</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_async_stream</refname>
+ <refpurpose>
+   </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_async_stream </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned int <parameter>channel</parameter></paramdef>
+   <paramdef>unsigned int <parameter>tag</parameter></paramdef>
+   <paramdef>unsigned int <parameter>sy</parameter></paramdef>
+   <paramdef>unsigned int <parameter>speed</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>data</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>sy</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>speed</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-async-send">raw1394_async_send</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_async_send</refname>
+ <refpurpose>
+   </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_async_send </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>size_t <parameter>header_length</parameter></paramdef>
+   <paramdef>unsigned int <parameter>expect_response</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>data</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>header_length</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>expect_response</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-start-fcp-listen">raw1394_start_fcp_listen</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_start_fcp_listen</refname>
+ <refpurpose>
+      enable reception of FCP events
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_start_fcp_listen </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   FCP = Function Control Protocol (see IEC 61883-1)
+   Enables the reception of FCP events (writes to the FCP_COMMAND or
+   FCP_RESPONSE address ranges) on <parameter>handle</parameter>.  FCP requests are then passed to the
+   callback specified with <function>raw1394_set_fcp_handler</function>.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-stop-fcp-listen">raw1394_stop_fcp_listen</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_stop_fcp_listen</refname>
+ <refpurpose>
+      disable reception of FCP events
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_stop_fcp_listen </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   Stops the reception of FCP events (writes to the FCP_COMMAND or
+   FCP_RESPONSE address ranges) on <parameter>handle</parameter>.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-get-libversion">raw1394_get_libversion</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_get_libversion</refname>
+ <refpurpose>
+      Returns the version string
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>const char * <function>raw1394_get_libversion </function></funcdef>
+   <paramdef> <parameter>void</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>void</parameter></term>
+   <listitem>
+    <para>
+     no arguments
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   </para><para>
+
+   Instead, typically, one uses 'pkg-config --mod-version libraw1394'
+   Might be useful for an application.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-update-config-rom">raw1394_update_config_rom</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_update_config_rom</refname>
+ <refpurpose>
+      updates the configuration rom of a host
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_update_config_rom </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>const quadlet_t         * <parameter>new_rom</parameter></paramdef>
+   <paramdef>size_t <parameter>size</parameter></paramdef>
+   <paramdef>unsigned char <parameter>rom_version</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>new_rom</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>size</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>rom_version</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   <parameter>rom_version</parameter> must be the current
+   version, otherwise it will fail with return value -1. 
+   Return value -2 indicates that the new rom version is too big.
+   Return value 0 indicates success
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-get-config-rom">raw1394_get_config_rom</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_get_config_rom</refname>
+ <refpurpose>
+      reads the current version of the configuration rom of a host
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_get_config_rom </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>buffer</parameter></paramdef>
+   <paramdef>size_t <parameter>buffersize</parameter></paramdef>
+   <paramdef>size_t * <parameter>rom_size</parameter></paramdef>
+   <paramdef>unsigned char * <parameter>rom_version</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>buffer</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>buffersize</parameter></term>
+   <listitem>
+    <para>
+      is the size of the buffer, <parameter>rom_size</parameter>
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>rom_size</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>rom_version</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   returns the size of the current rom image. <parameter>rom_version</parameter> is the
+   version number of the fetched rom.
+   return value -1 indicates, that the buffer was too small, 
+   0 indicates success.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-int">int</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>int</refname>
+ <refpurpose>
+      DEPRECATED
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>typedef <function>int </function></funcdef>
+   <paramdef>* <parameter>iso_handler_t</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>iso_handler_t</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   DEPRECATED
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-set-iso-handler">raw1394_set_iso_handler</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_set_iso_handler</refname>
+ <refpurpose>
+      set isochronous packet handler (DEPRECATED)
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>iso_handler_t <function>raw1394_set_iso_handler </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned int <parameter>channel</parameter></paramdef>
+   <paramdef>iso_handler_t <parameter>new_h</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>new_h</parameter></term>
+   <listitem>
+    <para>
+      pointer to new handler
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   DEPRECATED
+   </para><para>
+
+   Sets the handler to be called when an isochronous packet is received to
+   <parameter>new_h</parameter> and returns the old handler.  The default handler does nothing.
+   </para><para>
+
+   In order to actually get iso packet events, receiving on a specific channel
+   first has to be enabled with <function>raw1394_start_iso_rcv</function> and can be stopped again
+   with <function>raw1394_stop_iso_rcv</function>.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-start-iso-rcv">raw1394_start_iso_rcv</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_start_iso_rcv</refname>
+ <refpurpose>
+      enable isochronous receiving (DEPRECATED)
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_start_iso_rcv </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned int <parameter>channel</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+      channel number to start receiving on
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   DEPRECATED
+   </para><para>
+
+   Enables the reception of isochronous packets in <parameter>channel</parameter> on <parameter>handle</parameter>.
+   Isochronous packets are then passed to the callback specified with
+   <function>raw1394_set_iso_handler</function>.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-stop-iso-rcv">raw1394_stop_iso_rcv</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_stop_iso_rcv</refname>
+ <refpurpose>
+      stop isochronous receiving (DEPRECATED)
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_stop_iso_rcv </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned int <parameter>channel</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+      channel to stop receiving on
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   DEPRECATED
+   </para><para>
+
+   Stops the reception of isochronous packets in <parameter>channel</parameter> on <parameter>handle</parameter>.
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-start-iso-write">raw1394_start_iso_write</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_start_iso_write</refname>
+ <refpurpose>
+      initiate an isochronous packet write (DEPRECATED)
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_start_iso_write </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned int <parameter>channel</parameter></paramdef>
+   <paramdef>unsigned int <parameter>tag</parameter></paramdef>
+   <paramdef>unsigned int <parameter>sy</parameter></paramdef>
+   <paramdef>unsigned int <parameter>speed</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>data</parameter></paramdef>
+   <paramdef>unsigned long <parameter>rawtag</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+      channel number on which to send on
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag</parameter></term>
+   <listitem>
+    <para>
+      data to be put into packet's tag field
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>sy</parameter></term>
+   <listitem>
+    <para>
+      data to be put into packet's sy field
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>speed</parameter></term>
+   <listitem>
+    <para>
+      speed at which to send
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+      amount of data to send
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+      pointer to data to send
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>rawtag</parameter></term>
+   <listitem>
+    <para>
+      data to identify the request to completion handler
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   DEPRECATED
+   </para><para>
+
+   This function starts the specified isochronous packet transmission and
+   returns <constant>0</constant> for success and a negative number for an error, in which case
+   errno will be set.
+   </para><para>
+
+   When the send completes, a <function>raw1394_loop_iterate</function> will call the tag handler
+   and pass it the tag and error code of the transaction.  <parameter>tag</parameter> should therefore
+   be set to something that uniquely identifies this transaction (e.g. a struct
+   pointer casted to unsigned long).
+   </para><para>
+
+   Isochronous packets are automatically
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-iso-write">raw1394_iso_write</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_iso_write</refname>
+ <refpurpose>
+      DEPRECATED
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_iso_write </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>unsigned int <parameter>channel</parameter></paramdef>
+   <paramdef>unsigned int <parameter>tag</parameter></paramdef>
+   <paramdef>unsigned int <parameter>sy</parameter></paramdef>
+   <paramdef>unsigned int <parameter>speed</parameter></paramdef>
+   <paramdef>size_t <parameter>length</parameter></paramdef>
+   <paramdef>quadlet_t * <parameter>data</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>channel</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>sy</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>speed</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>length</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+     -- undescribed --
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   DEPRECATED
+ </para>
+</refsect1>
+</refentry>
 
-	<para>
-	  <function>raw1394_get_local_id()</function> returns the node ID of the
-	  local node (i.e. the hardware the driver is controlling directly).
-	  <function>raw1394_get_irm_id()</function> returns the node ID of the
-	  node that has become isochronous resource manager.
-	  <function>raw1394_get_nodecount</function> returns the number of nodes
-	  currently on the bus (including the local node).
-	</para>
-      </refsect1>
-    </refentry>
   </chapter>
 
 </book>
diff --git a/src/arm.c b/src/arm.c
index f185495..d87e326 100644
--- a/src/arm.c
+++ b/src/arm.c
@@ -52,8 +52,8 @@ int raw1394_arm_register(struct raw1394_handle *handle, nodeaddr_t start,
         int     retval=0;
         struct  raw1394_request req;
 
-	if (((start & ~(0xFFFFFFFFFFFF)) != 0) ||
-                (((start + length) & ~(0xFFFFFFFFFFFF)) != 0)) {
+	if (((start & ~(0xFFFFFFFF)) != 0) ||
+                (((start + length) & ~(0xFFFFFFFF)) != 0)) {
                 errno = EINVAL;
                 return (-1);
 	}
@@ -152,4 +152,3 @@ int raw1394_arm_get_buf (struct raw1394_handle *handle, nodeaddr_t start,
 
         return 0;
 }
-
diff --git a/src/errors.c b/src/errors.c
index e5f1af4..63db73d 100644
--- a/src/errors.c
+++ b/src/errors.c
@@ -17,42 +17,11 @@
 #include "ieee1394.h"
 
 
-/**
- * raw1394_get_errcode - return error code of async transaction
- *
- * Returns the error code of the last raw1394_read(), raw1394_write(),
- * raw1394_lock() or raw1394_iso_write().  The error code is either an internal
- * error (i.e. not a bus error) or a combination of acknowledge code and
- * response code, as appropriate.
- *
- * Some macros are available to extract information from the error code,
- * raw1394_errcode_to_errno() can be used to convert it to an errno number of
- * roughly the same meaning.
- **/
 raw1394_errcode_t raw1394_get_errcode(struct raw1394_handle *handle)
 {
         return handle->err;
 }
 
-/**
- * raw1394_errcode_to_errno - convert libraw1394 errcode to errno
- * @errcode: the error code to convert
- *
- * The error code as retrieved by raw1394_get_errcode() is converted into a
- * roughly equivalent errno number and returned.  %0xdead is returned for an
- * illegal errcode.
- *
- * It is intended to be used to decide what to do (retry, give up, report error)
- * for those programs that aren't interested in details, since these get lost in
- * the conversion.  However the returned errnos are equivalent in source code
- * meaning only, the associated text of e.g. perror() is not necessarily
- * meaningful.
- *
- * Returned values are %EAGAIN (retrying might succeed, also generation number
- * mismatch), %EREMOTEIO (other node had internal problems), %EPERM (operation
- * not allowed on this address, e.g. write on read-only location), %EINVAL
- * (invalid argument) and %EFAULT (invalid pointer).
- **/
 int raw1394_errcode_to_errno(raw1394_errcode_t errcode)
 {
         static const int ack2errno[16] = {
diff --git a/src/eventloop.c b/src/eventloop.c
index 982f700..5c3fc03 100644
--- a/src/eventloop.c
+++ b/src/eventloop.c
@@ -27,17 +27,6 @@
 #include "raw1394_private.h"
 
 
-/**
- * raw1394_loop_iterate - get and process one event message
- *
- * Get one new message through handle and process it with the registered message
- * handler.  This function will return %-1 for an error or the return value of
- * the handler which got executed.  The default handlers always return zero.
- *
- * Note that some other library functions may call this function multiple times
- * to wait for their completion, some handler return values may get lost if you
- * use these.
- **/
 int raw1394_loop_iterate(struct raw1394_handle *handle)
 {
         struct raw1394_request req;
@@ -115,13 +104,6 @@ int raw1394_loop_iterate(struct raw1394_handle *handle)
 }
 
 
-/**
- * raw1394_set_bus_reset_handler - set bus reset handler
- * @new_h: pointer to new handler
- *
- * Sets the handler to be called on every bus reset to @new_h and returns the
- * old handler. The default handler just calls raw1394_update_generation().
- **/
 bus_reset_handler_t raw1394_set_bus_reset_handler(struct raw1394_handle *handle,
                                                   bus_reset_handler_t new)
 {
@@ -133,19 +115,6 @@ bus_reset_handler_t raw1394_set_bus_reset_handler(struct raw1394_handle *handle,
         return old;
 }
 
-/**
- * raw1394_set_tag_handler - set request completion handler
- * @new_h: pointer to new handler
- *
- * Sets the handler to be called whenever a request completes to @new_h and
- * returns the old handler.  The default handler interprets the tag as a pointer
- * to a &struct raw1394_reqhandle and calls the callback in there.
- *
- * Care must be taken when replacing the tag handler and calling the synchronous
- * versions of the transaction functions (i.e. raw1394_read(), raw1394_write(),
- * raw1394_lock(), raw1394_iso_write()) since these do pass pointers to &struct
- * raw1394_reqhandle as the tag and expect the callback to be invoked.
- **/
 tag_handler_t raw1394_set_tag_handler(struct raw1394_handle *handle, 
                                       tag_handler_t new)
 {
@@ -169,17 +138,6 @@ arm_tag_handler_t raw1394_set_arm_tag_handler(struct raw1394_handle *handle,
 }
 
 
-/**
- * raw1394_set_iso_handler - set isochronous packet handler
- * @new_h: pointer to new handler
- *
- * Sets the handler to be called when an isochronous packet is received to
- * @new_h and returns the old handler.  The default handler does nothing.
- *
- * In order to actually get iso packet events, receiving on a specific channel
- * first has to be enabled with raw1394_start_iso_rcv() and can be stopped again
- * with raw1394_stop_iso_rcv().
- **/
 iso_handler_t raw1394_set_iso_handler(struct raw1394_handle *handle,
                                       unsigned int channel, iso_handler_t new)
 {
@@ -201,17 +159,6 @@ iso_handler_t raw1394_set_iso_handler(struct raw1394_handle *handle,
         return NULL;
 }
 
-/**
- * raw1394_set_fcp_handler - set FCP handler
- * @new_h: pointer to new handler
- *
- * Sets the handler to be called when either FCP command or FCP response
- * registers get written to @new_h and returns the old handler.  The default
- * handler does nothing.
- *
- * In order to actually get FCP events, you have to enable it with
- * raw1394_start_fcp_listen() and can stop it with raw1394_stop_fcp_listen().
- **/
 fcp_handler_t raw1394_set_fcp_handler(struct raw1394_handle *handle,
                                       fcp_handler_t new)
 {
diff --git a/src/fcp.c b/src/fcp.c
index da05b03..79939be 100644
--- a/src/fcp.c
+++ b/src/fcp.c
@@ -54,24 +54,11 @@ static int do_fcp_listen(struct raw1394_handle *handle, int startstop)
 }
 
 
-/**
- * raw1394_start_fcp_listen - enable reception of FCP events
- *
- * Enables the reception of FCP events (writes to the FCP_COMMAND or
- * FCP_RESPONSE address ranges) on @handle.  FCP requests are then passed to the
- * callback specified with raw1394_set_fcp_handler().
- **/
 int raw1394_start_fcp_listen(struct raw1394_handle *handle)
 {
         return do_fcp_listen(handle, 1);
 }
 
-/**
- * raw1394_stop_fcp_listen - disable reception of FCP events
- *
- * Stops the reception of FCP events (writes to the FCP_COMMAND or
- * FCP_RESPONSE address ranges) on @handle.
- **/
 int raw1394_stop_fcp_listen(struct raw1394_handle *handle)
 {
         return do_fcp_listen(handle, 0);
diff --git a/src/iso.c b/src/iso.c
index f4c6204..51e5921 100644
--- a/src/iso.c
+++ b/src/iso.c
@@ -60,14 +60,6 @@ static int do_iso_listen(struct raw1394_handle *handle, int channel)
         }
 }
 
-/**
- * raw1394_start_iso_rcv - enable isochronous receiving
- * @channel: channel number to start receiving on
- *
- * Enables the reception of isochronous packets in @channel on @handle.
- * Isochronous packets are then passed to the callback specified with
- * raw1394_set_iso_handler().
- **/
 int raw1394_start_iso_rcv(struct raw1394_handle *handle, unsigned int channel)
 {
         if (channel > 63) {
@@ -78,12 +70,6 @@ int raw1394_start_iso_rcv(struct raw1394_handle *handle, unsigned int channel)
         return do_iso_listen(handle, channel);
 }
 
-/**
- * raw1394_stop_iso_rcv - stop isochronous receiving
- * @channel: channel to stop receiving on
- *
- * Stops the reception of isochronous packets in @channel on @handle.
- **/
 int raw1394_stop_iso_rcv(struct raw1394_handle *handle, unsigned int channel)
 {
         if (channel > 63) {
@@ -169,17 +155,6 @@ static int do_iso_init(raw1394handle_t handle,
 	return 0;			
 }
 
-/**
- * raw1394_iso_xmit_init - initialize isochronous transmission
- * @handler: handler function for queueing packets
- * @buf_packets: number of isochronous packets to buffer
- * @max_packet_size: largest packet you need to handle, in bytes (not including the isochronous header)
- * @channel: isochronous channel on which to transmit
- * @speed: speed at which to transmit
- * @irq_interval: maximum latency of wake-ups, in packets (-1 if you don't care)
- *
- * Allocates all user and kernel resources necessary for isochronous transmission.
- **/
 int raw1394_iso_xmit_init(raw1394handle_t handle,
 			  raw1394_iso_xmit_handler_t handler,
 			  unsigned int buf_packets,
@@ -199,17 +174,6 @@ int raw1394_iso_xmit_init(raw1394handle_t handle,
 	return 0;
 }
 
-/**
- * raw1394_iso_recv_init - initialize isochronous reception
- * @handler: handler function for receiving packets
- * @buf_packets: number of isochronous packets to buffer
- * @max_packet_size: largest packet you need to handle, in bytes (not including the isochronous header)
- * @channel: isochronous channel to receive
- * @speed: speed at which to receive
- * @irq_interval: maximum latency of wake-ups, in packets (-1 if you don't care)
- *
- * Allocates all user and kernel resources necessary for isochronous reception.
- **/
 int raw1394_iso_recv_init(raw1394handle_t handle,
 			  raw1394_iso_recv_handler_t handler,
 			  unsigned int buf_packets,
@@ -228,16 +192,6 @@ int raw1394_iso_recv_init(raw1394handle_t handle,
 	return 0;
 }
 
-/**
- * raw1394_iso_multichannel_recv_init - initialize multi-channel isochronous reception
- * @handler: handler function for receiving packets
- * @buf_packets: number of isochronous packets to buffer
- * @max_packet_size: largest packet you need to handle, in bytes (not including the isochronous header)
- * @speed: speed at which to receive
- * @irq_interval: maximum latency of wake-ups, in packets (-1 if you don't care)
- *
- * Allocates all user and kernel resources necessary for isochronous reception.
- **/
 int raw1394_iso_multichannel_recv_init(raw1394handle_t handle,
 				       raw1394_iso_recv_handler_t handler,
 				       unsigned int buf_packets,
@@ -255,9 +209,6 @@ int raw1394_iso_multichannel_recv_init(raw1394handle_t handle,
 	return 0;
 }
 
-/**
- * raw1394_iso_recv_listen_channel - listen to a specific channel in multi-channel mode
- **/
 int raw1394_iso_recv_listen_channel(raw1394handle_t handle, unsigned char channel)
 {
 	if (handle->iso_mode != ISO_RECV) {
@@ -268,9 +219,6 @@ int raw1394_iso_recv_listen_channel(raw1394handle_t handle, unsigned char channe
 	return ioctl(handle->fd, RAW1394_IOC_ISO_RECV_LISTEN_CHANNEL, channel);
 }
 
-/**
- * raw1394_iso_recv_unlisten_channel - stop listening  to a specific channel in multi-channel mode
- **/
 int raw1394_iso_recv_unlisten_channel(raw1394handle_t handle, unsigned char channel)
 {
 	if (handle->iso_mode != ISO_RECV) {
@@ -281,16 +229,6 @@ int raw1394_iso_recv_unlisten_channel(raw1394handle_t handle, unsigned char chan
 	return ioctl(handle->fd, RAW1394_IOC_ISO_RECV_UNLISTEN_CHANNEL, channel);
 }
 
-/**
- * raw1394_iso_recv_flush - if you specified an irq_interval > 1 in
- * iso_recv_init, you won't be notified for every single iso packet, but
- * for groups of them. Now e.g. if irq_interval is 100, and you were just
- * notified about iso packets and after them only 20 more packets arrived,
- * no notification will be generated (20 < 100). In the case that you know
- * that there should be more packets at this moment, you can call this
- * function and all iso packets which are already received by the kernel
- * will be flushed out to user space.
- */
 int raw1394_iso_recv_flush(raw1394handle_t handle)
 {
 	if (handle->iso_mode != ISO_RECV) {
@@ -301,13 +239,6 @@ int raw1394_iso_recv_flush(raw1394handle_t handle)
 	return ioctl(handle->fd, RAW1394_IOC_ISO_RECV_FLUSH, 0);
 }
 
-/**
- * raw1394_iso_recv_set_channel_mask - listen or unlisten to a whole bunch of channels at once
- * @mask: 64-bit mask of channels, 1 means listen, 0 means unlisten,
- *        channel 0 is LSB, channel 63 is MSB
- *
- * for multi-channel reception mode only
- **/
 int raw1394_iso_recv_set_channel_mask(raw1394handle_t handle, u_int64_t mask)
 {
 	if (handle->iso_mode != ISO_RECV) {
@@ -318,12 +249,6 @@ int raw1394_iso_recv_set_channel_mask(raw1394handle_t handle, u_int64_t mask)
 	return ioctl(handle->fd, RAW1394_IOC_ISO_RECV_SET_CHANNEL_MASK, (void*) &mask);
 }
 
-/**
- * raw1394_iso_recv_start - begin isochronous reception
- * @start_on_cycle: isochronous cycle number on which to start (-1 if you don't care)
- * @tag_mask: mask of tag fields to match (-1 to receive all packets)
- * @sync: not used, reserved for future implementation
- **/
 int raw1394_iso_recv_start(raw1394handle_t handle, int start_on_cycle, int tag_mask, int sync)
 {
 	int args[3];
@@ -422,13 +347,6 @@ out:
 	return retval;
 }
 
-/**
- * raw1394_iso_xmit_write - alternative blocking-write API for ISO transmission
- * @data: pointer to packet data buffer
- * @len: length of packet, in bytes
- * @tag: tag field
- * @sy: sync field
- **/
 int raw1394_iso_xmit_write(raw1394handle_t handle, unsigned char *data, unsigned int len,
 			   unsigned char tag, unsigned char sy)
 {
@@ -477,11 +395,6 @@ int raw1394_iso_xmit_write(raw1394handle_t handle, unsigned char *data, unsigned
 	return 0;
 }
 
-/**
- * raw1394_iso_xmit_start - begin isochronous transmission
- * @start_on_cycle: isochronous cycle number on which to start (-1 if you don't care)
- * @prebuffer_packets: number of packets to queue up before starting transmission (-1 if you don't care)
- **/
 int raw1394_iso_xmit_start(raw1394handle_t handle, int start_on_cycle, int prebuffer_packets)
 {
 	int args[2];
@@ -501,9 +414,6 @@ int raw1394_iso_xmit_start(raw1394handle_t handle, int start_on_cycle, int prebu
 	return 0;
 }
 
-/**
- * raw1394_iso_xmit_sync - wait until all queued packets have been sent
- **/
 int raw1394_iso_xmit_sync(raw1394handle_t handle)
 {
 	if(handle->iso_mode != ISO_XMIT) {
@@ -513,9 +423,6 @@ int raw1394_iso_xmit_sync(raw1394handle_t handle)
 	return ioctl(handle->fd, RAW1394_IOC_ISO_XMIT_SYNC, 0);
 }
 
-/**
- * raw1394_iso_stop - halt isochronous transmission or reception
- **/
 void raw1394_iso_stop(raw1394handle_t handle)
 {
 	if(handle->iso_mode == ISO_INACTIVE) {
@@ -526,9 +433,6 @@ void raw1394_iso_stop(raw1394handle_t handle)
 	handle->iso_state = ISO_STOP;
 }
 
-/**
- * raw1394_iso_shutdown - clean up and deallocate all resources for isochronous transmission or reception
- **/
 void raw1394_iso_shutdown(raw1394handle_t handle)
 {
 	if(handle->iso_buffer) {
@@ -640,4 +544,3 @@ int _raw1394_iso_iterate(raw1394handle_t handle)
 
 	return 0;
 }
-
diff --git a/src/main.c b/src/main.c
index 39d93a6..88a04ac 100644
--- a/src/main.c
+++ b/src/main.c
@@ -109,18 +109,6 @@ static unsigned int init_rawdevice(struct raw1394_handle *h)
 }
 
 
-/**
- * raw1394_new_handle - create new handle
- *
- * Creates and returns a new handle which can (after being set up) control one
- * port.  It is not allowed to use the same handle in multiple threads or forked
- * processes.  It is allowed to create and use multiple handles, however.  Use
- * one handle per thread which needs it in the multithreaded case.
- *
- * Returns the created handle or %NULL when initialization fails.  In the latter
- * case errno either contains some OS specific error code or %0 if the error is
- * that libraw1394 and raw1394 don't support each other's protocol versions.
- **/
 struct raw1394_handle *raw1394_new_handle(void)
 {
         struct raw1394_handle *handle;
@@ -154,14 +142,6 @@ struct raw1394_handle *raw1394_new_handle(void)
         return handle;
 }
 
-/**
- * raw1394_destroy_handle - deallocate handle
- * @handle: handle to deallocate
- *
- * Closes connection with raw1394 on this handle and deallocates everything
- * associated with it.  It is safe to pass %NULL as handle, nothing is done in
- * this case.
- **/
 void raw1394_destroy_handle(struct raw1394_handle *handle)
 {
 	if (handle) {
@@ -173,137 +153,46 @@ void raw1394_destroy_handle(struct raw1394_handle *handle)
 	}
 }
 
-/**
- * raw1394_get_fd - get the communication file descriptor
- * @handle: raw1394 handle
- *
- * Returns the fd used for communication with the raw1394 kernel module.  This
- * can be used for select()/poll() calls if you wait on other fds or can be
- * integrated into another event loop (e.g. from a GUI application framework).
- * It can also be used to set/remove the O_NONBLOCK flag using fcntl() to modify
- * the blocking behaviour in raw1394_loop_iterate().  It must not be used for
- * anything else.
- **/
 int raw1394_get_fd(struct raw1394_handle *handle)
 {
         return handle->fd;
 }
 
-/**
- * raw1394_get_generation - get generation number of handle
- *
- * This function returns the generation number associated with the handle.  The
- * generation number is incremented on every bus reset, and every transaction
- * started by raw1394 is tagged with the stored generation number.  If these
- * don't match, the transaction will abort with an error.
- *
- * The generation number of the handle is not automatically updated,
- * raw1394_update_generation() has to be used for this.
- **/
 unsigned int raw1394_get_generation(struct raw1394_handle *handle)
 {
         return handle->generation;
 }
 
-/**
- * raw1394_update_generation - set generation number of handle
- * @gen: new generation number
- *
- * This function sets the generation number of the handle to @gen.  All requests
- * that apply to a single node ID are tagged with this number and abort with an
- * error if that is different from the generation number kept in the kernel.
- * This avoids acting on the wrong node which may have changed its ID in a bus
- * reset.
- *
- * TODO HERE
- **/
 void raw1394_update_generation(struct raw1394_handle *handle, unsigned int gen)
 {
         handle->generation = gen;
 }
 
-/**
- * raw1394_get_nodecount - get number of nodes on the bus
- * @handle: libraw1394 handle
- *
- * Returns the number of nodes on the bus to which the handle is connected.
- * This value can change with every bus reset.  Since the root node always has
- * the highest node ID, this number can be used to determine that ID (it's
- * LOCAL_BUS|(count-1)).
- **/
 int raw1394_get_nodecount(struct raw1394_handle *handle)
 {
         return handle->num_of_nodes;
 }
 
-/**
- * raw1394_get_local_id - get local node ID
- * @handle: libraw1394 handle
- *
- * Returns the node ID of the local node connected to which the handle is
- * connected.  This value can change with every bus reset.
- **/
 nodeid_t raw1394_get_local_id(struct raw1394_handle *handle)
 {
         return handle->local_id;
 }
 
-/**
- * raw1394_get_irm_id - get node ID of isochronous resource manager
- * @handle: libraw1394 handle
- *
- * Returns the node ID of the isochronous resource manager of the bus the handle
- * is connected to.  This value may change with every bus reset.
- **/
 nodeid_t raw1394_get_irm_id(struct raw1394_handle *handle)
 {
         return handle->irm_id;
 }
 
-/**
- * raw1394_set_userdata - associate user data with a handle
- * @handle: raw1394 handle
- * @data: user data (pointer)
- *
- * Allows to associate one void pointer with a handle.  libraw1394 does not care
- * about the data, it just stores it in the handle allowing it to be retrieved
- * at any time with raw1394_get_userdata().  This can be useful when multiple
- * handles are used, so that callbacks can identify the handle.
- **/
 void raw1394_set_userdata(struct raw1394_handle *handle, void *data)
 {
         handle->userdata = data;
 }
 
-/**
- * raw1394_get_userdata - retrieve user data from handle
- * @handle: libraw1394 handle
- *
- * Returns the user data pointer associated with the handle using
- * raw1394_set_userdata().
- **/
 void *raw1394_get_userdata(struct raw1394_handle *handle)
 {
         return handle->userdata;
 }
 
-/**
- * raw1394_get_port_info - get information about available ports
- * @pinf: pointer to an array of struct raw1394_portinfo
- * @maxports: number of elements in @pinf
- *
- * Before you can set which port to use, you have to use this function to find
- * out which ports exist.
- *
- * If your program is interactive, you should present the user with this list to
- * let them decide which port to use if there is more than one.  A
- * non-interactive program (and probably interactive ones, too) should provide a
- * command line option to choose the port.
- *
- * Returns the number of ports and writes information about them into @pinf, but
- * not into more than @maxports elements.  If @maxports is %0, @pinf can be
- * %NULL, too.
- **/
 int raw1394_get_port_info(struct raw1394_handle *handle, 
                           struct raw1394_portinfo *pinf, int maxports)
 {
@@ -341,21 +230,6 @@ int raw1394_get_port_info(struct raw1394_handle *handle,
 }
 
 
-/**
- * raw1394_set_port - choose port for handle
- * @port: port to connect to (corresponds to index of struct raw1394_portinfo)
- *
- * This function connects the handle to the port given (as queried with
- * raw1394_get_port_info()).  If successful, raw1394_get_port_info() and
- * raw1394_set_port() are not allowed to be called afterwards on this handle.
- * To make up for this, all the other functions (those handling asynchronous and
- * isochronous transmissions) can now be called.
- *
- * Returns %0 for success and -1 for failure with errno set appropriately.  A
- * possible failure mode is with errno = %ESTALE, in this case the configuration
- * has changed since the call to raw1394_get_port_info() and it has to be called
- * again to update your view of the available ports.
- **/
 int raw1394_set_port(struct raw1394_handle *handle, int port)
 {
         struct raw1394_request req;
@@ -394,16 +268,6 @@ int raw1394_set_port(struct raw1394_handle *handle, int port)
         }
 }
 
-/**
- * raw1394_new_handle_on_port - create a new handle and bind it to a port
- * @port: port to connect to (same as argument to raw1394_set_port())
- *
- * Same as raw1394_new_handle(), but also binds the handle to the
- * specified 1394 port. Equivalent to raw1394_new_handle() followed by
- * raw1394_get_port_info() and raw1394_set_port(). Useful for
- * command-line programs that already know what port they want. If
- * raw1394_set_port() returns ESTALE, retries automatically.
- **/
 raw1394handle_t raw1394_new_handle_on_port(int port)
 {
 	raw1394handle_t handle = raw1394_new_handle();
@@ -444,15 +308,6 @@ int raw1394_reset_bus_new(struct raw1394_handle *handle, int type)
 }
 
 
-/**
- * raw1394_reset_bus - initiate bus reset
- *
- * This function initiates a bus reset on the connected port.  Usually this is
- * not necessary and should be avoided, this function is here for low level bus
- * control and debugging.
- *
- * Returns %0 for success and -1 for failure with errno set appropriately.
- **/
 int raw1394_reset_bus(struct raw1394_handle *handle)
 {
         return raw1394_reset_bus_new (handle, RAW1394_LONG_RESET);
diff --git a/src/raw1394.h b/src/raw1394.h
index c4112a3..c3cdd22 100644
--- a/src/raw1394.h
+++ b/src/raw1394.h
@@ -1,3 +1,14 @@
+/*
+ * libraw1394 - library for raw access to the 1394 bus with the Linux subsystem.
+ *
+ * Copyright (C) 1999-2004 Andreas Bombe, Dan Maas, Manfred Weihs, and
+ *    Christian Toegel
+ *
+ * This library is licensed under the GNU Lesser General Public License (LGPL),
+ * version 2.1 or later. See the file COPYING.LIB in the distribution for
+ * details.
+ */
+
 #ifndef _LIBRAW1394_RAW1394_H
 #define _LIBRAW1394_RAW1394_H
 
@@ -87,66 +98,182 @@ extern "C" {
 
 /* handlers for transmitting/receiving isochronous packets */
 
-typedef enum raw1394_iso_disposition (*raw1394_iso_xmit_handler_t)(raw1394handle_t,
-								   unsigned char *data,
-								   unsigned int *len,
-								   unsigned char *tag,
-								   unsigned char *sy,
-								   int cycle, /* -1 if unknown */
-								   unsigned int dropped);
-
-typedef enum raw1394_iso_disposition (*raw1394_iso_recv_handler_t)(raw1394handle_t,
-								   unsigned char *data,
-								   unsigned int len,
-								   unsigned char channel,
-								   unsigned char tag,
-								   unsigned char sy,
-								   unsigned int cycle,
-								   unsigned int dropped);
-
+typedef enum raw1394_iso_disposition (*raw1394_iso_xmit_handler_t)(
+	raw1394handle_t handle,
+	unsigned char *data,
+	unsigned int *len,
+	unsigned char *tag,
+	unsigned char *sy,
+	int cycle, /* -1 if unknown */
+	unsigned int dropped);
+
+typedef enum raw1394_iso_disposition (*raw1394_iso_recv_handler_t)(
+	raw1394handle_t handle,
+	unsigned char *data,
+	unsigned int len,
+	unsigned char channel,
+	unsigned char tag,
+	unsigned char sy,
+	unsigned int cycle,
+	unsigned int dropped);
+
+/**
+ * raw1394_iso_xmit_init - initialize isochronous transmission
+ * @handle: libraw1394 handle
+ * @handler: handler function for queueing packets
+ * @buf_packets: number of isochronous packets to buffer
+ * @max_packet_size: largest packet you need to handle, in bytes
+ * (not including the isochronous header)
+ * @channel: isochronous channel on which to transmit
+ * @speed: speed at which to transmit
+ * @irq_interval: maximum latency of wake-ups, in packets (-1 if you don't care)
+ *
+ * Allocates all user and kernel resources necessary for isochronous transmission.
+ **/
 int raw1394_iso_xmit_init(raw1394handle_t handle,
-			  raw1394_iso_xmit_handler_t handler,
-			  unsigned int buf_packets,
-			  unsigned int max_packet_size,
-			  unsigned char channel,
-			  enum raw1394_iso_speed speed,
-			  int irq_interval);
-
+                          raw1394_iso_xmit_handler_t handler,
+                          unsigned int buf_packets,
+                          unsigned int max_packet_size,
+                          unsigned char channel,
+                          enum raw1394_iso_speed speed,
+                          int irq_interval);
+
+/**
+ * raw1394_iso_recv_init - initialize isochronous reception
+ * @handle: libraw1394 handle
+ * @handler: handler function for receiving packets
+ * @buf_packets: number of isochronous packets to buffer
+ * @max_packet_size: largest packet you need to handle, in bytes (not including
+ * the isochronous header)
+ * @channel: isochronous channel to receive
+ * @speed: speed at which to receive
+ * @irq_interval: maximum latency of wake-ups, in packets
+ * (-1 if you don't care)
+ *
+ * Allocates all user and kernel resources necessary for isochronous reception.
+ **/
 int raw1394_iso_recv_init(raw1394handle_t handle,
-			  raw1394_iso_recv_handler_t handler,
-			  unsigned int buf_packets,
-			  unsigned int max_packet_size,
-			  unsigned char channel,
-			  enum raw1394_iso_dma_recv_mode mode,
-			  int irq_interval);
-
+                          raw1394_iso_recv_handler_t handler,
+                          unsigned int buf_packets,
+                          unsigned int max_packet_size,
+                          unsigned char channel,
+                          enum raw1394_iso_dma_recv_mode mode,
+                          int irq_interval);
+
+/**
+ * raw1394_iso_multichannel_recv_init - initialize multi-channel iso reception
+ * @handle: libraw1394 handle
+ * @handler: handler function for receiving packets
+ * @buf_packets: number of isochronous packets to buffer
+ * @max_packet_size: largest packet you need to handle, in bytes (not including
+ * the isochronous header)
+ * @speed: speed at which to receive
+ * @irq_interval: maximum latency of wake-ups, in packets (-1 if you don't care)
+ *
+ * Allocates all user and kernel resources necessary for isochronous reception.
+ **/
 int raw1394_iso_multichannel_recv_init(raw1394handle_t handle,
-				       raw1394_iso_recv_handler_t handler,
-				       unsigned int buf_packets,
-				       unsigned int max_packet_size,
-				       int irq_interval);
-
-/* listen/unlisten on a specific channel (multi-channel mode ONLY) */	
-int raw1394_iso_recv_listen_channel(raw1394handle_t handle, unsigned char channel);
-int raw1394_iso_recv_unlisten_channel(raw1394handle_t handle, unsigned char channel);
+                                       raw1394_iso_recv_handler_t handler,
+                                       unsigned int buf_packets,
+                                       unsigned int max_packet_size,
+                                       int irq_interval);
+
+/**
+ * raw1394_iso_recv_listen_channel - listen to a specific channel in multi-channel mode
+ * @handle: libraw1394 handle
+ *
+ * listen/unlisten on a specific channel (multi-channel mode ONLY)	
+ **/
+int raw1394_iso_recv_listen_channel(raw1394handle_t handle, 
+                                    unsigned char channel);
+
+/**
+ * raw1394_iso_recv_unlisten_channel - stop listening  to a specific channel in multi-channel mode
+ * @handle: libraw1394 handle
+ **/
+int raw1394_iso_recv_unlisten_channel(raw1394handle_t handle, 
+                                      unsigned char channel);
+
+/**
+ * raw1394_iso_recv_set_channel_mask - listen or unlisten to a whole bunch of channels at once
+ * @handle: libraw1394 handle
+ * @mask: 64-bit mask of channels, 1 means listen, 0 means unlisten,
+ *        channel 0 is LSB, channel 63 is MSB
+ *
+ * for multi-channel reception mode only
+ **/
 int raw1394_iso_recv_set_channel_mask(raw1394handle_t handle, u_int64_t mask);
 
-int raw1394_iso_xmit_start(raw1394handle_t handle, int start_on_cycle, int prebuffer_packets);
-int raw1394_iso_recv_start(raw1394handle_t handle, int start_on_cycle, int tag_mask, int sync);
-
-/* write() style API - do NOT use this if you have set an xmit_handler
+/**
+ * raw1394_iso_xmit_start - begin isochronous transmission
+ * @handle: libraw1394 handle
+ * @start_on_cycle: isochronous cycle number on which to start 
+ * (-1 if you don't care)
+ * @prebuffer_packets: number of packets to queue up before starting transmission
+ * (-1 if you don't care)
+ **/
+int raw1394_iso_xmit_start(raw1394handle_t handle, int start_on_cycle,
+                           int prebuffer_packets);
+
+/**
+ * raw1394_iso_recv_start - begin isochronous reception
+ * @handle: libraw1394 handle
+ * @start_on_cycle: isochronous cycle number on which to start 
+ * (-1 if you don't care)
+ * @tag_mask: mask of tag fields to match (-1 to receive all packets)
+ * @sync: not used, reserved for future implementation
+ **/
+int raw1394_iso_recv_start(raw1394handle_t handle, int start_on_cycle, 
+                           int tag_mask, int sync);
+
+/**
+ * raw1394_iso_xmit_write - alternative blocking-write API for ISO transmission
+ * @handle: libraw1394 handle
+ * @data: pointer to packet data buffer
+ * @len: length of packet, in bytes
+ * @tag: tag field
+ * @sy: sync field
+ *
+ * write() style API - do NOT use this if you have set an xmit_handler
  * if buffer is full, waits for more space UNLESS the file descriptor is
- * set to non-blocking, in which case xmit_write() will return -1 with errno = EAGAIN */
-int raw1394_iso_xmit_write(raw1394handle_t handle, unsigned char *data, unsigned int len,
-			   unsigned char tag, unsigned char sy);
-
-/* wait until all queued packets have been sent */
+ * set to non-blocking, in which case xmit_write() will return -1 with
+ * errno = EAGAIN
+ **/
+int raw1394_iso_xmit_write(raw1394handle_t handle, unsigned char *data, 
+                           unsigned int len, unsigned char tag, 
+                           unsigned char sy);
+
+/**
+ * raw1394_iso_xmit_sync - wait until all queued packets have been sent
+ * @handle: libraw1394 handle
+ **/
 int raw1394_iso_xmit_sync(raw1394handle_t handle);
 
-/* flush all already received iso packets from kernel into user space*/
+/**
+ * raw1394_iso_recv_flush - flush all already received iso packets from kernel into user space
+ * @handle: libraw1394 handle
+ *
+ * If you specified an irq_interval > 1 in
+ * iso_recv_init, you won't be notified for every single iso packet, but
+ * for groups of them. Now e.g. if irq_interval is 100, and you were just
+ * notified about iso packets and after them only 20 more packets arrived,
+ * no notification will be generated (20 < 100). In the case that you know
+ * that there should be more packets at this moment, you can call this
+ * function and all iso packets which are already received by the kernel
+ * will be flushed out to user space.
+ **/
 int raw1394_iso_recv_flush(raw1394handle_t handle);
 
+/**
+ * raw1394_iso_stop - halt isochronous transmission or reception
+ * @handle: libraw1394 handle
+ **/
 void raw1394_iso_stop(raw1394handle_t handle);
+
+/**
+ * raw1394_iso_shutdown - clean up and deallocate all resources for isochronous transmission or reception
+ * @handle: libraw1394 handle
+ **/
 void raw1394_iso_shutdown(raw1394handle_t handle);
 
 typedef int raw1394_errcode_t;
@@ -155,187 +282,354 @@ typedef int raw1394_errcode_t;
 #define raw1394_get_ack(errcode) ((errcode) >> 16)
 #define raw1394_get_rcode(errcode) ((errcode) & 0xf)
 #define raw1394_get_internal(errcode) (errcode)
-raw1394_errcode_t raw1394_get_errcode(raw1394handle_t);
-int raw1394_errcode_to_errno(raw1394_errcode_t);
 
-/*
- * Required as initialization.  One handle can control one port, it is possible
- * to use multiple handles.  raw1394_new_handle returns NULL for failure,
- * raw1394_destroy_handle accepts NULL.  If raw1394_new_handle returns NULL and
- * errno is 0, this version of libraw1394 is incompatible with the kernel.  
- */
+/**
+ * raw1394_get_errcode - return error code of async transaction
+ * @handle: libraw1394 handle
+ *
+ * Returns the error code of the last raw1394_read(), raw1394_write(),
+ * raw1394_lock() or raw1394_iso_write().  The error code is either an internal
+ * error (i.e. not a bus error) or a combination of acknowledge code and
+ * response code, as appropriate.
+ *
+ * Some macros are available to extract information from the error code,
+ * raw1394_errcode_to_errno() can be used to convert it to an errno number of
+ * roughly the same meaning.
+ **/
+raw1394_errcode_t raw1394_get_errcode(raw1394handle_t handle);
+
+/**
+ * raw1394_errcode_to_errno - convert libraw1394 errcode to errno
+ * @errcode: the error code to convert
+ *
+ * The error code as retrieved by raw1394_get_errcode() is converted into a
+ * roughly equivalent errno number and returned.  %0xdead is returned for an
+ * illegal errcode.
+ *
+ * It is intended to be used to decide what to do (retry, give up, report error)
+ * for those programs that aren't interested in details, since these get lost in
+ * the conversion.  However the returned errnos are equivalent in source code
+ * meaning only, the associated text of e.g. perror() is not necessarily
+ * meaningful.
+ *
+ * Returned values are %EAGAIN (retrying might succeed, also generation number
+ * mismatch), %EREMOTEIO (other node had internal problems), %EPERM (operation
+ * not allowed on this address, e.g. write on read-only location), %EINVAL
+ * (invalid argument) and %EFAULT (invalid pointer).
+ **/
+int raw1394_errcode_to_errno(raw1394_errcode_t errcode);
+
+/**
+ * raw1394_new_handle - create new handle
+ *
+ * Creates and returns a new handle which can (after being set up) control one
+ * port.  It is not allowed to use the same handle in multiple threads or forked
+ * processes.  It is allowed to create and use multiple handles, however.  Use
+ * one handle per thread which needs it in the multithreaded case.
+ *
+ * Returns the created handle or %NULL when initialization fails.  In the latter
+ * case errno either contains some OS specific error code or %0 if the error is
+ * that libraw1394 and raw1394 don't support each other's protocol versions.
+ **/
 raw1394handle_t raw1394_new_handle(void);
+
+/**
+ * raw1394_destroy_handle - deallocate handle
+ * @handle: handle to deallocate
+ *
+ * Closes connection with raw1394 on this handle and deallocates everything
+ * associated with it.  It is safe to pass %NULL as handle, nothing is done in
+ * this case.
+ **/
 void raw1394_destroy_handle(raw1394handle_t handle);
 
-/*
+/**
+ * raw1394_new_handle_on_port - create a new handle and bind it to a port
+ * @port: port to connect to (same as argument to raw1394_set_port())
+ *
  * Same as raw1394_new_handle(), but also binds the handle to the
  * specified 1394 port. Equivalent to raw1394_new_handle() followed by
  * raw1394_get_port_info() and raw1394_set_port(). Useful for
- * command-line programs that already know what port they want.
- */
+ * command-line programs that already know what port they want. If
+ * raw1394_set_port() returns ESTALE, retries automatically.
+ **/
 raw1394handle_t raw1394_new_handle_on_port(int port);
 
-/*
- * Switch off/on busreset-notification for handle
- * return-value:
+/**
+ * raw1394_busreset_notify - Switch off/on busreset-notification for handle
+ * @handle: libraw1394 handle
+ *
+ * returns:
  * ==0 success 
  * !=0 failure
  * off_on_switch .... RAW1394_NOTIFY_OFF or RAW1394_NOTIFY_ON
- */
+ **/
 int raw1394_busreset_notify (raw1394handle_t handle, int off_on_switch);
 
-/*
- * Get the fd of this handle to select()/poll() on it.  Don't try to mess around
- * with it any other way.  Valid only after the handle got attached to a port.
- */
+/**
+ * raw1394_get_fd - get the communication file descriptor
+ * @handle: libraw1394 handle
+ *
+ * Returns the fd used for communication with the raw1394 kernel module.  This
+ * can be used for select()/poll() calls if you wait on other fds or can be
+ * integrated into another event loop (e.g. from a GUI application framework).
+ * It can also be used to set/remove the O_NONBLOCK flag using fcntl() to modify
+ * the blocking behaviour in raw1394_loop_iterate().  It must not be used for
+ * anything else.
+ **/
 int raw1394_get_fd(raw1394handle_t handle);
 
-/*
- * Set and get user data.  This isn't used inside libraw1394, you can use it for
- * your own purposes.
- */
-void *raw1394_get_userdata(raw1394handle_t handle);
+/**
+ * raw1394_set_userdata - associate user data with a handle
+ * @handle: libraw1394 handle
+ * @data: user data (pointer)
+ *
+ * Allows to associate one void pointer with a handle.  libraw1394 does not care
+ * about the data, it just stores it in the handle allowing it to be retrieved
+ * at any time with raw1394_get_userdata().  This can be useful when multiple
+ * handles are used, so that callbacks can identify the handle.
+ **/
 void raw1394_set_userdata(raw1394handle_t handle, void *data);
 
+/**
+ * raw1394_get_userdata - retrieve user data from handle
+ * @handle: libraw1394 handle
+ *
+ * Returns the user data pointer associated with the handle using
+ * raw1394_set_userdata().
+ **/
+void *raw1394_get_userdata(raw1394handle_t handle);
+
+/**
+ * raw1394_get_local_id - get node ID of the current port
+ * @handle: libraw1394 handle
+ *
+ * Returns the node ID of the local node connected to which the handle is
+ * connected.  This value can change with every bus reset.
+ **/
 nodeid_t raw1394_get_local_id(raw1394handle_t handle);
+
+/**
+ * raw1394_get_irm_id - get node ID of isochronous resource manager
+ * @handle: libraw1394 handle
+ *
+ * Returns the node ID of the isochronous resource manager of the bus the handle
+ * is connected to.  This value may change with every bus reset.
+ **/
 nodeid_t raw1394_get_irm_id(raw1394handle_t handle);
 
-/* Get number of nodes on bus. */
+/**
+ * raw1394_get_nodecount - get number of nodes on the bus
+ * @handle: libraw1394 handle
+ *
+ * Returns the number of nodes on the bus to which the handle is connected.
+ * This value can change with every bus reset.  Since the root node always has
+ * the highest node ID, this number can be used to determine that ID (it's
+ * LOCAL_BUS|(count-1)).
+ **/
 int raw1394_get_nodecount(raw1394handle_t handle);
 
-/*
- * Returns number of available ports (port == one IEEE 1394 card or onboard
- * chip).  A maximum number of maxport raw1394_portinfos will be filled out at
- * *pinf, zero is valid if you're only interested in the number of ports (which
- * is returned).
- */
 struct raw1394_portinfo {
         int nodes;
         char name[32];
 };
 
+/**
+ * raw1394_get_port_info - get information about available ports
+ * @handle: libraw1394 handle
+ * @pinf: pointer to an array of struct raw1394_portinfo
+ * @maxports: number of elements in @pinf
+ *
+ * Before you can set which port to use, you have to use this function to find
+ * out which ports exist.
+ *
+ * If your program is interactive, you should present the user with this list to
+ * let them decide which port to use if there is more than one.  A
+ * non-interactive program (and probably interactive ones, too) should provide a
+ * command line option to choose the port.
+ *
+ * Returns the number of ports and writes information about them into @pinf, but
+ * not into more than @maxports elements.  If @maxports is %0, @pinf can be
+ * %NULL, too.
+ **/
 int raw1394_get_port_info(raw1394handle_t handle, struct raw1394_portinfo *pinf,
                           int maxports);
 
-/*
- * Attach handle to port (counted from zero).  Returns zero for success or -1
- * for failure.  If in the case of failure errno is set to ESTALE the generation
- * number has changed and you should reget the port info.
- */
+/**
+ * raw1394_set_port - choose port for handle
+ * @handle: libraw1394 handle
+ * @port: port to connect to (corresponds to index of struct raw1394_portinfo)
+ *
+ * This function connects the handle to the port given (as queried with
+ * raw1394_get_port_info()).  If successful, raw1394_get_port_info() and
+ * raw1394_set_port() are not allowed to be called afterwards on this handle.
+ * To make up for this, all the other functions (those handling asynchronous and
+ * isochronous transmissions) can now be called.
+ *
+ * Returns %0 for success and -1 for failure with errno set appropriately.  A
+ * possible failure mode is with errno = %ESTALE, in this case the configuration
+ * has changed since the call to raw1394_get_port_info() and it has to be called
+ * again to update your view of the available ports.
+ **/
 int raw1394_set_port(raw1394handle_t handle, int port);
 
-/*
- * Reset the connected bus.  Returns -1 for failure, 0 for success.
- */
+/**
+ * raw1394_reset_bus - initiate bus reset
+ * @handle: libraw1394 handle
+ *
+ * This function initiates a bus reset on the connected port.  Usually this is
+ * not necessary and should be avoided, this function is here for low level bus
+ * control and debugging.
+ *
+ * Returns: %0 for success and -1 for failure with errno set appropriately.
+ **/
 int raw1394_reset_bus(raw1394handle_t handle);
 
-/*
- * Reset the connected bus (with certain type). 
- * return-value:
+/**
+ * raw1394_reset_bus_new - Reset the connected bus (with certain type). 
+ * @handle: libraw1394 handle
+ *
+ * returns:
  * -1 failure 
  * 0  success
  * type .... RAW1394_SHORT_RESET or RAW1394_LONG_RESET
- */
+ **/
 int raw1394_reset_bus_new(raw1394handle_t handle, int type);
 
-/*
- * Get one new message through handle and process it.  See below for handler
- * registering functions.  This function will return -1 for an error or the
- * return value of the handler which got executed.  Default handlers always
- * return zero.
+/**
+ * raw1394_loop_iterate - get and process one event message
+ * @handle: libraw1394 handle
+ *
+ * Get one new message through handle and process it with the registered message
+ * handler.  This function will return %-1 for an error or the return value of
+ * the handler which got executed.  The default handlers always return zero.
  *
  * Note that some other library functions may call this function multiple times
  * to wait for their completion, some handler return values may get lost if you
  * use these.
- */
+ **/
 int raw1394_loop_iterate(raw1394handle_t handle);
 
-/*
- * Set the handler that will be called when a bus reset message is encountered.
- * The default action is to just call raw1394_update_generation().  Returns old
- * handler.
- */
 typedef int (*bus_reset_handler_t)(raw1394handle_t, unsigned int generation);
+
+/**
+ * raw1394_set_bus_reset_handler - set bus reset handler
+ * @handle: libraw1394 handle
+ * @new_h: pointer to new handler
+ *
+ * Sets the handler to be called on every bus reset to @new_h and returns the
+ * old handler. The default handler just calls raw1394_update_generation().
+ **/
 bus_reset_handler_t raw1394_set_bus_reset_handler(raw1394handle_t handle,
                                                   bus_reset_handler_t new_h);
 
-/*
- * Since node IDs may change during a bus reset, generation numbers incremented
- * every bus reset are used to verify if a transaction request is intended for
- * this configuration.  If numbers don't match, they will fail immediately.
+/**
+ * raw1394_get_generation - get generation number of handle
+ * @handle: libraw1394 handle
  *
- * raw1394_get_generation() returns the generation number in use by the handle,
- * not the current generation number.  The current generation number is passed
- * to the bus reset handler.
- */
+ * This function returns the generation number associated with the handle.  The
+ * generation number is incremented on every bus reset, and every transaction
+ * started by raw1394 is tagged with the stored generation number.  If these
+ * don't match, the transaction will abort with an error.
+ *
+ * The generation number of the handle is not automatically updated,
+ * raw1394_update_generation() has to be used for this.
+ **/
 unsigned int raw1394_get_generation(raw1394handle_t handle);
+
+/**
+ * raw1394_update_generation - set generation number of handle
+ * @generation: new generation number
+ * @handle: libraw1394 handle
+ *
+ * This function sets the generation number of the handle to @gen.  All requests
+ * that apply to a single node ID are tagged with this number and abort with an
+ * error if that is different from the generation number kept in the kernel.
+ * This avoids acting on the wrong node which may have changed its ID in a bus
+ * reset.
+ *
+ * You should call this within your bus reset handler with an incremented value.
+ **/
 void raw1394_update_generation(raw1394handle_t handle, unsigned int generation);
 
-/*
- * Set the handler that will be called when an async read/write/lock returns.
- * The default action is to call the callback in the raw1394_reqhandle pointed
- * to by tag.  Returns old handler.
- */
 typedef int (*tag_handler_t)(raw1394handle_t, unsigned long tag,
                              raw1394_errcode_t err);
+
+/**
+ * raw1394_set_tag_handler - set request completion handler
+ * @handle: libraw1394 handle
+ * @new_h: pointer to new handler
+ *
+ * Sets the handler to be called whenever a request completes to @new_h and
+ * returns the old handler.  The default handler interprets the tag as a pointer
+ * to a &struct raw1394_reqhandle and calls the callback in there.
+ *
+ * Care must be taken when replacing the tag handler and calling the synchronous
+ * versions of the transaction functions (i.e. raw1394_read(), raw1394_write(),
+ * raw1394_lock(), raw1394_iso_write()) since these do pass pointers to &struct
+ * raw1394_reqhandle as the tag and expect the callback to be invoked.
+ **/
 tag_handler_t raw1394_set_tag_handler(raw1394handle_t handle,
                                       tag_handler_t new_h);
 
-/*
- * Set the handler that will be called when an async read/write/lock arm_request
- * arrived. The default action is to call the arm_callback in the 
- * raw1394_arm_reqhandle pointed to by arm_tag.  Returns old handler.
- */
 typedef int (*arm_tag_handler_t)(raw1394handle_t handle, unsigned long arm_tag,
                              byte_t request_type, unsigned int requested_length,
                              void *data); 
+
+/**
+ * raw1394_set_arm_tag_handler - set the async request handler
+ * @handle: libraw1394 handle
+ * @new_h: pointer to new handler
+ *
+ * Set the handler that will be called when an async read/write/lock arm_request
+ * arrived. The default action is to call the arm_callback in the 
+ * raw1394_arm_reqhandle pointed to by arm_tag.  Returns old handler.
+ **/
 arm_tag_handler_t raw1394_set_arm_tag_handler(raw1394handle_t handle,
                                       arm_tag_handler_t new_h);
 
-/*
- * Set the handler that will be called when an iso packet arrives (data points
- * to the iso packet header).  The default action is to do nothing.
- *
- * Handlers have to be set separately for each channel, it is not possible to
- * set a handler when there is already one set for that channel.  Handlers can
- * be cleared by passing NULL for "new" parameter, in that case the old handler
- * will be returned.  Otherwise the return value is NULL for success and -1 for
- * failure.
- */
-typedef int (*iso_handler_t)(raw1394handle_t, int channel, size_t length,
-                             quadlet_t *data);
-iso_handler_t raw1394_set_iso_handler(raw1394handle_t handle,
-                                      unsigned int channel,
-                                      iso_handler_t new_h);
-
-/*
- * Set the handler that will be called when the local FCP_COMMAND or
- * FCP_RESPONSE register gets written to.  Returns old handler.
- *
- * The handler arg nodeid contains the node ID of the writer.  If response is 0
- * FCP_COMMAND was written, FCP_RESPONSE otherwise.
- */
 typedef int (*fcp_handler_t)(raw1394handle_t, nodeid_t nodeid, int response,
                              size_t length, unsigned char *data);
-fcp_handler_t raw1394_set_fcp_handler(raw1394handle_t, fcp_handler_t);
 
-/*
- * This is the general request handle.  It is used by the default tag handler
+/**
+ * raw1394_set_fcp_handler - set FCP handler
+ * @handle: libraw1394 handle
+ * @new_h: pointer to new handler
+ *
+ * Function Control Protocol is defined in IEC 61883-1.
+ *
+ * Sets the handler to be called when either FCP command or FCP response
+ * registers get written to @new_h and returns the old handler.  The default
+ * handler does nothing.
+ *
+ * In order to actually get FCP events, you have to enable it with
+ * raw1394_start_fcp_listen() and can stop it with raw1394_stop_fcp_listen().
+ **/
+fcp_handler_t raw1394_set_fcp_handler(raw1394handle_t handle, fcp_handler_t new_h);
+
+/**
+ * req_callback_t - This is the general request handler
+ *
+ * It is used by the default tag handler
  * when a request completes, it calls the callback and passes it the data
  * pointer and the error code of the request.
- */
+ **/
 typedef int (*req_callback_t)(raw1394handle_t, void *data,
                               raw1394_errcode_t err);
+
 struct raw1394_reqhandle {
         req_callback_t callback;
         void *data;
 };
 
-/*
- * This is the genereal arm-request handle. (arm...address range mapping)
+/**
+ * arm_req_callback_t - This is the general arm-request handle
+ * @handle: libraw1394 handle
+ *
+ * (arm = address range mapping)
  * It is used by the default arm-tag handler when a request has been 
  * received, it calls the arm_callback.
- */
+ **/
 typedef int (*arm_req_callback_t) (raw1394handle_t,
                                    struct raw1394_arm_request_response *arm_req_resp,
                                    unsigned int requested_length,
@@ -346,213 +640,463 @@ struct raw1394_arm_reqhandle {
         void *pcontext;
 };
 
-/*
- * AdressRangeMapping REGISTERING:
- * start, length .... identifies addressrange
- * *initial_value ... pointer to buffer containing (if necessary) initial value
+/**
+ * raw1394_arm_register - register an AddressRangeMapping
+ * @handle: libraw1394 handle
+ * @start:            identifies addressrange
+ * @length:           identifies addressrange
+ * @initial_value:    pointer to buffer containing (if necessary) initial value
  *                    NULL means undefined
- * arm_tag .......... identifier for arm_tag_handler 
+ * @arm_tag:          identifier for arm_tag_handler 
  *                    (usually pointer to raw1394_arm_reqhandle)
- * access_rights .... access-rights for registered addressrange handled 
+ * @access_rights:    access-rights for registered addressrange handled 
  *                    by kernel-part. Value is one or more binary or of the 
- *                    following flags: ARM_READ, ARM_WRITE, ARM_LOCK
- * notification_options ... identifies for which type of request you want
+ *                    following flags - ARM_READ, ARM_WRITE, ARM_LOCK
+ * @notification_options: identifies for which type of request you want
  *                    to be notified. Value is one or more binary or of the 
- *                    following flags: ARM_READ, ARM_WRITE, ARM_LOCK
- * client_transactions ... identifies for which type of request you want
+ *                    following flags - ARM_READ, ARM_WRITE, ARM_LOCK
+ * @client_transactions: identifies for which type of request you want
  *                    to handle the request by the client application.
  *                    for those requests no response will be generated, but
  *                    has to be generated by the application.
  *                    Value is one or more binary or of the 
- *                    following flags: ARM_READ, ARM_WRITE, ARM_LOCK
+ *                    following flags - ARM_READ, ARM_WRITE, ARM_LOCK
  *                    For each bit set here, notification_options and
  *                    access_rights will be ignored.
- * returnvalue:       0  ... success
+ *
+ * ARM = Adress Range Mapping
+ * returns:            0  ... success
  *                    <0 ... failure
- */
-int raw1394_arm_register(struct raw1394_handle *handle, nodeaddr_t start, 
+ **/
+int raw1394_arm_register(raw1394handle_t handle, nodeaddr_t start, 
                          size_t length, byte_t *initial_value,
                          octlet_t arm_tag, arm_options_t access_rights,
                          arm_options_t notification_options,
                          arm_options_t client_transactions);
-/*
- * AdressRangeMapping UNREGISTERING:
- * start ............ identifies addressrange for unregistering 
+/**
+ * raw1394_arm_unregister - unregister an AddressRangeMapping
+ * @handle: libraw1394 handle
+ * @start:            identifies addressrange for unregistering 
  *                    (value of start have to be the same value 
  *                    used for registering this adressrange)
- * returnvalue:       0  ... success
+ * 
+ * returns:           0  ... success
  *                    <0 ... failure
- */
+ **/
 int raw1394_arm_unregister(raw1394handle_t handle, nodeaddr_t start);
 
-/*
- * AdressRangeMapping SET BUFFER:
- * start, length .... identifies addressrange
- * buf .............. pointer to buffer
+/**
+ * raw1394_arm_set_buf - set the buffer of an AdressRangeMapping
+ * @start: identifies addressrange
+ * @length: identifies addressrange
+ * @buf: pointer to buffer
  *
- * This function copies 'length' bytes from user memory area 'buf'
+ * This function copies @length bytes from user memory area @buf
  * to one ARM block in kernel memory area
- * with start offset 'start'.
+ * with start offset @start.
  *
- * returnvalue:       0  ... success
- *                    <0 ... failure, and errno - error code
- */
-int raw1394_arm_set_buf (struct raw1394_handle *handle, nodeaddr_t start,
+ * returns:       0  ... success
+ *                <0 ... failure, and errno - error code
+ **/
+int raw1394_arm_set_buf (raw1394handle_t handle, nodeaddr_t start,
                          size_t length, void *buf);
 
-/*
- * AdressRangeMapping GET BUFFER:
- * start, length .... identifies addressrange
- * buf .............. pointer to buffer
+/**
+ * raw1394_arm_get_buf - get the buffer of an AdressRangeMapping
+ * @handle: libraw1394 handle
+ * @start: identifies addressrange
+ * @length: identifies addressrange
+ * @buf: pointer to buffer
  *
- * This function copies 'length' bytes from one
- * ARM block in kernel memory area with start offset `start`
- * to user memory area 'buf'
+ * This function copies @length bytes from one
+ * ARM block in kernel memory area with start offset @start
+ * to user memory area @buf
  *
- * returnvalue:       0  ... success
- *                    <0 ... failure, and errno - error code
- */
-int raw1394_arm_get_buf (struct raw1394_handle *handle, nodeaddr_t start,
+ * returns:       0  ... success
+ *                <0 ... failure, and errno - error code
+ **/
+int raw1394_arm_get_buf (raw1394handle_t handle, nodeaddr_t start,
                          size_t length, void *buf);
 
-/* 
- * send an echo request to the driver. the driver then send back the
+/**
+ * raw1394_echo_request - send an echo request to the driver
+ * @handle: libraw1394 handle
+ * @data:              arbitrary data; raw1394_loop_iterate will return it
+ *
+ * the driver then send back the
  * same request. raw1394_loop_iterate will return data as return value,
  * when it processes the echo. 
+ * returns:       0 .... success
+ *                <0 ... failure
+ **/
+int raw1394_echo_request(raw1394handle_t handle, quadlet_t data);
+
+/**
+ * raw1394_wake_up - wake up raw1394_loop_iterate
+ * @handle: libraw1394 handle
  *
- * data:              arbitrary data; raw1394_loop_iterate will return it
- * returnvalue:       0 .... success
- *                    <0 ... failure
- */
-int raw1394_echo_request(struct raw1394_handle *handle, quadlet_t data);
-
-/* 
- * wake up raw1394_loop_iterate (or a blocking read from the device
+ * (or a blocking read from the device
  * file). actually this calls raw1394_echo_request with 0 as data. 
  *
- * returnvalue:       0 .... success
- *                    <0 ... failure
- */
+ * returns:       0 .... success
+ *                <0 ... failure
+ **/
 int raw1394_wake_up(raw1394handle_t handle);
 
  
-/* 
- * send physical request such as linkon, physicalconfigurationpacket ... etc.
+/**
+ * raw1394_phy_packet_write - send physical request
+ * @handle: libraw1394 handle
  *
- * returnvalue:       0 .... success
- *                    <0 ... failure
- */
+ * examples of physical requests are linkon, physicalconfigurationpacket, etc.
+ * returns:       0 .... success
+ *                <0 ... failure
+ **/
 int raw1394_phy_packet_write (raw1394handle_t handle, quadlet_t data);
 int raw1394_start_phy_packet_write(raw1394handle_t handle, 
         quadlet_t data, unsigned long tag);
 
-/*
- * Passes custom tag.  Use pointer to raw1394_reqhandle if you use the standard
- * tag handler.
- */
+/**
+ * raw1394_start_read - initiate a read transaction
+ * @handle: libraw1394 handle
+ * @node: target node
+ * @addr: address to read from
+ * @length: amount of data to read
+ * @buffer: pointer to buffer where data will be saved
+ * @tag: data to identify the request to completion handler
+ *
+ * This function starts the specified read request and returns %0 for success
+ * and a negative number for an error, in which case errno will be set.  If
+ * @length is %4 a quadlet read is initiated and a block read otherwise.
+ *
+ * The transaction is only started, no success of the transaction is implied
+ * with a successful return of this function.  When the transaction completes, a
+ * raw1394_loop_iterate() will call the tag handler and pass it the tag and
+ * error code of the transaction.  @tag should therefore be set to something
+ * that uniquely identifies this transaction (e.g. a struct pointer casted to
+ * unsigned long).
+ **/
 int raw1394_start_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                        size_t length, quadlet_t *buffer, unsigned long tag);
+
+/**
+ * raw1394_start_write - initiate a write transaction
+ * @handle: libraw1394 handle
+ * @node: target node
+ * @addr: address to write to
+ * @length: amount of data to write
+ * @data: pointer to data to be sent
+ * @tag: data to identify the request to completion handler
+ *
+ * This function starts the specified write request and returns %0 for success
+ * and a negative number for an error, in which case errno will be set.  If
+ * @length is %4 a quadlet write is initiated and a block write otherwise.
+ *
+ * The transaction is only started, no success of the transaction is implied
+ * with a successful return of this function.  When the transaction completes, a
+ * raw1394_loop_iterate() will call the tag handler and pass it the tag and
+ * error code of the transaction.  @tag should therefore be set to something
+ * that uniquely identifies this transaction (e.g. a struct pointer casted to
+ * unsigned long).
+ **/
 int raw1394_start_write(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                         size_t length, quadlet_t *data, unsigned long tag);
+
+/**
+ * raw1394_start_lock - initiate a 32-bit compare-swap lock transaction
+ * @handle: libraw1394 handle
+ * @node: target node
+ * @addr: address to read from
+ * @extcode: extended transaction code determining the lock operation
+ * @data: data part of lock parameters
+ * @arg: arg part of lock parameters
+ * @result: address where return value will be written
+ * @tag: data to identify the request to completion handler
+ *
+ * This function starts the specified lock request and returns %0 for success
+ * and a negative number for an error, in which case errno will be set.
+ *
+ * The transaction is only started, no success of the transaction is implied
+ * with a successful return of this function.  When the transaction completes, a
+ * raw1394_loop_iterate() will call the tag handler and pass it the tag and
+ * error code of the transaction.  @tag should therefore be set to something
+ * that uniquely identifies this transaction (e.g. a struct pointer casted to
+ * unsigned long).
+ **/
 int raw1394_start_lock(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                        unsigned int extcode, quadlet_t data, quadlet_t arg,
                        quadlet_t *result, unsigned long tag);
+
+/**
+ * raw1394_start_lock64 - initiate a 64-bit compare-swap lock transaction
+ * @handle: libraw1394 handle
+ * @node: target node
+ * @addr: address to read from
+ * @extcode: extended transaction code determining the lock operation
+ * @data: data part of lock parameters
+ * @arg: arg part of lock parameters
+ * @result: address where return value will be written
+ * @tag: data to identify the request to completion handler
+ *
+ * This function starts the specified lock request and returns %0 for success
+ * and a negative number for an error, in which case errno will be set.
+ *
+ * The transaction is only started, no success of the transaction is implied
+ * with a successful return of this function.  When the transaction completes, a
+ * raw1394_loop_iterate() will call the tag handler and pass it the tag and
+ * error code of the transaction.  @tag should therefore be set to something
+ * that uniquely identifies this transaction (e.g. a struct pointer casted to
+ * unsigned long).
+ **/
 int raw1394_start_lock64(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                        unsigned int extcode, octlet_t data, octlet_t arg,
                        octlet_t *result, unsigned long tag);
-int raw1394_start_iso_write(raw1394handle_t handle, unsigned int channel,
-                            unsigned int tag, unsigned int sy,
-                            unsigned int speed, size_t length, quadlet_t *data,
-                            unsigned long rawtag);
+
+/**
+ * raw1394_start_read - initiate asynchronous stream
+ * @handle: libraw1394 handle
+ *
+ * Passes custom tag.  Use pointer to raw1394_reqhandle if you use the standard
+ * tag handler.
+ **/
 int raw1394_start_async_stream(raw1394handle_t handle, unsigned int channel,
                                unsigned int tag, unsigned int sy,
                                unsigned int speed, size_t length, quadlet_t *data,
                                unsigned long rawtag);
 
 
-/* This starts sending an arbitrary async packet. It gets an array of quadlets consisting of
-   header and data (without CRC in between). Header information is always in machine byte order,
-   data (data block as well as quadlet data in a read response for data quadlet) shall be in
-   big endian byte order. expect_response indicates, if we expect a response (i.e. if we will
-   get the tag back after the packet was sent or after a response arrived). length is the length
-   of the complete packet (header_length + length of the data block).
-   The main purpose of this function is to send responses for incoming transactions, that
-   are handled by the application.
-   Do not use that function, unless you really know, what you do! Sending corrupt packet may
-   lead to weird results.
-*/
+/**
+ * raw1394_start_async_send - send an asynchronous packet
+ * @handle: libraw1394 handle
+ *
+ * This starts sending an arbitrary async packet. It gets an array of quadlets 
+ * consisting of header and data (without CRC in between). Header information 
+ * is always in machine byte order, data (data block as well as quadlet data 
+ * in a read response for data quadlet) shall be in big endian byte order. 
+ * expect_response indicates, if we expect a response (i.e. if we will get the 
+ * tag back after the packet was sent or after a response arrived). length is 
+ * the length of the complete packet (header_length + length of the data block).
+ * The main purpose of this function is to send responses for incoming 
+ * transactions, that are handled by the application.
+ * Do not use that function, unless you really know, what you do! Sending 
+ * corrupt packet may lead to weird results.
+ **/
 int raw1394_start_async_send(raw1394handle_t handle,
-                             size_t length, size_t header_length, unsigned int expect_response,
+                             size_t length, size_t header_length, 
+                             unsigned int expect_response,
                              quadlet_t *data, unsigned long rawtag);
 
-/*
+/**
+ * raw1394_read - send async read request to a node and wait for response.
+ * @handle: libraw1394 handle
+ *
  * This does the complete transaction and will return when it's finished.  It
  * will call raw1394_loop_iterate() as often as necessary, return values of
  * handlers called will be therefore lost.
- */
+ **/
 int raw1394_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                  size_t length, quadlet_t *buffer);
+
+/**
+ * raw1394_write - send async write request to a node and wait for response.
+ * @handle: libraw1394 handle
+ *
+ * This does the complete transaction and will return when it's finished.  It
+ * will call raw1394_loop_iterate() as often as necessary, return values of
+ * handlers called will be therefore lost.
+ **/
 int raw1394_write(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                   size_t length, quadlet_t *data);
+
+/**
+ * raw1394_lock - send 32-bit compare-swap lock request and wait for response.
+ * @handle: libraw1394 handle
+ *
+ * This does the complete transaction and will return when it's finished.  It
+ * will call raw1394_loop_iterate() as often as necessary, return values of
+ * handlers called will be therefore lost.
+ **/
 int raw1394_lock(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                  unsigned int extcode, quadlet_t data, quadlet_t arg,
                  quadlet_t *result);
+
+/**
+ * raw1394_lock64 - send 64-bit compare-swap lock request and wait for response.
+ * @handle: libraw1394 handle
+ *
+ * This does the complete transaction and will return when it's finished.  It
+ * will call raw1394_loop_iterate() as often as necessary, return values of
+ * handlers called will be therefore lost.
+ **/
 int raw1394_lock64(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                  unsigned int extcode, octlet_t data, octlet_t arg,
                  octlet_t *result);
-int raw1394_iso_write(raw1394handle_t handle, unsigned int channel,
-                      unsigned int tag, unsigned int sy, unsigned int speed,
-                      size_t length, quadlet_t *data);
+
+/**
+ * raw1394_async_stream
+ * @handle: libraw1394 handle
+ **/
 int raw1394_async_stream(raw1394handle_t handle, unsigned int channel,
                          unsigned int tag, unsigned int sy, unsigned int speed,
                          size_t length, quadlet_t *data);
-int raw1394_async_send(raw1394handle_t handle,
-                             size_t length, size_t header_length, unsigned int expect_response,
-                             quadlet_t *data);
 
-/*
- * Start and stop receiving a certain isochronous channel.  You have to set an
- * iso handler (see above).  You can receive multiple channels simultaneously.
- */
-int raw1394_start_iso_rcv(raw1394handle_t handle, unsigned int channel);
-int raw1394_stop_iso_rcv(raw1394handle_t handle, unsigned int channel);
+/**
+ * raw1394_async_send
+ * @handle: libraw1394 handle
+ **/
+int raw1394_async_send(raw1394handle_t handle,
+                       size_t length, size_t header_length,
+                       unsigned int expect_response,
+                       quadlet_t *data);
 
-/*
- * Start and stop receiving requests sent to the local FCP_COMMAND and
- * FCP_RESPONSE registers.
- */
+/**
+ * raw1394_start_fcp_listen - enable reception of FCP events
+ * @handle: libraw1394 handle
+ *
+ * FCP = Function Control Protocol (see IEC 61883-1)
+ * Enables the reception of FCP events (writes to the FCP_COMMAND or
+ * FCP_RESPONSE address ranges) on @handle.  FCP requests are then passed to the
+ * callback specified with raw1394_set_fcp_handler().
+ **/
 int raw1394_start_fcp_listen(raw1394handle_t handle);
+
+/**
+ * raw1394_stop_fcp_listen - disable reception of FCP events
+ * @handle: libraw1394 handle
+ *
+ * Stops the reception of FCP events (writes to the FCP_COMMAND or
+ * FCP_RESPONSE address ranges) on @handle.
+ **/
 int raw1394_stop_fcp_listen(raw1394handle_t handle);
 
 
-/*
- * Returns the version string.  Designed to be used by the autoconf macro to
- * detect the libraw version, not really intended for general use.
+/**
+ * raw1394_get_libversion - Returns the version string
+ *
+ * Instead, typically, one uses 'pkg-config --mod-version libraw1394'
+ * Might be useful for an application.
  */
 const char *raw1394_get_libversion(void);
 
 
-/* updates the configuration rom of a host. rom_version must be the current
+/**
+ * raw1394_update_config_rom - updates the configuration rom of a host
+ * @handle: libraw1394 handle
+ *
+ * @rom_version must be the current
  * version, otherwise it will fail with return value -1. 
  * Return value -2 indicates that the new rom version is too big.
  * Return value 0 indicates success
-*/
+ **/
 
 int raw1394_update_config_rom(raw1394handle_t handle, const quadlet_t
         *new_rom, size_t size, unsigned char rom_version);
 
 
-/* reads the current version of the configuration rom of a host. 
- * buffersize is the size of the buffer, rom_size
- * returns the size of the current rom image.. rom_version is the
+/**
+ * raw1394_get_config_rom - reads the current version of the configuration rom of a host
+ * @handle: libraw1394 handle
+ * @buffersize: is the size of the buffer, @rom_size
+ *
+ * returns the size of the current rom image. @rom_version is the
  * version number of the fetched rom.
  * return value -1 indicates, that the buffer was too small, 
  * 0 indicates success.
- */
+ **/
 
 int raw1394_get_config_rom(raw1394handle_t handle, quadlet_t *buffer,
         size_t buffersize, size_t *rom_size, unsigned char *rom_version);
 
+
+/**
+ * iso_handler_t - DEPRECATED
+ * @handle: libraw1394 handle
+ *
+ * DEPRECATED
+ **/
+typedef int (*iso_handler_t)(raw1394handle_t, int channel, size_t length,
+                             quadlet_t *data);
+ 
+/**
+ * raw1394_set_iso_handler - set isochronous packet handler (DEPRECATED)
+ * @handle: libraw1394 handle
+ * @new_h: pointer to new handler
+ *
+ * DEPRECATED
+ *
+ * Sets the handler to be called when an isochronous packet is received to
+ * @new_h and returns the old handler.  The default handler does nothing.
+ *
+ * In order to actually get iso packet events, receiving on a specific channel
+ * first has to be enabled with raw1394_start_iso_rcv() and can be stopped again
+ * with raw1394_stop_iso_rcv().
+ **/
+iso_handler_t raw1394_set_iso_handler(raw1394handle_t handle,
+                                      unsigned int channel,
+                                      iso_handler_t new_h);
+/**
+ * raw1394_start_iso_rcv - enable isochronous receiving (DEPRECATED)
+ * @handle: libraw1394 handle
+ * @channel: channel number to start receiving on
+ *
+ * DEPRECATED
+ *
+ * Enables the reception of isochronous packets in @channel on @handle.
+ * Isochronous packets are then passed to the callback specified with
+ * raw1394_set_iso_handler().
+ **/
+int raw1394_start_iso_rcv(raw1394handle_t handle, unsigned int channel);
+
+/**
+ * raw1394_stop_iso_rcv - stop isochronous receiving (DEPRECATED)
+ * @handle: libraw1394 handle
+ * @channel: channel to stop receiving on
+ *
+ * DEPRECATED
+ *
+ * Stops the reception of isochronous packets in @channel on @handle.
+ **/
+int raw1394_stop_iso_rcv(raw1394handle_t handle, unsigned int channel);
+
+/**
+ * raw1394_start_iso_write - initiate an isochronous packet write (DEPRECATED)
+ * @handle: libraw1394 handle
+ * @channel: channel number on which to send on
+ * @tag: data to be put into packet's tag field
+ * @sy: data to be put into packet's sy field
+ * @speed: speed at which to send
+ * @length: amount of data to send
+ * @data: pointer to data to send
+ * @rawtag: data to identify the request to completion handler
+ *
+ * DEPRECATED
+ *
+ * This function starts the specified isochronous packet transmission and
+ * returns %0 for success and a negative number for an error, in which case
+ * errno will be set.
+ *
+ * When the send completes, a raw1394_loop_iterate() will call the tag handler
+ * and pass it the tag and error code of the transaction.  @tag should therefore
+ * be set to something that uniquely identifies this transaction (e.g. a struct
+ * pointer casted to unsigned long).
+ *
+ * Isochronous packets are automatically
+ **/
+int raw1394_start_iso_write(raw1394handle_t handle, unsigned int channel,
+                            unsigned int tag, unsigned int sy,
+                            unsigned int speed, size_t length, quadlet_t *data,
+                            unsigned long rawtag);
+
+/**
+ * raw1394_iso_write - DEPRECATED
+ * @handle: libraw1394 handle
+ *
+ * DEPRECATED
+ **/
+int raw1394_iso_write(raw1394handle_t handle, unsigned int channel,
+                      unsigned int tag, unsigned int sy, unsigned int speed,
+                      size_t length, quadlet_t *data);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/src/readwrite.c b/src/readwrite.c
index 4e2e6ea..8f5948d 100644
--- a/src/readwrite.c
+++ b/src/readwrite.c
@@ -31,25 +31,6 @@
 #include "raw1394_private.h"
 
 
-/**
- * raw1394_start_read - initiate a read transaction
- * @node: target node
- * @addr: address to read from
- * @length: amount of data to read
- * @buffer: pointer to buffer where data will be saved
- * @tag: data to identify the request to completion handler
- *
- * This function starts the specified read request and returns %0 for success
- * and a negative number for an error, in which case errno will be set.  If
- * @length is %4 a quadlet read is initiated and a block read otherwise.
- *
- * The transaction is only started, no success of the transaction is implied
- * with a successful return of this function.  When the transaction completes, a
- * raw1394_loop_iterate() will call the tag handler and pass it the tag and
- * error code of the transaction.  @tag should therefore be set to something
- * that uniquely identifies this transaction (e.g. a struct pointer casted to
- * unsigned long).
- **/
 int raw1394_start_read(struct raw1394_handle *handle, nodeid_t node,
                        nodeaddr_t addr, size_t length, quadlet_t *buffer,
                        unsigned long tag)
@@ -70,25 +51,6 @@ int raw1394_start_read(struct raw1394_handle *handle, nodeid_t node,
 }
 
 
-/**
- * raw1394_start_write - initiate a write transaction
- * @node: target node
- * @addr: address to write to
- * @length: amount of data to write
- * @data: pointer to data to be sent
- * @tag: data to identify the request to completion handler
- *
- * This function starts the specified write request and returns %0 for success
- * and a negative number for an error, in which case errno will be set.  If
- * @length is %4 a quadlet write is initiated and a block write otherwise.
- *
- * The transaction is only started, no success of the transaction is implied
- * with a successful return of this function.  When the transaction completes, a
- * raw1394_loop_iterate() will call the tag handler and pass it the tag and
- * error code of the transaction.  @tag should therefore be set to something
- * that uniquely identifies this transaction (e.g. a struct pointer casted to
- * unsigned long).
- **/
 int raw1394_start_write(struct raw1394_handle *handle, nodeid_t node,
                         nodeaddr_t addr, size_t length, quadlet_t *data,
                         unsigned long tag)
@@ -109,26 +71,6 @@ int raw1394_start_write(struct raw1394_handle *handle, nodeid_t node,
 }
 
 
-/**
- * raw1394_start_lock - initiate a lock transaction
- * @node: target node
- * @addr: address to read from
- * @extcode: extended transaction code determining the lock operation
- * @data: data part of lock parameters
- * @arg: arg part of lock parameters
- * @result: address where return value will be written
- * @tag: data to identify the request to completion handler
- *
- * This function starts the specified lock request and returns %0 for success
- * and a negative number for an error, in which case errno will be set.
- *
- * The transaction is only started, no success of the transaction is implied
- * with a successful return of this function.  When the transaction completes, a
- * raw1394_loop_iterate() will call the tag handler and pass it the tag and
- * error code of the transaction.  @tag should therefore be set to something
- * that uniquely identifies this transaction (e.g. a struct pointer casted to
- * unsigned long).
- **/
 int raw1394_start_lock(struct raw1394_handle *handle, nodeid_t node,
                        nodeaddr_t addr, unsigned int extcode, quadlet_t data,
                        quadlet_t arg, quadlet_t *result, unsigned long tag)
@@ -207,27 +149,6 @@ int raw1394_start_lock64(struct raw1394_handle *handle, nodeid_t node,
 }
 
 
-/**
- * raw1394_start_iso_write - initiate an isochronous packet write
- * @channel: channel number on which to send on
- * @tag: data to be put into packet's tag field
- * @sy: data to be put into packet's sy field
- * @speed: speed at which to send
- * @length: amount of data to send
- * @data: pointer to data to send
- * @rawtag: data to identify the request to completion handler
- *
- * This function starts the specified isochronous packet transmission and
- * returns %0 for success and a negative number for an error, in which case
- * errno will be set.
- *
- * When the send completes, a raw1394_loop_iterate() will call the tag handler
- * and pass it the tag and error code of the transaction.  @tag should therefore
- * be set to something that uniquely identifies this transaction (e.g. a struct
- * pointer casted to unsigned long).
- *
- * Isochronous packets are automatically
- **/
 int raw1394_start_iso_write(struct raw1394_handle *handle, unsigned int channel,
                             unsigned int tag, unsigned int sy,
                             unsigned int speed, size_t length, quadlet_t *data,
diff --git a/src/version.c b/src/version.c
index 2ca5b1e..1a00510 100644
--- a/src/version.c
+++ b/src/version.c
@@ -10,7 +10,6 @@
 
 #include <config.h>
 
-/* This function is to be used by the autoconf macro to find the lib version */
 const char *raw1394_get_libversion()
 {
         return VERSION;