81 lines
3.4 KiB
Plaintext
81 lines
3.4 KiB
Plaintext
|
|
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
|