(Note that this section completely obsoletes the current manual s Chapter 2.)

Transcription

1 July 7, 2010 ChipWrights SDK (VM Edition) Installation and Release Notes This is the VM edition of the ChipWrights SDK. It runs as a Linux (CentOS) virtual machine inside an existing Windows or Linux machine. All documentation for the older, Windowshosted SDK applies to this edition, except that all windows look like Linux windows instead of Windows programs. In addition, certain Linux-specific issues are detailed in this document. INSTALLATION NOTES (Note that this section completely obsoletes the current manual s Chapter 2.) Initial Setup Go to and download the latest version of the VMware Player installer. Note that the current distribution of the ChipWrights SDK has been tested using VMware Player Version 3.0. Depending on your distribution media, physical or electronic, you will have an archive of some sort for the virtual machine. This file will be several gigabytes in size, even in its compressed form. Run the VMware Player installer, and then expand the VM s archive. Start the player and browse to the directory contained the expanded VM, and have it start the VM. You ll be asked whether you moved or copied the VM; answer copied. You ll see a boot screen as if you were looking at a real Linux console. (During the time from the beginning of the boot process to the appearance of the graphic login prompt, the only way to switch mouse control in and out of the VM is with Ctrl-A, as is mentioned in the player s status bar. Once you ve logged into the desktop, the mouse will move in and out of the player transparently, and cut-and-paste will be enabled between the VM and your non-virtual applications.) The boot process will take couple of minutes; eventually you ll see a graphic login prompt. The only user id available is "user", and the password is "password". (The root password is "chipwrights".) The login will start up a GNOME desktop. Updating from RPMs If you had an earlier version of the virtual machine release, you can update your installation using ChipWrights-supplied RPMs. Currently, there are three RPMs: cwsdk-2.1-#####.noarch.rpm cwsdksys-2.1-#####.noarch.rpm cwsdk-tools-2.1-#####.noarch.rpm

2 (The ##### represent build numbers, which may vary.) To update your installation, make these RPM files available to your VM, either by tftp-ing them into the VM or by mounting an external file system on the VM and putting those files on that file system. Then, as root (password is chipwrights ), apply the RPMs with # rpm Uvh cwsdk*.rpm There is one further rpm to install; this rpm installs a specific version of the svn configuration management system so that the Eclipse plugin SubClipse can do svn operations. Install this with # rpm Uvh CollabNetSubversion-client i386.rpm Keyboard Setup After logging in, users outside the USA should change the Keyboard setting to match their country. This is in the menu System->Administration->Keyboard. Network Setup Be sure that the Devices menu of VMware Player has the Ethernet device mode set to Bridged. The networking may need some tuning for your environment. As it is, it makes a DHCP request and adds itself to the local network. However, it won't be able to refer to your local network's host names in their unqualified form (without <yourdomain.com>) unless you change the name of the host machine. You can do this from Administration->Network, in the DNS tab. (It'll prompt you for the superuser password.) You need to change the name of the machine to <some-new-machine-name>.yourdomain.com Also note that the VM is currently configured to use the addresses of the ChipWrights local DNS servers, which will probably not be correct for an installation outside of ChipWrights itself. That setting is also in DNS tab. Users who will be accessing the files that the VM exports with NFS in order to mount the root file system in a CWvX-ARM Linux system will probably have to change the network address mask in the dialog System-->Administration-->Server Settings-->NFS The two NFS directories there have this setting as their "host lists": /24

3 This was correct for internal testing in the ChipWrights network. You'll have to change these settings so that these directories are visible on your network. After you make any of these network changes the system will suggest that you reboot or restart the networking in your machine. You can do this without rebooting -- again, as superuser -- with the command # /etc/init.d/network restart A note: some users have found that the VM occasionally loses contact with the networking on the host, to the extent that the above restart command does not complete properly it waits for a very long time when trying to get an IP address, then reports failure. Some things that have helped in this case have been: Confirm that the Network device is in Bridged mode, on the Devices menu of the VMware Player Check the Properties of your Windows host s Local Area Connection and confirm that the VMware Bridge Protocol is on that list Check the Services of your Windows host and make sure that all of the VMware services are Started. Mounting external file systems in the VM To mount a Windows directory from your real Windows machine into the VM: -- create a "mount point" directory anywhere in the VM, using mkdir -- export your Windows directory with Windows sharing -- execute this command as superuser (all one line): mount -t cifs -o user=[windows-user-name] //winmachinename/winsharename /mountpoint The command will ask for your Windows password. To mount an nfs file system, again as superuser: mount -t nfs [serverhostname]:[serverdirectory] /mountpoint Note that the serverhostname may need to be a fully-qualified name if you haven't also changed the hostname as described above. After this, you'll be able to see all the files on the nfs mount, but you won't have your usual write permissions. To get that, you'd need to add a user to the VM with your normal name, uid, and gid; then that user will be the same person over the network on the NFS drives. See the adduser man page in the VM for more details.

4 Tftp Server Another way of getting a few files into and out of the VM is to use the tftp server that is running on the VM. You can connect from another machine with the tftp command, and then use get and put to move files back and forth. Note that some versions of Microsoft Windows do not have a tftp client, although one can be downloaded from the Internet; Linux machines generally do have a tftp client. The tftp directory in the VM is /tftpboot. Debugging DSP/SAP Code on a CW5631 ARM Linux Target The VM includes an ARM linux distribution, in the directory /targetimages, that is intended to be exported over NFS and run by the ARM core of the CW5631. In order to make it easier to debug code running on the CW5631's DSP and SAP, we provide a cwvx gdbserver in this ARM linux distribution. This works as follows: start the DSP code on the CW5631. start the cwvx-gdbserver on the ARM linux console: # cwvx-gdbserver localhost: attach -1 The "55555" is arbitrary but must match the value that you set up later in the Eclipse debug panel, below. The --attach -1 must be given as you see here; it's a fake "process id" because the DSP code is not actually a linux process. You should see, in the above example, Attached; pid = -1 Listening on port The cwvx-gdbserver now waits for a connection. go to your Eclipse session on the VM itself, and create a new Debug Configuration for your target program. Set this configuration up in the Debug Configurations panels as a new CWvX Application, and fill in the Project and the C/C++ Application as usual. (You can copy this configuration from an existing configuration of the same executable, to start.) In this configuration, the.elf file given must exactly match the.bin file that's running on the CW that is, the.bin should have generated from the.elf by the build process. Go to the Debugger tab of the dialog, and change the Debugger to "gdbserver Debugger". Turn off "Stop on startup", and make sure that "Execution target" is "Board", and "Attach to running board" is selected. In the Debugger Options subpanel, make sure that the GDB debugger is "cwvx-gdb" and not "gdb". Finally, go to the Connection subpanel and select Type TCP, fill in the target CW5631 linux's IP address, and enter the port number that matches the cwvx-gdbserver invocation ("55555" in the above example).

5 You can now debug the program. Once connected, you'll see two "threads" in the Debug view; these actually correspond to the two processors, the DSP and the SAP. The two threads will either be stopped at the locations the processors were at when the debugger connected, or, more likely, they'll seem to be running. In that second case, sekect the "gdbserver Debugger" line in the Debug view and then click the pause button. Both "threads" should then stop. You can examine each processor's stack and variables from its "thread". To resume, re-select "gdbserver debugger" and click the continue button. Real-Time Profiling Feature The software tools now support program profiling on hardware as well as on isim, in a form that's compatible with the standard Linux "gprof" tool. Here's how you use it: To your program, add a buffer for the profiling samples, and some calls to set up and start profiling: #include "timestamp.h"... #define TIMEBUFSIZE static int dspbuffer[timebufsize]; // for comparison: is just about enough for 5 frames of mp4 videoencode at 640x cc_enable(); timestamp_init(0, dspbuffer, TIMEBUFSIZE); timestamp_set_enabled(0, 1); // First arg to both of those functions tells which core to monitor. For dsp and sap profiling, you need two separate buffers and sets of timestamp_init and timestamp_set_enabled calls. 0==dsp, 1==sap. Rebuild your program with -pg. Both C and Cas allow this option. In Cas, only routines with PROLOGUE/EPILOGUE will be instrumented. Note that uninstrumented routines, including system runtime library routines, will have their samples included with their callers. Now run your program. Once you're done, you need to get the samples buffer back to the host system. In isim, this is easily done by adding this to the.cfg file: isim_output_section { write dspbuffer into "profiling.samples" length ; }

6 Under hardware, the user must work out some other method of getting the samples data back to the host. Once you have your samples file, run the new tool samples_to_gmon: % samples_to_gmon profiling.samples elf-file.elf [optional-output-name] The optional-output-name defaults to gmon.out, which is the default name for gprof's samples file. Finally, run the standard Linux program gprof: % gprof elf-file.elf will produce both a flat profile, with times in milliseconds, and a call graph, in standard gprof format. Olimex/USB issues In order to use the Olimex jtag pod, including its serial port, the VMware player must have control of the Olimex usb device. This should happen automatically if the pod is plugged into the host machine. If not, use Devices menu of the VMware player to connect the VM to the pod. (You do not need to install a host (Windows) device driver for the Olimex pod in order to use it in the VM.) If you are not sure if the VM is seeing the USB device, run the command % usbview in the VM. You'll see a window listing USB devices connected to the VM. If you ve installed the Olimex drivers on the host typically MS Windows -- the VM will list the device as "Olimex OpenOCD JTAG". If you ve never installed those drivers, but only connected the device to your (real) computer, you ll see a reference to something whose name includes the string 0x15ba, which is Olimex s vendor id. In either case, the VM should be able to control the both the JTAG and serial ports of the pod. There are also two other desktop shortcuts for accessing serial ports. One, labeled Read-serial- COM1 connection will control a serial line connected to the normal serial port on your host computer, if it has one. The other, labeled Other-USB-serial connection will control a serial port that s part of a common USB-to-serial adapter, aside from the Olimex adapter, if one is plugged into your host computer s USB port. These are provided to make it easy to have two serial connections to CW5631 hardware, one to the ARM s serial port and one to the DSP s. Note that the VM can, in addition, recognize many standard USB devices, such as card readers. Simply plug the USB device in, and if it s one of those recognized devices, the VM will see it. However, only root (the Linux superuser) can directly access usb devices. In the case of a card

7 reader, Linux (as root) will mount the device as a file system, and it should work as normal. For some other devices, it may be necessary to become root in order to access the device. Disk Space Usage The VM's virtual disk can hold up to 100 Gigabytes of data. When you first install the VM, the virtual disk uses only as much real storage as is needed to store the virtual files that are on the virtual disk. As files are added to the virtual disk, more real disk space is allocated, so the VM's directory on the host system will increase in size. However, when virtual files are deleted, that real disk space is not released. As a result, if you add and delete files repeatedly, you'll find that the real disk usage keeps increasing. There's a tool that you can run inside the VM that reorganizes the virtual disk so that it once again is only as big as it needs to be to store its files. You can run this tool with # vmware-toolbox Note that you must be root to run this program. Go to the "Shrink" tab in that program, select '/' and shrink the disk. The program runs in two stages. The first stage is a process inside the VM. After this stage is run, the VM is suspended, and an external component of VMware completes the shrinking process. The entire process can take up to an hour. General Issues Although in general you can suspend and resume the VM arbitrarily, sometimes after a suspend/resume the VM will start to use as much of the host CPU as it can. This has generally been in caused by bim and/or minicom coming out of the resume state incorrectly. Shutting those down and restarting them clears it. As a workaround, it s better not to suspend with those programs still running. Release History Release 2.1, July 7, 2010 CWvX tools: New features: The various standard tools that underlie the CWvX tools have been upgraded as follows: Eclipse and CDT 6.0.2, collectively known as the Galileo release of Eclipse; and gdb For those users upgrading through RPMs rather than through replacing their VM: note that there are now several rpm files. The old cwsdk is replaced by a new cwsdk, which contains the Eclipse/CDT installation, and a new cwsdk-tools, which includes

8 the ChipWrights-specific plugins and language tools. This will allow more-convenient updating of the cwsdk-tools between now and the next major release, when Eclipse, which is on an annual release cycle, will be updated again. Also for RPM users: the Eclipse installation now includes the SubClipse plugin, which is an Eclipse interface to svn (subversion). The plugin requires svn 1.6, which can be found in the supporting rpm file CollabNetSubversion-client i386.rpm. (Note that the plugin requires the Collabnet version of Subversion, in particular.) The Cas,section modifier zero_fill has been changed to no_fill, for clarity. The previous syntax is allowed but is deprecated with a warning. The compiler now supports this new pragma: #pragma no_preg_prologue_save [on off] Use this with care. When this setting is on, parallel registers in the saved group (P14- P30) will not be preserved in the prologue/epilogue. This saves cycles, but the programmer must be sure that the code in question is not called from any other code that expects these registers to be preserved. Isim now warns if a DMA is set up with a non-aligned source or target. The compiler now allows multi-line inline asm blocks to be surrounded with parentheses, in addition to the existing {} syntax. The parenthesis form allows the Eclipse source code browser to parse the asm blocks, ignoring the code inside the block and then resuming the parse after the block. Previously, the {} syntax had caused spurious parse errors during and after the asm block. The earlier syntax will continue to be supported. Cas now gives warnings about FOR_x loops with fewer than three instructions. These are legal for the current CW5631 and earlier processors, but it is anticipated that a future chip design will disallow these loops. The inline assembler is now more capable of emitting scratch instructions in order to handle memory operands that are used where the CWvX instruction itself requires a register. Because of the above change, inline asm now gives warnings on the explicit use of the S1 register in code. This register is reserved for those cases where the compiler needs a scratch register in order to emit the desired final instruction. Bugs fixed: Internal error in 'PCodeUtilities.c' line: 1394 attempt to create FOR-instruction based loop could go wrong Tag registers could spill to stack and then not get reloaded when need by their $SP register, in inline asm BALIGN use in inline asm could result in bad code memset(), when executed by the SAP on fully-aligned destination addresses, did not write out four copies of the input byte for each longword; only a bug if the fill value was not 0. Inline asm code with FOR instructions could get bad register allocation

9 In Eclipse debugging, the working directory for a Launch Configuration was not honored, causing the simulator to be unable to find its.cfg file. In Cas, unions with bitfields in them could get laid out incorrectly. The simulator-based host i/o routines added in the last release did not properly include lseek() and fstat(). Release 1.05, January 7, 2010 CWvX tools: New features: Bugs fixed: Programs running under the simulator can now do normal hosted file i/o using fopen, fread, and other typical ANSI C functions, and the host will carry out these operations on the host file system. This makes it easier to write code that can run both in a purely native build for the host machine, and under simulation. Note that this requires support from the version of the standard ANSI C runtime library included with the software tools. The profile argument to cwvx_isim now takes an optional filename. In addition to the existing profile output from the simulator, the tools now support traditional profiling with call-graph output, using the standard Linux tool gprof. This is described in a separate section, above. The C compiler s inline assembler was rejecting some uses of subtraction in parallel instructions, where the underlying instruction only had an addition form. The compiler now correctly uses an addition of a negative number in this context. Bim (and thus board_comm) would fail in cases where it was asked to write a 4-byte item that was not aligned at a 4-byte boundary. The C compiler s inline assembler gave incorrect assembly for some forms of the RDTTA and WRTTA instructions. The Cas assembler was not reporting an error on an illegal (non-multiple of 4) stride operand. Vectorizing of short arrays gave bad output when using the += operator to sum over the entire array. An illegal use of a tagged operand with the RDTTA instruction was not reported as an error by the simulator. The simulator had some incorrect stall computations for the RDTTA instruction. In Cas, typedefs of structs that referred to struct pointers of the same type inside the structure would variously crash the assembler or (incorrectly) report an error. The compiler s peepholing sometimes gave an internal compiler error in the presence of parallel i/o instructions (RDS, WRS, and others). General:

10 All installed Centos packages have been updated to their latest versions as of December 15, Release 1.04, September 28, 2009 CWvX tools: New features: In the C compiler, inline asm now supports the structured parts of the CAS language: multi-line then and else clauses, do-while loops, and structured use of the FOR instruction. Note that despite the increasing similarity to the C language, each ifcondition must correspond to a single CWvX instruction; the same applies to while clauses, which are actually backward-branching IF instructions. The compiler now honors the restrict keyword, which is a promise by the user to the compiler that a pointer declared with restrict will not point to the same storage as any other pointer. This allows more optimizations, especially in re-ordering reads and writes to avoid stalls. Further, the compiler now supports the command-line flag, and corresponding #pragma -pointersnoalias, which indicates that all pointers declared while the option/pragma is active are to be considered restrict. If used indiscriminately this option can create invalid code, so use it with care. In cwvx_isim, if the PC is about to jump into a region that s not part of any executable section in the ELF file, the simulator now generates a warning. In cwvx_isim, the execsap option cause the simulator to start the SAP, not the DSP. Normally the simulator starts the DSP and not the SAP, leaving the DSP to start the SAP from code. The simulator now supports a magic routine name, _Isim_printf(), which can be used to cause the simulator itself to do the output formatting that a target-side printf() might otherwise do, thus saving the simulation time of that formatting. When the PC goes to the location of that routine, the simulator examines the stack arguments to the routine and does all of the output (to standard output) itself on the development machine. The _Isim_printf() routine itself should be an empty routine. Note that it must be declared varargs as with printf(). The simulator supports runtime range checking with the rangecheck option. This option requires support from the running code; such support is built into the default libraries supplied with the release, and if rangecheck is on, the simulator will verify that pointers that are returned from malloc() do not end up pointing outside their valid boundaries, and that the stack and frame pointers do not access memory beyond the boundaries of the stack. Specifically, the support code uses the simulator-only control registers C26, C27, and C28. The interface is as follows: C28 = Sx; C28 = Sy; // need both values to create the range

11 This sequence creates a range with the values of Sx and Sy as the boundaries, in either order. The range itself is then attached to the register Sy, and future memory references through Sy or through any register whose value is tracked as coming directly or indirectly from Sy, will be checked against that range. C27 = Sy; This removes the range information from the register Sy. Sx = 1; C28 = Sx; This disables range checking. Sx = 2; C28 = Sx; This re-enables range checking, if the rangecheck option to the simulator has been used. Bugs fixed: General: When gdb, or the Eclipse debugger, was asked by the user to write a 2-byte value into target memory, it actually wrote 4 bytes. Inline asm single-stepping now works, rather than jumping to the end of an entire multiline inline asm block. In some cases, gdb/eclipse would lose the value of locals in routines that were not currently at the top of the call stack. In cwvx_isim, the isim_init_section part of the.cfg file did not correctly handle negative or float values. When attaching to a running board, bim had no hope of communicating the values of parallel registers back to the debugger. If the VM and/or its host machine was in a state where the VM couldn t get a TCP address, the licensing for the CWvX linker failed. Mixing simulator profiling and debugging often resulted in a truncated, or zero-length, html profile. All installed Centos packages have been updated to their latest versions as of Sept. 2, Release 1.03, June 26, 2009 Desktop:

12 CWvX tools: General: Several useful documents about the CWvX architecture and tools are now available from a folder on the desktop. There are two new shortcuts on the desktop to support serial connections. One connects to the host computer's COM1 port. The other will connect to any usb-to-serial adapter that is installed on the host computer, with the exception of the olimex jtag/serial device, which already has its own shortcut. These have been added so that users can connect to the DSP and ARM uarts at the same time. The linker had a problem where it was very slow creating the closure part of the xmap file; this has been improved. A compiler bug in inline asm has been fixed; the triggering case was a complex interaction of tagged pointers with other, normal serial registers. All installed Centos packages have been updated to their latest versions. The ChipWrights SDK and its support tools are now installed from rpms, for easier updating in the future. Release 1.02, May General linux environment: Compiler: Assembler: Simulator: The serial usb device name is now fixed at olimex-usb-tty, and the connection to it is more stable The compiler's handling of RDS instructions of the form RDS (POSTADD ($in0, ndp4), 4) in inline assembly code was wrong The assembler did not always agree with the compiler in laying out structures with oddlength fields Cas options: added -enum [min int] as in the compiler, and fixed bug where -numdp option was ignored The simulator would scribble over simulated memory when a parallel instruction triggered a watchpoint The simulator has improved accuracy in stall computations for the CW5631

13 If a loop was not executed because its condition was false the first time through, the simulator was not setting PE to 0 Release 1.01, March 2, 2009 In order to run the cwvx linker, you must have a license key. To get a key, once the VM is started run the program % /sbin/ifconfig and the output to support@chipwrights.com. ChipWrights will send you a CWlicense.dat file; put this in /usr/local/bin/cwsdk in the VM, using tftp to send the file from your host to the VM s /tftpboot directory. Note that this license is tied to the (virtual) MAC address of the VM, which is automatically generated and will be different for each installed copy of it. [Note: as of Release 1.04, the command to be run above is % /sbin/ifconfig a ] CWvX tool bugs fixed: In Cas, some struct alignment cases were wrong. In the compiler s inline assembler, some operands of some parallel instructions were not properly tracked into and out of the inline assembler blocks. In cwvx_isim, watchpoints in pmem were not working In dsp/sap simultaneous hardware debugging in the attach to running board case, the sap was never started after the debugger s initial connection. New features added: In board_comm, the command read ahb [address] is now allowed as an abbreviation for read ahb [address] 1 In board_comm, the new command treset will reset the jtag connection without resetting the rest of the target hardware The VM now attempt to keep its system time synchronized with that of the host computer In addition, the usb connection between the host usb device and the VM has been made more reliable, particularly in the case where the usb has been physically disconnected from the host computer and then reconnected. Release 1.00, Jan Initial release

14