documentation and header comment corrections from Stefan Richter

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

2 files changed, 57 insertions, 43 deletions

diff --git a/doc/libraw1394.sgml b/doc/libraw1394.sgml
index f61b669..9987865 100644
--- a/doc/libraw1394.sgml
+++ b/doc/libraw1394.sgml
@@ -73,9 +73,9 @@
     </para>
 
     <para>
-      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.
+      If you are familiar with CSR architectures (as defined in ISO/IEC 13213
+      (ANSI/IEEE 1212)), then you already know quite a bit of 1394, which is a
+      CSR implementation.
     </para>
 
     <sect1>
@@ -94,20 +94,30 @@
       <para>
 	A 1394 bus consists of up to 64 nodes (with multiple buses possibly
 	being connected, but that is outside of the scope of this document and
-	not completely standardized yet), each having a local address space with
-	48 bit wide addressing.  Each node is addressed with a 16 bit address,
-	which is further divided into a 10 bit bus ID and a 6 bit local node ID.
-	The highest value for both is a special value.  Bus ID equal to 1023
-	means "local bus" (the bus the node is connected to), node ID equal to
-	63 means "all nodes" (broadcast).
+	not completely standardized yet).  Each node is addressed with a 16 bit
+	address, which is further divided into a 10 bit bus ID and a 6 bit local
+	node number, the so-called physical ID.  The physical IDs are completely
+	dynamic and determined during the bus reset.  The highest values for
+	both are special values.  Bus ID equal to 1023 means "local bus" (the
+	bus the node is connected to), physical ID equal to 63 means "all nodes"
+	(broadcast).
       </para>
 
       <para>
+	The local bus ID 1023 is the only one that can be used unless IEEE
+	1394.1 bridge portals to more buses were available. Therefore the node
+	IDs have to be given as (1023&lt;&lt;6) | phy_ID.  (This is also true
+	if libraw1394 runs at a host which contains multiple 1394 bus adapters.
+	The local ID 1023 is valid on each of these buses. The Linux host
+	itself is no IEEE 1394.1 bridge.)
+      </para>
+
+      <para>
+	Each node has a local address space with 48 bit wide addressing.
 	The whole bus can thus be seen as a linear 64 bit address space by
-	concatenating the node address (most significant bits) and and node
+	concatenating the node ID (most significant bits) and local
 	address (least significant bits).  libraw1394 treats them separately in
 	function arguments to save the application some fiddling with the bits.
-	The node IDs are completely dynamic and determined during the bus reset.
       </para>
 
       <para>
@@ -156,23 +166,23 @@
 	The root node sends a SelfID grant on its first port connected to a
 	child.  If that is not a leaf node, it will itself forward the grant to
 	its first child.  When a leaf node gets a grant, it will pick the lowest
-	node ID not yet in use (starting with 0) and send out a SelfID packet
-	with its node ID and more information, then acknowledge the SelfID grant
-	to its parent, which will send a grant to its next child until it
-	configured all its children, then pick a node ID itself, send SelfID
+	physical ID not yet in use (starting with 0) and send out a SelfID packet
+	with its physical ID and more information, then acknowledge the SelfID
+	grant to its parent, which will send a grant to its next child until it
+	configured all its children, then pick a physical ID itself, send SelfID
 	packet and ack to parent.
       </para>
 
       <para>
-	After bus reset the used node IDs are in a sequential range with no
-	holes starting from 0 with the root node having the highest ID.  This
-	also means that node IDs can change for many or all nodes with the
+	After bus reset the used physical IDs are in a sequential range with no
+	holes starting from 0 up to the root node having the highest ID.  This
+	also means that physical IDs can change for many or all nodes with the
 	insertion of a new node or moving the role of root to another node.  In
 	libraw1394 all transactions are tagged automatically with a generation
 	number which is increased in every bus reset and transactions with an
 	obsolete generation will fail in order to avoid targetting the wrong
 	node.  Nodes have to be identified in a different way than their
-	volatile node IDs, namely by reading their globally unique ID (GUID)
+	volatile physical IDs, namely by reading their globally unique ID (GUID)
 	contained in the configuration ROM.
       </para>
     </sect1>
@@ -304,11 +314,11 @@
 	values (all channels free, all bandwidth minus some amount set aside for
 	asynchronous communication available), this has to happen since the
 	isochronous manager may have moved to another node.  Isochronous
-	transmissions may continue with the old allocations for a certain
-	(FIXME) amount of time.  During that time, the nodes have to reallocate
-	their resources and no new allocations are allowed to occur.  Only after
-	this period new allocations may be done, this avoids nodes losing their
-	allocations over a bus reset.
+	transmissions may continue with the old allocations for 1000ms. During
+	that time, the nodes have to reallocate	their resources and no new
+	allocations are allowed to occur.  Only after this period new
+	allocations may be done, this avoids nodes losing their	allocations over
+	a bus reset.
       </para>
 
       <para>
diff --git a/src/raw1394.h b/src/raw1394.h
index 5f19e20..1d52bbe 100644
--- a/src/raw1394.h
+++ b/src/raw1394.h
@@ -824,9 +824,9 @@ int raw1394_start_phy_packet_write(raw1394handle_t handle,
 /**
  * raw1394_start_read - initiate a read transaction
  * @handle: libraw1394 handle
- * @node: target node
+ * @node: target node ID
  * @addr: address to read from
- * @length: amount of data to read
+ * @length: amount of bytes of data to read
  * @buffer: pointer to buffer where data will be saved
  * @tag: data to identify the request to completion handler
  *
@@ -848,9 +848,9 @@ int raw1394_start_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_start_write - initiate a write transaction
  * @handle: libraw1394 handle
- * @node: target node
+ * @node: target node ID
  * @addr: address to write to
- * @length: amount of data to write
+ * @length: amount of bytes of data to write
  * @data: pointer to data to be sent
  * @tag: data to identify the request to completion handler
  *
@@ -872,7 +872,7 @@ int raw1394_start_write(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_start_lock - initiate a 32-bit compare-swap lock transaction
  * @handle: libraw1394 handle
- * @node: target node
+ * @node: target node ID
  * @addr: address to read from
  * @extcode: extended transaction code determining the lock operation
  * @data: data part of lock parameters
@@ -897,7 +897,7 @@ int raw1394_start_lock(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_start_lock64 - initiate a 64-bit compare-swap lock transaction
  * @handle: libraw1394 handle
- * @node: target node
+ * @node: target node ID
  * @addr: address to read from
  * @extcode: extended transaction code determining the lock operation
  * @data: data part of lock parameters
@@ -920,13 +920,13 @@ int raw1394_start_lock64(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                        octlet_t *result, unsigned long tag);
 
 /**
- * raw1394_start_read - initiate asynchronous stream
+ * raw1394_start_async_stream - initiate asynchronous stream
  * @handle: libraw1394 handle
  * @channel: the isochronous channel number 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
+ * @length: amount of data to send, in bytes
  * @data: pointer to data to send
  * @rawtag: data to identify the request to completion handler
  *
@@ -944,8 +944,8 @@ int raw1394_start_async_stream(raw1394handle_t handle, unsigned int channel,
 /**
  * raw1394_start_async_send - send an asynchronous packet
  * @handle: libraw1394 handle
- * @length: the amount of quadlets of data to send
- * @header_length: the number of quadlets in the header
+ * @length: the amount of bytes of data to send
+ * @header_length: the number of bytes in the header
  * @expect_response: indicate with a 0 or 1 whether to receive a completion event
  * @data: pointer to data to send
  * @rawtag: data to identify the request to completion handler
@@ -972,11 +972,13 @@ int raw1394_start_async_send(raw1394handle_t handle,
 /**
  * raw1394_read - send async read request to a node and wait for response.
  * @handle: libraw1394 handle
- * @node: target node
+ * @node: target node ID
  * @addr: address to read from
- * @length: amount of data to read in quadlets
+ * @length: amount of bytes of data to read
  * @buffer: pointer to buffer where data will be saved
  *
+ * If @length is %4, a quadlet read request is used.
+ *
  * This does the complete transaction and will return when it's finished.  It
  * will call raw1394_loop_iterate() as often as necessary, return values of
  * handlers called will be therefore lost.
@@ -989,11 +991,13 @@ int raw1394_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_write - send async write request to a node and wait for response.
  * @handle: libraw1394 handle
- * @node: target node
+ * @node: target node ID
  * @addr: address to write to
- * @length: amount of data to write in quadlets
+ * @length: amount of bytes of data to write
  * @data: pointer to data to be sent
  *
+ * If @length is %4, a quadlet write request is used.
+ *
  * This does the complete transaction and will return when it's finished.  It
  * will call raw1394_loop_iterate() as often as necessary, return values of
  * handlers called will be therefore lost.
@@ -1006,7 +1010,7 @@ int raw1394_write(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_lock - send 32-bit compare-swap lock request and wait for response.
  * @handle: libraw1394 handle
- * @node: target node
+ * @node: target node ID
  * @addr: address to read from
  * @extcode: extended transaction code determining the lock operation
  * @data: data part of lock parameters
@@ -1026,7 +1030,7 @@ int raw1394_lock(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_lock64 - send 64-bit compare-swap lock request and wait for response.
  * @handle: libraw1394 handle
- * @node: target node
+ * @node: target node ID
  * @addr: address to read from
  * @extcode: extended transaction code determining the lock operation
  * @data: data part of lock parameters
@@ -1050,7 +1054,7 @@ int raw1394_lock64(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
  * @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
+ * @length: amount of bytes of data to send
  * @data: pointer to data to send
  *
  * Returns: 0 on success or -1 on failure (sets errno)
@@ -1062,8 +1066,8 @@ int raw1394_async_stream(raw1394handle_t handle, unsigned int channel,
 /**
  * raw1394_async_send
  * @handle: libraw1394 handle
- * @length: the amount of quadlets of data to send
- * @header_length: the number of quadlets in the header
+ * @length: the amount of bytes of data to send
+ * @header_length: the number of bytes in the header
  * @expect_response: indicate with a 0 or 1 whether to receive a completion event
  * @data: pointer to data to send
  *