Description

Several processors in the Freescale ColdFire family come with one or more on-chip I²C bus devices. This package provides an eCos I²C bus driver. It was originally developed on an MCF5280 but should work with any ColdFire processor that uses a compatible bus device. The driver implements the functionality defined by the generic I²C package CYGPKG_IO_I2C.

	Caution
	The hardware does not support DMA or fifos, so usually a transfer will involve an interrupt for every byte transferred. Since the I2C bus typically runs at 100KHz large transfers will consume much of the available cpu time.

This package does not provide any cyg_i2c_bus structures. The number of I²C buses varies between ColdFire processors. If multiple buses are available then exactly which one(s) are in use on a given hardware platform depends entirely on that platform. The desired I²C bus speed also depends on the platform, and there may be other issues such as how the processor pins should be set up. Hence it is left to other code, usually the processor HAL, to instantiate the bus structure(s). This driver package supplies the necessary functions and utility macros. Similarly this package does not provide any cyg_i2c_device structures. Which I²C devices are hooked up to which I²C bus is entirely a characteristic of the hardware platform, so it is up to the platform HAL to instantiate the necessary structures.

The driver will operate in interrupt-driven mode if interrupts are enabled when a transfer is initiated. Otherwise it will operate in polled mode. This allows the driver to be used in a variety of configurations including inside RedBoot.

Configuration Options

The I²C bus driver package should be loaded automatically when selecting a target containing a suitable ColdFire processor, and it should never be necessary to load the package explicitly. If the application does not use any of the I²C functionality, directly or indirectly, then all the I²C code should be removed at link-time and the application does not suffer any overheads.

By default the driver assumes a single I²C bus and optimizes for that case. For example options like the ISR vector and priority are handled by compile-time #define's in the platform HAL's exported header files rather than by per-bus structure fields. This helps to reduce both code and data overheads. If the driver should support multiple I²C buses then CYGHWR_DEVS_I2C_MCFxxxx_MULTIPLE_BUSES should be enabled. Typically this will be done by the processor HAL using a CDL requires property. If bus instantiation happens outside the processor HAL and hence the HAL's header files do not provide the appropriate definitions, then this configuration option should also be defined.

The only other configuration options in this package provide control over the compiler flags used to build the driver code.

Defining the Bus and Devices

For most hardware targets the processor HAL will instantiate the cyg_i2c_bus and the platform HAL will instantiate the cyg_i2c_device structures. Between them they will also initialize the hardware so that the I²C-related pins are connected appropriately. Some development boards have no I²C devices, but the I²C bus signals are accessible via an expansion connector and I²C devices can be put on a daughter board. In such cases it may be necessary for the application to instantiate the device structures.

To facilitate bus instantiation the header file cyg/io/i2c_mcfxxxx.h provides a utility macro CYG_MCFxxxx_I2C_BUS. This takes six parameters:

For the common case where only a single I²C bus should be supported (CYGHWR_DEVS_I2C_MCFxxxx_MULTIPLE_BUSES is disabled), the last four parameters should be provided by preprocessor #define's, typically in cyg/hal/plf_io.h which gets #include'd automatically via cyg/hal/hal_io.h. This header can also define the HAL_I2C_EXPORTED_DEVICES macro as per the generic I²C package:

#include <pkgconf/hal_m68k_dnp5280.h>
…
#ifdef CYGHWR_HAL_M68K_DNP5280_I2C
#define HAL_MCFxxxx_I2C_SINGLETON_BASE   (HAL_MCFxxxx_MBAR+HAL_MCF5282_I2C0_BASE)
#define HAL_MCFxxxx_I2C_SINGLETON_ISRVEC CYGNUM_HAL_ISR_I2C_IIF
#define HAL_MCFxxxx_I2C_SINGLETON_ISRPRI CYGNUM_HAL_M68K_DNP5280_I2C_ISRPRI
#define HAL_MCFxxxx_I2C_SINGLETON_FDR    CYGNUM_HAL_M68K_DNP5280_I2C_FDR

#define HAL_I2C_EXPORTED_DEVICES \
    extern cyg_i2c_bus hal_dnp5280_i2c_bus;
#endif

On this particular platform the I²C bus is only accessible on an expansion connector so the support is conditional on a configuration option CYGHWR_HAL_M68K_DNP5280_I2C. The interrupt priority and I2FDR values are also controlled by configuration options. On other platforms the I²C support may not be conditional and the priority and/or FDR values may be hard-wired.

The I²C bus instantiation should happen in an ordinary C or C++ file, typically in the platform HAL. The corresponding object file should go into libtarget.a and the file should only contain I²C-related code to get the maximum benefit of linker garbage collection.

#include <cyg/infra/cyg_type.h>
#include <cyg/hal/hal_io.h>
#include <cyg/io/i2c.h>
#include <cyg/io/i2c_mcfxxxx.h>

CYG_MCFxxxx_I2C_BUS(hal_dnp5280_i2c_bus,
                    &cyg_mcfxxxx_i2c_init,
                    HAL_MCFxxxx_I2C_SINGLETON_BASE,
                    HAL_MCFxxxx_I2C_SINGLETON_ISRVEC,
                    HAL_MCFxxxx_I2C_SINGLETON_ISRPRI,
                    HAL_MCFxxxx_I2C_SINGLETON_FDR);

Obviously if CYGHWR_DEVS_I2C_MCFxxxx_MULTIPLE_BUSES is enabled then the singleton macros may not be defined and the appropriate numbers should be used directly. This example assumes no special initialization is needed. If there are special initialization requirements then a custom function can be used instead of cyg_mcfxxxx_i2c_init, and the custom function should chain to the latter.

I²C device structures can be instantiated in the usual way, for example:

CYG_I2C_DEVICE(cyg_i2c_wallclock_ds1307,
               &hal_dnp5280_i2c_bus,
               0x68,
               0x00,
               CYG_I2C_DEFAULT_DELAY);