Wind River Systems, Inc. 1997

Chapter - 3 Chapter - 3

Cross-Development

3-2

Cross-Development

WindSh

Cross-Development

Browser

3-3

WindSh

• Interactive Tcl interpreter allows :

• Interactive C-expression interpreter allows :• Accessing all VxWorks facilities.• Invoking any subroutine in memory.• Creating and examining variables.

• Defining user commands• Automating interactions with target.

• For UNIX hosts, invoke from the Launcher.(UNIX Hosts)

• For PC host, invoke from the Tornado development environment Tools menu or the launch toolbar.(PC Host)

3-4

How the Shell interprets Commands

• WindSh uses the target server’s system symbol table and the following rules to interpret an expression : -> retVal = printf (“Foo is %d\n”, foo) -> i (tWdbTask)

• If you do not specify one of the arguments to a function, the Shell will pass a zero. Some common commands are WindSh built-ins and not functions.

1. Look for symbol in the symbol table.2. Look for _symbol in the symbol table.3. Create symbol if it is to the left of a ‘=‘ and does not exist in the symbol table.4. Convert a task name to a task ID.

3-5

System Symbol Table

-> x = 10

symbolname

Pointerto memory

_printf

Type

_accept

.

.

.x 0x2ea36 bss

Memory

0000000A0x2ea36

text

text

3-6

WindSh as a C Interpreter

•Shell command syntax is generally the same as the C programming language.

-> x = (8 * 6) / 4x=0x20ff378: value = 12 = 0xc

-> name = “Nelson”new symbol “name” added to symbol table.name = 0x23fe798: value = 37742504 = 0x23fe7a8 = name + 0x10

-> printf (“Hello %s, number is %d.\n”, name, 0x20)value = 29 = 0x1d

-> xx = 0x20ff378: value = 12 = 0xc

3-7

Caveat - Examining Variables

• The shell interprets all variables as 32-bit integers unless specified otherwise.

• Casts must be used to tell the shell how to interpret non-integer types.

-> z = (short) 0x90z = 0x20ff370: value = 144 = 0x90-> (short) zz = 0x20ff370: value = 144 = 0x90-> zz = 0x20ff370: value = 9498350 = 0x90eeee

3-8

Caveat - Data Structures

• The shell does not understand data structures. To manipulate data structures, use a remote, source-leveldebugger.

• To display memory:

-> d pMyBuf003fe770 0023 09ea e030 2647 a682 eeee * #. . . 0&G . . . *003fe780 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *003fe790 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *003fe7a0 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *003fe7b0 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *003fe7c0 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *003fe7d0 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *003fe7e0 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *003fe7f0 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *003fe800 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *003fe810 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *003fe820 eeee eeee eeee eeee eeee eeee eeee eeee * . . . . . . . . . . . . . . . . *

3-9

Caveat - Macros

• The shell does not recognize symbolic macros (defined for the C preprocessor with #define directives).

• Must examine header files to find the value corresponding to a symbolic constant.

3-10

Symbol Table Look Up

• Display symbols containing a given substring with lkup().

-> lkup (“stuff”)stuff 0x23eb3e0 bssvalue = 0 = 0x0

-> lkup (“Help”)_netHelp 0x201a910 text_objHelp 0x200afbe text...value = 0 = 0x0

3-11

Shell Line Editing

• History mechanism like UNIX Korn Shell.

• Type h to see previous commands.

• Press esc to toggle from input to edit mode.

• Leave edit mode by pressing esc or return.

• Editing mode uses vi - like commands , including :

h j k l

3-12

Shell Special Characters

Character Description

^H Delete a character (backspace).

^U Delete an entire line.

^C (UNIX) Terminate a function call and return to^-Break (PC) shell prompt.

^X (UNIX) Reboot VxWorks (trap to the boot ROM’s).

^S Temporarily suspend terminal output.

^Q Resume terminal output.

Esc Toggle between regular input mode and K-shell edit mode.

3-13

Shell Built-in Commands

WindSh provides common commands needed for development:• sp Create a task with default options.• td Delete a task.• ts / tr Suspend / resume a task.• b Set or display break point.• s Step a task.• c Continue a task.• tt Trace a task’s stack.• i / ti Give (detailed) task information.• ld/unld Load / unload a module.• browse Display object information in Browser.• show Display object information in WindSh.

3-14

WindSh Primitives and Target Resources

• Shell built-in commands execute as C-interpreter primitives on the host when possible.

• Some commands require modules to be loaded into the target address space.

• The shell primitive lkup() executes as a C-interpreter primitive on the host.

• The shell primitive period() executes as a function _periodHost on the target.• The shell primitive repeat() executes as a function _repeatHost on the target.

3-15

Changing Directories

• Use cd() to set WindSh’s working directory (on the host). -> cd (“/u/team3”) (quotes required)

• pwd() shows the current working directory.

• Use ls() to show contents of the directory.

• cd() is a WindSh primitive.

3-16

Shell Redirection

• Shell input can be redirected to come from a file. -> < script

• Shell output can be redirected to a file. -> h( ) > hFile

• Caveat: I/O can only be redirected to devices accessible to the WindSh process running on the development host, not local devices on the target !

3-17

WindSh Debugging

•Can debug target resident tasks from WindSh:

•See the windsh appendix to the Tornado User’s Guide for information on these (and other) windsh primitives.

•Set and remove breakpoints b, bd, bdall•Single step s, so•Disassemble code l•Trace a task’s stack tt•Resume execution c

•Debugging is done at the assembly code level. Use remote debugger for source-level debugging.

3-18

• Example: -> b (printf) -> sp (stuff) task spawned: id = 0x23e0a3c, name = t3 value = 37620284 = 0x23e0a3c Break at 0x2005f78: _printf Task: 0x23e0a3c (t3)

-> tt( ) 20461b8 _vxTaskEntry+10: _stuff (0, 0, 0, 0, 0, 0, 0, 0, 0, 0) 23feb4a _stuff +12: func1 (1) 23febf2 _func1 +18: _printf (23fec39, 23fec2e) value = 0 = 0x0

• If a task halts unexpectedly, tt( ) can be used to find out what routine failed.

Debugging Example

3-19

Tcl and WindSh Customization

• Tcl is a powerful scripting language which:

• To run Tcl command from WindSh, preface your command with a ‘?’: -> ?myCmd

• Is interpreted.• Allows commands to take arguments.• Has standard flow-control structures.• Has powerful string manipulation facilities.

• To toggle between C and Tcl mode, enter ‘?’ at the prompt : -> ? tcl> proc myCmd {...} {...}

3-20

Virtual I/O

• By default, a target’s standard input , output, and error are directed to the console used to set boot parameters.

• Click the Virtual Console checkbox when configuring the target server and redirect the target’s standard I/O to a file descriptor opened on “/vio/0”.

• Once a Virtual I/O channel is opened, it behaves like a normal character (stream) I/O device.

• Useful if target lacks an I/O channel , or if developing remotely.

• Use Virtual I/O to associate the target’s input / output with a Virtual Console.

3-21

Target-Resident Tools

• Target-resident tools are available:

• Caveats:

• loadLib Dynamic module loading.• unldLib Dynamic module unloading.• shellLib Target-resident C-interpreter.• usrLib Useful utilities like cd, copy, etc.

• The tools require a target-resident symbol table.

• dbgLib Native debug library.

• These tools consume target resources (RAM).• Be cautious using these tools in conjunction with Tornado host-based tools !

• See the manuals for details.

3-22

Symbol Table Synchronization

• When using both host-based and target-based tools ,the host and target symbol tables can become inconsistent.

• The task tSymSync is spawned. It does the following :

• Makes modules or symbols loaded on target before target server attached visible to target server.

• When modules are loaded / unloaded by target server, updates the target symbol table; when modules are loaded / unloaded by loadLib / unldLib, informs the target server.

• To prevent this , enable symbol table synchronization :

• Define INCLUDE_SYM_TBL_SYNC in config/all/configAll.h or config/bspName/config.h

• Launch the target server with -s option

3-23

Cross-Development

WindSh

Cross-Development

Browser

3-24

Cross-Development Overview

• Link modules with VxWorks image and load into target address space :

• Compile translation units using the appropriate host based cross-compiler for target environment.

• Dynamic links integrate modules into the VxWorks image on the target when the modules load, after VxWorks is already running.

• Static links integrate application modules into the VxWorks image when it is built. VxWorks is then loaded onto the target at boot time.

• Static links usually used for production code.

• Dynamic links usually used during development.

3-25

demo.c

/* * demo.c - a simple demo routine * This routine prints its task id, name and start-up parameter */

#include “vxWorks.h”#include “stdio.h”#include “taskLib.h”

void demo (int param){

/* find out what task we are and print message */printf (“Hello from task %#x (%s). Start-up param was %d.\n”,

taskIdSelf(), taskName(0), param);}

3-26

UNIX : Compiling Code

ccX -c -I${WIND_BASE}/target/h -DCPU=CPUtype \ -fno-builtin -nostdinc -Wall -pedantic -O demo.c

-c Create only an object file, no linking.-I Location of VxWorks header files.-D Define target CPU type.-fno-builtin Don’t use compiler built-in functions.-nostdinc Don’t use usual Unix include directories.-Wall Produce all extra warning messages.-pedantic Produce strict ANSI C warning.-O Perform standard optimizations.

• Creates an object file named demo.o

3-27

PC : Compiling Code

• Build a loadable object module using the Makefile in the directory which contains the source file.

• A Build Output window appears displaying the build commands as they are executed. If an error occurs, click on the error line in the Build Output window to open the appropriate source file at the offending location.

• Select Project => Make Current Source File.

• Select the file to be compiled using File => Open.

• You may modify Makefile to change the CPU , toolchain, compiler flags, or other make variables.

• If no Makefile exists for the directory, tornado will offer to construct a default Makefile.

3-28

Unresolved External References

demo (param)

{

printf (...)

taskIdSelf (...)

taskName (...)

}

% nm68k demo.o

00000000 T _demo

U _printf

U _taskIdSelf

U _taskName

%

3-29

Downloading a Program

• Loads fileName into the target server’s memory pool.

• Adds global symbols to host resident symbol table (default). If addSyms == 1, then load static symbols.

• Resolves undefined symbols as module is loaded.

• If loader is unable to resolve an external reference, then ld( ) issues a warning; however the load does not fail and the loaded module is present on the target.

-> ld (addSyms) < fileName

• Returns ERROR on error, or a nonzero host-based module ID on success.

• Unloads old version of module if it exists.

3-30

Incremental Linking

• If two modules call each other, you can’t load them independently.

• To incrementally link code, use the linker’s -r flag. For a 68k target: ld68k -r foo.o goo.o -o myProg.o

• Typically done in a makefile.

• Download the composite module into the target address space : -> ld ( ) < /u/team1/myProg.o

3-31

moduleShow

• To see all currently loaded modules:

-> moduleShowMODULE NAME MODULE ID GROUP # TEXT START DATA START BSS START---------------------- ----------------- ------------- ------------------ ------------------ ----------------- vxWorks 0x302c90 1 0x20000 0x7bccc 0x84fc0 A.o 0xeb8008 2 0xc4730 0xc479c 0xc47a4 B.o 0xeb8270 3 0xc46d0value = 0 = 0x0

• To see a particular module, specify either name or module ID.

-> moduleShow “B.o”MODULE NAME MODULE ID GROUP # TEXT START DATA START BSS START---------------------- ----------------- ------------- ----------------- ------------------ -----------------

B.o 0xeb8270 3 0xc46d0value = 0 = 0x0

3-32

Unloading Modules

•moduleNameOrId can be either a module name (e.g. foo.o) or a module ID.

STATUS unld (moduleNameOrId)

• Make sure that no loaded modules depend on the module you are unloading.

• Frees target memory occupied by text, data and bss segments.

• Remove associated symbols from the symbol table.

-> unld (“foo.o”)

3-33

Running Demo

• From WindSh:

• WindSh blocks until demo returns.

host

WindSh

-> demo (8)

target

tN

demo

3-34

Running Demo (continued)

• As a task:

• WindSh returns immediately after spawning the task “uN”.

host

WindSh

-> sp (demo, 8) ->

target

uN

demo

3-35

Task Creation

• VxWorks model:

• UNIX / NT model:

• An object module is downloaded.• Execution can begin at any routine in that module.

• An executable file name is specified.• Execution starts in that file’s main( ) routine.

• For example, if foo( ) is a function in myProg.c -> ld ( ) < myProg.o -> sp (foo, “stringParam”, 7)

3-36

The i function

• Example: -> i (tNetTask)

NAME ENTRY TID PRI STATUS PC SP ERRNO DELAY -------- ---------- ----- ----- ----------- ------------ ---------- ----------- --------- tNetTask _netTask 23e808c 50 READY 20259e8 23e7d60 0 0 value = 0 = 0x0

• To display task information:i (taskNameOrId)

• If taskNameOrId = 0, display information for all tasks.

• Use ti( ) for detailed task information.

3-37

Cross-Development

WindSh

Cross-Development

Browser

3-38

Browser Overview

• Graphical tool for displaying target information:• Loaded object modules.• Tasks.

• Information is updated on demand or periodically.

• Memory Usage.

• VxWorks objects like semaphores, message queues, and timers.

• CPU utilization

• Invoke Browser from the Launcher’s main panel for a UNIX host.

• Invoke Browser from the Launcher or the Tools menu for a PC host.

3-39

UNIX: The Browser

Button Bar

System Tasks

Object DisplaySelection

Loaded Modules

User Tasks

MemoryConsumption

3-40

PC: The Browser

Browser DisplaySelector

Data Panel

3-41

UNIX: Examining Objects

Message QueueDisplay

SemaphoreDisplay

3-42

Timing Overview

• timexLib

• Acitivity Profiler (% CPU utilization per task).• Browser’s spy facility

• Uses the auxiliary clock.

• subroutine timer.• Uses the system clock.

• WindView• Uses instrumented kernel and high-resolution timer drivers to capture precise event data.• Intuitive GUI for analyzing data.• Discussed in Optional Products chapter.

3-43

Browser’s Activity Profiler

3-44

Subroutine Timer

timex (func, args) Timers single execution of functimexN (func, args) Repeated execution to obtain accurate timing.

• Example:-> timex (stuff)timex: execution time too short to be measuredmeaningfully in a single execution.

Type “timexN” to time repeated execution.Type “timexHelp” for more information.

value = 46 = 0x2e = ‘.’

-> timexN (stuff)timex: 50 reps, time per rep = 50293 +/- 333 (0%) microsecs

3-45

Summary

• WindSh is a C and Tcl interpreter shell for accessing the target.

• Tools for compiling and incrementally linking:ccX flags ldX -r Makefile

• Tools for managing target resident object modules:ld unld moduleShow

• Tools for starting / stopping a thread of execution:sp td

• Tools for debugging from WindSh:i lkup l tt

3-46

• Use the Browser to:• Display system information.• Examine object.• Display CPU utilization.

• Performance monitoring tools: timex timexN spy

Summary