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

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     ixdp425.sgml                                                -->
<!--                                                                 -->
<!--     Intel XScale IXDP425 Development Platform HAL documentation -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                       -->
<!-- ===============================================================     -->
<!-- Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. -->
<!-- Copyright (C) 2004, 2005, 2006 eCosCentric Limited                  -->
<!-- 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):   jlarmour                                           -->
<!-- Contact(s):  jlarmour                                           -->
<!-- Date:        2006-01-27                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<part id="hal-arm-ixdp425-part"><title>Intel XScale IXDP425 Network Processor Evaluation Board Support</title>

<!-- {{{ Overview                       -->

<refentry id="arm-ixdp425">
  <refmeta>
    <refentrytitle>Overview</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname>eCos and RedBoot Support for the Intel XScale IXDP425 Network Processor Evaluation Board</refname>
    <refpurpose>Overview</refpurpose>
  </refnamediv>

  <refsect1 id="arm-ixdp425-description"><title>Description</title>
    <para>
This document covers the configuration and usage of eCos and RedBoot on
the Intel XScale IXDP425 Network Processor Evaluation Board.
The IXDP425 board contains the Intel XScale IXP425 processor,
256Mbytes of SDRAM, 16MByte of parallel NOR flash memory, an I2C
EEPROM, hexadecimal debug display, LEDs, and external connections for
two serial channels, two NPE ethernet daughterboards and an expansion
bus based on the Utopia-2 interface standard. eCos and RedBoot
support for the devices and peripherals on this board is described
below.
    </para>
    <para>
In normal operation, a RedBoot image is programmed into the
flash memory, and the board will boot into this image from
reset. RedBoot provides gdb stub functionality so it is then possible
to download and debug stand-alone applications via the gdb
debugger. RedBoot can also load and execute Linux kernels.
This can happen over either a serial line or over ethernet.
    </para>
    <para>
This document should be read in conjunction with the <citetitle
pubwork="Part">Intel XScale IXP4xx Network Processor Support</citetitle>
processor HAL documentation in the eCos documentation set, as well as the
generic HAL documentation.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-hardware"><title>Supported Hardware</title>
    <para>
The parallel NOR flash memory supplied by default with the IXDP425 -
a single Intel StrataFlash 28F128J3 - consists of 128 blocks of
128Kbytes each. In a typical setup, the first four blocks, 512
Kbytes, are reserved for the use of the RedBoot ROM image.  The
topmost block is used to manage the flash and hold RedBoot
<command>fconfig</command> values. The remaining blocks can be used by
application code. There are 123 blocks available between 0x50080000
and 0x50FE0000.
    </para>
    <para>
RedBoot supports the built-in high-speed and console UARTs. The default
serial port settings are 115200,8,N,1. 
    </para>
    <para>
There is an ethernet driver
<varname>CYGPKG_DEVS_ETH_INTEL_I82559</varname> intended for
use with a PCI I82559-based ethernet device to allow communication
and downloads. A separate package,
<varname>CYGPKG_DEVS_ETH_ARM_IXDP425_I82559</varname>, is responsible for
configuring this generic driver to the IXDP425 hardware. This driver
is also loaded automatically when configuring for the IXDP425 target.
    </para>
    <para>
IDE support is available to support most PCI IDE
controllers. Separate support is also available to support CompactFlash
cards fitted to an optional daughterboard, in True IDE mode. These
features are described in the IXP4xx processor HAL documentation.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-tools"><title>Tools</title>
    <para>
The IXDP425 support is intended to work with
GNU tools configured for an arm-elf target. The original port was undertaken
using arm-elf-gcc version 3.4.4, arm-elf-gdb version 6.3, and
binutils version 2.15.
    </para>
  </refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ Hardware setup                 -->

<refentry id="arm-ixdp425-setup">
  <refmeta>
    <refentrytitle>Setup</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname>Setup</refname>
    <refpurpose>Setting up the IXDP425 board</refpurpose>
  </refnamediv>

  <refsect1 id="arm-ixdp425-setup-overview"><title>Overview</title>
    <para>
In a typical development environment, the IXDP425 board boots from
the parallel NOR Flash and runs the RedBoot ROM monitor directly. Applications
are then downloaded into RAM and run directly on the board using the
command line interface, or for standalone applications, via the debugger
<command>arm-elf-gdb</command>. Alternatively applications can be stored
in Flash to be subsequently loaded into RAM for execution. Preparing the board
therefore usually involves programming a suitable RedBoot image into flash
memory.
    </para>
    <para>
The following RedBoot configurations are supported:
    </para>
    <informaltable frame="all">
      <tgroup cols="4" colsep="1" rowsep="1" align="left">
        <thead>
          <row>
            <entry>Configuration</entry>
            <entry>Description</entry>
            <entry>Use</entry>
            <entry>File</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>ROM</entry>
            <entry>RedBoot running from ROM</entry>
            <entry>redboot_ROM.ecm</entry>
            <entry>redboot_ROM.bin</entry>
          </row>
          <row>
            <entry>RAM</entry>
            <entry>RedBoot running from RAM</entry>
            <entry>redboot_RAM.ecm</entry>
            <entry>redboot_RAM.bin</entry>
          </row>
          <row>
            <entry>ROMRAM</entry>
            <entry>RedBoot running from RAM, but contained in the board's flash boot sector</entry>
            <entry>redboot_ROMRAM.ecm</entry>
            <entry>redboot_ROMRAM.bin</entry>
          </row>
          <row>
            <entry>ROM_CFIDE</entry>
            <entry>Same as ROM, but with additional CompactFlash IDE and FAT FS support</entry>
            <entry>redboot_ROM_CFIDE.ecm</entry>
            <entry>redboot_ROM_CFIDE.bin</entry>
          </row>
          <row>
            <entry>ROMRAM_CFIDE</entry>
            <entry>Same as ROMRAM, but with additional CompactFlash IDE and FAT FS support</entry>
            <entry>redboot_ROMRAM_CFIDE.ecm</entry>
            <entry>redboot_ROMRAM_CFIDE.bin</entry>
          </row>
          <row>
            <entry>ROMLE</entry>
            <entry>RedBoot running from ROM configured for little-endian operation</entry>
            <entry>redboot_ROMLE.ecm</entry>
            <entry>redboot_ROMLE.bin</entry>
          </row>
          <row>
            <entry>RAMLE</entry>
            <entry>RedBoot running from RAM configured for little-endian operation</entry>
            <entry>redboot_RAMLE.ecm</entry>
            <entry>redboot_RAMLE.bin</entry>
          </row>
          <row>
            <entry>ROMRAMLE</entry>
            <entry>RedBoot running from RAM and configured for little-endian operation,
                   but contained in the board's flash boot sector</entry>
            <entry>redboot_ROMRAMLE.ecm</entry>
            <entry>redboot_ROMRAMLE.bin</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    <para>
For serial communications, all versions run with 8 bits, no parity,
and 1 stop bit at 115200 baud. RedBoot also supports
ethernet communication and flash management.
    </para>
    <para>
If the ROM version is to be chosen, then the RAM version is provided to
allow for updating the resident RedBoot image in Flash. The ample
provision of RAM memory on the board allows the ROMRAM version of
RedBoot to be used instead of the standard ROM version which executes
directly from Flash.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-setup-first"><title>Initial Installation</title>

    <refsect2 id="arm-ixdp425-flash-socket-install">
      <title>Installation with a Flash programmer</title>
      
      <para>
This approach to initial installation may be used if a Flash device programmer
is available. The IXDP425 Flash is socketed at U22. Although the supplied Flash
part is an Intel StrataFlash 28F128J3, any 28FxxxJ3 part may be substituted -
RedBoot will use the Common Flash Interface (CFI) to determine the Flash device
geometry.
      </para>

      <para>
In this mode, the ROM mode RedBoot is programmed into the boot flash at offset
0x00000000.
      </para>
    </refsect2>

   <refsect2 id="arm-ixdp425-jtag-install">
     <title>Installation via JTAG</title>

     <para>
A JTAG device may also be used to perform initial programming. Some
JTAG devices have in-built capabilities that permit programming of the
Flash part. Other JTAG devices are able to load a RAM RedBoot image
into SDRAM, from where a ROM RedBoot image can then in turn be loaded
and then programmed.
     </para>
     <para>
If using a JTAG device that supports direct programming of the Flash
part, the Flash is usually located at 0x50000000 in the CPU memory map,
assuming the JTAG device initialisation has not remapped it elsewhere.
It will usually need to first unlocked and then erased before
programming.
     </para>
     <para>
For other JTAG devices, to load a RAM RedBoot image into SDRAM it
will first be required to initialise the memory interface, and in
particular configure the SDRAM controller.
Consult your JTAG device documentation on how
to access IXP425 registers.
     </para>
     <para>
One example of a JTAG device capable of direct programming of Flash
is the Abatron BDI2000, and in the following sections are the steps
required to program RedBoot using it.
     </para>

     <refsect3 id="arm-ixdp425-bdi2000-prep">
       <title>Preparing the Abatron BDI2000 JTAG debugger</title>
       <para>
The BDI2000 must first be configured to allow communication with
your local network, and configured with the parameters for interfacing
with the target board. The following steps should be followed:
     </para>
     <orderedlist>
      <listitem><para>
Prepare a PC to act as a host PC and start a TFTP server on it.
      </para></listitem>
      <listitem><para>
Connect the Abatron BDI2000 JTAG debugger via both serial and ethernet
to the host PC and power it on. Use the serial cable supplied with the
BDI2000.
      </para></listitem>
      <listitem><para>
Install the Abatron BDI2000 bdiGDB support software on the host PC.
      </para></listitem>
      <listitem><para>
Confirm that the XScale firmware is resident in the BDI2000. For
example, using the <command>bdisetup</command> utility:
         <screen>
$ <userinput>bdisetup -v -s</userinput>
BDI Type : BDI2000 Rev.C (SN: xxxxxxxx)
Loader   : V1.05
Firmware : V1.08 bdiGDB for XScale
Logic    : V1.03 XScale
MAC      : 00-0c-01-96-64-92
IP Addr  : 192.168.7.220
Subnet   : 255.255.255.0
Gateway  : 192.168.7.1
Host IP  : 192.168.7.9
Config   : /ixdp425.cfg
          </screen>
        </para>
        <para>
To upload firmware if needed, follow the procedures in the BDI2000
manual, for example using the <command>bdisetup</command> utility:
          <screen>
$ <userinput>bdisetup -u -p/dev/ttyS0 -b57 -aGDB -tXSCALE</userinput>
Connecting to BDI loader
Erasing CPLD
Programming firmware with ./b20xscgd.108
Erasing firmware flash ....
Erasing firmware flash passed
Programming firmware flash ....
Programming firmware flash passed
Programming CPLD with ./xscjed21.103
          </screen>
      </para></listitem>
      <listitem><para>
Locate the file <filename>ixdp425.cfg</filename>
within the BDI2000 software installation.
      </para></listitem>
      <listitem><para>
Locate the file <filename>regIXP425.def</filename> within the installation
of the BDI2000 bdiGDB support software.
      </para></listitem>
      <listitem><para>
Place the <filename>ixdp425.cfg</filename> file in a location on the
PC accessible to the TFTP server. Later you will configure the BDI2000 to load
this file via TFTP as its configuration file.
      </para></listitem>
      <listitem><para>
Similarly place the file <filename>regIXP425.def</filename> in a location
accessible to the TFTP server.
      </para></listitem>
      <listitem><para>
Open <filename>ixdp425.cfg</filename> in an editor such as
emacs or notepad and if necessary adjust the path of the
<filename>regIXP425.def</filename> file in the <literal>[REGS]</literal>
section to match its location relative to the TFTP server root.
Also comment out with a ';' the IP line in the <literal>[HOST]</literal>
section, or update it to refer to the development PC.
      </para></listitem>
      <listitem><para>
Install and configure the Abatron BDI2000 in line with the bdiGDB
instruction manual. Configure the BDI2000 to use the
<filename>ixdp425.cfg</filename> configuration file at the
appropriate point of this process. For example, using the
<command>bdisetup</command> utility:
          <screen>
$ <userinput>bdisetup -c -p/dev/ttyS0 -b57 -i192.168.7.220 -h192.168.7.9 -m255.255.255.0 -g192.168.7.1 -f/ixdp425.cfg</userinput>
Connecting to BDI loader
Writing network configuration
Configuration passed
          </screen>
The above command uses the first serial port at 57,600 baud to set the BDI2000's IP
address to 192.168.7.220, its default TFTP host to 192.168.7.9, the network mask
to 255.255.255.0, the default gateway to 192.168.7.1, and the configuration file
to load to <filename>/ixdp425.cfg</filename>.
      </para></listitem>
     </orderedlist>
   </refsect3>

   <refsect3 id="arm-ixdp425-board-setup">
     <title>Preparing the IXDP425 board for programming</title>
     <para>
Follow the steps in this section in order to allow communication between
the board and the host PC, and between the board and the JTAG device.
     </para>
     <orderedlist>
      <listitem><para>
First you must connect a straight through DB9 serial cable between the high
speed serial port labelled UART0 on the board and a serial port on the host
computer.
      </para></listitem>
      <listitem><para>
Start a suitable terminal emulator on the host computer such as
<command>minicom</command> or <productname>HyperTerminal</productname>.
Set the communication parameters to 115200 baud, 8 data bits,
no parity bit and 1 stop bit with no flow control.
      </para></listitem>
      <listitem><para>
If using a PCI ethernet card, connect the board to your host PC's LAN
with an Ethernet cable.
      </para></listitem>
      <listitem><para>
If using a PCI ethernet card, you may need to designate the ethernet
interface with a new Ethernet MAC address. The RedBoot binary image
contains a default address, but each board requires its own unique
address. It is advisable to mark each board with its programmed MAC
address for future identification.
      </para></listitem>
      <listitem><para>
Connect the board to the BDI2000 using a 20-pin ARM/Xscale cable
from the JTAG/ICE interface connector (J12) to the Target A port on the BDI2000.
      </para></listitem>
      <listitem><para>
Power up the IXDP425 board. You should see the hex display and various LEDs
illuminate.
      </para></listitem>
      <listitem><para>
Connect to the BDI2000's CLI interface via TCP/IP on the standard
telnet port 23. The <command>telnet</command> application is suitable
for this. You should see usage information followed by the prompt:
<screen>
Core#0&gt;
</screen>
      </para></listitem>
      <listitem><para>
Confirm correct connection with the BDI2000 with the <command>reset
halt</command> command as follows:

<screen>
Core#0&gt; <userinput>reset halt</userinput>
- TARGET: processing reset request
- TARGET: BDI asserts RESET and TRST
- TARGET: BDI removed TRST
- TARGET: Bypass check: 0x000000001 =&gt; 0x00000001
- TARGET: JTAG exists check passed
- Core#0: ID code is 0x19274013
- Core#0: BDI sets hold_rst and halt mode
- TARGET: BDI removes RESET
- Core#0: BDI sets hold_rst and halt mode again
- Core#0: BDI loads debug handler to mini IC
- Core#0: BDI clears hold_rst
- TARGET: resetting target passed
- TARGET: processing target startup ....
- TARGET: processing target startup passed
Core#0&gt;
</screen>
      </para></listitem>
      <listitem><para>
Locate the <filename>redboot_ROM.bin</filename> image within the <filename class=directory>
loaders</filename> subdirectory of the base of the eCos installation.
      </para></listitem>
      <listitem><para>
Copy the <filename>redboot_ROM.bin</filename> file into a location on the host computer accessible
to its TFTP server.
      </para></listitem>
     </orderedlist>
   </refsect3>

   <refsect3 id="arm-ixdp425-redboot-bdi2000-flash">
     <title>Using the BDI2000 to directly program RedBoot into Flash</title>
     <para>
As previously mentioned, there are two methods of programming
a RedBoot image into the parallel NOR Flash via JTAG, depending on
the capabilities of the JTAG device. The BDI2000 supports direct
programming of the Flash device and so that is the approach described
here.
     </para>
     <para>
This is a three stage process. The relevant Flash blocks must first be
unlocked, then erased, and finally programmed. This can be accomplished
with the following steps:
     </para>
     <orderedlist>
      <listitem><para>
Connect to the BDI2000 telnet port as before.
      </para></listitem>
      <listitem><para>
Use the following commands in the BDI2000 telnet session to unlock
and then erase the relevant Flash blocks that will contain RedBoot.
       <programlisting>
Core#0&gt;<userinput>unlock 0x50000000 0x20000 4</userinput>
Unlocking flash at 0x50000000
Unlocking flash at 0x50020000
Unlocking flash at 0x50040000
Unlocking flash at 0x50060000
Unlocking flash passed
Core#0&gt;<userinput>erase 0x50000000 0x20000 4</userinput>
Erasing flash at 0x50000000
Erasing flash at 0x50020000
Erasing flash at 0x50040000
Erasing flash at 0x50060000
Erasing flash passed
       </programlisting>
      </para></listitem>
      <listitem><para>
Program the RedBoot image into Flash with the following command,
replacing <replaceable>/RBPATH</replaceable> with the location of
the redboot_ROM.bin file relative to the TFTP server root directory:
<screen>
Core#0&gt;<userinput>prog 0x50000000 <replaceable>/RBPATH/</replaceable>redboot_ROM.bin bin</userinput>
Programming /RBPATH/redboot_ROM.bin , please wait ....
Programming flash passed
Core#0&gt;
</screen>
This operation can take some time.
      </para></listitem>
     </orderedlist>
     <para>
The RedBoot installation is now complete. This can be tested by
powering off the board, disconnecting the JTAG, and then powering on
the board again. The RedBoot banner should be visible on the serial
port. The message
<screen>flash configuration checksum error or invalid key</screen>
does not indicate a problem at this stage of installation. It just
means that RedBoot Flash configuration has yet to be performed,
as described <link linkend="arm-ixdp425-flash-ram-redboot-fconfig">below</link>.
     </para>
     <para>
If it proves necessary to re-install RedBoot, this may be achieved by
repeating the above process. Alternatively, a new image may be downloaded and programmed into
flash more directly using RedBoot's own commands. See the RedBoot
documentation for details.
     </para>
   </refsect3>
  </refsect2> 

  <refsect2 id="arm-ixdp425-flash-ram-redboot-fconfig">
     <title>RedBoot Flash configuration</title>
     <para>
The following steps describe how to initialize RedBoot's Flash configuration.
This must be performed when using a RAM RedBoot to program Flash, but is
also applicable to initial configuration of a ROM or ROMRAM RedBoot <link
linkend="arm-ixdp425-jtag-install">loaded using JTAG</link> or with a
<link linkend="arm-ixdp425-flash-socket-install">Flash device programmer</link>.
     </para>
     <orderedlist>
      <listitem><para>
Use the following command to initialize RedBoot's Flash
Information System (FIS):
<screen>
RedBoot&gt; <userinput>fis init -f</userinput>
About to initialize [format] FLASH image system - continue (y/n)? <userinput>y</userinput>
*** Initialize FLASH Image System
... Erase from 0x50080000-0x50fdffff: ...........................................................................................
... Unlocking from 0x50fe0000-0x50ffffff: .
... Erase from 0x50fe0000-0x50ffffff: .
... Program from 0x0ffd0000-0x0fff0000 to 0x50fe0000: .
... Locking from 0x50fe0000-0x50ffffff: .
RedBoot&gt;
</screen>
      </para></listitem>
      <listitem><para>
Now configure RedBoot's Flash configuration with the command:
<screen>
RedBoot&gt; <userinput>fconfig -i</userinput>
</screen>
      </para>
      <para>
If a BOOTP/DHCP server is not available,
then IP configuration may be set manually. The default server IP
address can be set to a PC that will act as a TFTP host for
future RedBoot load operations, or may be left unset. The
following gives an example configuration:
<screen>     
RedBoot&gt; <userinput>fconfig -i</userinput>
Initialize non-volatile configuration - continue (y/n)? <userinput>y</userinput>
Run script at boot: <userinput>false</userinput>
Use BOOTP for network configuration: <userinput>false</userinput>
Gateway IP address: <userinput>192.168.7.11</userinput>
Local IP address: <userinput>192.168.7.222</userinput>
Local IP address mask: <userinput>255.255.255.0</userinput>
Default server IP address: <userinput>192.168.7.9</userinput>
Console baud rate: <userinput>115200</userinput>
DNS server IP address: <userinput>192.168.7.11</userinput>
GDB connection port: <userinput>9000</userinput>
Force console for special debug messages: <userinput>false</userinput>
Network debug at boot time: <userinput>false</userinput>
Update RedBoot non-volatile configuration - continue (y/n)? <userinput>y</userinput>
... Unlocking from 0x50fe0000-0x50ffffff: .
... Erase from 0x50fe0000-0x50ffffff: .
... Program from 0x0ffd0000-0x0fff0000 to 0x50fe0000: .
... Locking from 0x50fe0000-0x50ffffff: .
RedBoot&gt; 
</screen>
      </para></listitem>
     </orderedlist>
    </refsect2>
  </refsect1>

  <refsect1 id="arm-ixdp425-setup-rebuild"><title>Rebuilding RedBoot</title>
    <para>
Should it prove necessary to rebuild a RedBoot binary, this is done
most conveniently at the command line. The steps needed to rebuild the
the ROM version of RedBoot for the IXDP425 are:
    </para>
    <screen>
$ mkdir redboot_ixdp425_romram
$ cd redboot_ixdp425_romram
$ ecosconfig new ixdp425 redboot
$ ecosconfig import $ECOS_REPOSITORY/hal/arm/xscale/ixdp425/<replaceable>VERSION</replaceable>/misc/redboot_ROM.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make
    </screen>
    <para>
At the end of the build the <filename
class="directory">install/bin</filename> subdirectory should contain
the file <filename>redboot.bin</filename>. 
    </para>
    <para>
The other versions of RedBoot - RAM, ROMRAM or the little-endian variants - may
be similarly built by choosing the appropriate alternative .ecm file.
    </para>
  </refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ Config                         -->

<refentry id="arm-ixdp425-config">
  <refmeta>
    <refentrytitle>Configuration</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname>Configuration</refname>
    <refpurpose>Platform-specific Configuration Options</refpurpose>
  </refnamediv>

  <refsect1 id="arm-ixdp425-config-overview"><title>Overview</title>
    <para>
The IXDP425 platform HAL package is loaded automatically when eCos is
configured for the <literal>ixdp425</literal> target. It should never be
necessary to load this package explicitly. Unloading the package
should only happen as a side effect of switching target hardware.
    </para>
    <para>
Configuring for the <literal>ixdp425</literal> target also causes
the IXP4xx processor HAL to be included. Many configuration
options in relation to the peripheral IXP425 devices including
serial UARTs, clocks, etc. are described in the IXP4xx processor
HAL documentation, which should be referred to.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-config-startup"><title>Startup</title>
<para>

</para>
    <para>
The platform HAL package supports three separate startup types:
    </para>
    <variablelist>
      <varlistentry>
        <term>RAM</term>
        <listitem><para>
This is the startup type which is normally used during application
development. The board has RedBoot programmed into flash
and boots into that initially.
<application>arm-elf-gdb</application> is then used to load a RAM
startup application into memory and debug it. It is assumed that the
hardware has already been initialized by RedBoot. By default a standalone
application will use the eCos virtual vectors mechanism to obtain certain
services from RedBoot, including diagnostic output.
        </para></listitem>
      </varlistentry>
      <varlistentry>
        <term>ROM</term>
        <listitem><para>
This startup type can be used for finished applications which will
be programmed into flash at physical address 0x50000000. The application will
be self-contained with no dependencies on services provided by other
software. eCos startup code will perform all necessary hardware
initialization.
        </para></listitem>
      </varlistentry>
      <varlistentry>
        <term>ROMRAM</term>
        <listitem><para>
This startup type can be used for finished applications which will be
programmed into flash at physical location 0x50000000. However, when it starts
up, the application will first copy itself to RAM at virtual address
0x00000000 and then run from there. RAM is generally faster than flash
memory, so the program will run more quickly than a ROM-startup application. The
application will be self-contained with no dependencies on services
provided by other software. eCos startup code will perform all
necessary hardware initialization.
        </para></listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1 id="arm-ixdp425-config-redboot"><title>RedBoot and Virtual Vectors</title>
    <para>
If the application is intended to act as a ROM monitor, providing
services for other applications, then the configuration option
<varname>CYGSEM_HAL_ROM_MONITOR</varname> should be set. Typically
this option is set only when building RedBoot.
    </para>
    <para>
If the application is supposed to make use of services provided by a
ROM monitor, via the eCos virtual vector mechanism, then the
configuration option <varname>CYGSEM_HAL_USE_ROM_MONITOR</varname>
should be set. By default this option is enabled when building for a
RAM startup, disabled otherwise. It can be manually disabled for a RAM
startup, making the application self-contained, as a testing step
before switching to ROM startup.
    </para>
    <para>
If the application does not rely on a ROM monitor for diagnostic
services then the serial port will be claimed for HAL
diagnostics.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-config-flash"><title>Flash Driver</title>
    <para>
The IXDP425 is supplied by default with a 16Mbyte Intel StrataFlash 28F128J3
parallel Flash device.
    </para>
    <para>
The <varname>CYGPKG_DEVS_FLASH_STRATA_V2</varname> package contains all the
code necessary to support this part and the platform HAL package contains
definitions that customize the driver to the IXDP425 board. This driver is
not active until the generic Flash support package,
<varname>CYGPKG_IO_FLASH</varname>, is included in the configuration.
    </para>
    <para>
 The device is located in a socket on a board labelled
both U22 and "BOOT ROM", and can be replaced with compatible Intel StrataFlash
28FxxxJ3 parts. RedBoot will use the Common Flash Interface (CFI) to determine
the Flash device geometry.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-config-eth"><title>Ethernet Driver</title>
    <para>
The IXDP425 development kit includes an Intel i82559-based PCI Ethernet NIC.
The <varname>CYGPKG_DEVS_ETH_INTEL_I82559</varname> package contains all the
code necessary to support this device and the
<varname>CYGPKG_DEVS_ETH_ARM_IXDP425_I82559</varname> package contains
definitions that customize the driver to the IXDP425 board.
This driver is not active until the generic Ethernet support package,
<varname>CYGPKG_IO_ETH_DRIVERS</varname>, is included in the configuration.
    </para>
    <para>
The IXDP425 is also supplied with Network Processing Engine (NPE) modules,
however these are not supported in this release.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-config-cf-ide"><title>CompactFlash True IDE Driver</title>
    <para>
The IXP425 variant HAL includes support for CompactFlash IDE devices
accessed in True IDE mode directly on the IXP425 expansion bus.
This is described further in the IXP4xx processor HAL
documentation.
    </para>
    <para>
However note that the use of CS2 conflicts with use of the hex display,
which also operates from the CS2 chip select, and so the use of the hex
display by eCos/RedBoot will be disabled if CF IDE support is enabled.
In addition it is expected that the hex display will show random unpredictable
values during CF IDE accesses.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-config-ixp425-peripherals">
    <title>Other IXP425 peripherals</title>
    <para>
Details in relation to on-chip IXP425 peripherals such as PCI IDE
driver, watchdog support, serial support, clocks, interrupts and so forth
are described further in the IXP4xx processor HAL documentation.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-config-flags"><title>Compiler Flags</title>
    <para>
The platform HAL defines the default compiler and linker flags for all
packages, although it is possible to override these on a per-package
basis. Most of the flags used are the same as for other architectures
supported by eCos. There are just two flags specific to this port:
    </para>
    <variablelist>
      <varlistentry>
        <term><option>-mcpu=xscale</option></term>
        <listitem><para>
The <application>arm-elf-gcc</application> compiler supports many
variants of the ARM architecture.
A <option>-m</option> option should be used to select the specific
variant in use, and with current tools <option>-mcpu=xscale</option> is the
correct option for the XScale IXP425 CPU.
        </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-mbig-endian</option></term>
        <listitem><para>
The <application>arm-elf-gcc</application> compiler will compile
all code into big endian (most significant byte first) format. This is
the default endianness for this port. Without this flag,
<application>arm-elf-gcc</application> generates little endian
code. You must ensure your application is built for the same
endianness as RedBoot.
        </para>
        <para>
Although RedBoot endianness can be controlled by enabling or disabling
the configuration option <varname>CYGHWR_HAL_ARM_BIGENDIAN</varname>,
it is more convenient to use the minimal configuration
files (.ecm files) as <link linkend="arm-ixdp425-setup-overview">described
earlier</link>.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-mthumb</option></term>
        <listitem><para>
The <application>arm-elf-gcc</application> compiler will compile
C and C++ files into the Thumb instruction set when this option is used.
The best way to build eCos in Thumb mode is to enable the configuration
option <varname>CYGHWR_THUMB</varname>.
        </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-mthumb-interwork</option></term>
        <listitem><para>
This option allows programs to be created that mix ARM and Thumb instruction
sets. Without this option, some memory can be saved. This option should
be used if -mthumb is used. The best way to build eCos with Thumb interworking
is to enable the configuration option
<varname>CYGBLD_ARM_ENABLE_THUMB_INTERWORK</varname>.
        </para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

</refentry>

<!-- }}} -->

<!-- {{{ JTAG debug                     -->

<refentry id="arm-ixdp425-jtag">
  <refmeta>
    <refentrytitle>JTAG debugging support</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname>JTAG support</refname>
    <refpurpose>Usage</refpurpose>
  </refnamediv>

  <refsect1 id="arm-ixdp425-jtag-usage"><title>Use of JTAG for debugging</title>
    <para>
JTAG can be used to single-step and debug loaded RAM applications, or even
applications resident in ROM, including RedBoot.
    </para>
    <para>
Debugging of ROM applications is only possible if using hardware breakpoints. The
XScale only supports four such hardware breakpoints - two for instruction breakpoints
and two for data breakpoints, and so they should be used sparingly. If using a GDB
front-end such as Eclipse, check it
has not set unnecessary extra breakpoints. Some JTAG devices give the option
of whether to set hardware or software breakpoints by default. Be sure to configure
your device appropriately.
    </para>
    <refsect2 id="arm-ixdp425-jtag-bdi2000"><title>Abatron BDI2000 notes</title>
      <para>
On the Abatron BDI2000, the <filename>ixdp425.cfg</filename> file that is
included with the BDI2000 software should
be used to setup and configure the hardware to an appropriate state to load
programs. This includes setting up the SDRAM controller.
      </para>
      <para>
The <filename>ixdp425.cfg</filename> file also contains an option
to define whether hardware or software breakpoints are used by default, using
the <literal>BREAKMODE</literal> directive in the <literal>[TARGET]</literal>
section. Edit this file if you wish to use software break points, and remember
to use the <command>boot</command> command on the BDI2000 command line interface
to make the changes take effect.
      </para>
      <para>
On the BDI2000, debugging can be
performed either via the telnet interface or using <command>arm-elf-gdb</command>
and the bdiGDB interface. In the case of the latter, <command>arm-elf-gdb</command>
needs to connect to TCP port 2001 on the BDI2000's IP address. For example:
<screen>
(gdb) <userinput>target remote 111.222.333.444:2001</userinput>
</screen>
      </para>
      <para>
By default when the BDI2000 is powered up, the target will always run the
initialization section of the <filename>ixdp425.cfg</filename>
file (which configures the SDRAM among other things), and halts the target.
This behavior is repeated with the <command>reset halt</command> command.
      </para>
      <para>
      If the board is reset when in '<command>reset halt</command>' mode
(either with the '<command>reset halt</command>' or '<command>reset</command>'
commands, or by pressing the reset button) and the '<command>go</command>'
command is then given, then the board will boot as normal. If a ROMRAM RedBoot
is resident in Flash, it will be run.
      </para>
      <para>
It is also possible for the target to always run, without initialization,
after the reset button has been pressed.
This mode is selected with the <command>reset run</command> command. This
conveniently allows the target to be connected to the JTAG debugger, and
be able to reset it with the reset button, without being required to always
type '<command>go</command>' every time. Thereafter, invoking the
<command>reset</command> command will repeat the previous reset style. Also
in this mode, exceptions will be handled by board software, rather than
causing the JTAG debugger to halt the CPU.
      </para>

<!-- Wait for eCos support - needs altered ixdp425.cfg for bdi2000
      <para>
<link linkend="arm-ixdp425-jtag-configuration">Suitably configured</link>
RAM applications can be loaded either via GDB, or directly via
the telnet CLI. For example:
<screen>
Core#0&gt;<userinput>load 0x80000 /test.bin bin</userinput>
Loading /test.bin , please wait ....
Loading program file passed
Core#0&gt;<userinput>go 0x80000</userinput>
</screen>
      Consult the BDI2000 documentation for information on other formats.
      </para>
    </refsect2>
    <refsect2 id="arm-ixdp425-jtag-configuration">
      <title>Configuration of RAM applications</title>
      <para>
If the JTAG device has initialized the SDRAM, such as by using the
<filename>ixdp425.cfg</filename> configuration on the BDI2000,
RAM applications can be loaded directly into SDRAM without requiring
a ROM monitor. This loading can be done directly through the JTAG device,
or where supported by the JTAG device, through GDB. 
      </para>
      <para>
In order to configure the application to support this mode, some configuration
settings are required. Firstly <varname>CYGSEM_HAL_USE_ROM_MONITOR</varname>
must be disabled. This will also cause the
<varname>CYGBLD_HAL_ARM9_ATMEL_AT91RM9200_KITS_PHYS_SDRAM_LOAD</varname>
configuration option to be enabled allowing the application to be built with
a set of memory layout files that will configure the linker script to set
the program load address to be within the physical SDRAM space. Secondly
the <varname>CYGDBG_HAL_DIAG_TO_DEBUG_CHAN</varname> option should be
enabled in order to prevent HAL diagnostic output being encoded into
GDB ($O) packets.
      </para>
    </refsect2>
    <refsect2 id="arm-ixdp425-jtag-running-ram">
      <title>Running RAM applications</title>
      <para>
Once the application is built, the start address will have to be set
manually to be the current start address but within the SDRAM physical
address space. This can be determined by adding 0x20000000 to the
existing start address. This can be done in GDB using, for example:
<screen>
(gdb) set $pc=0x20008000
</screen>
      </para>
      <para>
HAL diagnostic output will appear by default on the serial debug
port. USART 1 can be chosen instead by setting the
<varname>CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL</varname>
configuration option in the platform HAL to channel 1.
      </para>
-->
    </refsect2>
  </refsect1>
</refentry>

<!-- }}} -->

<!-- {{{ Port                           -->

<refentry id="arm-ixdp425-port">
  <refmeta>
    <refentrytitle>The HAL Port</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname>HAL Port</refname>
    <refpurpose>Implementation Details</refpurpose>
  </refnamediv>

  <refsect1 id="arm-ixdp425-port-overview"><title>Overview</title>
    <para>
This documentation explains how the eCos HAL specification has been
mapped onto the IXDP425 hardware, and should be read in conjunction
with that specification. The IXDP425 platform HAL package complements
the ARM architectural HAL, the XScale variant HAL and the IXP425 processor
HAL. It provides functionality which is specific to the target board.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-port-startup"><title>Startup</title>
    <para>
Following a hard or soft reset, the HAL will initialize or
reinitialize most of the on-chip peripherals. There is an exception
for RAM startup applications which depend on a ROM monitor for certain
services.
    </para>
    <para>
For ROM or ROMRAM startup, the HAL will perform additional
initialization, setting up the external RAM and programming the
various internal registers. This is all done in the
<function>PLATFORM_SETUP1</function> macro in the assembler
header file <filename>hal_platform_setup.h</filename>.
    </para>
  </refsect1>

  <refsect1 id="arm-ixdp425-port-leds"><title>LED Codes</title>
    <para>
Unless the <link linkend="arm-ixdp425-config-cf-ide">Compact Flash IDE
configuration option</link> is selected, RedBoot uses the 4 digit LED
display to indicate status during board initialization. Possible codes
are:
    </para>
    <literallayout width=72>
LED     Actions
-------------------------------------------------------------
  	Power-On/Reset
        Set the CPSR
        Enable coprocessor access
        Drain write and fill buffer
        Setup expansion bus chip selects
1001
        Enable Icache
1002
        Initialize SDRAM controller
1003
        Switch flash (CS0) from 0x00000000 to 0x50000000
1004
        Copy MMU table to RAM
1005
        Setup TTB and domain permissions
1006
        Enable MMU
1007
        Enable DCache
1008
        Enable branch target buffer
1009
        Drain write and fill buffer
        Flush caches
100A
        Start up the eCos kernel or RedBoot
0001
    </literallayout>
  </refsect1>

  <refsect1 id="arm-ixdp425-port-linker"><title>Linker Scripts and Memory Maps</title>
    <para>
The platform HAL package provides the memory layout information needed
to generate the linker script. The key memory locations are as follows:
    </para>
    <variablelist>
      <varlistentry>
        <term>Flash</term>
        <listitem><para>
This is located at address 0x50000000 of the physical memory space.
At initialization, the HAL uses the MMU to retain it at virtual
address 0x50000000, while also providing an uncached mapping at
0xB0000000 and a data coherent mapping at 0xA0000000.
        </para></listitem>
      </varlistentry>
      <varlistentry>
        <term>SDRAM</term>
        <listitem>
        <para>
This is located at address 0x00000000 of the physical memory
space. The HAL uses the MMU to retain this at virtual address 0x00000000, along
with an alias at 0x10000000. The same memory is also accessible uncached at
virtual location 0x20000000 for use by devices, and at 0x30000000
for data coherent access. The
first 32 bytes are used for hardware exception vectors. The next 32
bytes are used for the VSR table and the next 256 bytes are normally
used for the eCos virtual vectors, allowing RAM-based applications to
use services provided by the ROM monitor. Memory is required for the
MMU tables, and must be aligned on a 16Kbyte boundary. These therefore
occupy memory from 0x4000 to 0x8000. For ROM/ROMRAM startup, all
remaining SDRAM is available. For RAM startup, available RAM starts at
virtual location 0x00080000, with the bottom 512 kilobytes reserved for use
by RedBoot.
        </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>On-chip Peripheral Registers</term>
        <listitem>
          <para>
There are several regions in the memory map devoted to on-chip peripherals
or on-chip device controllers. When the MMU is enabled, all these regions
are set up with a direct, uncached and unbuffered mapping so that these
registers remain accessible at their physical locations.
          </para>
          <para>
As such, the address space for the AHB Queue Manager (AQM) resides at
0x60000000; the PCI controller resides at 0xC0000000; the expansion bus
controller configuration registers reside at 0xC4000000; the SDRAM
controller configuration registers resides at 0xCC000000; and all
remaining IXP425 on-chip peripherals reside in the block at 0xC8000000.
This latter block includes peripheral control for on-chip high-speed
and console UARTs, internal bus performance monitoring unit, interrupt
controller, GPIO controller, timers, WAN/Voice and Ethernet NPEs,
Ethernet MACs, and the USB controller.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Off-chip Peripherals</term>
        <listitem>
          <para>
RedBoot and eCos access the SDRAM, parallel NOR flash, and hex display
on CS2 (mapped to 0x52000000). In addition a CompactFlash True IDE mode disk may be accessed
via the expansion bus on CS1/CS2 (0x51000000/0x52000000), although the
hex display is not usable in that case.
          </para>
          <para>
In addition a 64MiB PCI window is mapped to 0x48000000, for communication
with devices on the PCI bus.
          </para>
          <para>
RedBoot and eCos do not currently make any use of any other off-chip
peripherals present on the IXDP425 board.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <refsect2 id="arm-ixdp425-port-memory-map-summary"><title>Memory map summary</title>
      <para>
The virtual memory maps in this section use a C, B, and X column to indicate
the caching policy for the region.
      </para>
      <para>
        <programlisting>
X C B  Description
- - -  ---------------------------------------------
0 0 0  Uncached/Unbuffered
0 0 1  Uncached/Buffered
0 1 0  Cached/Buffered    Write Through, Read Allocate
0 1 1  Cached/Buffered    Write Back, Read Allocate
1 0 0  Invalid - not used
1 0 1  Uncached/Buffered  No write buffer coalescing
1 1 0  Mini DCache - Policy set by Aux Ctl Register
1 1 1  Cached/Buffered    Write Back, Read/Write Allocate

Virtual Address   Physical Address  XCB  Size (MB)  Description
   0x00000000       0x00000000      010     256     SDRAM (cached)
   0x10000000       0x00000000      010     256     SDRAM (alias)
   0x20000000       0x00000000      000     256     SDRAM (uncached)
   0x30000000       0x00000000      010     256     SDRAM (cached, DC)
   0x48000000       0x48000000      000      64     PCI Data
   0x50000000       0x50000000      010      16     Flash (CS0, cached)
   0x51000000       0x51000000      000      16     CF True IDE mode chip select #0 (CS1)
   0x52000000       0x52000000      000      16     Hex display/CF True IDE mode chip select #1 (CS2)
   0x53000000       0x53000000      000      80     CS3 - CS7
   0x60000000       0x60000000      000      64     Queue Manager
   0xA0000000       0x50000000      010      16     Flash (CS0, cached, DC)
   0xB0000000       0x50000000      000      16     Flash (CS0, uncached)
   0xC0000000       0xC0000000      000       1     PCI Controller
   0xC4000000       0xC4000000      000       1     Exp. Bus Config
   0xC8000000       0xC8000000      000       1     Misc IXP425 IO
   0xCC000000       0xCC000000      000       1     SDRAM Config
        </programlisting>
      </para>
    </refsect2>
  </refsect1>

  <refsect1 id="arm-ixdp425-port-other-hal"><title>Other Issues</title>
    <para>
The IXDP425 platform HAL does not affect the implementation of other
parts of the eCos HAL specification. The XScale variant HAL, the IXP4xx
processor HAL documentation and the ARM
architectural HAL documentation should be consulted for further
details.
    </para>
  </refsect1>

</refentry>

<!-- }}} -->

</part>
