packages/devs/i2c/m68k/mcf52xx/v2_0/doc/mcf52xx_i2c.sgml

   1 <!-- DOCTYPE refentry  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
   2
   3 <!-- {{{ Banner                         -->
   4
   5 <!-- =============================================================== -->
   6 <!--                                                                 -->
   7 <!--     mcf52xx_i2c.sgml                                            -->
   8 <!--                                                                 -->
   9 <!--     Documentation for the mcf52xx I2C bus driver                -->
  10 <!--                                                                 -->
  11 <!-- =============================================================== -->
  12 <!-- ####COPYRIGHTBEGIN####                                          -->
  13 <!--                                                                 -->
  14 <!-- =============================================================== -->
  15 <!-- Copyright (C) 2006 eCosCentric Limited                          -->
  16 <!-- This material may be distributed only subject to the terms      -->
  17 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  18 <!-- or later (the latest version is presently available at          -->
  19 <!-- http://www.opencontent.org/openpub/)                            -->
  20 <!-- Distribution of the work or derivative of the work in any       -->
  21 <!-- standard (paper) book form is prohibited unless prior           -->
  22 <!-- permission obtained from the copyright holder                   -->
  23 <!-- =============================================================== -->
  24 <!--                                                                 -->
  25 <!-- ####COPYRIGHTEND####                                            -->
  26 <!-- =============================================================== -->
  27 <!-- #####DESCRIPTIONBEGIN####                                       -->
  28 <!--                                                                 -->
  29 <!-- Author(s):   bartv                                              -->
  30 <!-- Contact(s):  bartv                                              -->
  31 <!-- Date:        2006/02/19                                         -->
  32 <!-- Version:     0.01                                               -->
  33 <!--                                                                 -->
  34 <!-- ####DESCRIPTIONEND####                                          -->
  35 <!-- =============================================================== -->
  36
  37 <!-- }}} -->
  38
  39 <part id="devs-i2c-m68k-mcf52xx-part"><title>Motorola MCF52xx ColdFire I<superscript>2</superscript>C Bus Driver</title>
  40
  41 <refentry id="devs-i2c-m68k-mcf52xx">
  42   <refmeta>
  43     <refentrytitle>Motorola MCF52xx Coldfire I<superscript>2</superscript>C Bus  Driver</refentrytitle>
  44   </refmeta>
  45   <refnamediv>
  46     <refname><varname>CYGPKG_DEVS_I2C_MCF52xx</varname></refname>
  47     <refpurpose>eCos Support for the Motorola Coldfire I<superscript>2</superscript>C Bus</refpurpose>
  48   </refnamediv>
  49
  50   <refsect1 id="devs-i2c-m68k-mcf52xx-description"><title>Description</title>
  51     <para>
  52 Several processors in the Motorola ColdFire family come with one or
  53 more on-chip I<superscript>2</superscript>C bus devices. This package
  54 provides an eCos I<superscript>2</superscript>C bus driver. It was
  55 originally developed on an MCF5280 but should work with any ColdFire
  56 processor that uses a compatible bus device. The driver implements the
  57 functionality defined by the generic I<superscript>2</superscript>C
  58 package <varname>CYGPKG_IO_I2C</varname>.
  59     </para>
  60     <caution><para>
  61 The hardware does not support DMA or fifos, so usually a transfer will
  62 involve an interrupt for every byte transferred. Since the
  63 I<superscript>2</superscript>C bus typically runs at 100KHz large
  64 transfers will consume much of the available cpu time.
  65     </para></caution>
  66     <para>
  67 This package does not provide any <structname>cyg_i2c_bus</structname>
  68 structures. The number of I<superscript>2</superscript>C buses varies
  69 between ColdFire processors. If multiple buses are available then
  70 exactly which one(s) are in use on a given hardware platform depends
  71 entirely on that platform. The desired I<superscript>2</superscript>C
  72 bus speed also depends on the platform, and there may be other issues
  73 such as how the processor pins should be set up. Hence it is left to
  74 other code, usually the platform HAL, to instantiate the bus
  75 structure(s). This driver package supplies the necessary functions and
  76 utility macros. Similarly this package does not provide any
  77 <structname>cyg_i2c_device</structname> structures. Which
  78 I<superscript>2</superscript>C devices are hooked up to which
  79 I<superscript>2</superscript>C bus is entirely a characteristic of the
  80 hardware platform, so again it is up to the platform HAL to
  81 instantiate the necessary structures.
  82     </para>
  83     <para>
  84 The driver will operate in interrupt-driven mode if interrupts are
  85 enabled when a transfer is initiated. Otherwise it will operate in
  86 polled mode. This allows the driver to be used in a variety of
  87 configurations including inside RedBoot.
  88     </para>
  89   </refsect1>
  90
  91   <refsect1 id="devs-i2c-m68k-mcf52xx-config"><title>Configuration Options</title>
  92     <para>
  93 The I<superscript>2</superscript>C bus driver package should be loaded
  94 automatically when selecting a target containing a suitable ColdFire
  95 processor, and it should never be necessary to load the package
  96 explicitly. If the application does not use any of the
  97 I<superscript>2</superscript>C functionality, directly or indirectly,
  98 then all the I<superscript>2</superscript>C code should be removed at
  99 link-time and the application does not suffer any overheads.
 100     </para>
 101     <para>
 102 By default the driver assumes a single I<superscript>2</superscript>C
 103 bus and optimizes for that case. For example options like the ISR
 104 vector and priority are handled by compile-time
 105 <literal>#define</literal>'s in the platform HAL's exported header
 106 files rather than by per-bus structure fields. This helps to reduce
 107 both code and data overheads. If the driver should support multiple
 108 I<superscript>2</superscript>C buses then
 109 <varname>CYGHWR_DEVS_I2C_MCF52xx_MULTIPLE_BUSES</varname> should be
 110 enabled. Typically this will be done by the platform HAL using a CDL
 111 <property>requires</property> property. If bus instantiation happens
 112 outside the platform HAL and hence the HAL's header files do not
 113 provide the appropriate definitions, then this configuration option
 114 should also be defined.
 115     </para>
 116     <para>
 117 The only other configuration options in this package provide control
 118 over the compiler flags used to build the driver code.
 119     </para>
 120   </refsect1>
 121
 122   <refsect1 id="devs-i2c-m68k-mcf52xx-bus-devices"><title>Defining the Bus and Devices</title>
 123     <para>
 124 For most hardware targets the platform HAL will instantiate the
 125 <structname>cyg_i2c_bus</structname> and
 126 <structname>cyg_i2c_device</structname> structures, and it will also
 127 initialize the hardware so that the
 128 I<superscript>2</superscript>C-related pins are connected
 129 appropriately. Some development boards have no
 130 I<superscript>2</superscript>C devices, but the
 131 I<superscript>2</superscript>C bus signals are accessible via an
 132 expansion connector and I<superscript>2</superscript>C devices can be
 133 put on a daughter board. In such cases it may be necessary for the
 134 application to instantiate both the bus and all the device structures.
 135 Alternatively the platform HAL may provide a configuration option to
 136 enable just the bus, with the devices still left to application code.
 137     </para>
 138     <para>
 139 To facilitate bus instantiation the header file <filename
 140 class="headerfile">cyg/io/i2c_mcf52xx.h</filename> provides a utility
 141 macro <function>CYG_MCF52xx_I2C_BUS</function>. This takes six
 142 parameters:
 143     </para>
 144     <orderedlist>
 145       <listitem><para>
 146 The name of the bus, for example
 147 <varname>hal_dnp5280_i2c_bus</varname>. This name will be used when
 148 instantiating the I<superscript>2</superscript>C devices.
 149       </para></listitem>
 150       <listitem><para>
 151 An initialization function. If no platform-specific initialization is
 152 needed then this can be the <function>cyg_mcf52xx_i2c_init</function>
 153 function exported by this driver. Otherwise it can be a
 154 platform-specific function which, for example, sets up the relevant
 155 pins appropriately and then chains into
 156 <function>cyg_mcf52xx_i2c_init</function>.
 157       </para></listitem>
 158       <listitem><para>
 159 The base address of the I<superscript>2</superscript>C bus. For
 160 example on an MCF5282 with the IPSBAR set to its usual value of
 161 0x40000000, the I<superscript>2</superscript>C bus is at location
 162 0x40000300.
 163       </para></listitem>
 164       <listitem><para>
 165 The interrupt vector, for example
 166 <varname>CYGNUM_HAL_ISR_I2C_IIF</varname> on an MCF5282.
 167       </para></listitem>
 168       <listitem><para>
 169 The interrupt priority. Typically this will be a configurable option
 170 within the platform HAL.
 171       </para></listitem>
 172       <listitem><para>
 173 A value for the I<superscript>2</superscript>C bus's I2FDR register.
 174 That register controls the bus speed. Typical bus speeds are 100KHz
 175 and 400KHz, depending on the capabilities of the attached devices.
 176 There is no simple relationship between the system clock speed, the
 177 desired bus speed, and the FDR register. Although the driver could
 178 determine the FDR setting using a lookup table and appropriate code,
 179 it is better to determine the correct value once during the porting
 180 process and avoid unnecessary run-time overheads.
 181       </para></listitem>
 182     </orderedlist>
 183     <para>
 184 For the common case where only a single I<superscript>2</superscript>C
 185 bus should be supported
 186 (<varname>CYGHWR_DEVS_I2C_MCF52xx_MULTIPLE_BUSES</varname> is
 187 disabled), the last four parameters should be provided by preprocessor
 188 <literal>#define</literal>'s, typically in <filename
 189 class="headerfile">cyg/hal/plf_io.h</filename> which gets
 190 <literal>#include</literal>'d automatically via
 191 <filename>cyg/hal/hal_io.h</filename>. This header can also define the
 192 <varname>HAL_I2C_EXPORTED_DEVICES</varname> macro as per the generic
 193 I<superscript>2</superscript>C package:
 194     </para>
 195     <programlisting width=72>
 196 #include &lt;pkgconf/hal_m68k_dnp5280.h&gt;
 197 &hellip;
 198 #ifdef CYGHWR_HAL_M68K_DNP5280_I2C
 199 #define HAL_MCF52xx_I2C_SINGLETON_BASE   (HAL_MCF52xx_MBAR+HAL_MCF5282_I2C0_BASE)
 200 #define HAL_MCF52xx_I2C_SINGLETON_ISRVEC CYGNUM_HAL_ISR_I2C_IIF
 201 #define HAL_MCF52xx_I2C_SINGLETON_ISRPRI CYGNUM_HAL_M68K_DNP5280_I2C_ISRPRI
 202 #define HAL_MCF52xx_I2C_SINGLETON_FDR    CYGNUM_HAL_M68K_DNP5280_I2C_FDR
 203
 204 #define HAL_I2C_EXPORTED_DEVICES \
 205     extern cyg_i2c_bus hal_dnp5280_i2c_bus;
 206 #endif
 207     </programlisting>
 208     <para>
 209 On this particular platform the I<superscript>2</superscript>C bus is
 210 only accessible on an expansion connector so the support is
 211 conditional on a configuration option
 212 <varname>CYGHWR_HAL_M68K_DNP5280_I2C</varname>. The interrupt priority
 213 and I2FDR values are also controlled by configuration options. On
 214 other platforms the I<superscript>2</superscript>C support may not be
 215 conditional and the priority and/or FDR values may be hard-wired.
 216     </para>
 217     <para>
 218 The I<superscript>2</superscript>C bus instantiation should happen in
 219 an ordinary C or C++ file, typically in the platform HAL. The
 220 corresponding object file should go into
 221 <filename>libtarget.a</filename> and the file should only contain
 222 I<superscript>2</superscript>C-related code to get the maximum benefit
 223 of linker garbage collection.
 224     </para>
 225     <programlisting width=72>
 226 #include &lt;cyg/infra/cyg_type.h&gt;
 227 #include &lt;cyg/hal/hal_io.h&gt;
 228 #include &lt;cyg/io/i2c.h&gt;
 229 #include &lt;cyg/io/i2c_mcf52xx.h&gt;
 230
 231 static void
 232 dnp5280_i2c_init(struct cyg_i2c_bus* bus)
 233 {
 234     cyg_uint16   paspar;
 235     // Reset GPIO pins PAS0/1 to their alternative SCL/SDA settings
 236     HAL_READ_UINT16(HAL_MCF5282_IPSBAR + HAL_MCF5282_GPIO_PASPAR, paspar);
 237     paspar &amp;= ~(HAL_MCF5282_GPIO_PASPAR_A0_MASK | HAL_MCF5282_GPIO_PASPAR_A1_MASK);
 238     paspar |= (HAL_MCF5282_GPIO_PASPAR_A0_SCL | HAL_MCF5282_GPIO_PASPAR_A1_SDA);
 239     HAL_WRITE_UINT16(HAL_MCF5282_IPSBAR + HAL_MCF5282_GPIO_PASPAR, paspar);
 240
 241     // And leave the driver to take care of the rest.
 242     cyg_mcf52xx_i2c_init(bus);
 243 }
 244
 245 CYG_MCF52xx_I2C_BUS(hal_dnp5280_i2c_bus,
 246                     &amp;dnp5280_i2c_init,
 247                     HAL_MCF52xx_I2C_SINGLETON_BASE,
 248                     HAL_MCF52xx_I2C_SINGLETON_ISRVEC,
 249                     HAL_MCF52xx_I2C_SINGLETON_ISRPRI,
 250                     HAL_MCF52xx_I2C_SINGLETON_FDR);
 251
 252     </programlisting>
 253     <para>
 254 Obviously if <varname>CYGHWR_DEVS_I2C_MCF52xx_MULTIPLE_BUSES</varname>
 255 is enabled then the singleton macros may not be defined and the
 256 appropriate numbers should be used directly. This example uses a
 257 custom initialization function which sets up the relevant pins and
 258 then chains into the I<superscript>2</superscript>C drivers'
 259 <function>cyg_mcf52xx_i2c_init</function> function. If the platform
 260 HAL has already set up the pins correctly then
 261 <function>cyg_mcf52xx_i2c_init</function> could be used directly in
 262 the bus instantiation, saving a small amount of code for the custom
 263 initialization function.
 264     </para>
 265     <para>
 266 I<superscript>2</superscript>C device structures can be instantiated
 267 in the usual way, for example:
 268     </para>
 269     <programlisting width=72>
 270 CYG_I2C_DEVICE(cyg_i2c_wallclock_ds1307,
 271                &amp;hal_dnp5280_i2c_bus,
 272                0x68,
 273                0x00,
 274                CYG_I2C_DEFAULT_DELAY);
 275     </programlisting>
 276   </refsect1>
 277
 278 </refentry>
 279 </part>