Freescale MCFxxxx Coldfire QSPI Bus Driver

Description

Several processors in the Freescale ColdFire family come with an on-chip SPI device, also known as QSPI. This package provides an eCos bus driver for that device. It implements the functionality defined by the generic SPI package CYGPKG_IO_SPI. The driver supports both polled and interrupt-driven transfers. Typical supported transfer rates range from 128KHz to 33MHz, although the exact details depend on the specific ColdFire processor being used and on the processor's clock speed. The hardware does not support DMA so large transfers at high transfer rates will consume much of the available cpu time.

This bus driver package does not instantiate any cyg_spi_bus structures. It is possible for a processor to have more than one SPI bus, so it is better to leave it to the processor HAL to define the bus or buses. Instead the bus driver package just provides functions and utility macros for use by the processor HAL. Similarly the bus driver package does not provide any cyg_spi_device structures. Exactly which devices are attached to the SPI bus is a characteristic of the platform so usually it is the platform HAL which provides the device instances.

Configuration Options

This SPI bus driver package should be loaded automatically when selecting a target containing a ColdFire processor with QSPI hardware, and it should never be necessary to load the package explicitly. If the application does not use any of the SPI functionality then all the SPI support code should be removed at link-time and the application does not suffer any overheads.

The package contains a single configuration option CYGHWR_DEVS_SPI_MCFxxxx_QSPI_MULTIPLE_BUSES. Usually this option should not be manipulated by application developers, instead it is set by the processor HAL. When the option is disabled the driver will optimize for the common case of a single bus.

The only other configuration options provided by this package relate to compiler flags.

Defining Buses

The header file cyg/io/mcfxxxx_qspi.h provides a utility macro CYG_MCFxxxx_QSPI_BUS to allow processor HALs to instantiate a bus. Existing HALs such as the MCF521x's will show how to use this macro.

Defining Devices

For most boards the platform HAL will create cyg_spi_device instances for all attached SPI devices, and will initialize the system so that the SPI-related processor pins are connected appropriately. Some development boards may not have any SPI devices but instead export the relevant signals to expansion connectors. In those cases it will be the responsibility of application code to create the device instances and manipulate the GPIO pins appropriately.

Device instances should take the form of a cyg_mcfxxxx_qspi_device structure, which contains a cyg_spi_device as its first field.

#include <cyg/io/mcfxxxx_qspi.h>
…
cyg_mcfxxxx_qspi_device hal_spi_atod CYG_SPI_DEVICE_ON_BUS(mcfxxxx_qspi) = {
    .qspi_common.spi_bus    = &cyg_mcfxxxx_qspi_bus,
    …
};
    

This defines a variable hal_spi_atod which can be used by other packages or by application code as an argument to the I/O functions provided by the generic SPI package CYGPKG_IO_SPI. A gcc extension, designated initializers, is used to fill in the qspi_common.spi_bus structure field. The structure contains a further seven fields which define exactly how to interact with the SPI device. Most of these fields are simply hardware register values, and the appropriate ColdFire User Manual should be consulted for full details of these registers. The header file cyg/hal/hal_io.h will provide #define's for the various bits, for example HAL_MCFxxxx_QSPIx_QMR_MSTR for the master mode bit of the QMR register.

Consider a simple SPI device on a board with a 64MHz MCF5282 processor. The device uses 8-bit data, default clock polarity and phase, can be driven at up to 10 MHz, does not require any special delays, has an active-high chip select, and is connected to the processor's QSPI CS0 pin. There are no other devices on the bus.

#include <cyg/io/mcfxxxx_qspi.h>
…
cyg_mcfxxxx_qspi_device hal_spi_dev0 CYG_SPI_DEVICE_ON_BUS(mcfxxxx_qspi) = {
    .qspi_common.spi_bus    = &cyg_mcfxxxx_qspi_bus,
    .qspi_qmr               = HAL_MCFxxxx_QSPIx_QMR_MSTR |
                              HAL_MCFxxxx_QSPIx_QMR_BITS_8 |
                              0x04,
    .qspi_qdlyr             = 0,
    .qspi_qwr               = 0,
    .qspi_qcr               = HAL_MCFxxxx_QSPIx_QCRn_QSPI_CS_CS0,
    .qspi_qcr_tick          = 0,
    .qspi_tick_data         = 0xFF,
    .qspi_cs_control        = (void (*)(cyg_mcfxxxx_qspi_device*, int)) 0
};
    

For a more complicated example, consider a board with an MCF5272 processor and an SPI device that involves 12-bit data items, uses inverted clock polarity and phase, can only be driven at the slowest clock rate, does not require any special delays or chip select logic, has an active-low chip select, and is connected to the processor's QSPI CS2 pin:

#include <cyg/io/mcfxxxx_qspi.h>
…
cyg_mcfxxxx_qspi_device hal_spi_dev2 CYG_SPI_DEVICE_ON_BUS(mcfxxxx_qspi) = {
    .qspi_common.spi_bus    = &cyg_mcfxxxx_qspi_bus,
    .qspi_qmr               = HAL_MCFxxxx_QSPIx_QMR_MSTR |
                              HAL_MCFxxxx_QSPIx_QMR_BITS_12 |
                              HAL_MCFxxxx_QSPIx_QMR_CPOL |
                              HAL_MCFxxxx_QSPIx_QMR_CPHA |
                              0xFF,
    .qspi_qdlyr             = 0,
    .qspi_qwr               = HAL_MCFxxxx_QSPIx_QWR_CSIV,
    .qspi_qcr               = HAL_MCFxxxx_QSPIx_QCRn_BITSE |
                              HAL_MCFxxxx_QSPIx_QCRn_QSPI_CS_CS0 |
                              HAL_MCFxxxx_QSPIx_QCRn_QSPI_CS_CS1 |
                              HAL_MCFxxxx_QSPIx_QCRn_QSPI_CS_CS3,
    .qspi_qcr_tick          = HAL_MCFxxxx_QSPIx_QCRn_BITSE |
                              HAL_MCFxxxx_QSPIx_QCRn_QSPI_CS_CS0 |
                              HAL_MCFxxxx_QSPIx_QCRn_QSPI_CS_CS1 |
                              HAL_MCFxxxx_QSPIx_QCRn_QSPI_CS_CS2 |
                              HAL_MCFxxxx_QSPIx_QCRn_QSPI_CS_CS3,
    .qspi_tick_data         = 0xFF,
    .qspi_cs_control        = (void (*)(cyg_mcfxxxx_qspi_device*, int)) 0
};
    

This definition assumes that there are no attached SPI devices with an active-high chip select. If there are such devices then the qspi_qcr and qspi_qcr_tick fields should be modified so that these devices are not activated at the wrong time.

The header file cyg/io/mcfxxxx_qspi.h provides a utility macro CYG_MCFxxxx_QSPI_DEVICE which can be used to instantiate a device. Essentially the macro just expands to a structure definition as above.

Advanced Chip Select Control

The ColdFire QSPI hardware provides support for controlling the chip select signals of up to four SPI devices. In many situations this support is adequate, but there are exceptions:

1. The QSPI chip select outputs may share processor pins with other on-chip ColdFire devices. For example on the mcf5272 the QSPI CS2 signal uses the same pin as the uart1 CTS signal, so if the application needs uart1 and hardware flow-control then that QSPI CS2 pin is no longer available.

2. If the hardware has more than four SPI devices then additional chip selects are needed.

3. With most SPI devices the chip select signal only needs to be asserted while I/O is taking place, but there are exceptions. For example interactions with an MMC card involve a sequence of transfers, and the chip select must remain asserted in between these transfers. Depending on thread priorities and other factors there may be a considerable delay between these transfers and the QSPI hardware does not provide any way of keeping a chip select asserted indefinitely.

The issue of insufficient chip selects can usually be handled by adding extra hardware, for example an external decoder chip possibly complemented by inverters if there is a mixture of active-high and active-low devices. This approach can be supported simply by programming the right values for qspi_qcr and qspi_qcr_tick, but the cost of the extra hardware may be unacceptable. An alternative approach is to use one or more of the processor's GPIO pins to control the extra devices.

The issue of persistent chip selects can be handled in one of two main ways. A GPIO pin can be used to control the chip select, bypassing the QSPI support. Alternatively the QWR CSIV bit can be used in an inverted sense, to activate an SPI device rather than to define the inactive state.

To support these variations an arbitrary chip select control function can be specified for a device. Such a function takes two arguments. The first is a pointer to the SPI device, possibly allowing the function to be shared between multiple devices. The second is one of the following:

To support persistent chip selects via the CSIV signal the bus driver package provides two chip control functions cyg_mcfxxxx_qspi_csiv_cs_control_active_high and cyg_mcfxxxx_qspi_csiv_cs_control_active_low. To use these with say an active-low device:

1. The qspi_qwr field should be set to HAL_MCFxxxx_QSPIx_QWR_CSIV, so the chip select is high when there is no I/O taking place.

2. The qspi_cs_control field should be set to &cyg_mcfxxxx_qspi_csiv_cs_control_active_low. This function will be invoked by the bus driver to assert or drop the signal (initialization is a no-op).

3. The QSPI_CS bits in the qspi_qcr field still have the usual meaning.

4. At the start of a transfer cyg_mcfxxxx_qspi_csiv_cs_control_active_low will clear the QWR CSIV bit. There is no I/O taking place yet so all chip select outputs will switch to low, activating all active-low devices. This is generally harmless since there is no clock signal.

5. When the I/O actually starts the qspi_qcr field will be used, deactivating all devices except the current one.

6. At the end of each individual transfer the chip selects will revert to their inactive state, which because of the CSIV setting means low. Again this will activate all active-low devices, but there is no clock signal so no I/O takes place.

7. For the last transfer of a transaction or for a tick operation cyg_mcfxxxx_qspi_cs_control_active_low will be invoked again with a DROP argument. It will reset the QWR CSIV bit to 1, deactivating all devices.

The overall effect is a persistent chip select with the desired polarity, using just the QSPI hardware facilities rather than a GPIO pin.