libraw1394
				   ==========

1. About libraw1394

	libraw1394 is the only supported interface to the kernel side raw1394 of
the Linux IEEE-1394 subsystem, which provides direct access to the connected
1394 buses to user space.  Through libraw1394/raw1394, applications can directly
send to and receive from other nodes without requiring a kernel driver for the
protocol in question.

	The reason for making a library the interface to the kernel is to avoid
a program dependancy on the kernel version, which would hinder development and
optimization of raw1394.  If development changed the protocol and made it
incompatible with previous versions only the libraw1394 has to be upgraded to
match the kernel version (instead of all applications).


2. Copyleft

	libraw1394 itself is licensed under the Lesser General Public License
(short LGPL, see file COPYING.LIB in the source distribution).  Other files in
the source archives not belonging to but being part of the build procedure of
libraw1394 are under their own licenses, as stated at the top of the individual
files.


3. API documentation

	There is currently no external document describing the library
functions, but you can find documentation for all functions in the header file
raw1394.h.  Some real documentation will come Real Soon Now.

	To clear up some confusion (it wasn't documented before, what was I
thinking), here is a description of the return values of the
raw1394_(read|write|lock) functions and also the errcode parameter of
tag_handler_t or reeqhandler_t:

	If it is negative it signals an error in handling the request locally
(1394 target node not reached) and errno contains a Unix error code just like
with other library functions.  If it is positive it still does not signal
success of the request itself, just that it was properly communicated to the
1394 target node.  To know whether it succeeded the lower 32 bits have to be
further decoded.

	The upper 16 bits contain the acknowledge code from the other node, the
lower 16 bits the response code.  Both of these codes are the standard codes
from the 1394 standard with the exception of 0x10 for the ack which is set on an
access to the local node (there is no 1394 bus involved and therefore no ack
exists).  Most of the acks completely determine the success of the request
(ack_complete or one of the error codes).  The response code has to be
interpreted if the ack is ack_pending or the dummy ack 0x10.  Only in this case
is the response code valid.

	This way of reporting errors will be replaced by a more sensible
approach with (one of the, but hopefully) the next version of libraw.
Documented here only for those who can't wait.


4. Multithreading

	This library should be multithreadable with the restriction that one
raw1394handle_t may be used only within a single thread.  Multiple threads
operating on the same handle would royally mess up the kernel-user protocol.
Simply use separate handles for each thread in which you need to use libraw1394.


5. Maintainer

	Maintainer of libraw1394 is currently Andreas Bombe.  Send suggestions,
bug reports and fixes to andreas.bombe@munich.netsurf.de.  See the file AUTHORS
for a complete list of contributors to libraw1394.

	You can get updates through this project's homepage on SourceForge, see
http://sourceforge.net/project/?group_id=2514 for more information.  You can
also submit bugs through this page.


2000-11-25  Andreas Bombe