1229 lines
44 KiB
Plaintext
1229 lines
44 KiB
Plaintext
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
|
|
|
|
<book>
|
|
<bookinfo>
|
|
|
|
<title>libraw1394</title>
|
|
<subtitle>version 0.9</subtitle>
|
|
|
|
<copyright>
|
|
<year>2001</year>
|
|
<holder>Andreas Bombe</holder>
|
|
</copyright>
|
|
|
|
</bookinfo>
|
|
|
|
<toc></toc>
|
|
|
|
<chapter id="introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
The Linux kernel's IEEE 1394 subsystem provides access to the raw 1394 bus
|
|
through the raw1394 module. This includes the standard 1394 transactions
|
|
(read, write, lock) on the active side, isochronous stream receiving and
|
|
sending and dumps of data written to the FCP_COMMAND and FCP_RESPONSE
|
|
registers. raw1394 uses a character device to communicate to user
|
|
programs using a special protocol.
|
|
</para>
|
|
|
|
<para>
|
|
libraw1394 was created with the intent to hide that protocol from
|
|
applications so that
|
|
<orderedlist numeration="arabic">
|
|
<listitem>
|
|
<para>
|
|
the protocol has to be implemented correctly only once.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
all work can be done using easy to understand functions instead of
|
|
handling a complicated command structure.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
only libraw1394 has to be changed when raw1394's interface changes.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>
|
|
To fully achieve the goals (especially 3) libraw1394 is distributed under
|
|
the LGPL (Lesser General Public License - see file COPYING.LIB for more
|
|
information.) to allow linking with any program, be it open source or
|
|
binary only. The requirements are that the libraw1394 part can be
|
|
replaced (relinked) with another version of the library and that changes
|
|
to libraw1394 itself fall under LGPL again. Refer to the LGPL text for
|
|
details.
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter id="intro1394">
|
|
<title>Short Introduction into IEEE 1394</title>
|
|
|
|
<para>
|
|
IEEE 1394 in fact defines two types of hardware implementations for this
|
|
bus system, cable and backplane. The only one described here and
|
|
supported by the Linux subsystem is the cable implementation. Most people
|
|
not familiar with the standard probably don't even know that there is
|
|
something else than the 1394 cable specification.
|
|
</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.
|
|
</para>
|
|
|
|
<sect1>
|
|
<title>Bus Structure</title>
|
|
|
|
<para>
|
|
The basic data structures defined in the standard and used in this
|
|
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, 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, ...).
|
|
</para>
|
|
|
|
<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).
|
|
</para>
|
|
|
|
<para>
|
|
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
|
|
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>
|
|
Unlike other buses there aren't many transactions or commands defined,
|
|
higher level commands are defined in terms of addresses accessed instead
|
|
of separate transaction types (comparable to memory mapped registers in
|
|
hardware). The 1394 transactions are:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>read (quadlets and blocks)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>write (quadlets and blocks)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>lock (some atomic modifications)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
There is also the isochronous transaction (the above three are called
|
|
asynchronous transactions), which is a broadcast stream with guaranteed
|
|
bandwidth. It doesn't contain any address but is distinguished by a 6
|
|
bit channel number.
|
|
</para>
|
|
|
|
<para>
|
|
The bus view is only logical, physically it consists of many
|
|
point-to-point connections between nodes with every node forwarding data
|
|
it receives to every other port which is capable of the speed the
|
|
transaction is sent at (thus a S200 node in the path between two S400
|
|
nodes would limit their communication speed to S200). It forms a tree
|
|
structure with all but one node having a parent and a number of
|
|
children. One node is the root node and has no parents.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Bus Reset</title>
|
|
|
|
<para>
|
|
A bus reset occurs whenever the state of any node changes (including
|
|
addition and removal of nodes). At the beginning a root node is chosen,
|
|
then the tree identification determines for every node which port is
|
|
connected to a parent, child or nothing. Then the SelfID phase begins.
|
|
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
|
|
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
|
|
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)
|
|
contained in the configuration ROM.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Transactions</title>
|
|
|
|
<para>
|
|
The packets transmitted on the bus are acknowledged by the receiving end
|
|
unless they are broadcast packets (broadcast writes and isochronous
|
|
packets). The acknowledge code contains an error code, which either
|
|
signifies error, success or packet pending. In the first two cases the
|
|
transaction completes, in the last a response packet will follow at a
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
For read and write there are two different types, quadlet and block.
|
|
The quadlet types have all their payload (exactly one quadlet) in the
|
|
packet header, the block types have a variable length data block
|
|
appended to the header. Programs using libraw1394 don't have to care
|
|
about that, quadlet transactions are automatically used when the data
|
|
length is 4 bytes and block transactions otherwise.
|
|
</para>
|
|
|
|
<para>
|
|
The lock transaction has several extended transaction codes defined
|
|
which choose the atomic operation to perform, the most used being the
|
|
compare-and-swap (code 0x2). The transaction passes the data value and
|
|
(depending on the operation) the arg value to the target node and
|
|
returns the old value at the target address, but only when the
|
|
transaction does not have an error. All three values are of the same
|
|
size, either one quadlet or one octlet.
|
|
</para>
|
|
|
|
<para>
|
|
In the compare-and-swap case, the data value is written to the target
|
|
address if the old value is identical to the arg value. The old value
|
|
is returned in any case and can be used to find out whether the swap
|
|
succeeded by repeating the compare locally. Compare-and-swap
|
|
is useful for avoiding race conditions when accessing the same
|
|
address from multiple nodes. For example, isochronous resource
|
|
allocation is done using compare-and-swap, as described below. Since
|
|
the old value is always returned, it more efficient to do the first
|
|
attempt with the reset value of the target register as arg instead of
|
|
reading it first. Repeat with the returned old value as new arg value
|
|
if it didn't succeed.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Bus Management</title>
|
|
|
|
<para>
|
|
There are three basic bus service nodes defined in IEEE 1394 (higher
|
|
level protocols may define more): cycle master, isochronous resource
|
|
manager and bus manager. These positions are contended for in and
|
|
shortly after the bus reset and may all be taken by a single node. A
|
|
node does not have to support being any of those but if it is bus
|
|
manager capable it also has to be iso manager capable, if it is iso
|
|
manager capable it also has to be cycle master capable.
|
|
</para>
|
|
|
|
<para>
|
|
The cycle master sends 8000 cycle start packets per second, which
|
|
initiate an iso cycle. Without that, no isochronous transmission is
|
|
possible. Only the root node is allowed to be cycle master, if it is
|
|
not capable then no iso transmissions can occur (and the iso or bus
|
|
manager have to select another node to become root and initiate a bus
|
|
reset).
|
|
</para>
|
|
|
|
<para>
|
|
The isochronous resource manager is the central point where channel and
|
|
bandwidth allocations are stored. A bit in the SelfID shows whether a
|
|
node is iso manager capable or not, the iso manager capable node with
|
|
the highest ID wins the position after a bus reset. Apart from
|
|
containing allocation registers, this one doesn't do much. Only if
|
|
there is no bus manager, it may determine a cycle master capable node to
|
|
become root and initiate a bus reset.
|
|
</para>
|
|
|
|
<para>
|
|
The bus manager has more responsibilities: power management (calculate
|
|
power provision and consumption on the bus and turn on disabled nodes if
|
|
enough power is available), bus optimization (calculate an effective gap
|
|
count, optimize the topology by selecting a better positioned node for
|
|
root) and some registers relevant to topology (topology map containing
|
|
the SelfIDs of the last reset and a speed map, which is obsoleted in
|
|
IEEE 1394a). The bus manager capable nodes contend for the role by
|
|
doing a lock transaction on the bus manager ID register in the iso
|
|
manager, the first to successfully complete the transaction wins the
|
|
role.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Isochronous Transmissions</title>
|
|
|
|
<para>
|
|
Nodes can allocate a channel and bandwidth for isochronous transmissions
|
|
at the iso manager to broadcast timing critical data (e.g. multimedia
|
|
streams) on the bus. However these transmissions are unreliable, there
|
|
is no guarantee that every packet reaches the intended recipients (the
|
|
software and hardware involved also take iso packets a bit more
|
|
lightly). After a cycle start packet, the isochronous cycle begins and
|
|
every node can transmit iso packets, however only one packet per channel
|
|
is allowed. As soon as a gap of a certain length appears (i.e. no node
|
|
sends anymore), the iso cycle ends and the rest of the time until the
|
|
next cycle start is reserved for asynchronous packets.
|
|
</para>
|
|
|
|
<para>
|
|
The channel register on the iso manager consists of 64 bits, each of
|
|
which signifies one channel. A channel can be allocated by any node by
|
|
doing a compare-swap lock request with the new bitmask. Likewise the
|
|
bandwidth can be allocated by doing a lock request with the new value.
|
|
The bandwidth register contains the remaining time available for every
|
|
iso cycle. Since you allocate time, the maximum data you are allowed to
|
|
put into an iso packet depends on the speed you will send at.
|
|
</para>
|
|
|
|
<para>
|
|
On every bus reset, the resource registers are resetted to their initial
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
libraw1394 does not provide special functions for allocating iso
|
|
resources nor does it clean up after programs when they exit. Protocols
|
|
exist that require the first node to use some resources to allocate it
|
|
and then leave it for the last node using it to deallocate it. This may
|
|
be different nodes, so automatic behaviour would be very undesirable in
|
|
these cases.
|
|
</para>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="general">
|
|
<title>Data Structures and Program Flow</title>
|
|
|
|
<sect1>
|
|
<title>Overview</title>
|
|
|
|
<para>
|
|
The 1394 subsystem in Linux is divided into the classical
|
|
three layers, like most other interface subsystems in Linux.
|
|
The in-kernel subsystem consists of the ieee1394 core, which
|
|
provides basic services like handling of the 1394 protocol
|
|
(converting the abstract transactions into packets and back),
|
|
collecting information about bus and nodes and providing some
|
|
services to the bus that are required to be available for
|
|
standards conformant nodes (e.g. CSR registers). Below that
|
|
are the hardware drivers, which handle converting packets and
|
|
bus events to and from hardware accesses on specific 1394
|
|
chipsets.
|
|
</para>
|
|
|
|
<para>
|
|
Above the core are the highlevel drivers, which use the services
|
|
provided by the core to implement protocols for certain devices and act
|
|
as drivers to these. raw1394 is one such driver, however it is not
|
|
specialized to handle one kind of device but is designed to accept
|
|
commands from user space to do any transaction wanted (as far as
|
|
possible from current core design). Using raw1394, normal applications
|
|
can access 1394 nodes on the bus and it is not neccessary to write
|
|
kernel code just for that.
|
|
</para>
|
|
|
|
<para>
|
|
raw1394 communicates to user space like most device drivers do, through
|
|
device files in /dev. It uses a defined protocol on that device, but
|
|
applications don't have to and should not care about that. All of this
|
|
is taken care of by libraw1394, which provides a set of functions that
|
|
convert to and from raw1394 protocol packets and are a lot easier to
|
|
handle than that underlying protocol.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Handles</title>
|
|
|
|
<para>
|
|
The handle presented to the application for using libraw1394 is the
|
|
raw1394handle_t, an opaque data structure (which means you don't need to
|
|
know its internals). The handle (and with it a connection to the kernel
|
|
side of raw1394) is obtained using
|
|
<function>raw1394_new_handle()</function>. Insufficient permissions to
|
|
access the kernel driver will result in failure of this function, among
|
|
other possibilities of failure.
|
|
</para>
|
|
|
|
<para>
|
|
While initializing the handle, a certain order of function calls have to
|
|
be obeyed or undefined results will occur. This order reflects the
|
|
various states of initialization to be done:
|
|
</para>
|
|
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><function>raw1394_new_handle()</function></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><function>raw1394_get_port_info()</function></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><function>raw1394_set_port()</function></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Ports</title>
|
|
|
|
<para>
|
|
A computer may have multiple 1394 buses connected by having multiple
|
|
1394 chips. Each of these is called a port, and the handle has to be
|
|
connected to one port before it can be used for anything. Even if no
|
|
nodes are connected to the chip in question, it forms a complete bus
|
|
(with just one node, itself).
|
|
</para>
|
|
|
|
<para>
|
|
A list of available ports together with some information about it (name
|
|
of the hardware, number of connected nodes) is available via
|
|
<function>raw1394_get_port_info()</function>, which is to be called
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
The choice of port is then reported using
|
|
<function>raw1394_set_port()</function>. If this function fails and
|
|
<symbol>errno</symbol> is set to <symbol>ESTALE</symbol>, then
|
|
something has changed about the ports (port was added or removed)
|
|
between getting the port info and trying to set a port. It is
|
|
required that the current port list is fetched (presenting the user
|
|
with the choice again) and setting the port is retried with the new
|
|
data.
|
|
</para>
|
|
|
|
<para>
|
|
After a successful <function>raw1394_set_port()</function>, the get and
|
|
set port functions must not be used anymore on this handle. Undefined
|
|
results occur if you do so. To make up for this, all the other
|
|
functions are allowed now.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>The Event Loop</title>
|
|
|
|
<para>
|
|
All commands in libraw1394 are asynchronous, with some
|
|
synchronous wrapper functions for some types of transactions.
|
|
This means that there are two streams of data, one going into
|
|
raw1394 and one coming out. With this design you can send out
|
|
multiple transactions without having to wait for the response
|
|
before you can continue (sending out other transactions, for
|
|
example). The responses and other events (like bus resets and
|
|
received isochronous packets) are queued, and you can get them
|
|
with <function>raw1394_loop_iterate()</function> or
|
|
<function>raw1394_loop_iterate_timeout()</function> (which
|
|
always returns after a user-specified timeout if no
|
|
raw1394 event has occurred).
|
|
</para>
|
|
|
|
<para>
|
|
This forms an event loop you may already know from similar systems like
|
|
GUI toolkits. <function>raw1394_loop_iterate()</function> gets one
|
|
message from the event queue in raw1394, processes it with the
|
|
configured callback functions and returns the value returned by the
|
|
callback (so you can signal to the main loop from your callback; the
|
|
standard callbacks all return 0). It normally blocks when there are no
|
|
events and always processes only one event. If you are only receiving
|
|
broadcast events like isochronous packets you thus have to set up a loop
|
|
continuously calling the iterate function to get your callbacks called.
|
|
</para>
|
|
|
|
<para>
|
|
Often it is necessary to have multiple event loops and combine
|
|
them, e.g. if your application uses a GUI toolkit which also
|
|
has its own event loop. In that case you can use
|
|
<function>raw1394_get_fd()</function> to get the file
|
|
descriptor used for this handle by libraw1394. The fd can be
|
|
used to for <function>select()</function> or
|
|
<function>poll()</function> calls together with the other
|
|
loop's fd. (Most toolkits, like GTK and Qt, have special APIs
|
|
for integrating file descriptors into their own event loops).
|
|
</para>
|
|
|
|
<para>
|
|
If using <function>poll()</function>, you must test for
|
|
<symbol>POLLIN</symbol> and <symbol>POLLPRI</symbol>
|
|
events. If using <function>select()</function>, you must test
|
|
for both read and exception activity.
|
|
</para>
|
|
|
|
<para> If any of these conditions trigger, you should then call
|
|
<function>raw1394_loop_iterate()</function> to pick up the
|
|
event. <function>raw1394_loop_iterate()</function> is
|
|
guaranteed not to block when called immediately after select()
|
|
or poll() indicates activity. After the first call you
|
|
continue the main event loop. If more events wait, the
|
|
<function>select()</function>/<function>poll()</function> will
|
|
immediately return again.
|
|
</para>
|
|
|
|
<para>
|
|
You can also use the fd to set the <symbol>O_NONBLOCK</symbol> flag with
|
|
<function>fcntl()</function>. After that, the iterate function will not
|
|
block anymore but fail with <symbol>errno</symbol> set to
|
|
<symbol>EAGAIN</symbol> if no events wait. These are the only legal
|
|
uses for the fd returned by <function>raw1394_get_fd()</function>.
|
|
</para>
|
|
|
|
<para>
|
|
There are some functions which provide a synchronous wrapper for
|
|
transactions, note that these will call
|
|
<function>raw1394_loop_iterate()</function> continuously until their
|
|
transaction is completed, thus having implicit callback invocations
|
|
during their execution. The standard transaction functions have names
|
|
of the form <function>raw1394_start_xxx</function>, the synchronous
|
|
wrappers are called <function>raw1394_xxx</function>.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Handlers</title>
|
|
|
|
<para>
|
|
There are a number of handlers which can be set using the appropriate
|
|
function as described in the function reference and which libraw1394
|
|
will call during a <function>raw1394_loop_iterate()</function>. These
|
|
are:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>tag handler (called for completed commands)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>bus reset handler (called when a bus reset happens)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>iso handler (called when an iso packet is received)
|
|
(deprecated by the new iso API)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>fcp handler (called when a FCP command or response is
|
|
received)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
The bus reset handler is always called, the tag handler for every
|
|
command that completes, the iso handler and fcp handler are only called
|
|
when the application chooses to receive these packets. Handlers return
|
|
an integer value which is passed on by
|
|
<function>raw1394_loop_iterate()</function> (only one handler is called
|
|
per invocation), <constant>0</constant> is returned without a handler in
|
|
place.
|
|
</para>
|
|
|
|
<para>
|
|
The tag handler case is a bit special since the default handler is
|
|
actually doing something. Every command that you start can be given an
|
|
unsigned long tag which is passed untouched to the tag handler when the
|
|
event loop sees a completed command. The default handler expects this
|
|
value to be a pointer to a <structname>raw1394_reqhandle</structname>
|
|
structure, which contains a data pointer and its own callback function
|
|
pointer. The callback gets the untouched data pointer and error code as
|
|
arguments. If you want to use tags that are not
|
|
<structname>raw1394_reqhandle</structname> pointers you have to set up
|
|
your own tag handler.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Generation Numbers</title>
|
|
|
|
<para>
|
|
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
|
|
<function>raw1394_set_port()</function> function to make sure you don't
|
|
use stale port numbers. This is done transparently to you.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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
|
|
<function>raw1394_update_generation()</function> directly in the handler
|
|
or later.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Error and Success Codes</title>
|
|
|
|
<para>
|
|
libraw1394 returns the ack/rcode pair in most transaction cases. The
|
|
rcode is undefined in cases where the ack code is not equal to
|
|
<symbol>ack_pending</symbol>. This is stored in a type
|
|
<type>raw1394_errcode_t</type>, from which the ack and rcode parts can
|
|
be extracted using two macros.
|
|
</para>
|
|
|
|
<para>
|
|
With the function <function>raw1394_errcode_to_errno()</function> 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 <symbol>errno</symbol> variable
|
|
to the appropriate code. The raw ack/rcode pair can then still be
|
|
retrieved using <function>raw1394_get_errcode()</function>.
|
|
</para>
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="isochronous">
|
|
<title>Isochronous Transmission and Reception</title>
|
|
|
|
<sect1>
|
|
<title>Overview</title>
|
|
<para>
|
|
Isochronous operations involve sending or receiving a constant
|
|
stream of packets at a fixed rate of 8KHz. Unlike raw1394's
|
|
asynchronous API, where you "push" packets to raw1394
|
|
functions at your leisure, the isochronous API is based around
|
|
a "pull" model. During isochronous transmission or reception,
|
|
raw1394 informs your application when a packet must be sent or
|
|
received. You must fulfill these requests in a timely manner
|
|
to avoid breaking the constant stream of isochronous packets.
|
|
</para>
|
|
<para>
|
|
A raw1394 handle may be associated with one isochronous
|
|
stream, either transmitting or receiving (but not both at the
|
|
same time). To transmit or receive more than one stream
|
|
simultaneously, you must create more than one raw1394 handle.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
|
|
<title>Initialization</title>
|
|
|
|
<para>
|
|
When a raw1394 handle is first created, no isochronous
|
|
stream is assocated with it. To begin isochronous
|
|
operations, call either
|
|
<function>raw1394_iso_xmit_init()</function> (transmission) or
|
|
<function>raw1394_iso_recv_init()</function>
|
|
(reception). The parameters to these functions are as follows:
|
|
</para>
|
|
|
|
<para>
|
|
<symbol>handler</symbol> is your function for queueing
|
|
packets to be sent (transmission) or processing received
|
|
packets (reception).
|
|
</para>
|
|
|
|
<para>
|
|
<symbol>buf_packets</symbol> is the number of packets that
|
|
will be buffered at the kernel level. A larger packet buffer
|
|
will be more forgiving of IRQ and application latency,
|
|
however it will consume more kernel memory. For most
|
|
applications, it is sufficient to buffer 2000-16000 packets
|
|
(0.25 seconds to 2.0 seconds maximum latency).
|
|
</para>
|
|
|
|
<para>
|
|
<symbol>max_packet_size</symbol> is the size, in bytes, of
|
|
the largest isochronous packet you intend to handle. This
|
|
size does not include the isochronous header but it does
|
|
include the CIP header specified by many isochronous
|
|
protocols.
|
|
</para>
|
|
|
|
<para>
|
|
<symbol>channel</symbol> is the isochronous channel on which
|
|
you wish to receive or transmit. (currently there is no
|
|
facility for multi-channel transmission or reception).
|
|
</para>
|
|
|
|
<para>
|
|
<symbol>speed</symbol> is the isochronous speed at which you
|
|
wish to operate. Possible values are
|
|
<symbol>RAW1394_ISO_SPEED_100</symbol> through
|
|
<symbol>RAW1394_ISO_SPEED_400</symbol>.
|
|
</para>
|
|
|
|
<para>
|
|
<symbol>irq_interval</symbol> is the maximum latency of the
|
|
kernel buffer, in packets. (To avoid excessive IRQ rates, the
|
|
low-level drivers only trigger an interrupt every
|
|
irq_interval packets). Pass -1 to receive a default value
|
|
that should be suitable for most applications.
|
|
</para>
|
|
|
|
<para>
|
|
If <function>raw1394_iso_xmit/recv_init()</function> retuns
|
|
successfully, then you may start isochronous operations. You
|
|
may not call
|
|
<function>raw1394_iso_xmit/recv_init()</function> again on
|
|
the same handle without first shutting down the isochronous
|
|
operation with <function>raw1394_iso_shutdown()</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Note that <function>raw1394_iso_xmit_init()</function> and
|
|
<function>raw1394_iso_recv_init()</function> involve
|
|
potentially time-consuming operations like allocating kernel
|
|
and device resources. If you intend to transmit or receive
|
|
several isochronous streams simultaneously, it is advisable
|
|
to initialize all streams before starting any packet
|
|
transmission or reception.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1>
|
|
|
|
<title>Stopping and Starting</title>
|
|
|
|
<para>
|
|
Once the isochronous operation has been initialized, you may
|
|
start and stop packet transmission with
|
|
<function>raw1394_iso_xmit/recv_start()</function> and
|
|
<function>raw1394_iso_stop()</function>. It is legal to call
|
|
these as many times as you want, and it is permissible to
|
|
start an already-started stream or stop an already-stopped
|
|
stream. Packets that have been queued for transmission or
|
|
reception will remain queued when the operation is stopped.
|
|
</para>
|
|
|
|
<para>
|
|
<function>raw1394_iso_xmit/recv_start()</function> allow you
|
|
to specify on which isochronous cycle number to start
|
|
transmitting or receiving packets. Pass -1 to start
|
|
immediately. This parameter is ignored if isochronous
|
|
transmission or reception is already in progress.
|
|
</para>
|
|
|
|
<para>
|
|
<function>raw1394_iso_xmit_start()</function> has an
|
|
additional parameter, <symbol>prebuffer_packets</symbol>,
|
|
which specifies how many packets to queue up before starting
|
|
transmission. Possible values range from zero (start
|
|
transmission immediately after the first packet is queued)
|
|
up to the total number of packets in the buffer.
|
|
</para>
|
|
|
|
<para>
|
|
Once the isochronous operation has started, you must
|
|
repeatedly call <function>raw1394_loop_iterate()</function>
|
|
as usual to drive packet processing.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1>
|
|
|
|
<title>Receiving Packets</title>
|
|
|
|
<para>
|
|
Raw1394 maintains a fixed-size ringbuffer of packets in
|
|
kernel memory. The buffer is filled by the low-level driver
|
|
as it receives packets from the bus. It is your
|
|
application's job to process each packet, after which the
|
|
buffer space it occupied can be re-used for future packets.
|
|
</para>
|
|
|
|
<para>
|
|
The isochronous receive handler you provided will be called
|
|
from <function>raw1394_loop_iterate()</function> after each
|
|
packet is received. Your handler is passed a pointer to the
|
|
first byte of the packet's data payload, plus the packet's
|
|
length in bytes (not counting the isochronous header), the
|
|
cycle number at which it was received, the channel on which
|
|
it was received, and the "tag" and "sy" fields from the
|
|
isochronous header. Note that the packet is at this point
|
|
still in the kernel's receive buffer, so the data pointer is
|
|
only valid until the receive handler returns. You must make
|
|
a copy of the packet's data if you want to keep it.
|
|
</para>
|
|
|
|
<para>
|
|
The receive handler is also passed a "packet(s) dropped"
|
|
flag. If this flag is nonzero, it means that one or more
|
|
incoming packets have been dropped since the last call to
|
|
your handler (usually this is because the kernel buffer has
|
|
completely filled up with packets or a bus reset has
|
|
occurred).
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1>
|
|
|
|
<title>Transmitting Packets</title>
|
|
|
|
<para>
|
|
Similar to reception, raw1394 maintains a fixed-size
|
|
ringbuffer of packets in kernel memory. The buffer is filled
|
|
by your application as it queues packets to be sent. The
|
|
buffer is drained by the hardware driver as it transmits
|
|
packets on the 1394 bus.
|
|
</para>
|
|
|
|
<para>
|
|
The isochronous transmit handler you provided will be called
|
|
from <function>raw1394_loop_iterate()</function> whenever
|
|
there is space in the buffer to queue another packet. The
|
|
handler is passed a pointer to the first byte of the buffer
|
|
space for the packet's data payload, pointers to words
|
|
containing the data length in bytes (not counting the
|
|
isochronous header), "tag" and "sy" fields, and the
|
|
isochronous cycle number at which this packet will be
|
|
transmitted. The handler must write the packet's data
|
|
payload into the supplied buffer space, and set the values
|
|
pointed to by "len", "tag", and "sy" to the appropriate
|
|
values. The handler is permitted to write any number of data
|
|
bytes, up and including to the value of
|
|
<symbol>max_packet_size</symbol> passed to
|
|
<function>raw1394_iso_xmit_init()</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Note: If you passed -1 as the starting cycle to
|
|
<function>raw1394_iso_xmit_init()</function>, the cycle
|
|
number provided to your handler will be incorrect until after
|
|
one buffer's worth of packets have been transmitted.
|
|
</para>
|
|
|
|
<para>
|
|
The transmit handler is also passed a "packet(s) dropped"
|
|
flag. If this flag is nonzero, it means that one or more
|
|
outgoing packets have been dropped since the last call to
|
|
your handler (usually this is because the kernel buffer has
|
|
gone completely empty or a bus reset has occurred).
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1>
|
|
|
|
<title>Shutting down</title>
|
|
|
|
<para>
|
|
When the isochronous operation has finished, call
|
|
<function>raw1394_iso_shutdown()</function> to release all
|
|
associated resources. If you don't call this function
|
|
explicitly, it will be called automatically when the raw1394
|
|
handle is destroyed.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="functions">
|
|
<title>Function Reference</title>
|
|
|
|
<refentry>
|
|
<refmeta>
|
|
<refentrytitle>raw1394_new_handle</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>raw1394_new_handle</refname>
|
|
<refpurpose>create new handle</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>raw1394handle_t <function>raw1394_new_handle</function></funcdef>
|
|
<void>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Creates and returns a new handle. It is not allowed to use the same
|
|
handle in multiple threads or forked processes. It is allowed to
|
|
create and use multiple handles, however. Use one handle per thread
|
|
which needs it in the multithreaded case.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
Returns the created handle or <constant>NULL</constant> when
|
|
initialization fails. In the latter case <varname>errno</varname>
|
|
either contains some OS specific error code or <constant>0</constant>
|
|
if the error is that libraw1394 and raw1394 don't support each other's
|
|
protocol versions.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry>
|
|
<refmeta>
|
|
<refentrytitle>raw1394_destroy_handle</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>raw1394_destroy_handle</refname>
|
|
<refpurpose>deallocate handle</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>raw1394_destroy_handle</function></funcdef>
|
|
<paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>handle</parameter></term>
|
|
<listitem>
|
|
<para>handle to be deallocated</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Closes connection with raw1394 on this handle and deallocates
|
|
everything associated with it. It is safe to pass
|
|
<constant>NULL</constant> as handle, nothing is done in this case.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry>
|
|
<refmeta>
|
|
<refentrytitle>raw1394_get_port_info</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>raw1394_get_port_info</refname>
|
|
<refpurpose>get information about connected ports</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>raw1394_get_port_info</function></funcdef>
|
|
<paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
|
|
<paramdef>struct raw1394_port_info *<parameter>pinf</parameter></paramdef>
|
|
<paramdef>int <parameter>maxports</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>pinf</parameter></term>
|
|
<listitem>
|
|
<para>Pointer to an array of structure of type
|
|
<structname>raw1394_port_info</structname> which will be filled in
|
|
by the function.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>maxports</parameter></term>
|
|
<listitem>
|
|
<para>Maximum number of <parameter>pinf</parameter> structures to
|
|
fill in. Zero is valid.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
The number of ports currently existing.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Before you can set which port to use, you use this function to find
|
|
out which ports exist. The <structname>raw1394_port_info</structname>
|
|
structure looks like this:
|
|
|
|
<programlisting>
|
|
struct <structname>raw1394_portinfo</structname> {
|
|
int <structfield>nodes</structfield>;
|
|
char <structfield>name</structfield>[32];
|
|
};
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The field <structfield>nodes</structfield> contains the number of
|
|
nodes that are currently connected to that port, the field
|
|
<structfield>name</structfield> 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.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry>
|
|
<refmeta>
|
|
<refentrytitle>raw1394_get_fd</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>raw1394_get_fd</refname>
|
|
<refpurpose>get the communication file descriptor</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>raw1394_get_fd</function></funcdef>
|
|
<paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>handle</parameter></term>
|
|
<listitem>
|
|
<para>handle of which the fd is to be returned from</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Returns the fd used for communication with the raw1394 kernel module.
|
|
This can be used for
|
|
<function>select()</function>/<function>poll()</function> calls if you
|
|
wait on other fds or can be integrated into another event loop
|
|
(e.g. from a GUI application framework). It can also be used to
|
|
set/remove the <constant>O_NONBLOCK</constant> flag using
|
|
<function>fcntl()</function> to modify the block behaviour in
|
|
<function>raw1394_loop_iterate()</function>. It must not be used for
|
|
anything else.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
The fd of the communication stream. Invalid fds may be returned
|
|
before a port was set using <function>raw1394_set_port()</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry>
|
|
<refmeta>
|
|
<refentrytitle>raw1394_(get|set)_userdata</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>raw1394_get_userdata</refname>
|
|
<refname>raw1394_set_userdata</refname>
|
|
<refpurpose>associate user data with a handle</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void *<function>raw1394_get_userdata</function></funcdef>
|
|
<paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>void <function>raw1394_set_userdata</function></funcdef>
|
|
<paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>handle</parameter></term>
|
|
<listitem>
|
|
<para>handle associated with the user data</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Allows to associate one void pointer with a handle. libraw1394 does
|
|
not care about the data, it just stores it in the handle allowing it
|
|
to be retrieved at any time. This can be useful when multiple handles
|
|
are used, so that callbacks can identify the handle.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
<function>raw1394_get_userdata()</function> returns the void pointer
|
|
associated with the handle.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry>
|
|
<refmeta>
|
|
<refentrytitle>raw1394_get_(local_id|irm_id|nodecount)</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>raw1394_get_local_id</refname>
|
|
<refname>raw1394_get_irm_id</refname>
|
|
<refname>raw1394_get_nodecount</refname>
|
|
<refpurpose>return basic information about the bus</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>nodeid_t <function>raw1394_get_local_id</function></funcdef>
|
|
<paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>nodeid_t <function>raw1394_get_irm_id</function></funcdef>
|
|
<paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>int <function>raw1394_get_nodecount</function></funcdef>
|
|
<paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>handle</parameter></term>
|
|
<listitem>
|
|
<para>handle associated with a 1394 bus</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
These functions return information about the 1394 bus the handle is
|
|
associated with. The values that can be queried through these
|
|
functions can change with every bus reset.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>
|
|
<function>raw1394_get_local_id()</function> returns the node ID of the
|
|
local node (i.e. the hardware the driver is controlling directly).
|
|
<function>raw1394_get_irm_id()</function> returns the node ID of the
|
|
node that has become isochronous resource manager.
|
|
<function>raw1394_get_nodecount</function> returns the number of nodes
|
|
currently on the bus (including the local node).
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
</chapter>
|
|
|
|
</book>
|