®3-1

WindSh and BrowserWindSh and Browser

3.1 WindSh

Browser

®3-2

WindShWindSh

Interactive C-expression interpreter allows:– Accessing VxWorks facilities

– Downloading and invoking code

– Creating and examining variables

Interactive Tcl interpreter allows:– Defining user commands

– Automating interactions with target.

For UNIX hosts, invoke from the LauncherLauncher. (UNIX Host)

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

®3-3

How the Shell Interprets CommandsHow the Shell Interprets Commands

WindSh uses the target server’s system symbol table and the following rules to interpret names in expressions:

-> retVal = printf (“Foo is %d\n”, foo)-> i (tWdbTask)

1.Use a WindSh built-in command in preference to a target symbol of the same name.

2.Look for symbol in the symbol table.

3.Look for _symbol in the symbol table.

4.Convert a task name to a task ID.

5.Create symbol if it is to the left of ‘=‘ and does not exist in the symbol table or as a task name.

®3-4

System Symbol TableSystem Symbol Table

-> x = 10new symbol "x" added to symbol table.x = 0xda188: value = 10 = 0xa

®3-5

WindSh as a C InterpreterWindSh as a C Interpreter

Shell command syntax is generally the same as the C programming language:

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

-> Nom = “Nelson”new symbol “Nom” added to symbol table.Nom = 0x23fe798: value = 37742496 = 0x23fe7a0 = Nom + 0x8

-> printf (“Hello %s, number is %d.\n”, Nom, 0x20)Hello Nelson, number is 32.value = 28 = 0x1c

-> &xvalue = 34599800 = 0x20ff378 = x

®3-6

Syntax QuirksSyntax Quirks

WindSh built-in functions screen target symbols of the same name. To access the target symbol rather than the built-in, prefix its name with ‘@’ :-> @i = @i + 3-> @i = @i + 3

Target functions are always called (spawned) with 10 integer arguments. For example,-> 2 * foo (&mac, 27)-> 2 * foo (&mac, 27) is really-> 2 * foo (&mac, 27, 0,0,0,0,0,0,0,0)-> 2 * foo (&mac, 27, 0,0,0,0,0,0,0,0)

If the entire expression is a function call, with the function name first on the line, parentheses may be omitted:-> foo &mac, 27-> foo &mac, 27 but not-> 2 * foo &mac, 27-> 2 * foo &mac, 27

®3-7

Caveat - Examining VariablesCaveat - 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) 0x90-> z = (short) 0x90z = 0x20ff370: value =144 = 0x90-> (short) z-> (short) zz = 0x20ff370: value = 144 = 0x90-> z-> zz = 0x20ff370: value = 9498350 = 0x90eeee

All variables created in the WindSh are allocated 8 bytes of target memory, to preserve space in case the variable’s value is changed to a double.

®3-8

Caveat - Data StructuresCaveat - Data Structures

The shell does not recognize data structures. To view and manipulate data structures, use a source-level debugger.

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 - MacrosCaveat - 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 UpSymbol Table Look Up

Display symbols matching a regular expresson with lkup( ).

-> lkup (“stuff”)-> lkup (“stuff”)_stuff 0xda1a0 data (foo.o)value = 0 = 0x0-> lkup (“^_print”)-> lkup (“^_print”)_printf 0x00029622 text (vxWorks)_printErr 0x00029640 text (vxWorks)_printExc 0x0002965e text (vxWorks)value = 0 = 0x0-> lkup "^x$"-> lkup "^x$"x 0x000da188 bss ()value = 0 = 0x0

®3-11

Shell Line EditingShell Line Editing

History mechanism like the UNIX Korn Shell’s.

Type hh to see list of previous commands.

Press escesc to enter line editing mode.

Accept changes by hitting returnreturn. To quit, type ^U.

Editing mode uses vi-like commands, including:

h j lk

®3-12

Shell Special CharactersShell Special Characters

Character Description

^C (UNIX) Terminate a function call and

^-Break (PC) return shell prompt.

^X (UNIX) Reboot VxWorks target.

^D, TAB Symbol and filename completion;command synopses.

^W Show HTML help for command.

Esc Enter Vi-like editing mode from input mode.

^U Delete an entire line, return to normal input mode.

®3-13

Shell Built-in CommandsShell 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 points.

–s/c Step/continue a task.

–tt Trace a task’s stack.

–i/ti Give (detailed) task information.

–w/tw Show which objects are tasks waiting for.

–ld/unld Load/unload a module.

–show Display object information in WindSh.

®3-14

WindSh Primitives and Target WindSh Primitives and Target ResourcesResources

Shell built-in commands execute as C-interpreter primitives on the host when possible.– Example: the built-in lkup( ) executes entirely on the host. No

communication with the target is required.

Some built-in commands require modules to be loaded into target memory.– The shell primitive period( ) executes as a function _periodHost_periodHost

on the target.

– The shell primitive repeat( ) executes as function _repeatHost_repeatHost on the target.

®3-15

Changing DirectoriesChanging 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.

These functions are WindSh primitives.

®3-16

Downloading via WindShDownloading via WindSh

ld (addSyms) < fileName Loads object module fileName into the target server’s

memory pool on the target.

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

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.

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

Unloads old version of module if it exists.

®3-17

WindSh Loading ExampleWindSh Loading Example

-> ld 1 < foo.oLoading /folk/swagon/prog/foo.o |value = 402912 = 0x625e0-> moduleShowMODULE NAME MODULE ID GROUP TEXT START DATA START BSS START----------- ---------- ------- ---------- ---------- ----------vxWorks 0x5b588 1 0x10074 0x9ae90 0xa0228foo.o 0x62878 2 0xd76c0 0xd7930 0xd7bb4value = 0 = 0x0-> fooInit### Warning: Snafu #6. Continuing anyway...value = 0 = 0x0->

...

-> unld "foo.o"value = 0 = 0x0-> moduleShowMODULE NAME MODULE ID GROUP TEXT START DATA START BSS START----------- ---------- ------- ---------- ---------- ----------vxWorks 0x5b588 1 0x10074 0x9ae90 0xa0228value = 0 = 0x0->

®3-18

Function Call ExecutionFunction Call Execution

From WindSh:

WindSh blocks until demo returns.

Standard I/O of tN is redirected to WindSh (default).

®3-19

Spawning tasks with sp()Spawning tasks with sp()

As a task:

WindSh returns immediately after spawning the task “sMuN”. This task’s I/O is not redirected to the shell.

®3-20

The i functionThe i function

To display task information:

i (taskNameOrId)

Example: -> i (tNetTask) NAME ENTRY TID PRI STATUS PC SP ERRNO DELAY -------- --------- ------ --- ------- ------ ------- ------ ----- tNetTask _netTask 3e1d28 50 READY 261e4 3e1cc0 0 0 value = 0 = 0x0

If taskNameOrId = 0, display information for all tasks.

Use ti( ) for detailed task information.

®3-21

WindSh Assembly Level DebuggingWindSh Assembly Level Debugging

Example:

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

-> b (printf)-> sp (stuff)task spawned: id = 0x23e0a3c, name = s1u3value = 37620284 = 0x23e0a3cBreak at 0x2005f78: _printf Task: 0x23e0a3c (s1u3)-> 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 -> c

value = 0 = 0x0

®3-22

Tcl and WindSh CustomizationTcl and WindSh Customization

Tcl is a powerful scripting language which:– Is interpreted

– Allows commands to take arguments

– Has standard flow-control structures

– Has powerful string manipulation facilities

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

To run a single Tcl command from WindSh, preface the command with a ‘?’:

-> ?myCmd

®3-23

Shell Configuration VariablesShell Configuration Variables

The WindSh has a few configuration variables which govern some aspects of its operation.

-> ?shConfigDSM_HEX_MODE = offLD_CALL_XTORS = targetLD_COMMON_MATCH_ALL = onLD_PATH = .LD_SEND_MODULES = onSH_GET_TASK_IO = on-> The above are the default values.

To change a value:-> ?shConfig SH_GET_TASK_IO off?shConfig SH_GET_TASK_IO off->

®3-24

Virtual I/OVirtual I/O

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

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

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

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

Click the Virtual Console and Target I/O Redirect checkboxes when configuring the target server.

®3-25

Shell Host I/O RedirectionShell Host I/O 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 files accessible to the WindSh process running on the development host, not to local devices on the target!

®3-26

Target-resident ToolsTarget-resident Tools

Target-resident tools are available:– loadLibDynamic module loading.

– unldLib Dynamic module unloading.

– shellLib Target-resident C interpreter.

– usrLib Useful utilities like cd, copy, etc.

– dbgLib Native debug library.

The tools require a target-resident symbol table.

Caveats: – These tools consume target resources (RAM).

– Be cautious using these tools in conjunction with Tornado host-based tools!

See the manuals for details.

®3-27

Symbol Table SynchronizationSymbol Table Synchronization

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

To prevent this, enable symbol table synchronization:– Include the component development tool components > symbol table development tool components > symbol table

components > synchronize host and target symbol tablescomponents > synchronize host and target symbol tables in VxWorks.

– Launch the target server with the -s-s option

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 host symbol table changed, updates the target symbol table; when target symbol table changed, informs the target server.

®3-28

WindSh and BrowserWindSh and Browser

WindSh

3.2 Browser

®3-29

Browser OverviewBrowser Overview

Graphical tool for displaying target information:– Loaded object modules

– Tasks

– Memory and stack usage

– Interrupt vector table

– VxWorks objects such as semaphores, message queues, and watchdog timers

– CPU utilization

Information is updated on demand or periodically.

Invoke Browser from – launcher’s application pane (UNIX)

– launch toolbar or the Tools menu (Windows)

®3-30

UNIX: The BrowserUNIX: The Browser

Button Bar

System Tasks

User Tasks

Object DisplaySelection

MemoryConsumption

LoadedModules

®3-31

PC: The BrowserPC: The Browser

Browser Display

Selector

Data

Panel

®3-32

Browser: Examining ObjectsBrowser: Examining Objects

Message Queue Display

Semaphore Display

®3-33

Timing OverviewTiming Overview

Browser’s spy facility– Activity profiler (% CPU utilization per task).

– Uses the auxiliary clock.

timexLib– 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 chapter 7.

®3-34

Browser’s Activity ProfilerBrowser’s Activity Profiler

Configure Spy’s sampling with the Browser configuration button

– Browser update time /

– Spy report time.

– Spy collection frequency.

– Spy mode: differential or

– cumulative

®3-35

Subroutine TimerSubroutine Timer

timex (func, args) Times single execution of func.

timexN (func, args) Repeats execution to obtainaccurate timing.

Example:

-> timex (stuff, "The answer is", 42)timex (stuff, "The answer is", 42)timex: execution time too short to be measured meaningfully in a single execution.

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

value = 46 = 0x2e = ‘.’-> timexN (stuff, "The answer is", 42)timexN (stuff, "The answer is", 42)timex: 50 reps, time per rep = 50293 +/- 333 (0%) microsecs

®3-36

SummarySummary

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

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-37

SummarySummary

Use the Browser to:– Display system information.

– Examine objects.

– Display CPU utilization.

Performance monitoring tools:

timex timexN

spy