libraw1394.sgml

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

	  </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>, 
		 <symbol>RAW1394_ISO_SPEED_200</symbol>, and
         <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>
         <symbol>mode</symbol> for <function>raw1394_iso_recv_init()</function>
         sets whether to use packet-per-buffer or buffer-fill receive mode.
		 Possible values are <symbol>RAW1394_DMA_DEFAULT</symbol> (bufferfill 
		 on ohci1394), <symbol>RAW1394_DMA_BUFFERFILL</symbol>, and 
		 <symbol>RAW1394_DMA_PACKET_PER_BUFFER</symbol>.
       </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>