📄 spi-api.html
字号:
<!-- Copyright (C) 2009 Free Software Foundation, 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 is obtained from the copyright holder. -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>SPI Interface</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
REL="UP"
TITLE="SPI Support"
HREF="io-spi.html"><LINK
REL="PREVIOUS"
TITLE="Overview"
HREF="spi.html"><LINK
REL="NEXT"
TITLE="Porting to New Hardware"
HREF="spi-porting.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Reference Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="spi.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="spi-porting.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SPI-API"
></A
>SPI Interface</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8309"
></A
><H2
>Name</H2
>SPI Functions -- allow applications and other packages to access SPI devices</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8312"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN8313"
></A
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <cyg/io/spi.h>
</PRE
></TD
></TR
></TABLE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_spi_transfer</CODE
>(cyg_spi_device* device, cyg_bool polled, cyg_uint32 count, const cyg_uint8* tx_data, cyg_uint8* rx_data);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_spi_tick</CODE
>(cyg_spi_device* device, cyg_bool polled, cyg_uint32 count);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int cyg_spi_get_config</CODE
>(cyg_spi_device* device, cyg_uint32 key, void* buf, cyg_uint32* len);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int cyg_spi_set_config</CODE
>(cyg_spi_device* device, cyg_uint32 key, const void* buf, cyg_uint32* len);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_spi_transaction_begin</CODE
>(cyg_spi_device* device);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>cyg_bool cyg_spi_transaction_begin_nb</CODE
>(cyg_spi_device* device);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_spi_transaction_transfer</CODE
>(cyg_spi_device* device, cyg_bool polled, cyg_uint32 count, const cyg_uint8* tx_data, cyg_uint8* rx_data, cyg_bool drop_cs);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_spi_transaction_tick</CODE
>(cyg_spi_device* device, cyg_bool polled, cyg_uint32 count);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_spi_transaction_end</CODE
>(cyg_spi_device* device);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SPI-API-DESCRIPTION"
></A
><H2
>Description</H2
><P
>All SPI functions take a pointer to a
<CODE
CLASS="STRUCTNAME"
>cyg_spi_device</CODE
> structure as their first
argument. This is an opaque data structure, usually provided by the
platform HAL. It contains the information needed by the SPI bus driver
to interact with the device, for example the required clock rate and
polarity.
</P
><P
>An SPI transfer involves the following stages:
</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Perform thread-level locking on the bus. Only one thread at a time is
allowed to access an SPI bus. This eliminates the need to worry about
locking at the bus driver level. If a platform involves multiple SPI
buses then each one will have its own lock. Prepare the bus for
transfers to the specified device, for example by making sure it will
tick at the right clock rate.
</P
></LI
><LI
><P
>Assert the chip select on the specified device, then transfer data to
and from the device. There may be a single data transfer or a
sequence. It may or may not be necessary to keep the chip select
asserted throughout a sequence.
</P
></LI
><LI
><P
>Optionally generate some number of clock ticks without asserting a
chip select, for those devices which need this to complete an
operation.
</P
></LI
><LI
><P
>Return the bus to a quiescent state. Then unlock the bus, allowing
other threads to perform SPI operations on devices attached to this
bus.
</P
></LI
></OL
><P
>The simple functions <CODE
CLASS="FUNCTION"
>cyg_spi_transfer</CODE
> and
<CODE
CLASS="FUNCTION"
>cyg_spi_tick</CODE
> perform all these steps in a single
call. These are suitable for simple I/O operations. The alternative
transaction-oriented functions each perform just one of these steps.
This makes it possible to perform multiple transfers while only
locking and unlocking the bus once, as required for more complicated
devices.
</P
><P
>With the exception of
<CODE
CLASS="FUNCTION"
>cyg_spi_transaction_begin_nb</CODE
> all the functions
will block until completion. There are no error conditions. An SPI
transfer will always take a predictable amount of time, depending on
the transfer size and the clock rate. The SPI bus does not receive any
feedback from a device about possible errors, instead those have to be
handled by software at a higher level. If a thread cannot afford the
time it will take to perform a complete large transfer then a number
of smaller transfers can be used instead.
</P
><P
>SPI operations should always be performed at thread-level or during
system initialization, and not inside an ISR or DSR. This greatly
simplifies locking. Also a typical ISR or DSR should not perform a
blocking operation such as an SPI transfer.
</P
><P
>SPI transfers can happen in either polled or interrupt-driven mode.
Typically polled mode should be used during system initialization,
before the scheduler has been started and interrupts have been
enabled. Polled mode should also be used in single-threaded
applications such as RedBoot. A typical multi-threaded application
should normally use interrupt-driven mode because this allows for more
efficient use of cpu cycles. Polled mode may be used in a
multi-threaded application but this is generally undesirable: the cpu
will spin while waiting for a transfer to complete, wasting cycles;
also the current thread may get preempted or timesliced, making the
timing of an SPI transfer much less predictable. On some hardware
interrupt-driven mode is impossible or would be very inefficient. In
such cases the bus drivers will only support polled mode and will
ignore the <CODE
CLASS="VARNAME"
>polled</CODE
> argument.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SPI-API-TRANSFER"
></A
><H2
>Simple Transfers</H2
><P
><CODE
CLASS="FUNCTION"
>cyg_spi_transfer</CODE
> can be used for SPI operations
to simple devices. It takes the following arguments:
</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="TYPE"
>cyg_spi_device*</SPAN
> <CODE
CLASS="VARNAME"
>device</CODE
></DT
><DD
><P
>This identifies the SPI device that should be used.
</P
></DD
><DT
><SPAN
CLASS="TYPE"
>cyg_bool</SPAN
> <CODE
CLASS="VARNAME"
>polled</CODE
></DT
><DD
><P
>Polled mode should be used during system initialization and in a
single-threaded application. Interrupt-driven mode should normally be
used in a multi-threaded application.
</P
></DD
><DT
><SPAN
CLASS="TYPE"
>cyg_uint32</SPAN
> <CODE
CLASS="VARNAME"
>count</CODE
></DT
><DD
><P
>This identifies the number of data items to be transferred. Usually
each data item is a single byte, but some devices use a larger size up
to 16 bits.
</P
></DD
><DT
><SPAN
CLASS="TYPE"
>const cyg_uint8*</SPAN
> <CODE
CLASS="VARNAME"
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -