vxworks jtag access thomas turney - florida gulf...

1

VxWorks JTAG Access

Thomas Turney

Final Draft

4/30/2015

CEN 4935 Senior Software Engineering Project

Instructor: Dr. Janusz Zalewski

Software Engineering Program

Florida Gulf Coast University

Ft. Myers, FL 33965

2

1. Introduction

The objective of this project is to interface the single board computer SBC83XX Power QUICC

II Pro Workbench with WindRiver ICE 2 JTAG debugger through VxWorks real-time kernel.

JTAG, or Joint Test Action Group, is a standard implemented by IEEE Std. 1149 [6]. The JTAG

will enable an interface to view a graphical display of the scan chain and allow viewing of

registry components of the Workbench machine. This allows diagnosis of complex errors within

an embedded environment to be done within the bounds of the real-time operating system,

without sacrificing how the VxWorks system should be configured. This is important for large

scale programs that work on specialized hardware, as the JTAG debugger will give a full view of

the system and can bypass any of the hardware access restrictions that are imposed.

3

2. Project General Description

Figure 1: QUIOCC II Reference Board

The embedded computer, known as VxWorks SBC83XX Power QUICC II Pro, is a reference

platform 6U board for VxWorks development. It interfaces through RS-232 Mini DB9

connectors to a Host computer, and can communicate to the ICE 2 JTAG debugger through a

PCI-X controller bus with a 52 pin connector [1]. Figure 1 displays the Power QUICC II

reference processor. In this figure, the importance is that the processor runs as a real-time

system, and any programs to run have to be loaded directly onto the board in order to be

processed. The reference boards allow one to upload and view results of the program through a

Host machine. For VxWorks, the system being used is Windows XP.

4

Figure 2: VxWorks Workbench Startup

Wind River Workbench, shown in Figure 2, is the software component that can interface with

the VxWorks machine, either through RS232 or Ethernet upload. The Workbench is a

repurposed integrated development environment, or IDE, of Eclipse. The Workbench supports C

and C++ development over x86, SPARC, MIPS, and PowerPC CPU architectures [2]. Since

Workbench is a graphical based development suite, debugging cannot be accessed after the

completed code is uploaded to the VxWorks machine. To interface with the VxWorks machine

to see the output and running state, command line utilities would have to be used.

As programs become more complex in real-time machines, debugging efforts become more

difficult over command line. The JTAG standard, however, addresses this difficulty by allowing

OCD, or On-chip debugging tools, to monitor the VxWorks machine while it is running through

code [3].The purpose is to observe and modify circuit behavior during the normal operation [6].

5

Figure 3: JTAG Debugger

Figure 3 shows the JTAG debugger, which can connect through the 52 pin connector. The

second port, USB, allows connection to an external machine to view and manipulate the

VxWorks environment.

Figure 4: Full Stack of a VxWorks machine

6

JTAG allows many features of on chip debuggers. Figure 4 lists the full stack of a VxWorks

machines, which the JTAG debugger can access. Among these are multicore debugging up to 16

CPU cores, RAM cache viewing and modification, flash programming to the boot loader, and

kernel level interaction [4]. JTAG is also known as an ICE debugger, which stands for “In-

Circuit Emulator”. An ICE is defined as an emulation state where the internal state of the system

can be modified [5]. This project aims to implement these emulation states and showcase them

within sample programs executed on the VxWorks machine.

Figure 5: VxWorks command line Debugger

A benefit of JTAG debugger is that it can interface within the Eclipse environment. Within

VxWorks, all threads can be viewed through the command line, shown in Figure 5. This is a

built-in utility the VxWorks kernel provides, but can be cryptic. Within Figure 5, it is hard to

determine what name corresponds to with regards to TID, or Thread ID. While we can view

7

which name corresponds to a CPU #, the built-in utility does not give any information on what

the current state of the registers are, or the name of the currently running program. The built-in

utility does show threads that are not currently being processed within the CPU, but does not

show how much the threads are utilized by the CPU, which are features that a graphical

debugger provides. By using JTAG, a more concise and understandable debugger can be

provided, which can speed up development time and decrease the time for debugging complex

threading or processing errors.

8

3. Software Requirements Specification

The primary objective of this project is to run the JTAG debugger on the VxWorks WindRiver

platform, as well as validating the WindRiver platform is functioning properly. In order to

complete these objectives, certain requirements must be met. These requirements must allow for

a VxWorks system to boot, interface with the Host computer, and accept communication from

the JTAG debugger. The previous projects on VxWorks have registered the WindRiver

Workbench within the FGCU lab, so the requirements will have to be within that environment.

While one machine is currently functioning as a host, the aim for the end of this project is for a

secondary VxWorks machine to boot and for the JTAG debugger to interface within the system.

Figure 6: Physical Diagram

Figure 6 displays the scenario in which the VxWorks machine will interface through with JTAG.

First, the user will develop the software on the WindRiver Workbench, located on the Host

machine. Once development has completed, the code is executed with the JTAG debugger. The

JTAG debugger will interface through the 52 pin connector to the VxWorks machine processor,

which will execute the code instructions.

The processor will do this in real time, but the JTAG will still be able to update the Host

machine on all of the processor states of the VxWorks machine. The Host machine can choose to

modify registry segments, cache, or memory locations while the QUIOCC II processor is still

running, and the JTAG debugger will apply those changes to the machine.

9

Figure 7: Context Diagram

The context diagram, shown in Figure 7, highlights the key I/O aspects used when running the

JTAG debugger. The initial code upload from the Host through the mini DB9 connection sends

the instructions to the processor. The VxWorks system on the QUIOCC II, as it begins

executing, sends status messages to the JTAG through the 52 pin connector. JTAG will then

relay the status to the Host. While the QUIOCC II is processing, the Host can choose to send

commands back to JTAG via USB connection. The JTAG can then send commands to the

QUIOCC II processor. This allows the state of execution to change, as a new command is now

put as an instruction that can compromise the existing commands that have been executed. This

is where the in-circuit emulation occurs within the project.

Following the description of the software functionality, the requirements can be stated as

follows:

1. The Host shall upload code from Workbench to the VxWorks QUIOCC board.

2. The Host shall enable the JTAG debugger through the Workbench.

3. The QUIOCC II processor will execute code that is uploaded from the Host.

4. The QUIOCC II processor will give a status of its processing state to JTAG.

5. The JTAG machine shall relay to Workbench in a graphical format the status of the

QUIOCC board.

6. The Host shall modify a register on the QUIOCC board.

7. The JTAG machine will relay any modification commands to the QUIOCC II processor.

8. The QUIOCC Processor will apply any commands from the JTAG debugger in real-time.

10

4. Design Description

Figure 8: Architectural Diagram of the JTAG Debugger

Figure 8 presents the internal architecture of the JTAG debugger and how it interacts between

Host and VxWorks machines. The arrows to the right of the JTAG diagram are towards the

VxWorks machine, which sends and receive commands to/from the VxWorks Board Interface

module. The module will only relay commands to the Status Display, which outputs to the Host

machine. The Host machine can choose to send a command through the User Command

Manager, which will update the Status Display to state that the command is being executed. The

User Command Manager will also send the command for execution through the VxWorks Board

Interface, which will be processed on the VxWorks machine.

11

Figure 9: Sequence Diagram

A dynamic perspective is shown in Figure 9, which displays the sequence of steps performed by

the software. Since the system is a real-time based system, the sequence is expected to execute

exactly in order. With the JTAG debugger, the ability to send commands, as shown on the

sequence diagram, gives higher priority to the VxWorks machine that the current instruction set

being executed. This allows to break the real-time system constraints in a way that does not

compromise the software, but enhances debugging efforts.

With the Host, the diagram begins by initializing JTAG and the VxWorks machine. After

uploading code, the VxWorks hits an execution state that sends a status back to the JTAG

debugger (step 5). The JTAG will relay this status message back to the Host (step 6). Whenever

code is modified by the Host (step 7), this is relayed to the JTAG and the execution is modified

12

in VxWorks with the Update (step 9). Status is also still being set though step 5 in the real-time

environment.

13

5. Implementation and Testing

5.1 Implementation

Before starting any programming, proper connecting of hardware and Installation of

VxWorks needs to be done, which is described in Appendix A.

With the Workbench software, all projects must first be compiled through the use of a

boot image. Creation of a new boot image and set the parameters to default is needed. When

creating a kernel, the option is displayed which type of kernel one would like to use, select PPC,

as it matches the type of the QUIOCC II board. Then, load the kernel onto the board. At this

point, we have a connection established to a fresh QUIOCC II VxWorks image. From here, one

can begin testing the environment with C code that will be compiled and loaded with POSIX

style code. VxWorks also offers VxWorks header files, known as “VxWorks.h”, which can help

with priority inversion, threading, and scheduling multithreaded methods.

5.2 Testing

During the testing of the VxWorks and WindRiver environment, many test cases cover

the functionality of the Host machine in ensuring a proper connection to the QUIOCC II

embedded machine. Later test cases rely on the setup and connections are correct, so input

methods will assume that the previous test cases passed.

Before starting the test cases, the QUIOCC II can be loaded with a custom kernel as

mentioned in Section 5.1 which can configure the embedded machine for different functionality.

The test cases will use the real-time default kernel configuration settings, unless otherwise noted.

The test plan covers initialization of the machines, executing code, and debugging the output.

#include <stdio.h> int fac(int n ); int main (int argc, char ** argv) { printf("Debug Demonstration\n"); int x = 10; while (x > 0) { printf("%d\n",x); x--; }

14

printf("End of demonstration."); return 0; } int fac(int n) { if(n == 0) { return 1; } else { return n*fac(n-1); } }

Figure 10: Sample Test Code

Figure 10 displays the sample code used in test cases that is written on the Host machine

through the WindRiver Workbench development environment. This loads any other source code

that can be used be build an image using the project/build button. Check if successful, then run

using the green run button. The results should appear on the console window. If the console is

not showing, see Appendix A for how to start it.

In the code from Figure 10, the main function will be modified by adding a call to the factorial

function. The code segment to be modified is the first statement within the while loop, which

will display the results as follows:

printf("%d\n",fac(x));

This will have to be manually changed by the user. The JTAG debugger will also have to be

connected for test cases regarding the debugging environment. Figures 11.1 and 11.2 depicts the

input option to be selected. This option can be found on the top right of the WindRiver

Workbench environment.

15

Figure 11.1: Debug Start Option View

Figure 11.2: On-Chip Debugging selected (Windows 8.1)

The test cases described in Table A.1 are organized as follows. Column named “Description”

refers to the details of the Test Case. Column named “Input” defines an action taken by the

Tester. Results for each Test Case are referred to in column named “Output/Results”.

Table A.1

Test Case Description Input Output/Results Pass/Fail

1 Attempt to load WindRiver without initializing the server.

Launch WindRiver.exe Figure 12 Pass

16

2 Load WindRiver after initializing the server.

Run C:\WindRiver\licadmintools1.3\lmtools.exe and WindRiver.exe

Start Screen Loads.

Pass

3 Build sample program Figure 10 in project file “helloworld.c”

Figure 13 Pass

4 Connect to VxWorks Simulator

Define new connection, no SMP/64bit, 3 processors, 512mb size, NAT networking.

Figure 14 Pass

5 Run Sample Program on Local

Run helloworld.c Figure 15 Pass

6 Alter sample for Factorial function

printf("%d\n",fac(x));

Figure 16 Pass

7 Launch JTAG debugger

Set breakpoint at altered sample, enter debugging and Figure 11 (On-Chip debugging).

Figure 17.

Note that some Windows, such as registers need to be accessed from Windows - Show View

Pass

8 Change thread recursion on n=8

Change n=8 to n=10 under args classification

Figure 18 Pass

9 JTAG Change value for short termination

Change x=0 when x=7 and beginning while loop evaluation.

Figure 19 Pass

10 JTAG Modify a register value

Change Register rcx to 0 as you enter the recursion lopo

Figure 20.

Some variation can occur, as it depends on the current system configuration.

Pass

17

By repeatedly entering 0 into the register, you can approach the same result.

11 Offload to target server.

Set run configuration to remote target and run resulting code.

Figure 21 Pass..

Test Results are shown in Figures 12-21, linked by Test Case. Cross test results can be found in

Appendix B.

Figure 12: Workbench Licensing Error

18

Figure 13: Build Success on Host for Sample Program

Figure 14: VxWorks Simulator Launch Success

19

Figure 15: Sample Program Success

Figure 16: Factorial Sample Program Modification Success

Figure 17: On-Chip Debugging

20

Figure 18: Breakpoint Error

Figure 19: Short Escape JTAG On-Chip Debugging

Figure 20: Register Value Changes

21

Figure 21: WindRiver Remote Run Configuration Settings

22

6. Conclusion

The project has been completed for all requirements regarding the development of

software. The software was able to run on the WindRiver machine, and the JTAG debugger was

successfully able to analyze the QUIOCC II board. Modification to the registers and variables

had an impact on the running state of the software, and could be done within real-time running

states.

A major hurdle of WindRiver systems involves the authentication server and the

Workbench client, which often exist on the same machine. Many times, reading the

documentation leads a student to believe that the licenses to run the application will be dropped

in the license folder, which will subsequently ignore the licensing server. As a result, the

Workbench environment is rarely worked on. With Appendix A in this paper, any potential

installation issues are fully addressed and handled. Furthermore, suggestions were given for how

to migrate the license server to other machines. The license server program was authenticated to

run anywhere from Windows XP machines to Windows 8.1 without issue.

In some instances, a machine may have multiple disc drives. The license server will

attempt to list the volume of drive C, but if there are multiple drives an incorrect result could be

assigned. Refreshing the license server and restarting the service can mitigate or prevent this

from occurring.

For improving upon the project, it is evident that development on multithreaded instances

should be explored. Single threaded instances allow ease of use for modifying registers and

variable values, but multithreaded gives more opportunity for On-Chip Debugging. For instance,

semaphores that enter lock states can be observed in how they entered the lock state, and can be

manually switched back to an unlock state. Testing can also be improved by enabling a certain

number of locks, and changing this number each time the software is run. This will give some

insight in how the software could operate in a real-time environment, and potential issues could

be discovered earlier.

23

7. References

[1] WindRiver Systems. “Wind River SBC8347E/49E”

URL: http://www.windriver.com/products/OCD/SBC8347E_49E/

[2] Digital DNA. “MPC8260 PowerQUICC II User’s Manual” Revision 0.

URL: http://people.freebsd.org/~wpaul/MPC8260UM.pdf

[3] Graham, Bill. “The Multicore transition: tools are key to success”

URL: http://blogs.windriver.com/vxworks/2010/02/the-multicore-transition-tools-are-key-to-

success.html

[4] WindRiver Systems. “Wind River ICE 2”

URL: http://www.windriver.com/products/JTAG-debugging/ICE-2-debugger/ice2-details-

1.html#details1

[5] Collins, Robert. “Overview of Pentium Probe Mode”

URL: http://www.rcollins.org/articles/probemd/ProbeMode.html

[6] IEEE. “IEEE Standard for Test Access Port and Boundary-Scan Architecture” Revision

1149.1-2001

24

Appendix A:

The first step in setting up the Workbench project is to assemble all hardware that is necessary

for uploading code to a remote machine. Currently, the software supports Windows XP, 7, and

8.1 OS environments. The JTAG debugger is a necessary device, which is used extensively for

testing. Another mandatory component is the SBC83XX Power QUICC II Pro Workbench

board. The JTAG debugger and QUICC II each need their own power supply cable hooking into

available outlets. For the JTAG board, a JTAG connector is needed to establish a debugging

connection to the QUICC II. An example of the JTAG connection is shown in Figure H.1. A

serial micro db-9 connector will connect to the back of the JTAG board, and will be the basis of

communication between the Host and JTAG device. However, alternatives are also possible, and

either Ethernet or Mini-USB connectors will also establish a connection between Host and

JTAG. If the Host chooses to use the micro db-9 connector, but does not have a native Serial

port, a Serial-USB converter will be needed, depicted in Figure H.2.

Figure H.1 JTAG Connection to QUICC II board

25

Figure H.2 Serial to USB Connector

Once all hardware setup is done, installation of the WindRiver components can proceed.

WindRiver installation involves generating a license file first for the server. Within WindRiver,

there is a server that hands out licenses and clients which can ask the user for a license. Note that

the license is “loaned”, and can expire after a period of time.

Figure A.1 Hosts Licenses

Figure A.1 depicts necessary requirements for a license server. Within the hosts will be a

hostname, known as the name of the machine, Host ID which is the MAC address of the

26

machine, and TCP port for communication. Each host can generate their own license server, but

only one should be operational at any given time.

After downloading the license file generated from your unique host label, the service will need to

be started. This can be found by installing license administrator tools and running

lmtools.exe under administrative permissions (right click on the lmtools.exe icon).

Figure A.2 lmtools.exe Configuration Services Tab

Figure A.2 shows lmtools.exe being run, with the server configuration settings. One

important note is that the path to the license file should be located within the administrator tools

folder, not the license folder. The license that was generated is only for administrative use, and

Workbench will refuse to load correctly if it finds a license. This is because it will choose not to

check the service, and so will attempt to validate a client Host with a server license, and give an

error. In order to allow Workbench to check the server license, tab to the Start/Stop/Reread

section of lmtools.exe and select Start Service with the service name you have created.

Once that’s complete, you can start Workbench. To connect to a target VxWorks machine

(JTAG or source machine), connect the serial-db9 cable to it and create a target connection on

27

the lower left of the Workbench, shown in Figure A.3. As a result, Figure A.4 appears which

shows an example of connection. The connection is defined with backend as serial, with the host

connection port as COM5. A command line representation is at the bottom of the figure, will

redirect output into the Workbench. Once connected to target, any code written can be uploaded

to it.

Figure A.3 Connection String

28

Figure A.4 Serial Connection

In case the connection has been previously executed, select the connection depicted in

Figure A.5. As a result, the display from Figure 21 will appear on the bottom of the screen.

Figure A.5 Connection Button

29

Once you have a connection made, you can test by logging into the Debugger with the

default connection settings. A window shown in Figure A.6 will appear, which will be the

initialization of the debugger.

Figure A.6 Debugger Serial Output

Type in “ethsetup” to the terminal to set up communication over USB. The output will ask

for which option. Select option 2, with the option 10.0.0.1, and 2 for determining IP class. Then

hit 8 and 9 to save the configuration. This should be setup by default, but Figure A.7 depicts

resetting the IP configuration settings.

30

Figure A.7 Setup for Debugger

31

Appendix B:

VxWorks JTAG Access

Thomas Turney

Test Report

Austin Hughes

Stefan Oswald

Nowele Rechka

Draft 1

April 10, 2015

CEN 4935 Senior Software Engineering Project

Instructor: Dr. Janusz Zalewski

Software Engineering Program

Florida Gulf Coast University

Ft. Myers, FL 33965

32

1. Attempt to load WindRiver without initializing the server.

Input applied to software: Launched WindRiver.exe

Expected results: Error message shown in Figure 1.

Actual results: Error message appeared

Statement whether the test case passed or not: Test Case Passed

Suggestions if any, to make corrections or modifications: No suggestions

Figure 1: Workbench Licensing Error

33

2. Load WindRiver after initializing the server.

Input applied to software: Run C:\WindRiver\licadmintools1.3\lmtools.exe then selected start server. Afterwards WindRiver was launched.

Expected results: WindRiver loads successfully with no error message.

Actual results: WindRiver loaded successfully with no error message.


Suggestions if any, to make corrections or modifications: Show screenshot of how to start server after lmtools.exe is launched

34

3. Build sample program

Input applied to software: Copy paste figure 10 into helloworld.c file and then build.

Expected results: Project builds successfully.

Actual results: Project built successfully.


Suggestions if any, to make corrections or modifications: Explain input process in a more detailed fashion.

35

4. Connect to VxWorks Simulator

Input applied to software: Connected to a new VxWorks simulator with no SMP/64 bit,3 processors, 512 mb size, NAT networking.

Expected results: Can create and connect to VxWorks Simulator

Actual results: Created and connected to VxWorks Simulator


Suggestions if any, to make corrections or modifications: None

36

5. Run Sample Program on Local

Input applied to software: Selected run button.

Expected results: Program runs and outputs expected values (Figure 2).

Actual results: Program ran and generated the correct output (Figure 2).



Figure 2: Sample Program Success

37

6. Alter sample for Factorial function

Input applied to software: Altered program printf line to printf("%d\n",fac(x));

Expected results: Program runs and outputs expected values (Figure 3).

Actual results: Program ran and generated the correct output (Figure 3).



Figure 3: Factorial Sample Program Modification Success

38

7. Launch JTAG debugger

Input applied to software: Set a breakpoint and then ran program in debug mode.

Expected results: Program enters debugger and shows chip values (Figure 4).

Actual results: Program enters debugger and shows chip values (Figure 4).


Suggestions if any, to make corrections or modifications: Describe which line the the breakpoint should be set at.

Figure 4: On-Chip Debugging

39

8. Change thread recursion on n = 8

Input applied to software: Change n = 8 to n = 10 under args classification

Expected results: Output matches Figure 5.

Actual results: Output matches Figure 5.



Figure 5: Breakpoint Error

40

9. JTAG Change value for short termination

Input applied to software: Change x = 0 when x = 7 in debugger and beginning while loop evaluation.

Expected results: Output matches Figure 6.

Actual results: Output matches Figure 6.



Figure 6: Short Escape JTAG On-Chip Debugging

41

10. JTAG Modify a register value

Input applied to software: Change Register rcx to 0 as you enter the recursion loop.

Expected results: Output is similar to figure 7.

Actual results: Output is similar to figure 7.



Figure 7: Register Value Changes

42

11. Offload to target server

Input applied to software: Set run configuration to remote target and run resulting code.

Expected results: Run configuration is not able to be used (Figure 8).

Actual results: Run configuration was not able to be used (Figure 8).



Figure 8: WindRiver Remote Run Configuration Settings

vxworks jtag access thomas turney - florida gulf...

Documents