Subversion Repositories openrisc

    Motorola MCF52xx Coldfire I2C Bus  Driver

    CYGPKG_DEVS_I2C_MCF52xx

    eCos Support for the Motorola Coldfire I2C Bus

Several processors in the Motorola ColdFire family come with one or

more on-chip I2C bus devices. This package

provides an eCos I2C 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 I2C

package CYGPKG_IO_I2C.

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 I2C 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 I2C

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

I2C devices are hooked up to which

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

The I2C 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

I2C functionality, directly or indirectly,

then all the I2C code should be removed at

link-time and the application does not suffer any overheads.

By default the driver assumes a single I2C

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

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

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

I2C-related pins are connected

appropriately. Some development boards have no

I2C devices, but the

I2C bus signals are accessible via an

expansion connector and I2C 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 

class="headerfile">cyg/io/i2c_mcf52xx.h provides a utility

macro CYG_MCF52xx_I2C_BUS. This takes six

parameters:

The name of the bus, for example

hal_dnp5280_i2c_bus. This name will be used when

instantiating the I2C devices.

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.

The base address of the I2C bus. For

example on an MCF5282 with the IPSBAR set to its usual value of

0x40000000, the I2C bus is at location

0x40000300.

The interrupt vector, for example

CYGNUM_HAL_ISR_I2C_IIF on an MCF5282.

The interrupt priority. Typically this will be a configurable option

within the platform HAL.

A value for the I2C 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 I2C

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 

class="headerfile">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

I2C 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 I2C 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 I2C support may not be

conditional and the priority and/or FDR values may be hard-wired.

The I2C 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

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

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