Porting to New Hardware

Description

Adding I2C support to an eCos port involves a number of steps. The generic I2C package CYGPKG_IO_I2C should be included in the appropriate ecos.db target entry or entries. Next cyg_i2c_device structures should be provided for every device on the bus. Usually this is the responsibility of the platform HAL. In the case of development boards where the I2C SDA and SCL lines are accessible via an expansion connector, more devices may have been added and it will be the application's responsibility to provide the structures. Finally there is a need for one or more cyg_i2c_bus structures. Amongst other things these structures provide functions for actually driving the bus. If the processor has dedicated I2C hardware then this structure will usually be provided by a device driver package. If the bus is implemented by bit-banging then the bus structure will usually be provided by the platform HAL.

Adding a Device

The eCos I2C API works in terms of cyg_i2c_device structures, and these provide the information needed to access the hardware. A cyg_i2c_device structure contains the following fields:

The normal way to instantiate a cyg_i2c_device structure uses the CYG_I2C_DEVICE macro, also provided by cyg/io/i2c.h:

#include <cyg/io/i2c.h>

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

CYG_I2C_DEVICE(hal_alaia_i2c_fs6377,
               &hal_alaia_i2c_bus,
               0x58,
               0x00,
               CYG_I2C_DEFAULT_DELAY);
    

The arguments to the macro are the variable name, an I2C bus pointer, the device address, the flags field, and the delay field. The above code fragment defines two I2C device variables, cyg_i2c_wallclock_ds1307 and hal_alaia_i2c_fs6377, which can be used for the first argument to the cyg_i2c_ functions. Both devices are on the same bus. The device addresses are 0x68 and 0x58 respectively, and the devices do not have any special requirements.

When the platform HAL provides these structures it should also export them for use by the application and other packages. Usually this involves an entry in cyg/hal/plf_io.h, which gets included automatically via one of the main exported HAL header files cyg/hal/hal_io.h. Unfortunately exporting the structures directly can be problematical because of circular dependencies between the I2C header and the HAL headers. Instead the platform HAL should define a macro HAL_I2C_EXPORTED_DEVICES:

# define HAL_I2C_EXPORTED_DEVICES                                   \
    extern cyg_i2c_bus                  hal_alaia_i2c_bus;          \
    extern cyg_i2c_device               cyg_i2c_wallclock_ds1307;   \
    extern cyg_i2c_device               hal_alaia_i2c_fs6377;
    

This macro gets expanded automatically by cyg/io/i2c.h once the data structures themselves have been defined, so application code can just include that header and all the buses and devices will be properly exported and usable.

There is no single convention for naming the I2C devices. If the device will be used by some other package then typically that specifies the name that should be used. For example the DS1307 wallclock driver expects the I2C device to be called cyg_i2c_wallclock_ds1307, so failing to observe that convention will lead to compile-time and link-time errors. If the device will not be used by any other package then it is up to the platform HAL to select the name, and as long as reasonable care is taken to avoid name space pollution the exact name does not matter.

Bit-banged Bus

Some processors come with dedicated I2C hardware. On other hardware the I2C bus involves simply connecting some GPIO pins to the SCL and SDA lines and then using software to implement the I2C protocol. This is usually referred to as bit-banging the bus. The generic I2C package CYGPKG_IO_I2C provides the main code for a bit-banged implementation, requiring one platform-specific function that does the actual GPIO pin manipulation. This function is usually hardware-specific because different boards will use different pins for the I2C bus, so typically it is left to the platform HAL to provide this function and instantiate the I2C bus object. There is no point in creating a separate package for this because the code cannot be re-used for other platforms.

Instantiating a bit-banged I2C bus requires the following:

#include <cyg/io/i2c.h>

static cyg_bool
hal_alaia_i2c_bitbang(cyg_i2c_bus* bus, cyg_i2c_bitbang_op op)
{
    cyg_bool result    = 0;
    switch(op) {
        …
    }
    return result;
}

CYG_I2C_BITBANG_BUS(hal_alaia_i2c_bus, &hal_alaia_i2c_bitbang);
    

This gives a structure hal_alaia_i2c_bus which can be used when defining the cyg_i2c_device structures. The second argument specifies the function which will do the actual bit-banging. It takes two arguments. The first identifies the bus, which can be useful if the hardware has multiple I2C buses. The second specifies the bit-bang operation that should be performed. To understand these operations consider how I2C devices should be wired up according to the specification:

Master and slave devices are interfaced to the bus in exactly the same way. The default state of the bus is to have both lines high via the pull-up resistors. Any device on the bus can lower either line, when allowed to do so by the protocol. Usually the SDA line only changes while SCL is low, but the start and stop conditions involve SDA changing while SCL is high. All devices have the ability to both read and write both lines. In reality not all bit-banged hardware works quite like this. Instead just two GPIO pins are used, and these are switched between input and output mode as required.

The bitbang function should support the following operations:

The bitbang function returns a boolean. For most operations this return value is ignored. For CYG_I2C_BITBANG_SDA_READ it should be the current level of the SDA line.

Depending on the hardware some care may have to be taken when manipulating the GPIO pins. Although the I2C subsystem performs the required locking at the bus level, the device registers controlling the GPIO pins may get used by other subsystems or by the application. It is the responsibility of the bitbang function to perform appropriate locking, whether via a mutex or by briefly disabling interrupts around the register accesses.

Full Bus Driver

If the processor has dedicated I2C hardware then usually this will involve a separate device driver package in the devs/i2c hierarchy of the eCos component repository. That package should also be included in the appropriate ecos.db target entry or entries. The device driver may exist already, or it may have to be written from scratch.

A new I2C driver basically involves creating an cyg_i2c_bus structure. The device driver should supply the following fields:

To assist with instantiating a cyg_i2c_bus object the header file cyg/io/i2c.h provides a macro. Typical usage would be:

struct xyzzy_data {
    …
} xyzzy_object;

static void
xyzzy_i2c_init(struct cyg_i2c_bus* bus)
{
    …
}

static cyg_uint32
xyzzy_i2c_tx(const cyg_i2c_device* dev,
             cyg_bool send_start,
             const cyg_uint8* tx_data, cyg_uint32 count,
             cyg_bool send_stop)
{
    …
}

static cyg_uint32
xyzzy_i2c_rx(const cyg_i2c_device* dev,
             cyg_bool send_start,
             cyg_uint8* rx_data, cyg_uint32 count,
             cyg_bool send_nack, cyg_bool send_stop)
{
    …
}

static void
xyzzy_i2c_stop(const cyg_i2c_device* dev)
{
    …
}

CYG_I2C_BUS(cyg_i2c_xyzzy_bus,
            &xyzzy_i2c_init,
            &xyzzy_i2c_tx,
            &xyzzy_i2c_rx,
            &xyzzy_i2c_stop,
            (void*) &xyzzy_object);
    

The generic I2C code contains these functions for a bit-banged I2C bus device. It can be used as a starting point for new drivers. Note that the bit-bang code uses the i2c_extra field to hold the hardware-specific bitbang function rather than a pointer to some data structure.