peter
/
libraw1394
Archived
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

documentation and header comment corrections from Stefan Richter 

git-svn-id: svn://svn.linux1394.org/libraw1394/trunk@155 53a565d1-3bb7-0310-b661-cf11e63c67ab
This commit is contained in:
ddennedy 2005-06-02 18:30:57 +00:00
parent 246f623e35
commit 1c06177cd7
2 changed files with 57 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
doc/libraw1394.sgml
View File

@ -73,9 +73,9 @@
</para> </para>
<para> <para>
If you are familiar with CSR architectures (as defined in IEEE 1212 If you are familiar with CSR architectures (as defined in ISO/IEC 13213
(FIXME?)), then you already know most of 1394, which is a CSR (ANSI/IEEE 1212)), then you already know quite a bit of 1394, which is a
implementation. CSR implementation.
</para> </para>
<sect1> <sect1>
@ -94,20 +94,30 @@
<para> <para>
A 1394 bus consists of up to 64 nodes (with multiple buses possibly 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 being connected, but that is outside of the scope of this document and
not completely standardized yet), each having a local address space with not completely standardized yet). Each node is addressed with a 16 bit
48 bit wide addressing. Each node is addressed with a 16 bit address, address, which is further divided into a 10 bit bus ID and a 6 bit local
which is further divided into a 10 bit bus ID and a 6 bit local node ID. node number, the so-called physical ID. The physical IDs are completely
The highest value for both is a special value. Bus ID equal to 1023 dynamic and determined during the bus reset. The highest values for
means "local bus" (the bus the node is connected to), node ID equal to both are special values. Bus ID equal to 1023 means "local bus" (the
63 means "all nodes" (broadcast). bus the node is connected to), physical ID equal to 63 means "all nodes"
(broadcast).
</para> </para>
<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 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 address (least significant bits). libraw1394 treats them separately in
function arguments to save the application some fiddling with the bits. 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>
<para> <para>
@ -156,23 +166,23 @@
The root node sends a SelfID grant on its first port connected to a 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 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 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 physical 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 with its physical ID and more information, then acknowledge the SelfID
to its parent, which will send a grant to its next child until it 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 configured all its children, then pick a physical ID itself, send SelfID
packet and ack to parent. packet and ack to parent.
</para> </para>
<para> <para>
After bus reset the used node IDs are in a sequential range with no After bus reset the used physical IDs are in a sequential range with no
holes starting from 0 with the root node having the highest ID. This holes starting from 0 up to the root node having the highest ID. This
also means that node IDs can change for many or all nodes with the 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 insertion of a new node or moving the role of root to another node. In
libraw1394 all transactions are tagged automatically with a generation libraw1394 all transactions are tagged automatically with a generation
number which is increased in every bus reset and transactions with an number which is increased in every bus reset and transactions with an
obsolete generation will fail in order to avoid targetting the wrong obsolete generation will fail in order to avoid targetting the wrong
node. Nodes have to be identified in a different way than their 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. contained in the configuration ROM.
</para> </para>
</sect1> </sect1>
@ -304,11 +314,11 @@
values (all channels free, all bandwidth minus some amount set aside for values (all channels free, all bandwidth minus some amount set aside for
asynchronous communication available), this has to happen since the asynchronous communication available), this has to happen since the
isochronous manager may have moved to another node. Isochronous isochronous manager may have moved to another node. Isochronous
transmissions may continue with the old allocations for a certain transmissions may continue with the old allocations for 1000ms. During
(FIXME) amount of time. During that time, the nodes have to reallocate that time, the nodes have to reallocate their resources and no new
their resources and no new allocations are allowed to occur. Only after allocations are allowed to occur. Only after this period new
this period new allocations may be done, this avoids nodes losing their allocations may be done, this avoids nodes losing their allocations over
allocations over a bus reset. a bus reset.
</para> </para>
<para> <para>

42
src/raw1394.h
View File

@ -824,9 +824,9 @@ int raw1394_start_phy_packet_write(raw1394handle_t handle,
/** /**
* raw1394_start_read - initiate a read transaction * raw1394_start_read - initiate a read transaction
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @node: target node * @node: target node ID
* @addr: address to read from * @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 * @buffer: pointer to buffer where data will be saved
* @tag: data to identify the request to completion handler * @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 * raw1394_start_write - initiate a write transaction
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @node: target node * @node: target node ID
* @addr: address to write to * @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 * @data: pointer to data to be sent
* @tag: data to identify the request to completion handler * @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 * raw1394_start_lock - initiate a 32-bit compare-swap lock transaction
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @node: target node * @node: target node ID
* @addr: address to read from * @addr: address to read from
* @extcode: extended transaction code determining the lock operation * @extcode: extended transaction code determining the lock operation
* @data: data part of lock parameters * @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 * raw1394_start_lock64 - initiate a 64-bit compare-swap lock transaction
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @node: target node * @node: target node ID
* @addr: address to read from * @addr: address to read from
* @extcode: extended transaction code determining the lock operation * @extcode: extended transaction code determining the lock operation
* @data: data part of lock parameters * @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); octlet_t *result, unsigned long tag);
/** /**
* raw1394_start_read - initiate asynchronous stream * raw1394_start_async_stream - initiate asynchronous stream
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @channel: the isochronous channel number to send on * @channel: the isochronous channel number to send on
* @tag: data to be put into packet's tag field * @tag: data to be put into packet's tag field
* @sy: data to be put into packet's sy field * @sy: data to be put into packet's sy field
* @speed: speed at which to send * @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 * @data: pointer to data to send
* @rawtag: data to identify the request to completion handler * @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 * raw1394_start_async_send - send an asynchronous packet
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @length: the amount of quadlets of data to send * @length: the amount of bytes of data to send
* @header_length: the number of quadlets in the header * @header_length: the number of bytes in the header
* @expect_response: indicate with a 0 or 1 whether to receive a completion event * @expect_response: indicate with a 0 or 1 whether to receive a completion event
* @data: pointer to data to send * @data: pointer to data to send
* @rawtag: data to identify the request to completion handler * @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. * raw1394_read - send async read request to a node and wait for response.
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @node: target node * @node: target node ID
* @addr: address to read from * @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 * @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 * 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 * will call raw1394_loop_iterate() as often as necessary, return values of
* handlers called will be therefore lost. * 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. * raw1394_write - send async write request to a node and wait for response.
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @node: target node * @node: target node ID
* @addr: address to write to * @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 * @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 * 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 * will call raw1394_loop_iterate() as often as necessary, return values of
* handlers called will be therefore lost. * 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. * raw1394_lock - send 32-bit compare-swap lock request and wait for response.
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @node: target node * @node: target node ID
* @addr: address to read from * @addr: address to read from
* @extcode: extended transaction code determining the lock operation * @extcode: extended transaction code determining the lock operation
* @data: data part of lock parameters * @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. * raw1394_lock64 - send 64-bit compare-swap lock request and wait for response.
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @node: target node * @node: target node ID
* @addr: address to read from * @addr: address to read from
* @extcode: extended transaction code determining the lock operation * @extcode: extended transaction code determining the lock operation
* @data: data part of lock parameters * @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 * @tag: data to be put into packet's tag field
* @sy: data to be put into packet's sy field * @sy: data to be put into packet's sy field
* @speed: speed at which to send * @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 * @data: pointer to data to send
* *
* Returns: 0 on success or -1 on failure (sets errno) * 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 * raw1394_async_send
* @handle: libraw1394 handle * @handle: libraw1394 handle
* @length: the amount of quadlets of data to send * @length: the amount of bytes of data to send
* @header_length: the number of quadlets in the header * @header_length: the number of bytes in the header
* @expect_response: indicate with a 0 or 1 whether to receive a completion event * @expect_response: indicate with a 0 or 1 whether to receive a completion event
* @data: pointer to data to send * @data: pointer to data to send
* *