<!-- DOCTYPE refentry  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     mcf52xx_i2c.sgml                                            -->
<!--                                                                 -->
<!--     Documentation for the mcf52xx I2C bus driver                -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                   -->
<!-- =============================================================== -->
<!-- Copyright (C) 2006 Free Software Foundation, Inc.               -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!-- ####ECOSDOCCOPYRIGHTEND####                                     -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- Author(s):   bartv                                              -->
<!-- Contact(s):  bartv                                              -->
<!-- Date:        2006/02/19                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<part id="devs-i2c-m68k-mcf52xx-part"><title>Motorola MCF52xx ColdFire I<superscript>2</superscript>C Bus Driver</title>

<refentry id="devs-i2c-m68k-mcf52xx">
  <refmeta>
    <refentrytitle>Motorola MCF52xx Coldfire I<superscript>2</superscript>C Bus  Driver</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><varname>CYGPKG_DEVS_I2C_MCF52xx</varname></refname>
    <refpurpose>eCos Support for the Motorola Coldfire I<superscript>2</superscript>C Bus</refpurpose>
  </refnamediv>

  <refsect1 id="devs-i2c-m68k-mcf52xx-description"><title>Description</title>
    <para>
Several processors in the Motorola ColdFire family come with one or
more on-chip I<superscript>2</superscript>C bus devices. This package
provides an eCos I<superscript>2</superscript>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<superscript>2</superscript>C
package <varname>CYGPKG_IO_I2C</varname>.
    </para>
    <caution><para>
The hardware does not support DMA or fifos, so usually a transfer will
involve an interrupt for every byte transferred. Since the
I<superscript>2</superscript>C bus typically runs at 100KHz large
transfers will consume much of the available cpu time.
    </para></caution>
    <para>
This package does not provide any <structname>cyg_i2c_bus</structname>
structures. The number of I<superscript>2</superscript>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<superscript>2</superscript>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
<structname>cyg_i2c_device</structname> structures. Which
I<superscript>2</superscript>C devices are hooked up to which
I<superscript>2</superscript>C bus is entirely a characteristic of the
hardware platform, so again it is up to the platform HAL to
instantiate the necessary structures.
    </para>
    <para>
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.
    </para>
  </refsect1>

  <refsect1 id="devs-i2c-m68k-mcf52xx-config"><title>Configuration Options</title>
    <para>
The I<superscript>2</superscript>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<superscript>2</superscript>C functionality, directly or indirectly,
then all the I<superscript>2</superscript>C code should be removed at
link-time and the application does not suffer any overheads.
    </para>
    <para>
By default the driver assumes a single I<superscript>2</superscript>C
bus and optimizes for that case. For example options like the ISR
vector and priority are handled by compile-time
<literal>#define</literal>'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<superscript>2</superscript>C buses then
<varname>CYGHWR_DEVS_I2C_MCF52xx_MULTIPLE_BUSES</varname> should be
enabled. Typically this will be done by the platform HAL using a CDL
<property>requires</property> 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.
    </para>
    <para>
The only other configuration options in this package provide control
over the compiler flags used to build the driver code.
    </para>
  </refsect1>

  <refsect1 id="devs-i2c-m68k-mcf52xx-bus-devices"><title>Defining the Bus and Devices</title>
    <para>
For most hardware targets the platform HAL will instantiate the
<structname>cyg_i2c_bus</structname> and
<structname>cyg_i2c_device</structname> structures, and it will also
initialize the hardware so that the
I<superscript>2</superscript>C-related pins are connected
appropriately. Some development boards have no
I<superscript>2</superscript>C devices, but the
I<superscript>2</superscript>C bus signals are accessible via an
expansion connector and I<superscript>2</superscript>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.
    </para>
    <para>
To facilitate bus instantiation the header file <filename
class="headerfile">cyg/io/i2c_mcf52xx.h</filename> provides a utility
macro <function>CYG_MCF52xx_I2C_BUS</function>. This takes six
parameters:
    </para>
    <orderedlist>
      <listitem><para>
The name of the bus, for example
<varname>hal_dnp5280_i2c_bus</varname>. This name will be used when
instantiating the I<superscript>2</superscript>C devices.
      </para></listitem>
      <listitem><para>
An initialization function. If no platform-specific initialization is
needed then this can be the <function>cyg_mcf52xx_i2c_init</function>
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
<function>cyg_mcf52xx_i2c_init</function>.
      </para></listitem>
      <listitem><para>
The base address of the I<superscript>2</superscript>C bus. For
example on an MCF5282 with the IPSBAR set to its usual value of
0x40000000, the I<superscript>2</superscript>C bus is at location
0x40000300.
      </para></listitem>
      <listitem><para>
The interrupt vector, for example
<varname>CYGNUM_HAL_ISR_I2C_IIF</varname> on an MCF5282.
      </para></listitem>
      <listitem><para>
The interrupt priority. Typically this will be a configurable option
within the platform HAL.
      </para></listitem>
      <listitem><para>
A value for the I<superscript>2</superscript>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.
      </para></listitem>
    </orderedlist>
    <para>
For the common case where only a single I<superscript>2</superscript>C
bus should be supported
(<varname>CYGHWR_DEVS_I2C_MCF52xx_MULTIPLE_BUSES</varname> is
disabled), the last four parameters should be provided by preprocessor
<literal>#define</literal>'s, typically in <filename
class="headerfile">cyg/hal/plf_io.h</filename> which gets
<literal>#include</literal>'d automatically via
<filename>cyg/hal/hal_io.h</filename>. This header can also define the
<varname>HAL_I2C_EXPORTED_DEVICES</varname> macro as per the generic
I<superscript>2</superscript>C package:
    </para>
    <programlisting width=72>
#include &lt;pkgconf/hal_m68k_dnp5280.h&gt;
&hellip;
#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
    </programlisting>
    <para>
On this particular platform the I<superscript>2</superscript>C bus is
only accessible on an expansion connector so the support is
conditional on a configuration option
<varname>CYGHWR_HAL_M68K_DNP5280_I2C</varname>. The interrupt priority
and I2FDR values are also controlled by configuration options. On
other platforms the I<superscript>2</superscript>C support may not be
conditional and the priority and/or FDR values may be hard-wired.
    </para>
    <para>
The I<superscript>2</superscript>C bus instantiation should happen in
an ordinary C or C++ file, typically in the platform HAL. The
corresponding object file should go into
<filename>libtarget.a</filename> and the file should only contain
I<superscript>2</superscript>C-related code to get the maximum benefit
of linker garbage collection.
    </para>
    <programlisting width=72>
#include &lt;cyg/infra/cyg_type.h&gt;
#include &lt;cyg/hal/hal_io.h&gt;
#include &lt;cyg/io/i2c.h&gt;
#include &lt;cyg/io/i2c_mcf52xx.h&gt;

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 &amp;= ~(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,
                    &amp;dnp5280_i2c_init,
                    HAL_MCF52xx_I2C_SINGLETON_BASE,
                    HAL_MCF52xx_I2C_SINGLETON_ISRVEC,
                    HAL_MCF52xx_I2C_SINGLETON_ISRPRI,
                    HAL_MCF52xx_I2C_SINGLETON_FDR);

    </programlisting>
    <para>
Obviously if <varname>CYGHWR_DEVS_I2C_MCF52xx_MULTIPLE_BUSES</varname>
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<superscript>2</superscript>C drivers'
<function>cyg_mcf52xx_i2c_init</function> function. If the platform
HAL has already set up the pins correctly then
<function>cyg_mcf52xx_i2c_init</function> could be used directly in
the bus instantiation, saving a small amount of code for the custom
initialization function.
    </para>
    <para>
I<superscript>2</superscript>C device structures can be instantiated
in the usual way, for example:
    </para>
    <programlisting width=72>
CYG_I2C_DEVICE(cyg_i2c_wallclock_ds1307,
               &amp;hal_dnp5280_i2c_bus,
               0x68,
               0x00,
               CYG_I2C_DEFAULT_DELAY);
    </programlisting>
  </refsect1>

</refentry>  
</part>