libraw1394.sgml

libraw1394-1.1.0.tar.gz 1394的一个库文件

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>

<book>
  <bookinfo>

    <title>libraw1394</title>
    <subtitle>version 1.1.0</subtitle>

    <copyright>
      <year>2001-2004</year>
      <holder>Andreas Bombe, Dan Maas, Manfred Weihs, and Christian Toegel</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>
	</sect1>

  </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>