libraw1394.sgml

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

        <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><phrase id="API-raw1394-iso-xmit-init">raw1394_iso_xmit_init</phrase></refentrytitle>
</refmeta>
<refnamediv>
 <refname>raw1394_iso_xmit_init</refname>
 <refpurpose>
   initialize isochronous transmission
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>raw1394_iso_xmit_init </function></funcdef>
   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
   <paramdef>raw1394_iso_xmit_handler_t <parameter>handler</parameter></paramdef>
   <paramdef>unsigned int <parameter>buf_packets</parameter></paramdef>
   <paramdef>unsigned int <parameter>max_packet_size</parameter></paramdef>
   <paramdef>unsigned char <parameter>channel</parameter></paramdef>
   <paramdef>enum raw1394_iso_speed <parameter>speed</parameter></paramdef>
   <paramdef>int <parameter>irq_interval</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
      libraw1394 handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
      handler function for queueing packets
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf_packets</parameter></term>
   <listitem>
    <para>
      number of isochronous packets to buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_packet_size</parameter></term>
   <listitem>
    <para>
      largest packet you need to handle, in bytes
     (not including the isochronous header)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>channel</parameter></term>
   <listitem>
    <para>
      isochronous channel on which to transmit
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>speed</parameter></term>
   <listitem>
    <para>
      speed at which to transmit
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>irq_interval</parameter></term>
   <listitem>
    <para>
      maximum latency of wake-ups, in packets (-1 if you don't care)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
 <title>Description</title>
 <para>
   Allocates all user and kernel resources necessary for isochronous transmission.
 </para>
</refsect1>
<refsect1>
 <title>Returns</title>
 <para>
    0 on success or -1 on failure (sets errno)
 </para>
</refsect1>
</refentry>

<refentry>
<refmeta>
<refentrytitle><phrase id="API-raw1394-iso-recv-init">raw1394_iso_recv_init</phrase></refentrytitle>
</refmeta>
<refnamediv>
 <refname>raw1394_iso_recv_init</refname>
 <refpurpose>
      initialize isochronous reception
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>raw1394_iso_recv_init </function></funcdef>
   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
   <paramdef>raw1394_iso_recv_handler_t <parameter>handler</parameter></paramdef>
   <paramdef>unsigned int <parameter>buf_packets</parameter></paramdef>
   <paramdef>unsigned int <parameter>max_packet_size</parameter></paramdef>
   <paramdef>unsigned char <parameter>channel</parameter></paramdef>
   <paramdef>enum raw1394_iso_dma_recv_mode <parameter>mode</parameter></paramdef>
   <paramdef>int <parameter>irq_interval</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
      libraw1394 handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
      handler function for receiving packets
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf_packets</parameter></term>
   <listitem>
    <para>
      number of isochronous packets to buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_packet_size</parameter></term>
   <listitem>
    <para>
      largest packet you need to handle, in bytes (not including
     the isochronous header)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>channel</parameter></term>
   <listitem>
    <para>
      isochronous channel to receive
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
      bufferfill or packet per buffer mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>irq_interval</parameter></term>
   <listitem>
    <para>
      maximum latency of wake-ups, in packets
     (-1 if you don't care)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
 <title>Description</title>
 <para>
   Allocates all user and kernel resources necessary for isochronous reception.
 </para>
</refsect1>
<refsect1>
 <title>Returns</title>
 <para>
    0 on success or -1 on failure (sets errno)
 </para>
</refsect1>
</refentry>

<refentry>
<refmeta>
<refentrytitle><phrase id="API-raw1394-iso-multichannel-recv-init">raw1394_iso_multichannel_recv_init</phrase></refentrytitle>
</refmeta>
<refnamediv>
 <refname>raw1394_iso_multichannel_recv_init</refname>
 <refpurpose>
      initialize multi-channel iso reception
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>raw1394_iso_multichannel_recv_init </function></funcdef>
   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
   <paramdef>raw1394_iso_recv_handler_t <parameter>handler</parameter></paramdef>
   <paramdef>unsigned int <parameter>buf_packets</parameter></paramdef>
   <paramdef>unsigned int <parameter>max_packet_size</parameter></paramdef>
   <paramdef>int <parameter>irq_interval</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
      libraw1394 handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
      handler function for receiving packets
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf_packets</parameter></term>
   <listitem>
    <para>
      number of isochronous packets to buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_packet_size</parameter></term>
   <listitem>
    <para>
      largest packet you need to handle, in bytes (not including
     the isochronous header)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>irq_interval</parameter></term>
   <listitem>
    <para>
      maximum latency of wake-ups, in packets (-1 if you don't care)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
 <title>Description</title>
 <para>
   Allocates all user and kernel resources necessary for isochronous reception.
 </para>
</refsect1>
<refsect1>
 <title>Returns</title>
 <para>
    0 on success or -1 on failure (sets errno)
 </para>
</refsect1>
</refentry>

<refentry>
<refmeta>
<refentrytitle><phrase id="API-raw1394-iso-recv-listen-channel">raw1394_iso_recv_listen_channel</phrase></refentrytitle>
</refmeta>
<refnamediv>
 <refname>raw1394_iso_recv_listen_channel</refname>
 <refpurpose>
      listen to a specific channel in multi-channel mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>raw1394_iso_recv_listen_channel </function></funcdef>
   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
   <paramdef>unsigned char <parameter>channel</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handle</parameter></term>