Subversion Repositories openrisc

    Overview

    Overview

    eCos Support for SPI, the Serial Peripheral Interface

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.

A typical SPI system might look like this:

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.

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.

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.

SPI communication is not fully standardized. Variations between

devices include the following:

Many devices involve byte transfers, where the unit of data is 8 bits.

Others use larger units, up to 16 bits.

Chip selects may be active-high or active-low. If the attached devices

use a mixture of polarities then this can complicate things.

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.

The clock is inactive between data transfers. When inactive the

clock's polarity can be high or low.

Devices depend on the phase of the clock. Data may be sampled on

either the rising edge or the falling edge of the clock.

A device may need additional delays, for example between asserting

the chip select and the first clock tick.

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.

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.

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.

The eCos SPI support for any given platform is spread over a number of

different packages:

This package, CYGPKG_IO_SPI, 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.

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.

There will be a bus driver package for the specific SPI hardware on

the target hardware, for example

CYGPKG_DEVS_SPI_MCF52xx_QSPI. 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.

The generic API depends on cyg_spi_device

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.

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.

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.

Typically all appropriate packages will be loaded automatically when

you configure eCos for a given target. If the application does not use

any 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.

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.

    SPI Interface

    SPI Functions

    allow applications and other packages to access SPI devices

#include <cyg/io/spi.h>

        void cyg_spi_transfer

        cyg_spi_device* device

        cyg_bool polled

        cyg_uint32 count

        const cyg_uint8* tx_data

        cyg_uint8* rx_data

        void cyg_spi_tick

        cyg_spi_device* device

        cyg_bool polled

        cyg_uint32 count

        int cyg_spi_get_config

        cyg_spi_device* device

        cyg_uint32 key

        void* buf

        cyg_uint32* len

        int cyg_spi_set_config

        cyg_spi_device* device

        cyg_uint32 key

        const void* buf

        cyg_uint32* len

        void cyg_spi_transaction_begin

        cyg_spi_device* device

        cyg_bool cyg_spi_transaction_begin_nb

        cyg_spi_device* device

        void cyg_spi_transaction_transfer

        cyg_spi_device* device

        cyg_bool polled

        cyg_uint32 count

        const cyg_uint8* tx_data

        cyg_uint8* rx_data

        cyg_bool drop_cs

        void cyg_spi_transaction_tick

        cyg_spi_device* device

        cyg_bool polled

        cyg_uint32 count

        void cyg_spi_transaction_end

        cyg_spi_device* device

All SPI functions take a pointer to a

cyg_spi_device 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.

An SPI transfer involves the following stages:

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.

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.

Optionally generate some number of clock ticks without asserting a

chip select, for those devices which need this to complete an

operation.

Return the bus to a quiescent state. Then unlock the bus, allowing

other threads to perform SPI operations on devices attached to this

bus.

The simple functions cyg_spi_transfer and

cyg_spi_tick 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.

With the exception of

cyg_spi_transaction_begin_nb 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.

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.

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 polled argument.

cyg_spi_transfer can be used for SPI operations

to simple devices. It takes the following arguments:

        cyg_spi_device* device

This identifies the SPI device that should be used.

        cyg_bool polled

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.

        cyg_uint32 count

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.

        const cyg_uint8* tx_data

The data to be transferred to the device. If the device will only

output data and ignore its input then a null pointer can be used.

Otherwise the array should contain count data

items, usually bytes. For devices where each data item is larger than

one byte the argument will be interpreted as an array of shorts

instead, and should be aligned to a 2-byte boundary. The bottom n bits

of each short will be sent to the device. The buffer need not be

aligned to a cache-line boundary, even for SPI devices which use DMA

transfers, but some bus drivers may provide better performance if the

buffer is suitably aligned. The buffer will not be modified by the

transfer.

        cyg_uint8* rx_data

A buffer for the data to be received from the device. If the device

does not generate any output then a null pointer can be used.

The same size and alignment rules apply as for tx_data.

cyg_spi_transfer performs all the stages of an

SPI transfer: locking the bus; setting it up correctly for the

specified device; asserting the chip select and transferring the data;

dropping the chip select at the end of the transfer; returning the bus

to a quiescent state; and unlocking the bus.

Some devices require a number of clock ticks on the SPI bus between

transfers so that they can complete some internal processing. These

ticks must happen at the appropriate clock rate but no chip select

should be asserted and no data transfer will happen.

cyg_spi_tick provides this functionality.

The device argument identifies the SPI bus, the

required clock rate and the size of each data item. The

polled argument has the usual meaning. The

count argument specifies the number of data items

that would be transferred, which in conjunction with the size of each

data item determines the number of clock ticks.

A transaction-oriented API is available for interacting with more

complicated devices. This provides separate functions for each of the

steps in an SPI transfer.

cyg_spi_transaction_begin must be used at the

start of a transaction. This performs thread-level locking on the bus,

blocking if it is currently in use by another thread. Then it prepares

the bus for transfers to the specified device, for example by making

sure it will tick at the right clock rate.

cyg_spi_transaction_begin_nb is a non-blocking

variant, useful for threads which cannot afford to block for an

indefinite period. If the bus is currently locked the function returns

false immediately. If the bus is not locked then it acts as

cyg_spi_transaction_begin and returns true.

Once the bus has been locked it is possible to perform one or more

data transfers by calling

cyg_spi_transaction_transfer. This takes the same

arguments as cyg_spi_transfer, plus an additional

one drop_cs. A non-zero value specifies that

the device's chip select should be dropped at the end of the transfer,

otherwise the chip select remains asserted. It is essential that the

chip select be dropped in the final transfer of a transaction. If the

protocol makes this difficult then

cyg_spi_transaction_tick can be used to generate

dummy ticks with all chip selects dropped.

If the device requires additional clock ticks in the middle of a

transaction without being selected,

cyg_spi_transaction_tick can be used. This will

drop the device's chip select if necessary, then generate the

appropriate number of ticks. The arguments are the same as for

cyg_spi_tick.

cyg_spi_transaction_end should be called at the

end of a transaction. It returns the SPI bus to a quiescent state,

then unlocks it so that other threads can perform I/O.

A typical transaction might involve the following. First a command

should be sent to the device, consisting of four bytes. The device

will then respond with a single status byte, zero for failure,

non-zero for success. If successful then the device can accept another

n bytes of data, and will generate a 2-byte response including a

checksum. The device's chip select should remain asserted throughout.

The code for this would look something like:

#include <cyg/io/spi.h>

#include <cyg/hal/hal_io.h>    // Defines the SPI devices

…

    cyg_spi_transaction_begin(&hal_spi_eprom);

    // Interrupt-driven transfer, four bytes of command

    cyg_spi_transaction_transfer(&hal_spi_eprom, 0, 4, command, NULL, 0);

    // Read back the status

    cyg_spi_transaction_transfer(&hal_spi_eprom, 0, 1, NULL, status, 0);

    if (!status[0]) {

        // Command failed, generate some extra ticks to drop the chip select

        cyg_spi_transaction_tick(&hal_spi_eprom, 0, 1);

    } else {

        // Transfer the data, then read back the final status. The

        // chip select should be dropped at the end of this.

        cyg_spi_transaction_transfer(&hal_spi_eprom, 0, n, data, NULL, 0);

        cyg_spi_transaction_transfer(&hal_spi_eprom, 0, 2, NULL, status, 1);

        // Code for checking the final status should go here

    }

    // Transaction complete so clean up

    cyg_spi_transaction_end(&hal_spi_eprom);

A number of variations are possible. For example the command and

status could be packed into the beginning and end of two 5-byte

arrays, allowing a single transfer.

The functions cyg_spi_get_config and

cyg_spi_set_config can be used to examine and

change parameters associated with SPI transfers. The only keys that

are defined for all devices are

CYG_IO_GET_CONFIG_SPI_CLOCKRATE and

CYG_IO_SET_CONFIG_SPI_CLOCKRATE. Some types of

device, for example MMC cards, support a range of clock rates. The

cyg_spi_device structure will be initialized

with a low clock rate. During system initialization the device will be

queried for the optimal clock rate, and the

cyg_spi_device should then be updated. The

argument should be a clock rate in Hertz. For example the following

code switches communication to 1Mbit/s:

    cyg_uint32    new_clock_rate = 1000000;

    cyg_uint32    len            = sizeof(cyg_uint32);

    if (cyg_spi_set_config(&hal_mmc_device,

                           CYG_IO_SET_CONFIG_SPI_CLOCKRATE,

                           (const void *)&new_clock_rate, &len)) {

        // Error recovery code

    }

If an SPI bus driver does not support the exact clock rate specified

it will normally use the nearest valid one. SPI bus drivers may define

additional keys appropriate for specific hardware. This means that the

valid keys are not known by the generic code, and theoretically it is

possible to use a key that is not valid for the SPI bus to which the

device is attached. It is also possible that the argument used with

one of these keys is invalid. Hence both

cyg_spi_get_config and

cyg_spi_set_config can return error codes. The

return value will be 0 for success, non-zero for failure. The SPI bus

driver's documentation should be consulted for further details.

Both configuration functions will lock the bus, in the same way as

cyg_spi_transfer. Changing the clock rate in the

middle of a transfer or manipulating other parameters would have

unexpected consequences.

    Porting to New Hardware

    Porting

    Adding SPI support to new hardware

Adding SPI support to an eCos port can take two forms. If there is

already an SPI bus driver for the target hardware then both that

driver and this generic SPI package CYGPKG_IO_SPI

should be included in the ecos.db target entry.

Typically the platform HAL will need to supply some platform-specific

information needed by the bus driver. In addition the platform HAL

should provide cyg_spi_device structures for

every device attached to the bus. The exact details of this depend on

the bus driver so its documentation should be consulted for further

details. If there is no suitable SPI bus driver yet then a new driver

package will have to be written.

The generic SPI package CYGPKG_IO_SPI defines a

data structure cyg_spi_device. This contains

the information needed by the generic package, but not the additional

information needed by a bus driver to interact with the device. Each

bus driver will define a larger data structure, for example

cyg_mcf52xx_qspi_device, which contains a

cyg_spi_device as its first field. This is

analogous to C++ base and derived classes, but without any use of

virtual functions. The bus driver package should be consulted for the

details.

During initialization an SPI bus driver may need to know about all the

devices attached to that bus. For example it may need to know which

cpu pins should be configured as chip selects rather than GPIO pins.

To achieve this all device definitions should specify the particular

bus to which they are attached, for example:

struct cyg_mcf52xx_qspi_device hal_spi_atod CYG_SPI_DEVICE_ON_BUS(0) =

{

    .spi_common.spi_bus = &cyg_mcf52xx_qspi_bus,

    …

};

The CYG_SPI_DEVICE_ON_BUS macro adds information

to the structure which causes the linker to group all such structures

in a single table. The bus driver's initialization code can then

iterate over this table.

An SPI bus driver usually involves a new hardware package. This needs

to perform the following:

Define a device structure which contains a

cyg_spi_device as its first element. This

should contain all the information needed by the bus driver to

interact with a device on that bus.

Provide functions for the following operations:

        spi_transaction_begin

        spi_transaction_transfer

        spi_transaction_tick

        spi_transaction_end

        spi_get_config

        spi_set_config

These correspond to the main API functions, but can assume that the

bus is already locked so no other thread will be manipulating the bus

or any of the attached devices. Some of these operations may be no-ops.

Define a bus structure which contains a

cyg_spi_bus as its first element. This should

contain any additional information needed by the bus driver.

Optionally, instantiate the bus structure. The instance should have a

well-known name since it needs to be referenced by the device

structure initializers. For some drivers it may be best to create the

bus inside the driver package. For other drivers it may be better to

leave this to the platform HAL or the application. It depends on how

much platform-specific knowledge is needed to fill in the bus

structure.

Create a HAL table for the devices attached to this bus.

Arrange for the bus to be initialized early on during system

initialization. Typically this will happen via a prioritized static

constructor with priority CYG_INIT_BUS_SPI.

As part of this initialization the bus driver should

invoke the CYG_SPI_BUS_COMMON_INIT macro on its

cyg_spi_bus field.

Provide the appropriate documentation, including details of how the

SPI device structures should be initialized.

There are no standard SPI testcases. It is not possible to write SPI

code without knowing about the devices attached to the bus, and those

are inherently hardware-specific.