Motorola MCF52xx Coldfire I²C Bus Driver

Description

Several processors in the Motorola 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.

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 platform 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 again 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_MCF52xx_MULTIPLE_BUSES should be enabled. Typically this will be done by the platform HAL using a CDL requires property. If bus instantiation happens outside the platform 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 platform HAL will instantiate the cyg_i2c_bus and cyg_i2c_device structures, and it 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 both the bus and all the device structures. Alternatively the platform HAL may provide a configuration option to enable just the bus, with the devices still left to application code.

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

1. The name of the bus, for example hal_dnp5280_i2c_bus. This name will be used when instantiating the I²C devices.

2. An initialization function. If no platform-specific initialization is needed then this can be the cyg_mcf52xx_i2c_init function exported by this driver. Otherwise it can be a platform-specific function which, for example, sets up the relevant pins appropriately and then chains into cyg_mcf52xx_i2c_init.

3. The base address of the I²C bus. For example on an MCF5282 with the IPSBAR set to its usual value of 0x40000000, the I²C bus is at location 0x40000300.

4. The interrupt vector, for example CYGNUM_HAL_ISR_I2C_IIF on an MCF5282.

5. The interrupt priority. Typically this will be a configurable option within the platform HAL.

6. A value for the I²C bus's I2FDR register. That register controls the bus speed. Typical bus speeds are 100KHz and 400KHz, depending on the capabilities of the attached devices. There is no simple relationship between the system clock speed, the desired bus speed, and the FDR register. Although the driver could determine the FDR setting using a lookup table and appropriate code, it is better to determine the correct value once during the porting process and avoid unnecessary run-time overheads.

For the common case where only a single I²C bus should be supported (CYGHWR_DEVS_I2C_MCF52xx_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_MCF52xx_I2C_SINGLETON_BASE   (HAL_MCF52xx_MBAR+HAL_MCF5282_I2C0_BASE)
#define HAL_MCF52xx_I2C_SINGLETON_ISRVEC CYGNUM_HAL_ISR_I2C_IIF
#define HAL_MCF52xx_I2C_SINGLETON_ISRPRI CYGNUM_HAL_M68K_DNP5280_I2C_ISRPRI
#define HAL_MCF52xx_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_mcf52xx.h>

static void
dnp5280_i2c_init(struct cyg_i2c_bus* bus)
{
    cyg_uint16   paspar;
    // Reset GPIO pins PAS0/1 to their alternative SCL/SDA settings
    HAL_READ_UINT16(HAL_MCF5282_IPSBAR + HAL_MCF5282_GPIO_PASPAR, paspar);
    paspar &= ~(HAL_MCF5282_GPIO_PASPAR_A0_MASK | HAL_MCF5282_GPIO_PASPAR_A1_MASK);
    paspar |= (HAL_MCF5282_GPIO_PASPAR_A0_SCL | HAL_MCF5282_GPIO_PASPAR_A1_SDA);
    HAL_WRITE_UINT16(HAL_MCF5282_IPSBAR + HAL_MCF5282_GPIO_PASPAR, paspar);

    // And leave the driver to take care of the rest.
    cyg_mcf52xx_i2c_init(bus);
}

CYG_MCF52xx_I2C_BUS(hal_dnp5280_i2c_bus,
                    &dnp5280_i2c_init,
                    HAL_MCF52xx_I2C_SINGLETON_BASE,
                    HAL_MCF52xx_I2C_SINGLETON_ISRVEC,
                    HAL_MCF52xx_I2C_SINGLETON_ISRPRI,
                    HAL_MCF52xx_I2C_SINGLETON_FDR);

    

Obviously if CYGHWR_DEVS_I2C_MCF52xx_MULTIPLE_BUSES is enabled then the singleton macros may not be defined and the appropriate numbers should be used directly. This example uses a custom initialization function which sets up the relevant pins and then chains into the I²C drivers' cyg_mcf52xx_i2c_init function. If the platform HAL has already set up the pins correctly then cyg_mcf52xx_i2c_init could be used directly in the bus instantiation, saving a small amount of code for the custom initialization function.

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);