CWV X SDK - ADDENDUM This document is an addendum to the Software Development Kit for CWvX Processors, Eclipse Edition User Guide (SDK Guide), which describes a Windows-based installation of the SDK. The latest release of the SDK runs on a VmWare Virtual Machine as a Linux guest system inside VmWare s Virtual Machine Player. This distribution includes Virtual Machine Player for Microsoft Windows XP, version 2.5.1. The Player supports other host operating systems, including Mac OS and various Linux versions (available at www.vmware.com). The SDK can run on any host platform supported by VmWare. The SDK is thus now hosted on the (virtual) Linux operating system; however, this version is similar to the Windows-based version, with the exception that the screenshots shown in the user guide are from the Windows operating system instead of from the Linux operating system. For this reason, the SDK Guide is included with this addendum. The addendum lists the differences between the Windows- and Linux-based versions of the SDK, other than the graphics look-and-feel. This addendum assumes that the user is comfortable using Linux systems and an X-Windows screen manager. Throughout this addendum, there are references to Windows filenames, mostly in C:\Program Files\ChipWrights\SDK. The equivalent directory in the VM is /usr/local/bin/cwsdk. Software Development Kit Addendum A-1
A.1 Release Notes This section lists the sections and content from the SDK User Guide that are different for the VM installation. The information in this section supersedes the information in the SDK User Guide. Section 3.2.1 (Mapping your Files to the Projects Directory) is completely obsoleted in the Virtual Machine edition of the SDK. Section 3.4.1: In the Virtual Machine edition of the SDK, openocd is invoked via a desktop shortcut. Section 4.2.3 and elsewhere: in the Windows version of the SDK, the output of a cwvx_isim run appears in a separate DOS console window. In the Virtual Machine edition, that output appears in the Console view of the Eclipse workbench. In the various tutorials, you are sometimes asked to start the MS Windows program HyperTerminal. The nearest equivalent in the VM is MiniCom. The desktop shortcut USB-serial connection invokes MiniCom and connects it to the USB-serial port provided by the Olimex USB pod (see Section [A.7]). To use this port, connect the serial cable from the target board to the USB pod. The USB supplies the equivalent of a serial port over the USB connection. Section 4.4.1: to view various image formats inside the VM, use the gthumb Image Viewer, available from Application > Graphics > Chapter 9: Board Interface Module - is completely replaced with Section [A.9]. A-2
Installation A.2 Installation This section supersedes Chapter 2 of the SDK User Guide. Chapter 2 of the SDK User Guide is obsolete. Depending on your distribution media, physical or electronic, you should have these files: VmWare Player install file Virtual machine archive file. This file is several gigabytes in size, even in its compressed form. A.2.1 Installing VM Player 1) Run the VM Player installer. Expand the VM s archive. 2) Start the player. Browse to the directory containing the expanded VM, and have it start the VM. A boot screen appears, resembling a Linux console. This takes several minutes. A graphic login prompt appears. The available user ID is user; the password is password. (The root password is chipwrights.) The login starts a GNOME desktop. Software Development Kit Addendum A-3
A.3 Setting up the Keyboard After logging in, users located outside the USA should change the Keyboard setting to match their country. Select System > Administration > Keyboard. Select the country. A.4 Setting up the Network In the Devices menu of VMware Player, set the Ethernet device mode to Bridged. A.4.1 Tune the Networking Environment You may need to tune the networking environment. The system makes a DHCP request and adds itself to the local network. Occasionally, it assigns itself a machine name that used to exist on the network. However, the system doesn t know your local network's host names unless you change the name of the host machine. A.4.1.1 Changing the Name of the Host Machine 1) Select Administration > Network in the DNS tab. A prompt appears for the superuser password. Enter the password. 2) Change the name of the machine to: <some-new-machine-name>.yourdomain.com The VM is configured to use the addresses of the ChipWrights local DNS servers, which may be incorrect for an external installation. A.4.1.2 Changing the Network Address Mask If you will be exporting the directories /targetimages and /tftpboot with NFS in order to mount the root file system in a CWvX-ARM Linux system, you may need to change the network address mask in the dialog. 1) Select System > Administration > Server Settings > NFS. The two NFS directories have this setting as their host lists: 192.168.42.0/24 This setting was correct for internal testing in the ChipWrights network. You must change these settings so that these directories are visible on your network. A-4
Installation 1.4.1.3 Restarting the System After you make network changes, a prompt to reboot or restart the networking in your machine appears. To restart as superuser without rebooting, use this command: # /etc/init.d/network restart A.5 Mounting a Windows Directory into the VM This procedure describes how to mount a Windows directory from your Windowsbased machine into the VM. 1) Create a mount point directory anywhere in the VM, using mkdir. 2) Export your Windows directory with Windows sharing. 3) Execute this command as superuser: mount -t cifs -o user=[windows-user-name] //winmachinename/ winsharename /mountpoint A prompt for your password appears. A.6 Mounting an NFS File System into the VM To mount an NFS file system, as superuser type the following: mount -t nfs [serverhostname]:[serverdirectory] /mountpoint The server hostname may need to be a fully-qualified name if you haven't also changed the hostname as described in Section [A.4.1.1]. You can now see all the files on the NFS mount. You do not have your usual write permissions. A.6.1 To Obtain Write Permissions Add a user to the VM with your normal name, uid, and gid. The user is the same person over the network on the NFS drives. Refer to the adduser main page in the VM for more information. Software Development Kit Addendum A-5
A.7 Using the Olimex JTAG Pod To use the Olimex JTAG pod, including its serial port, the VMWare player must have control of the Olimex USB device. This happens automatically if the pod is plugged into the host machine. If not, you must set the VM to control the pod. A.7.1 To Set Control Over the Olimex USB Device 1) Connect the VM to the pod. You do not need to install a host (Windows-based) device driver for the Olimex pod to use it in the VM. 2) To ensure that VM recognizes the USB device, run the program usbview in the VM. A list of USB devices connected to the VM appears. If you ve installed the Olimex drivers on the host typically MS Windows -- the VM recognizes the device as Olimex OpenOCD JTAG. If the drivers are not installed, but the device is connected to your (real) computer, a reference that includes the string 0x15ba (Olimex s vendor id), appears. In either case, the VM should be able to control the both the JTAG and serial ports of the pod. The VM recognizes many standard USB devices, such as card readers. Plug the USB device in. If it is a recognized device, the VM sees it. Only root (Linux superuser) can directly access USB devices. For a card reader, Linux (as root) mounts the device as a file system, and it should work as normal. For other devices, it may be necessary to become a root user to access the device. A-6
Disk Space Usage A.8 Disk Space Usage The VM's virtual disk holds 100 Gigabytes of data (maximum). When you first install the VM, the virtual disk uses only as much real storage as necessary to store the virtual files that are on the virtual disk. As files are added, more real disk space is allocated so the VM's directory on the host system increases. However, when virtual files are deleted, that real disk space is not released. As a result, if you add and delete files repeatedly, the real disk usage keeps increasing. A.8.1 Reorganizing the Virtual Disk to Save Disk Space You can run the # vmware-toolbox tool inside the VM to reorganize the virtual disk so that it is only as big as necessary to store its files. The program runs in two stages: first inside the VM; after the stage is run, the VM is suspended. Next, an external part of VmWare completes the shrinking process. This process can take up to one hour. 1) Run the tool # vmware-toolbox You must be root to run this program. 2) Navigate to the Shrink tab. Select /. Shrink the disk. Software Development Kit Addendum A-7
A.9 Board Interface Module (BIM) The Board Interface Module (BIM) is a software application that communicates between the Hardware Development Kit board set and CWvX debugger. It s a server that does not respond directly to text input, although it displays status messages. You can invoke BIM from the desktop shortcut. In the ChipWrights SDK, the CWvX debugger must communicate with the target hardware. The BIM operates between the board and the client applications, sending, receiving and translating messages. You must launch BIM before launching a CWvX debug session. A.9.1 Launching and Running BIM To launch and use BIM, perform the following steps: 1) Supply power to the HDK board set, making sure that the JTAG connector is attached. 2) Double-click on the gray CW-BIM icon. If the board is connected properly, the BIM screen containing the following messages appears: The previous screen shows BIM connecting to a CW5631 processor on a Gallops board. Other ChipWrights processors provide similar output. While the CWvX debugger is running, the BIM screen displays error messages and status information. A-8
Board Interface Module (BIM) If used, a BIM initialization script initializes the CWvX processor by resetting it, enabling the clocks, and initializing the DRAM. You must use the correct initialization script for the hardware platform. The most likely scripts are as follows: Gallops5521_init_300.cmd Gallops5631_Init.cmd These scripts are in the directory cwvx/scripts in your SDK installation. You can select the scripts in the Windows shortcut for BIM, by using the -script option (see below). A.10 BIM Options Table A-1 BIM Options General Options -log <logfile>: Log file (replicates screen output) Startup Options -start <script>: Startup script run on connection. This is a script of commands of kind used by board_comm. (see Section 8.4). -srst_on_startup: SRST on startup -trst_on_startup: TRST on startup 5631-only Options -debugsap: (5631 only) Open debug ports to both DSP and SAP -breakusesinterrupt: (5631 only) breakpoint should use BREAK/interrupts (default is HALT) (see -breakusesinterrupt (page A-10)) Network/port Options -daddress <address>: numeric ip address of machine running debugger (defaults to 127.0.0.1) -dport <port>: tcp port used by debugger (defaults to 1500) -haddress <address>: numeric ip address of machine running board_comm. (defaults to 127.0.0.1) -hport <port>: tcp port used by board_comm (defaults to 1501) The defaults for these options are usually correct. Communication Options -par: Use parallel port for jtag (default) -usb: Use usb port for jtag -speed <num>: JTAG speed (0=fastest, 8=slowest) -v: Verbose jtag probe Board Configuration Options -chain <string>: Jtag chain descriptor (see -chain (page A-10)) -board <string>: Board type: "Gallops", "C6C", or "custom" Gallops and C6C set the values appropriately for rest of the flags in this category. -resetsigs none both srst trst: Describe which reset signals are connected to anything -resetcombo srst_pulls_trst trst_pulls_srst combined separate: Describe how reset signals are connected -[no]srst_push_pull: [No] SRST is push/pull (vs. open-drain) -[no]trst_push_pull: [No] TRST is push/pull (vs. open-drain) Software Development Kit Addendum A-9
Table A-1 BIM Options (Continued) BIM message logging -dumpcmds: Show bim transaction requests -dumpresponses: Show bim transaction responses -dumpdata: Show data in requests/responses (can generate copious output) -jdebug <num>: Debug JTAG communication itself (levels 0-3) -breakusesinterrupt Breakpoints are implemented by replacing the target instruction with some other CWvX instruction, either a HALT or a BREAK. These have different effects: If HALT instructions are used, any arbitrary program can be debugged. However, a breakpoint on the DSP or SAP does not propagate to the other core in anything like real time, since BIM must notice (through polling) that one of the cores has stopped and then stop the other. If HALT is not used, a BREAK instruction is used, which only works if a BREAK interrupt handler is installed and enabled. Our sample programs and sample support libraries do this. When a breakpoint is hit, the handler stops the other processor within a few cycles. There is one serious limitation: the BREAK instruction needs a breakpoint interrupt to do its work. If you hit a breakpoint when interrupts are off either because you're in an interrupt handler already, or your code has explicitly turned the interrupt enable bit off the breakpoint does not stop the processor. Even worse, because this scheme involves temporarily replacing a real instruction in your code with a BREAK instruction, your code does not execute that instruction but still continues. For this reason, the HALT is the better choice unless, when one processor hits a breakpoint, you need the other processor to halt immediately. -chain If no chain information is given, BIM assumes that there is one CWvX processor on the chain and nothing else. (This is correct for the ChipWrights HDK board.) The format is as follows: One or more devices, separated by commas Each device is of the form NAME:#-of-ir-bits:number-of-bypass-bits:JTAG-IDCODEinstruction Device names beginning with CW are assumed to be the CWvX processor. For example, if the CWvX's DSP and ARM are wired in series on the board, the chain descriptor is: CWDSP:4:1:2,ARM926EJS:4:1:0xe A-10
A.11 Getting a License Key To run the CWvX linker, you must have a license key. 1) To get a license key, start the VM and run the program: % /sbin/ifconfig -a 2) Email the output to support@chipwrights.com. ChipWrights will send you a CWlicense.dat file. 3) Put the CWlicense.dat file in /usr/local/bin/cwsdk in the VM, using tftp to send the file from your host to the VM s /tftpboot directory. This license corresponds to the (virtual) MAC address of the VM, which is automatically generated and differs for each installed copy. Software Development Kit Addendum A-11