diff --git a/doc/libraw1394.sgml b/doc/libraw1394.sgml
index e9f864f..7c7033f 100644
--- a/doc/libraw1394.sgml
+++ b/doc/libraw1394.sgml
@@ -73,8 +73,9 @@
- If you are familiar with CSR architectures (as defined in --FIXME--), then
- you already know most of 1394, which is a CSR implementation.
+ If you are familiar with CSR architectures (as defined in IEEE 1212
+ (FIXME?)), then you already know most of 1394, which is a CSR
+ implementation.
@@ -85,9 +86,9 @@
document are the quadlet (32 bit quantity) and the octlet (64 bit
quantity) and blocks (any quantity of bytes). The bus byte ordering is
big endian. A transmission can be sent at one of multiple possible
- speeds, from the slowest 100 Mbit/s over 200 and 400 Mbit/s up to 3.2
- Gbit/s in the future (these speeds are also referred to as S100, S200,
- ...).
+ speeds, which are 100, 200 and 400 Mbit/s for the currently mostly used
+ IEEE 1394a spec and up to 3.2 Gbit/s in the recently finalized 1394.b
+ standard (these speeds are also referred to as S100, S200, ...).
@@ -188,16 +189,8 @@
later time from the targetted node to the source node (this is called a
split transaction). Only writes can succeed and complete in the ack
code, reads and locks require a response. Error and packet pending can
- happen for every transaction.
-
-
-
- The response packets contain a response code (rcode) which signifies
- success or type of error. libraw1394 contains a function to convert
- ack/rcode pairs into errno codes which convey roughly the same meaning.
- This is done automatically for the synchronous read/write/lock wrapper
- functions, i.e. they return a negative value for failure and a standard
- error code can be found in the global variable errno.
+ happen for every transaction. The response packets contain a response
+ code (rcode) which signifies success or type of error.
@@ -411,15 +404,15 @@
- A list of available ports together with some information about it
- (name of the hardware, number of connected nodes) is available via
+ A list of available ports together with some information about it (name
+ of the hardware, number of connected nodes) is available via
raw1394_get_port_info(), which is to be called
- right getting a fresh handle. The user should be presented with a
+ right after getting a fresh handle. The user should be presented with a
choice of available ports if there is more than one. It may be good
practice to do that even if there is only one port, since that may
- result from a normally configured port just not being available,
- making it confusing to be dropped right into the application attached
- to a port without a choice and notion of anything going wrong.
+ result from a normally configured port just not being available, making
+ it confusing to be dropped right into the application attached to a port
+ without a choice and notion of anything going wrong.
@@ -551,6 +544,64 @@
+
+ Generation Numbers
+
+
+ libraw1394 and the kernel code use generation numbers to identify the
+ current bus configuration and increment those on every configuration
+ change. The most important generation number is stored per connected
+ 1394 bus and incremented on every bus reset. There is another number
+ managed by raw1394 which identifies global changes (like a complete port
+ being added or removed), which is used for the
+ raw1394_set_port() function to make sure you don't
+ use stale port numbers. This is done transparently to you.
+
+
+
+ The bus generation number is more relevant for your work. Since nodes
+ can change IDs with every bus reset, it is very likely that you don't
+ want to send a packet you constructed with the old ID before you noticed
+ the bus reset. This does not apply to isochronous transmissions, since
+ they are broadcast and do not depend on bus configuration. Therefore
+ every packet is automatically tagged with the expected generation
+ number, and it will fail to send if that does not match the number
+ managed in the kernel for the port in question.
+
+
+
+ You get the current generation number through the bus reset handler. If
+ you don't set a custom bus reset handler, the default handler will
+ update the generation number automatically. If you set your own
+ handler, you can update the generation number to be used through
+ raw1394_update_generation() directly in the handler
+ or later.
+
+
+
+
+ Error and Success Codes
+
+
+ libraw1394 returns the ack/rcode pair in most transaction cases. The
+ rcode is undefined in cases where the ack code is not equal to
+ ack_pending. This is stored in a type
+ raw1394_errcode_t, from which the ack and rcode parts can
+ be extracted using two macros.
+
+
+
+ With the function raw1394_errcode_to_errno() it is
+ possible to convert this to an errno number that conveys roughly the
+ same meaning. Many developers will find that easier to handle. This is
+ done automatically for the synchronous read/write/lock wrapper
+ functions, i.e. they return 0 for success and a negative value for
+ failure, in which case they also set the errno variable
+ to the appropriate code. The raw ack/rcode pair can then still be
+ retrieved using raw1394_get_errcode().
+
+
+
@@ -563,7 +614,7 @@
- raw1394_net_handle
+ raw1394_new_handle
create new handle
@@ -644,6 +695,87 @@
+
+
+ raw1394_get_port_info
+ 3
+
+
+
+ raw1394_get_port_info
+ get information about connected ports
+
+
+
+
+
+ int raw1394_get_port_info
+ raw1394handle_t handle
+ struct raw1394_port_info *pinf
+ int maxports
+
+
+
+
+
+ Arguments
+
+
+
+ pinf
+
+ Pointer to an array of structure of type
+ raw1394_port_info which will be filled in
+ by the function.
+
+
+
+ maxports
+
+ Maximum number of pinf structures to
+ fill in. Zero is valid.
+
+
+
+
+
+
+ Return Value
+
+
+ The number of ports currently existing.
+
+
+
+
+ Description
+
+
+ Before you can set which port to use, you use this function to find
+ out which ports exist. The raw1394_port_info
+ structure looks like this:
+
+
+struct raw1394_portinfo {
+ int nodes;
+ char name[32];
+};
+
+
+
+
+ The field nodes contains the number of
+ nodes that are currently connected to that port, the field
+ name 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.
+
+
+
+
+
raw1394_get_fd