io.sgml

eCos操作系统源码

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     io.sgml                                                     -->
<!--                                                                 -->
<!--     Generic I/O subsystem documentation                         -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<PART id="io">
<TITLE>I/O Package (Device Drivers)</TITLE>

<!-- {{{ Intro -->

<CHAPTER id="io-package-intro">
<TITLE>Introduction</TITLE>

<PARA>
The I/O package is designed as a general purpose framework for
supporting device drivers. This includes all classes of
drivers from simple serial to networking stacks and beyond.
</PARA>

<PARA>
Components of the I/O package, such as device drivers, are
configured into the system just like all other components.
Additionally, end users may add their own drivers to this set.
</PARA>

<PARA>
While the set of drivers (and the devices they represent) may be
considered static, they must be accessed via an opaque
&ldquo;handle&rdquo;. Each device in the system has a unique name and
the <FUNCTION>cyg_io_lookup()</FUNCTION> function is used to map that
name onto the handle for the device. This &ldquo;hiding&rdquo; of the
device implementation allows for generic, named devices, as well as
more flexibility. Also, the <FUNCTION>cyg_io_lookup()</FUNCTION>
function provides drivers the opportunity to initialize the device
when usage actually starts.
</PARA>

<PARA>
All devices have a name. The standard provided devices use names such
as <filename>&ldquo;/dev/console&rdquo;</filename> and
<filename>&ldquo;/dev/serial0&rdquo;</filename>, where the
<filename>&ldquo;/dev/&rdquo;</filename> prefix indicates that this is
the name of a device.
</PARA>

<PARA>The entire I/O package API, as well as the standard
set of provided drivers, is written in C. </PARA>

<PARA>Basic functions are provided to send data to and receive data
from a device. The details of how this is done is left to the device [class] itself.
For example, writing data to a block device like a disk drive may
have different semantics than writing to a serial port. </PARA>

<PARA>Additional functions are provided to manipulate the state
of the driver and/or the actual device. These functions
are, by design, quite specific to the actual driver. </PARA>

<PARA>This driver model supports layering; in other words, a device
may actually be created &ldquo;on top of&rdquo; another device.
For example, the &ldquo;tty&rdquo; (terminal-like) devices are
built on top of simple serial devices. The upper layer then has
the flexibility to add features and functions not found at the lower
layers. In this case the &ldquo;tty&rdquo; device provides
for line buffering and editing not available from the simple serial
drivers.
</PARA>

<PARA>Some drivers will support visibility of the layers they depend
upon. The &ldquo;tty&rdquo; driver allows information about
the actual serial device to be manipulated by passing get/set
config calls that use a serial driver &ldquo;key&rdquo; down
to the serial driver itself. </PARA>

</CHAPTER>

<!-- }}} -->
<!-- {{{ User API -->

<CHAPTER id="io-user-api">
<TITLE><!-- <index></index> -->User API</TITLE>

<PARA>
All functions, except <FUNCTION>cyg_io_lookup()</FUNCTION>
require an I/O &ldquo;<!-- <index></index> -->handle&rdquo;.
</PARA>

<PARA>
All functions return a value of the type <type>Cyg_ErrNo</type>. If an
error condition is detected, this value will be negative and the
absolute value indicates the actual error, as specified in
<filename>cyg/error/codes.h</filename>. The only other legal return
value will be <varname>ENOERR</varname>. All other function arguments
are pointers (references). This allows the drivers to pass information
efficiently, both into and out of the driver. The most striking
example of this is the &ldquo;length&rdquo; value passed to the read
and write functions. This parameter contains the desired length of
data on input to the function and the actual transferred length on
return.
</PARA>

<PROGRAMLISTING>
// Lookup a device and return its handle 
  Cyg_ErrNo <FUNCTION><!-- <index></index> -->cyg_io_lookup</function>( 
    const char <parameter>*name</parameter>,
    cyg_io_handle_t <parameter>*handle</parameter> )
</PROGRAMLISTING>

<PARA>
This function maps a device name onto an appropriate handle. If the
named device is not in the system, then the error
<varname>-ENOENT</varname> is returned. If the device is found, then
the handle for the device is returned by way of the handle pointer
<parameter>*handle</parameter>.
</PARA>

<PROGRAMLISTING>
// Write data to a device 
Cyg_ErrNo <FUNCTION><!-- <index></index> -->cyg_io_write</function>( 
    cyg_io_handle_t <parameter>handle</parameter>,
    const void <parameter>*buf</parameter>,
    cyg_uint32 <parameter>*len</parameter> )
</PROGRAMLISTING>

<PARA>
This function sends data to a device. The size of data to send is
contained in <parameter>*len</parameter> and the actual size sent will
be returned in the same place.
</PARA>

<PROGRAMLISTING>
// Read data from a device 
Cyg_ErrNo <!-- <index></index> --><function>cyg_io_read</function>( 
    cyg_io_handle_t <parameter>handle</parameter>,
    void <parameter>*buf</parameter>,
    cyg_uint32 <parameter>*len</parameter> )
</PROGRAMLISTING>

<PARA>
This function receives data from a device. The desired size of data to
receive is contained in <parameter>*len</parameter> and the actual
size obtained will be returned in the same place.
</PARA>

<PROGRAMLISTING>
// Get the configuration of a device 
Cyg_ErrNo <FUNCTION><!-- <index></index> -->cyg_io_get_config</FUNCTION>( 
    cyg_io_handle_t <parameter>handle</parameter>,
    cyg_uint32 <parameter>key</parameter>,
    void *<parameter>buf</parameter>,
    cyg_uint32 *<parameter>len</parameter> )
</PROGRAMLISTING>

<PARA>
This function is used to obtain run-time configuration about a
device. The type of information retrieved is specified by the
<parameter>key</parameter>. The data will be returned in the given
buffer. The value of <parameter>*len</parameter> should contain the
amount of data requested, which must be at least as large as the size
appropriate to the selected key. The actual size of data retrieved is
placed in <parameter> *len</parameter>. The appropriate key values
differ for each driver and are all listed in the file
<filename>&lt;cyg/io/config_keys.h&gt;</filename>.
</PARA>

<PROGRAMLISTING>
// Change the configuration of a device 
Cyg_ErrNo <!-- <index></index> --><function>cyg_io_set_config</function>( 
    cyg_io_handle_t <parameter>handle</parameter>,
    cyg_uint32 <parameter>key</parameter>,
    const void <parameter>*buf</parameter>,
    cyg_uint32 <parameter>*len</parameter> )
</PROGRAMLISTING>

<PARA>
This function is used to manipulate or change the run-time
configuration of a device. The type of information is specified by the
<parameter>key</parameter>. The data will be obtained from the given
buffer. The value of <parameter>*len</parameter> should contain the
amount of data provided, which must match the size appropriate to the
selected key.  The appropriate key values differ for each driver and
are all listed in the file
<filename>&lt;cyg/io/config_keys.h&gt;</filename>.
</PARA>

</CHAPTER>

<!-- }}} -->
<!-- {{{ Serial Drivers  -->

<CHAPTER id="io-serial-driver-details">
<TITLE>Serial driver details</TITLE>

<PARA>
Two different classes of serial drivers are provided as a standard
part of the eCos system. These are described as &ldquo;raw
serial&rdquo; (serial) and &ldquo;tty-like&rdquo; (tty).
</PARA>

<!-- {{{ Raw Serial Drivers -->

<SECTION id="io-simple-serial-driver">
<TITLE>Raw Serial Driver</TITLE>

<PARA>
Use the include file <FILENAME>&lt;cyg/io/serialio.h&gt;</FILENAME> for
this driver.
</PARA>

<PARA>
The <!-- <index></index> -->raw serial driver is capable of sending
and receiving blocks of raw data to a serial device. Controls are
provided to configure the actual hardware, but there is no manipulation
of the data by this driver.
</PARA>

<PARA>
There may be many instances of this driver in a given system,
one for each serial channel. Each channel corresponds to a physical
device and there will typically be a device module created for this
purpose. The device modules themselves are configurable, allowing
specification of the actual hardware details, as well as such details
as whether the channel should be buffered by the serial driver,
etc.
</PARA>

<!-- {{{ Runtime Configuration -->

<SECTION>
<TITLE>Runtime Configuration</TITLE>

<para>
Runtime configuration is achieved by exchanging data structures with
the driver via the <function>cyg_io_set_config()</function> and
<function>cyg_io_get_config()</function> functions.
</para>

<PROGRAMLISTING>
typedef struct {
 cyg_serial_baud_rate_t baud;
 cyg_serial_stop_bits_t stop;
 cyg_serial_parity_t parity;
 cyg_serial_word_length_t word_length;
 cyg_uint32 flags;
} cyg_serial_info_t;
</PROGRAMLISTING>

<PARA>
The field <structfield><!-- <index></index>
-->word_length</structfield> contains the number of data bits per word
(character). This must be one of the values:
</PARA>

<PROGRAMLISTING>
 CYGNUM_SERIAL_WORD_LENGTH_5
 CYGNUM_SERIAL_WORD_LENGTH_6
 CYGNUM_SERIAL_WORD_LENGTH_7
 CYGNUM_SERIAL_WORD_LENGTH_8
</PROGRAMLISTING>

<PARA>
The field <structfield><!-- <index></index>
-->baud</structfield> contains a baud rate selection.  This must be
one of the values:
</PARA>

<PROGRAMLISTING>
 CYGNUM_SERIAL_BAUD_50
 CYGNUM_SERIAL_BAUD_75
 CYGNUM_SERIAL_BAUD_110
 CYGNUM_SERIAL_BAUD_134_5
 CYGNUM_SERIAL_BAUD_150
 CYGNUM_SERIAL_BAUD_200
 CYGNUM_SERIAL_BAUD_300
 CYGNUM_SERIAL_BAUD_600
 CYGNUM_SERIAL_BAUD_1200
 CYGNUM_SERIAL_BAUD_1800
 CYGNUM_SERIAL_BAUD_2400
 CYGNUM_SERIAL_BAUD_3600
 CYGNUM_SERIAL_BAUD_4800
 CYGNUM_SERIAL_BAUD_7200
 CYGNUM_SERIAL_BAUD_9600
 CYGNUM_SERIAL_BAUD_14400
 CYGNUM_SERIAL_BAUD_19200
 CYGNUM_SERIAL_BAUD_38400
 CYGNUM_SERIAL_BAUD_57600
 CYGNUM_SERIAL_BAUD_115200
 CYGNUM_SERIAL_BAUD_234000
</PROGRAMLISTING>

<PARA>The field <structfield><!-- <index></index>
-->stop</structfield> contains the number of stop bits. This must be
one of the values:</PARA>

<PROGRAMLISTING>
 CYGNUM_SERIAL_STOP_1
 CYGNUM_SERIAL_STOP_1_5
 CYGNUM_SERIAL_STOP_2
</PROGRAMLISTING>

<NOTE>
<title>Note</title>
<PARA>
On most hardware, a selection of 1.5 stop bits is only valid
if the word (character) length is 5.
</PARA>
</NOTE>

<PARA>The field <structfield><!-- <index></index>
-->parity</structfield> contains the parity mode.  This must be one of
the values: </PARA>

<PROGRAMLISTING>
 CYGNUM_SERIAL_PARITY_NONE
 CYGNUM_SERIAL_PARITY_EVEN
 CYGNUM_SERIAL_PARITY_ODD
 CYGNUM_SERIAL_PARITY_MARK
 CYGNUM_SERIAL_PARITY_SPACE
</PROGRAMLISTING>

<PARA>The field <structfield><!-- <index></index>
-->flags</structfield> is a bitmask which controls the behavior of the
serial device driver. It should be built from the values
<literal>CYG_SERIAL_FLAGS_xxx</literal> defined below:
</PARA>

<PROGRAMLISTING>
#define CYG_SERIAL_FLAGS_RTSCTS 0x0001
</PROGRAMLISTING>

<PARA>If this bit is set then the port is placed in &ldquo;hardware
handshake&rdquo; mode. In this mode, the CTS and RTS pins control
when data is allowed to be sent/received at the port. This
bit is ignored if the hardware does not support this level of
handshake.
</PARA>

<PROGRAMLISTING>
typedef struct {
  cyg_int32 rx_bufsize;
  cyg_int32 rx_count;
  cyg_int32 tx_bufsize;
  cyg_int32 tx_count;
} cyg_serial_buf_info_t;     
</PROGRAMLISTING>

<PARA>The field <structfield>rx_bufsize</structfield> contains
the total size of the incoming data buffer. This is set to zero on
devices that do not support buffering (i.e. polled devices).</PARA>

<PARA>The field <structfield>rx_count</structfield> contains the
number of bytes currently occupied in the incoming data buffer.
This is set to zero on devices that do not support buffering (i.e. polled
devices).</PARA>

<PARA>The field <structfield>tx_bufsize</structfield> contains the
total size of the transmit data buffer. This is set to zero on devices
that do not support buffering (i.e. polled devices).</PARA>

<PARA>The field <structfield>tx_count</structfield> contains the
number of bytes currently occupied in the transmit data buffer.  This
is set to zero on devices that do not support buffering (i.e. polled
devices).</PARA>

</SECTION>

<!-- }}} -->
<!-- {{{ API Details -->

<SECTION>
<TITLE><!-- <index></index> -->API Details</TITLE>

<!-- {{{ cyg_io_write -->