spi.sgml

开放源码实时操作系统源码.

<!-- DOCTYPE part  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     spi.sgml                                                    -->
<!--                                                                 -->
<!--     Generic SPI documentation.                                  -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 2004 eCosCentric Limited                          -->
<!-- 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####                                       -->
<!--                                                                 -->
<!-- Author(s):   bartv                                              -->
<!-- Date:        2004/04/23                                         -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<part id="io-spi"><title>SPI Support</title>

<refentry id="spi">
  <refmeta>
    <refentrytitle>Overview</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname>Overview</refname>
    <refpurpose>eCos Support for SPI, the Serial Peripheral Interface</refpurpose>
  </refnamediv>

  <refsect1 id="spi-description"><title>Description</title>
    <para>
The Serial Peripheral Interface (SPI) is one of a number of serial bus
technologies. It can be used to connect a processor to one or more
peripheral chips, for example analog-to-digital convertors or real
time clocks, using only a small number of pins and PCB tracks. The
technology was originally developed by Motorola but is now also
supported by other vendors.
    </para>
    <para>
A typical SPI system might look like this:
    </para>
    <informalfigure PgWide=1>
      <mediaobject>
        <imageobject>
          <imagedata fileref="spi_net.png" Scalefit=1 Align="Center">
        </imageobject>
      </mediaobject>
    </informalfigure>
    <para>
At the start of a data transfer the master cpu asserts one of the chip
select signals and then generates a clock signal. During each clock
tick the cpu will output one bit on its master-out-slave-in line and
read one bit on the master-in-slave-out line. Each device is connected
to the clock line, the two data lines, and has its own chip select. If
a device's chip select is not asserted then it will ignore any
incoming data and will tristate its output. If a device's chip select
is asserted then during each clock tick it will read one bit of data
on its input pin and output one bit on its output pin.
    </para>
    <para>
The net effect is that the cpu can write an arbitrary amount of data
to one of the attached devices at a time, and simultaneously read the
same amount of data. Some devices are inherently uni-directional. For
example an LED unit would only accept data from the cpu: it will not
send anything meaningful back; the cpu will still sample its input
every clock tick, but this should be discarded.
    </para>
    <para>
A useful feature of SPI is that there is no flow control from the
device back to the cpu. If the cpu tries to communicate with a device
that is not currently present, for example an MMC socket which does
not contain a card, then the I/O will still proceed. However the cpu
will read random data. Typically software-level CRC checksums or
similar techniques will be used to allow the cpu to detect this.
    </para>
    <para>
SPI communication is not fully standardized. Variations between
devices include the following:
    </para>
    <orderedlist>
      <listitem><para>
Many devices involve byte transfers, where the unit of data is 8 bits.
Others use larger units, up to 16 bits.
      </para></listitem>
      <listitem><para>
Chip selects may be active-high or active-low. If the attached devices
use a mixture of polarities then this can complicate things.
      </para></listitem>
      <listitem><para>
Clock rates can vary from 128KHz to 20MHz or greater. With some
devices it is necessary to interrogate the device using a slow clock,
then use the obtained information to select a faster clock for
subsequent transfers.
      </para></listitem>
      <listitem><para>
The clock is inactive between data transfers. When inactive the
clock's polarity can be high or low.
      </para></listitem>
      <listitem><para>
Devices depend on the phase of the clock. Data may be sampled on
either the rising edge or the falling edge of the clock.
      </para></listitem>
      <listitem><para>
A device may need additional delays, for example between asserting
the chip select and the first clock tick.
      </para></listitem>
      <listitem><para>
Some devices involve complicated transactions: perhaps a command from
cpu to device; then an initial status response from the device; a data
transfer; and a final status response. From the cpu's perspective
these are separate stages and it may be necessary to abort the
operation after the initial status response. However the device may
require that the chip select remain asserted for the whole
transaction. A side effect of this is that it is not possible to do a
quick transfer with another device in the middle of the transaction.
      </para></listitem>
      <listitem><para>
Certain devices, for example MMC cards, depend on a clock signal after
a transfer has completed and the chip select has dropped. This clock
is used to finish some processing within the device.
      </para></listitem>
    </orderedlist>
    <para>
Inside the cpu the clock and data signals are usually managed by
dedicated hardware. Alternatively SPI can be implemented using
bit-banging, but that approach is normally used for other serial bus
technologies such as I2C. The chip selects may also be implemented by
the dedicated SPI hardware, but often GPIO pins are used instead.
    </para>
  </refsect1>

  <refsect1 id="spi-ecos-implementation"><title>eCos Support for SPI</title>
    <para>
The eCos SPI support for any given platform is spread over a number of
different packages:
    </para>
    <itemizedlist>
      <listitem><para>
This package, <varname>CYGPKG_IO_SPI</varname>, exports an API for
accessing devices attached to an SPI bus. This API handles issues such
as locking between threads. The package does not contain any
hardware-specific code, instead it will call into an SPI bus driver
package.
      </para>
      <para>
In future this package may be extended with a bit-banging
implementation of an SPI bus driver. This would depend on lower-level
code for manipulating the GPIO pins used for the clock, data and chip
select signals, but timing and framing could be handled by generic code.
      </para></listitem>
      <listitem><para>
There will be a bus driver package for the specific SPI hardware on
the target hardware, for example
<varname>CYGPKG_DEVS_SPI_MCF52xx_QSPI</varname>. This is responsible
for the actual I/O. A bus driver may be used on many different boards,
all with the same SPI bus but with different devices attached to that
bus. Details of the actual devices should be supplied by other code.
      </para></listitem>
      <listitem><para>
The generic API depends on <structname>cyg_spi_device</structname>
data structures. These contain the information needed by a bus driver,
for example the appropriate clock rate and the chip select to use.
Usually the data structures are provided by the platform HAL since it
is that package which knows about all the devices on the board.
      </para>
      <para>
On some development boards the SPI pins are brought out to expansion
connectors, allowing end users to add extra devices. In such cases the
platform HAL may not know about all the devices on the board. Data
structures for the additional devices can instead be supplied by
application code.
      </para></listitem>
      <listitem><para>
Some types of SPI devices may have their own driver package. For
example one common use for SPI buses is to provide low-cost
MultiMediaCard (MMC) support. An MMC is a non-trivial device so there
is an eCos package specially for that, providing a block device
interface for higher-level code such as file systems. Other SPI
devices such as analog-to-digital converters are much simpler and
come in many varieties. There are no dedicated packages to support
each such device: the chances are low that another board would use the
exact same device, so there are no opportunities for code re-use.
Instead the devices may be accessed directly by application code or by
extra functions in the platform HAL.
      </para></listitem>
    </itemizedlist>
    <para>
Typically all appropriate packages will be loaded automatically when
you configure eCos for a given target. If the application does not use
of the SPI I/O facilities, directly or indirectly, then linker garbage
collection should eliminate all unnecessary code and data. All
necessary initialization should happen automatically. However the
exact details may depend on the target, so the platform HAL
documentation should be checked for further details.
    </para>
    <para>
There is one important exception to this: if the SPI devices are
attached to an expansion connector then the platform HAL will not know
about these devices. Instead more work will have to be done by
application code.
    </para>
  </refsect1>

</refentry>

<refentry id="spi-api">
  <refmeta>
    <refentrytitle>SPI Interface</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname>SPI Functions</refname>
    <refpurpose>allow applications and other packages to access SPI devices</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
#include &lt;cyg/io/spi.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
        <funcdef>void <function>cyg_spi_transfer</function></funcdef>