io.sgml

eCos操作系统源码

<section id="io-serial-cyg-io-write">
<title>cyg_io_write</title>

<PROGRAMLISTING>
cyg_io_write(handle, buf, len)
</PROGRAMLISTING>

<PARA>
Send the data from <parameter>buf</parameter> to the device. The
driver maintains a buffer to hold the data. The size of the
intermediate buffer is configurable within the interface module. The
data is not modified at all while it is being buffered. On return,
<parameter>*len</parameter> contains the amount of characters actually
consumed .</PARA>

<PARA>
It is possible to configure the write call to be blocking
(default) or non-blocking. Non-blocking mode requires both the configuration
option <literal>CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING</literal>
to be enabled, and the specific device to be set to non-blocking
mode for writes (see <function>cyg_io_set_config()</function>).
</para>

<para>
In blocking mode, the call will not return until there is space in the
buffer and the entire contents of <parameter>buf</parameter> have been
consumed.
</PARA>

<PARA>
In non-blocking mode, as much as possible gets consumed from
<parameter>buf</parameter>. If everything was consumed, the call
returns <literal>ENOERR</literal>. If only part of the
<parameter>buf</parameter> contents was consumed,
<literal>-EAGAIN</literal> is returned and the caller must try
again. On return, <parameter>*len</parameter> contains the number of characters actually
consumed .</PARA>

<PARA>
The call can also return <literal>-EINTR</literal> if interrupted
via the <function>cyg_io_get_config()</function>/<literal>ABORT</literal> key.
</para>

</section>

<!-- }}} -->
<!-- {{{ cyg_io_read -->

<section id="io-serial-cyg-io-read">
<title>cyg_io_read</title>

<programlisting>
cyg_io_read(handle, buf, len)
</programlisting>

<PARA>
Receive data into the buffer, <parameter>buf</parameter>, from the
device. No manipulation of the data is performed before being
transferred.  An interrupt driven interface module will support data
arriving when no read is pending by buffering the data in the serial
driver.  Again, this buffering is completely configurable. On return,
<parameter>*len</parameter> contains the number of characters actually
received.</PARA>

<PARA>
It is possible to configure the read call to be blocking (default)
or  non-blocking. Non-blocking mode requires both the configuration
option  <literal>CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING</literal>
to be enabled, and the specific device to be set to non-blocking
mode for reads (see <function>cyg_io_set_config()</function>).
</PARA>

<PARA>
In blocking mode, the call will not return until the requested
amount of data has been read.</PARA>

<PARA>
In non-blocking mode, data waiting in the device buffer is copied to
<parameter>buf</parameter>, and the call returns immediately. If there
was enough data in the buffer to fulfill the request,
<literal>ENOERR</literal> is returned.  If only part of the request
could be fulfilled, <literal>-EAGAIN</literal> is returned and the
caller must try again. On return, <parameter>*len</parameter> contains
the number of characters actually received.</PARA>

<PARA>
The call can also return <literal>-EINTR</literal> if interrupted via
the <function>cyg_io_get_config()</function>/<literal>ABORT</literal>
key.
</PARA>

</section>

<!-- }}} -->
<!-- {{{ cyg_io_get_config -->

<section id="io-serial-cyg-get-config">
<title>cyg_io_get_config</title>

<PROGRAMLISTING>
cyg_io_get_config(handle, key, buf, len)
</PROGRAMLISTING>

<PARA>This function returns current [runtime] information
about the device and/or driver. </PARA>

<VARIABLELIST>
  <VARLISTENTRY>
    <TERM><literal>CYG_IO_GET_CONFIG_SERIAL_INFO</literal></TERM>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA>cyg_serial_info_t</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function:</TERM>
          <LISTITEM>
            <PARA>
              This function retrieves the current state of the driver
              and hardware. This information contains fields for
              hardware baud rate, number of stop bits, and parity
              mode. It also includes a set of flags that control the
              port, such as hardware flow control.
            </PARA>
          </LISTITEM>
        </VARLISTENTRY>
      </variablelist>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM><literal>CYG_IO_GET_CONFIG_SERIAL_BUFFER_INFO</literal></TERM>
    <LISTITEM>
       <variablelist>
         <VARLISTENTRY>
           <TERM>Buf type:</TERM>
           <LISTITEM>
             <PARA>cyg_serial_buf_info_t</PARA>
           </LISTITEM>
         </VARLISTENTRY>
         <VARLISTENTRY>
           <TERM>Function:</TERM>
           <LISTITEM>
             <PARA>
               This function retrieves the current state of the
               software buffers in the serial drivers. For both
               receive and transmit buffers it returns the total
               buffer size and the current number of bytes occupied in
               the buffer. It does not take into account any buffering
               such as FIFOs or holding registers that the serial
               device itself may have.
             </PARA>
           </LISTITEM>
         </VARLISTENTRY>
       </variablelist>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM><literal>CYG_IO_GET_CONFIG_SERIAL_OUTPUT_DRAIN</literal></TERM>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA>void *</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function:</TERM>
          <LISTITEM>
            <PARA>
              This function waits for any buffered output to
              complete. This function only completes when there is no
              more data remaining to be sent to the device.
            </PARA>
          </LISTITEM>
        </VARLISTENTRY>
      </variablelist>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM><literal>CYG_IO_GET_CONFIG_SERIAL_OUTPUT_FLUSH</literal></TERM>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA>void *</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function:</TERM>
          <LISTITEM>
            <PARA>
              This function discards any buffered output for the
	      device.
            </PARA>
          </LISTITEM>
        </VARLISTENTRY>
      </variablelist>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM><literal>CYG_IO_GET_CONFIG_SERIAL_INPUT_DRAIN</literal></term>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA>void *</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function: 	</TERM>
          <LISTITEM>
            <PARA>This function discards any buffered input for the
            device.</PARA>
          </LISTITEM>
        </VARLISTENTRY>
      </variablelist>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM><literal>CYG_IO_GET_CONFIG_SERIAL_ABORT</literal></TERM>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA> void*</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function:</TERM>
          <LISTITEM>
            <PARA>This function will cause any pending read or write calls on
            this device to return with <literal>-EABORT</literal>.</PARA>
          </LISTITEM>
        </VARLISTENTRY>
      </variablelist>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM><literal>CYG_IO_GET_CONFIG_SERIAL_READ_BLOCKING</literal></TERM>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA> cyg_uint32 (values 0 or 1)</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function:</TERM>
          <LISTITEM>
            <PARA>This function will read back the blocking-mode
            setting for read calls on this device. This call is only
            available if the configuration option
            <literal>CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING</literal> is
            enabled.</PARA>
          </LISTITEM>
        </VARLISTENTRY>
      </variablelist>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM><literal>CYG_IO_GET_CONFIG_SERIAL_WRITE_BLOCKING</literal></TERM>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA> cyg_uint32 (values 0 or 1)</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function:</TERM>
          <LISTITEM>
            <PARA>
            This function will read back the blocking-mode
            setting for write calls on this device. This call is only
            available if the configuration option
            <literal>CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING</literal> is enabled.</PARA>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
  </varlistentry>
</variablelist>

</section>

<!-- }}} -->
<!-- {{{ cyg_io_set_config -->

<section id="io-serial-cyg-set-config">
<title>cyg_io_set_config</title>

<PROGRAMLISTING>
cyg_io_set_config(handle, key, buf,len)
</PROGRAMLISTING>

<PARA>This function is used to update or change runtime configuration
of a port. </PARA>

<variablelist>
  <VARLISTENTRY>
    <TERM><literal>CYG_IO_SET_CONFIG_SERIAL_INFO</literal></TERM>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA>cyg_serial_info_t</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function:</TERM>
          <LISTITEM>
            <PARA>This function updates the information for the driver
            and hardware.  The information contains fields for
            hardware baud rate, number of stop bits, and parity
            mode. It also includes a set of flags that control the
            port, such as hardware flow control.
            </PARA>
          </LISTITEM>
        </VARLISTENTRY>
      </variablelist>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM><literal>CYG_IO_SET_CONFIG_SERIAL_READ_BLOCKING</literal></TERM>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA> cyg_uint32 (values 0 or 1)</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function:</TERM>
          <LISTITEM>
            <PARA>This function will set the blocking-mode for read
            calls on this device. This call is only available if the
            configuration option <literal>CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING</literal>
            is enabled.
            </PARA>
          </LISTITEM>
        </VARLISTENTRY>
      </variablelist>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM><literal>CYG_IO_SET_CONFIG_SERIAL_WRITE_BLOCKING</literal></TERM>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA>cyg_uint32 (values 0 or 1)</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function:</TERM>
          <LISTITEM>
            <PARA>This function will set the blocking-mode for write
            calls on this device. This call is only available if the
            configuration option <literal>CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING</literal>
            is enabled.
            </PARA>
          </LISTITEM>
        </VARLISTENTRY>
      </variablelist>
    </LISTITEM>
  </VARLISTENTRY>
</VARIABLELIST>

</section>

<!-- }}} -->

</SECTION>

<!-- }}} -->