From b0332cb93ee9079951ddc8b6a2c77904e0ee051c Mon Sep 17 00:00:00 2001 From: aeb Date: Sun, 13 Oct 2002 22:54:49 +0000 Subject: [PATCH] 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 --- src/errors.c | 34 ++++++++++- src/eventloop.c | 55 +++++++++++++++++- src/fcp.c | 16 +++++- src/iso.c | 16 +++++- src/main.c | 149 ++++++++++++++++++++++++++++++++++++++++++++++-- src/raw1394.h | 1 - src/readwrite.c | 84 ++++++++++++++++++++++++++- src/version.c | 2 +- 8 files changed, 344 insertions(+), 13 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) -{ - return handle->userdata; -} - +/** + * 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) { @@ -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