Add kernel-doc style documentation headers for most exported functions.

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

8 files changed, 343 insertions, 12 deletions

diff --git a/src/errors.c b/src/errors.c
index 08ce425..e5f1af4 100644
--- a/src/errors.c
+++ b/src/errors.c
@@ -1,7 +1,7 @@
 /*
  * libraw1394 - library for raw access to the 1394 bus with the Linux subsystem.
  *
- * Copyright (C) 1999,2000 Andreas Bombe
+ * Copyright (C) 1999,2000,2001,2002 Andreas Bombe
  *
  * 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
@@ -16,11 +16,43 @@
 #include "raw1394_private.h"
 #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 f3a8f7c..1f19613 100644
--- a/src/eventloop.c
+++ b/src/eventloop.c
@@ -1,7 +1,7 @@
 /*
  * libraw1394 - library for raw access to the 1394 bus with the Linux subsystem.
  *
- * Copyright (C) 1999,2000 Andreas Bombe
+ * Copyright (C) 1999,2000,2001,2002 Andreas Bombe
  *
  * 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
@@ -17,6 +17,17 @@
 #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 = &handle->req;
@@ -77,6 +88,13 @@ 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)
 {
@@ -88,6 +106,19 @@ 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)
 {
@@ -99,6 +130,17 @@ tag_handler_t raw1394_set_tag_handler(struct raw1394_handle *handle,
         return old;
 }
 
+/**
+ * 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)
 {
@@ -120,6 +162,17 @@ 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 5c29a6e..06fbab8 100644
--- a/src/fcp.c
+++ b/src/fcp.c
@@ -1,7 +1,7 @@
 /*
  * libraw1394 - library for raw access to the 1394 bus with the Linux subsystem.
  *
- * Copyright (C) 1999,2000 Andreas Bombe
+ * Copyright (C) 1999,2000,2001,2002 Andreas Bombe
  *
  * 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
@@ -52,11 +52,25 @@ 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 8d69b57..3d7131e 100644
--- a/src/iso.c
+++ b/src/iso.c
@@ -1,7 +1,7 @@
 /*
  * libraw1394 - library for raw access to the 1394 bus with the Linux subsystem.
  *
- * Copyright (C) 1999,2000 Andreas Bombe
+ * Copyright (C) 1999,2000,2001,2002 Andreas Bombe
  *
  * 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
@@ -53,6 +53,14 @@ 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) {
@@ -63,6 +71,12 @@ 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) {
diff --git a/src/main.c b/src/main.c
index d858c34..e8864de 100644
--- a/src/main.c
+++ b/src/main.c
@@ -1,7 +1,7 @@
 /*
  * libraw1394 - library for raw access to the 1394 bus with the Linux subsystem.
  *
- * Copyright (C) 1999,2000 Andreas Bombe
+ * Copyright (C) 1999,2000,2001,2002 Andreas Bombe
  *
  * 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
@@ -77,6 +77,18 @@ 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;
@@ -107,6 +119,14 @@ 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) {
@@ -115,46 +135,137 @@ 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;
 }
 
-void *raw1394_get_userdata(struct raw1394_handle *handle)
+/**
+ * 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)
 {
-        return handle->userdata;
+        handle->userdata = data;
 }
 
-void raw1394_set_userdata(struct raw1394_handle *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(struct raw1394_handle *handle)
 {
-        handle->userdata = data;
+        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)
 {
@@ -191,6 +302,22 @@ int raw1394_get_port_info(struct raw1394_handle *handle,
         return req->misc;
 }
 
+
+/**
+ * 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 = &handle->req;
@@ -229,6 +356,16 @@ int raw1394_set_port(struct raw1394_handle *handle, int port)
         }
 }
 
+
+/**
+ * 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)
 {
         struct raw1394_request *req = &handle->req;
diff --git a/src/raw1394.h b/src/raw1394.h
index 5314409..8d14264 100644
--- a/src/raw1394.h
+++ b/src/raw1394.h
@@ -1,4 +1,3 @@
-
 #ifndef _LIBRAW1394_RAW1394_H
 #define _LIBRAW1394_RAW1394_H
 
diff --git a/src/readwrite.c b/src/readwrite.c
index c4a571b..bb918d4 100644
--- a/src/readwrite.c
+++ b/src/readwrite.c
@@ -1,7 +1,7 @@
 /*
  * libraw1394 - library for raw access to the 1394 bus with the Linux subsystem.
  *
- * Copyright (C) 1999,2000 Andreas Bombe
+ * Copyright (C) 1999,2000,2001,2002 Andreas Bombe
  *
  * 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
@@ -17,6 +17,25 @@
 #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)
@@ -36,6 +55,26 @@ int raw1394_start_read(struct raw1394_handle *handle, nodeid_t node,
         return (int)write(handle->fd, req, sizeof(*req));
 }
 
+
+/**
+ * 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)
@@ -55,6 +94,27 @@ int raw1394_start_write(struct raw1394_handle *handle, nodeid_t node,
         return (int)write(handle->fd, req, sizeof(*req));
 }
 
+
+/**
+ * raw1394_start_read - 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)
@@ -94,6 +154,28 @@ int raw1394_start_lock(struct raw1394_handle *handle, nodeid_t node,
         return (int)write(handle->fd, req, sizeof(*req));
 }
 
+
+/**
+ * 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 3cedd13..0ff0b60 100644
--- a/src/version.c
+++ b/src/version.c
@@ -1,7 +1,7 @@
 /*
  * libraw1394 - library for raw access to the 1394 bus with the Linux subsystem.
  *
- * Copyright (C) 1999,2000,2001 Andreas Bombe
+ * Copyright (C) 1999,2000,2001,2002 Andreas Bombe
  *
  * 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