
          Texas Instruments Software Development Tools 
   +++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Thank you for choosing Texas Instruments software development tools.
It is our goal to provide you with the most useful and efficient
development tools to develop your applications around Texas
Instruments processors.
 
For questions or technical support, please consult your customer
support guide or contact customer support at:
 
Email: support@micro.ti.com
Phone: (412) 380-1550

This file contains:
1. Introduction
2. 2.00 Highlights
3. Solaris Device Driver Installation
4. Past Release Notes


1. Introduction
===============

---------------------------------------------------------------------
TMS470R1x Emulation Software Kit Version 2.00. for PC and Workstation
---------------------------------------------------------------------

Supported Platforms: Win95, WinNT 4.0, /SOLARIS (SunOS 5.5), and 
HP 10.20. 

This readme file contains information about this release as well as 
specific information about using some of the new features.

We also provide basic steps for getting started.  For more 
information on configuring hardware and software, please consult the
appropriate documentation:

TMS470R1x C Source Debugger UG, SPNU124C - provided with this release
in .pdf format (debugger.pdf) TMS470R1x Emulator Software Getting
Started Guide, SPNU123B XDS51x Emulator Installation Guide, SPNU070A
  

2.00 Highlights
===============

o   This release introduces TI's Graphical User Interface (GUI) 
    for 470's debugger.  Some features include:

     - Windows can be docked or moved outside of the main debugger
       window 
     - Context sensitive online help 
     - Context-menus for each window type offers specific options 
     - Registers can be rearranged in the CPU window by dragging them
       to a new location 
     - Multiple source FILE windows can be opened simultaneously 
     - Ability to save/load breakpoint lists in a window display 
     - Watch window can expand/contract arrays and structures 
     - Toolbar for frequently used commands 
     - New dialog boxes for Breakpoint, Alias, Log, and Memory-map
       commands 
     - Integrated profiler and debugger 
     - Function disambiguation window to support C++ function 
       overloading. (Overloading: Binding the same name to multiple
       operations whose signatures differ in number or types of
       arguments) 
     - Multiple memory windows 
     - Analysis interface: The analysis interface provides access to
       the TMS470 debugger analysis features. These features allow
       the user to monitor hardware functions and generate triggers
       based on the conditions defined by the user.

o   Generic on-line help is provided with this release.  To get help
    for a specific command, simply type 'help <command>' in the
    command window.

o   It is no longer necessary to use the -me option when little
    endian is desired.  The debugger performs a boundary scan on the
    ARM7TDMI to read the state of the BIGEND pin and configures
    itself appropriately.

o   XDS510PP is only available for Windows 95.

o   Tested with version 3.01 of the TMS320C54x (LEAD)  debugger. 

o   Variable Memory Width Access (VWMA) using IOPORT configuration.      
    This feature supports targets which allow only a specific type of 
    memory access on certain memory blocks. For example, it is
    possible that some targets require only half-word(16-bit)
    read/write accesses on a particular block of memory. Any other
    type of access such as byte or word can potentially cause the
    target to become "confused" and non-functional. The VWMA feature
    supports these types of targets if the user conforms to the
    following rules.
    1. The memory block must be configured as port.  
    2. If a memory window is opened, it should be configured to
       display its contents in memory block-width format. For 
       example, mem (short*)0x400000,x,win1 will open a memory
       window, win1, starting at location 0x400000 in half-word
       format. 
    3. If data is displayed in a watch window, the address for the
       data or variable should be casted with the appropriate type of
       access. 
       For example, wa *(short*)0x400000 displays the  content of
       address 0x400000 in half-word format.          

o   If memory area is configured as IOPORT, all target accesses are
    made directly from the target.  Data is not cached by the
    debugger. In addition, the access is made in the format of the
    display or as specified by the user.
    
o   If the memory is configured as anything other than IOPORT, target
    accesses are made from the debugger cache or the target as
    required.  Read accesses are always made in 32-bit format (for
    example, during screen refreshes).  Write accesses are
    controllable by the user via display format or via type casting. 
    For example, if the user writes a value into a memory window that
    is open in byte format, then the data will be written to the
    target using a true byte write instruction (ARM Instruction:
    STRB). 
   

---------------------------------------------------------------------
   About the TMS470R1x micro-controller:
---------------------------------------------------------------------

   The TMS470R1x micro-controller is based on the ARM7TDMI core from
   Advanced RISC Machines (ARM).  The tools provided in this release
   communicate with the processor's debug interface via its JTAG 
   port.  
   The debug interface module within the core is called ICEBreaker.
   For advanced debug support, Texas Instruments has developed an 
   enhancement to the debug interface which is called ICECrusher.  
   The part number for the micro-controller core which contains the 
   advanced debug interface is ARM7TDMIE.
 
   The following table highlights the key features which are
   available
   on the TMS470R1x and makes a distinction between what is available 
   on ARM7TDMI and ARM7TDMIE
 
   =====================================================================
   Feature                   TMS470R1x(ARM7TDMI) TMS470R1x(ARM7TDMIE) 
   =====================================================================
   Software Breakpoints        Unlimited             Unlimited 
   Hardware Breakpoints        1                     2    
   ROM Debug Support           SingleStep            SingleStep 
   Parallel Debug Manager      Supported             Supported  
   Analysis                    All except EMU        ALL  
   Run Benchmarking            Not Supported         Supported 
   Profiling                   Not Supported         Supported  
   Emulation Control Pins      Not Supported         Supported 
   =====================================================================


INVOKING THE DEBUGGER
---------------------

The emulation controller reset command.  This command does not perform a 
physical reset on the target.  

XDS510WS: emurst -p <port address> r470510ws.out
XDS510PC: emurst -p <port address>
XDS510PP: emurstpp -p <port address> (Windows 95 only)
where, <port address> corresponds to
1. For the XDS510WS this is the SCSI port address
2. For the XDS510PC, this is the address in the I/O space
   the default setting for the XDS510PC is 240.
3. For the XDS510PP, this option is not required.

The following is the syntax to invoke the debugger with minimum command 
line parameters:

emu470 -p <port address> -n <processor name> where, 
processor name is typically user definable via the board.cfg file and the 
resulting board.dat file. 
 

Hardware Installation
--------------------- 
   1. Plug the printer cable into the back of your PC.
   2. Connect the printer cable to the XDS510PP (Win95 only).
   3. Connect the 14 pin cable into your target.  If your target can
      supply 5 volts @300 mA on the XDS PD pin then you are ok.  If
      not then plug
      in the standard XDS510WS power supply plus 2.1 mm power adapter
      into the XDS510PP 5 volt input.

For more details see the XDS51x Emulator Installation Guide.

Software Installation
---------------------
 
1.  Check BIOS to see what printer setup is installed.  You should
     select one of the following modes:
 
     o  4-bit unidirectional mode
     o  8-bit bi-directional mode
     o  EPP, Enhanced Printer Port
 
     EPP is the recommended choice for best performance.
 
     Record the port address of your printer.  The default is usually
     port address 378.
 
2.  Create a file named XDS510PP.INI if it does not already exists.
    Setup the printer     address, printer mode, and optional speed
     parameters in this file.
    Following is an example of one such configuration:
 
       port  = 378
       mode  = EPP
       speed = 10
 
    where,
    port: is the address of your printer port.  Address 378 is
    generally the default address. 
    Mode: is the printer port mode.It must be one of the following
            SPP4   4-bit mode unidirectional mode
            SPP8   8-bit bi-directional mode
            EPP    Enhanced Printer Port,and
    Speed: is a delay parameter that is required on some systems.
 
    It is recommended to set this to 10 initially.  Once XDS510PP 
    is up and running, reduce this number or delete it entirely if
    the system performs nornally.
 
3.   Setup the XDS510PP DLL by copying the file smg510w.pp to
     smg510w.dll.
     The XDS debugger software will work with either the XDS510 or
     the XDS510PP.  When the debugger is invoked it looks for the DLL
     file smg510w.dll.  Your product is supported with a DLL file for
     the XDS510 (smg510w.xds) and XDS510PP (smg510w.pp).

4.   Install your debugger icons and invoke the debugger.
 

IMPORTANT NOTE:
 
o.    When using the debugger with the XDS510-PC card, run the batch
      file smg510.bat.  This batch file copies the smg510w.xds to
      smg510w.dll.
 
o.    When using the debugger with the XDS510PP card (Win95 only),
      run the batch file smg510pp.bat.  This batch file copies the
      smg510w.pp to smg510w.dll.
 

REVISION INFORMATION 
--------------------

When the debugger initially comes up, the command window displays 
the following version information.  This is a typical message for the 
Windows 95 platform using  XDS510.

TMS470 Debugger Version 2.00
Copyright (c) 1989-1998 Texas Instruments Incorporated
ARM7TDMI Silicon Revision 1100e02f                
XDS510 Emulator Revision 3

On the UNIX platform, the line displaying the silicon revision differs
as follows:
 
ARM7TDMI Silicon Revision 0.2.15 

Reading the correct silicon revision is crucial for proper operation
of the debugger. It also establishes proper JTAG connectivity, and
device scan chain integrity.  This is especially useful in
multiprocessor debug systems.  

BOARD CONFIGURATION FILE
------------------------

The board configuration file for a target with only one TMS470R1x at
the target should contain the following information: 
 
"TMS470" "TI470R1x"

The files, 470.cfg and 4al.cfg, provided in the composer directory
with this release are examples of various target configurations.  
Refer to Appendix B 
entitled "Describing Your Target System to the Debugger" in the 'C' 
Source Debugger User's Guide.

Configuring the test-board for Multiprocessor Emulation
-------------------------------------------------------
 
1.  On the LEAD board, place jumpers on the 14-pin header, JP4.
2.  Remove jumper J8 located next to the J7 JTAG connector on the
    LEAD board.
    Install this jumper in its alternate position.  The jumper should 
    now be across the pin pair that is farthest from J7 JTAG 
    connector.
3.  Place a jumper across J9 on the LEAD board.
4.  Connect the 3/5 V JTAG cable to J7 on the LEAD board.
5.  INFO: The TDI-TDO chain is as follows:
          JTAG TDI     -   LEAD TDI
          LEAD TDO     -   ARM7TDMI TDI
          ARM7TDMI TDO -   JTAG TDO



========================================================================
DOCUMENTATION on the TMS470R1x, AVAILABLE FROM OUR LITERATURE DEPARTMENT  
========================================================================

The following is a list of all the documentation which is available for 
the TMS470R1x. Emulator/Debugger:

    TMS470R1x Assembly Language Tools UG, SPNU118 
    TMS470R1x Optimizing C Compiler UG, SPNU119
    TMS470R1x Code Generation Tools: Getting Started Guide, SPNU117
    TMS470R1x C Source Debugger UG, SPNU124
    TMS470R1x Emulator Software Getting Started Guide, SPNU123
    XDS51x Emulator Installation Guide, SPNU070
    JTAG/MPSD Emulation Technical Reference, SPDU079 
    TMS470R1x Simulator Getting Started Guide, SPNU122
    TMS470R1x 32-bit RISC Micro-controller Family User's Guide,
    SPNU134

3. SOLARIS DEVICE DRIVER INSTALLATION (Workstation only)
========================================================

The device driver installation is a five step process.

1. Add the following line into the file devlink.tab.  This file is in
   the /etc directory.
   type=xds510ws;name=xds510;minor=character  rxds510\A1
   (Note: There is a <tab> after "chararcter")  
2. Copy the driver file "xds510" and the driver configuration
   "xds510.conf" into the /usr/kernel/drv on your machine.
3. Run /usr/sbin/add_drv xds510
4. Change permissions on the rxds5104 device as follows:
   chmod 777
/devices/iommu@0,10000000/sbus@0,10001000/espdma@5,8400000/esp@5,8800000/xds510@4,0:character*

5.  Reboot the system with a boot -r option.

Assumptions:
------------

1. User has root privileges.
2. Installation is done on SCSI port 4.
3. There are no other devices on SCSI port 4.

  If the installation is required on any port other than SCSI port 4,
  change the xds510.conf file appropriately.

Removing the driver
-------------------

1. Run /usr/sbin/rem_drv  xds510
2. Remove the links to rxds5104 in /dev
3. Remove the following line from the devlink.tab
   type=xds510ws;name=xds510;minor=character  rxds510\A1
4. Reboot the system.  Not necessary but recommended.


4. Past Release Notes:
======================


Highlights from release 1.10
----------------------------
  o Embedded Breakpoint support.  This allows CIO to be used when
    debugging an application in ROM/FLASH memory without sacrificing 
    the two hardware breakpoints 
    provided by the ICEBreaker.

  o Support for JTAG based POWER-ON reset hold circuit. This feature
    requires some hardware support. The software supports the release 
    of reset to the processor via a JTAG scanable latch.
  

Embedded Breakpoint support:
----------------------------

Abstract
--------
The embedded breakpoint feature allows the user to use the Console
I/O (CIO) 
capability while debugging code in ROM/FLASH memory and still have
two hardware breakpoints available (via ICEBreaker) for normal 
debugging.

What is Console I/O ?
---------------------
Console I/O is a debug facility provided by the TI-debugger which
allows the users to use printf statements linked in from the standard 
I/O library 
(stdio.h) in their code.  The output will be seen under debug, via
the debugger command window. 


Background
----------  
For debugging code in ROM, it is sometimes useful to have Console I/O 
capability provided in the debugger.  When console I/O (CIO) is used,
the application is loaded into the debugger as usual. When the target 
is in RUN mode, the application momentarily stops the processor to 
output data into the debugger command window.  In order to have the 
ability to stop the processor, the debugger has to set 
breakpoints at the location where the console I/O facility begins. 

There are two breakpoints set by the debugger if it identifies that
the console I/O facilities are going to be used by the application.  
If the application is loaded into RAM, there is no need to use the 
CIO, because there is virtually an unlimited number of software 
breakpoints. If the application is running in ROM only a limited number
of hardware breakpoints are available. 

The Problem
-----------
If the entire application is in ROM, and the user has correctly mapped
this area of memory (as ROM), it will be necessary to perform a "sload"
such that the symbolic debug information for the application in ROM 
becomes visible to the debugger.  So, if CIO is in the application, the
debugger will set two hardware breakpoints when the sload command is 
issued.  
However, since the TMS470 has only two hardware breakpoints, there
aren't any left for the user to assist in debugging the code in ROM.  

The solution using embedded breakpoints
---------------------------------------

Release 1.10 supports the embedded breakpoint concept for consoleI/O. 
The application must be linked with the appropriate run-time support 
library(which is provided with this release). The CIO facilities of 
the debugger disable the function of setting breakpoints altogether.

The application instead has the software breakpoint opcode embedded 
in the first word of the code which is responsible for facilitating the
Console I/O function. An embedded breakpoint is nothing more than 
the software breakpoint opcode embedded in the user application.  
Depending on the mode and endianness an embedded breakpoint appears 
as follows in memory (as viewed in the debugger memory window):  

1. An embedded breakpoint in ARM Mode (Big/Little Endian) is
   0xdefed0fe.
2. An embedded breakpoint in Thumb Mode (Big Endian) (A1=0; A0=0) is
   0xdefe
3. An embedded breakpoint in Thumb Mode (Little Endian) (A1=1; A0=1)
   is 0xd0fe

The user can take advantage of this feature by linking in the
appropriate run-time support library provided in this release with 
the application. 

These libraries are as follows:

 Library name  Description
 ------------  -----------
rts32e.lib    RTS library for 32-bis/embedded breakpoint support/Big
              Endian
rts16e.lib    RTS library for 16-bis/embedded breakpoint support/Big
              Endian  
rts32le.lib   RTS library for 32-bis/embedded breakpoint 
              support/Little Endian
rts16le.lib   RTS library for 16-bis/embedded breakpoint support/Little
              Endian
  
JTAG Based POWER ON Reset/Hold Circuit
--------------------------------------
 
As seen on sheet 1 of the schematic (reset.ps) for the evaluation
module, the flip-flop (U4) is cleared on initial power up.  Jumper
JP17 if placed across pins 2-3, enabling the JTAG based RESET
Hold/Release circuit.
 
Place the scannable latch into the JTAG scan chain.  This may be
achieved by connecting the TDO of the last scannable device to 
the TDI (pin 14) of the reset latch. TDO (pin 11) of the latch
must connect back to TDO of the JTAG header.
 
The user should ensure that the board configuration contains all
the devices in the scan chain. Please refer to the 'C' Source
debugger user's guide to get an understanding of how a board
configuration (board.cfg) is created and composed into a
board.dat file.  The appropriate board.cfg and board.dat files
for this feature are included with this release. They are
4LL.cfg and board.4LL respectively.
 
The following functionality is transparent to the user when the
debugger is invoked, but here is how it works.  In the normal
mode of operation (w/o the RESET Hold/Release) the ICEBreaker
Debug control register is written with a value of 0x02. This
sets the DBGRQ bit indicating a Debug Request to the core.  The
The debug status register is read to check if the processor has
asserted the DBGACK bit to acknowledge the Debug Request.
 
With the RESET Hold/Release circuitry in place, a couple of
additional steps take place during debugger invocation. The
scannable latch is scanned via JTAG and the state of the RESET_N
bit is read.  If it is a LOW, the processor is in reset and it
must be released. After the Debug Control Register is written
with the value of 0x02, the scannable latch is used to scan a
'1' into the bit location corresponding to pin 2 of U13.
 
This clocks the U4 flip-flop placing a HIGH on pin 1 of U1A.
This releases the reset on the processor. And because the DBGRQ
bit is set in the ICEBreaker Debug Control Register, the
processor is forced into debug mode immediately after the reset
is released.  DBGACK is set in the Debug Status register as soon
as the reset to the processor is released.
 
Since the RESET Hold/Release circuit will release the processor
RESET only after the debugger is invoked, jumper JP17 should be
placed across pins 1-2 if this is not desirable.
 
COMMENTS ON THE asys470.cmd FILE
--------------------------------
 
This file contains a series of initialization commands which are
used to set up the ARM7TDMIE core's internal watchpoint registers
to a known state, and avoid any undesired behavior of the debugger 
at initialization. For example, it is possible that
the core upon initial power up, comes up in a state where it is
looking for a LOW on its EXTERN pins to meet a halt condition.
 
If subsequently, a user programs the analysis interface with a break 
on a halfword read condition, the device will get programmed to not 
only break on a halfword read condition but also to look for a LOW on 
the EXTERN input. This may result in the user missing the break 
condition altogether.
 
To avoid this, it is recommended that the debugger perform a take
on the asys470.cmd file upon initial power up.
