This file contains a tutorial for running hyperSOURCE. It is highly recommended that you work through this tutorial, which will introduce you to the most frequently used commands and allow you to experiment with them in a controlled environment. Once you have completed the tutorial, you should be prepared to use the hyperSOURCE and MICE-V combination in your target system. Preparing to Run hyperSOURCE To execute hyperSOURCE, do the following steps: 1.Connect the RS-232 cable from the COM1 or COM2 port on your PC to the TERMINAL port on the back of the MICE-V chassis. 2.Power up your PC host. 3.If you have not already installed hyperSOURCE, do so at this time. Insert the hyperSOURCE distribution diskette into drive A and type a:install. If your RS-232 cable is connected to the COM2 port on your PC, then you must edit the environment (*.env) file. Change COM=1 to COM=2. Make sure you do not use an editor that embeds control characters. 4.Power up the MICE and invoke kermit. Verify that the emulator passes all power-up diagnostics properly. 5.Exit kermit and move to the hyperSOURCE directory. 6.Invoke hyperSOURCE as shown: > hs286v or > hs386 or > hs386sx or > hs486 or > hs (use the supplied batch file) Note When you first power up the MICE-V, it executes self diagnostics which take up to one minute to complete. HyperSOURCE will connect when these diagnostics complete. Subsequent connections will take only a few seconds to complete. HyperSOURCE Problems and Solutions NOTE: Skip ahead to the Tutorial unless you've encountered problems loading hyperSOURCE.) The following describes a few problems you might encounter with hyperSOURCE. The solutions to those problems are also described. 1. File Problems - HyperSOURCE is unable to open the necessary files. a) HyperSOURCE will quit and return control to the host operating system. This error can occur because: - The disk is full. - The maximum number of files that can be opened has been reached. You must increase the number by adding FILES=20 to your config.sys file. - You do not have write privilege in the current directory. b) HyperSOURCE is unable to load your OMF file properly. If you are using OMF files created with Intel development tools, modify the source file extension parameter in the *.env file. Refer to "Specifying Debug Characteristics" in Chapter One. 2. Host Memory Problems - The host system has insufficient or unusable memory. Use a system information utility to verify the host memory configuration. a) HyperSOURCE requires extended RAM, not expanded. b) HyperSOURCE conflicts with v2.66 of himem.sys. HyperSOURCE will initialize and appear to work, but OMF loads and other communication-intensive operations will fail. c) Four megabytes of extended RAM should be sufficient for nearly all configurations; however, very large OMF files containing large numbers of symbols may require additional memory. d) You may need to allocate more existing memory for hyperSOURCE. (e.g., log off network, remove resident (TSR) programs). Use the DOS "chkdsk" command to display the amount of free memory. 3. Communications Link Problems - HyperSOURCE cannot establish communication with the MICE-V. a) Make sure power is applied to the emulator. If not, turn the emulator on and re-execute hyperSOURCE. b) Make sure the RS-232 cable is connected to the serial port of the emulator. c) Verify that COM = 1 or COM = 2 in the *.env file matches the serial communications port on your PC. d) Make sure that the MICE-V emulator is initializing properly. Use the terminal port to establish communications with the emulator and verify power-up diagnostics. e) Make sure that target hardware is not introducing any problems. Bring hyperSOURCE up and verify operation prior to connecting to the target. f) Try using a faster PC host. Some slow PC ATs can cause communication problems with the MICE-V. g) Try eliminating unnecessary memory resident programs and device drivers from your autoexec.bat and config.sys files. For example, if you are not using a mouse with hyperSOURCE, you should remove the device driver for the mouse from your config.sys file. HYPERSOURCE TUTORIAL Once hyperSOURCE has initialized with the MICE-V, you may continue with the following tutorial. This tutorial expects a "normal" installation has been completed; i.e., that the hyperSOURCE executable, help files, *.env, and demo programs all reside in the appropriate subdirectories. If this setup has been changed, the tutorial may produce unpredictable results! This tutorial contains a C module which performs a continuous re-ordering of a linked list. Essentially it takes the fourth element of a linked list and substitutes another element into the linked list. Then the program loops, where it once again deletes the fourth element of the linked list and substitutes once again. In each one of the link list elements is an area containing a number. These numbers begin in the sequence 1, 2, 3, 5, 5. Then after the first substitution the sequence is 1, 2, 3, 4, 5. Then it changes back and forth between the two sequences forever. It calls other procedures which are contained in the module sub_func. Let's begin. -> hs Invoke hyperSOURCE if you have not already done so. ============================================================================== LOADING AND EXECUTING CODE This section of the tutorial demonstrates how to set up the emulator, load code for debugging, and execute code in various ways. -> reset Type reset unless you've just powered up the emulator. -> pause off Turn off screen pause. [For HS486, skip the next 3 MAP commands.] -> map clear This command maps all memory accesses to the target. -> map 0p 0ffffhp Map 64K of internal overlay RAM to low memory. fast ram ->map 0f0000p 0fffffhp Map 64K of internal overlay RAM to high memory. fast ram -> load demo.omf Load the OMF86 realmode file. -> go main Execute from the starting address to the main C function main(). We'll return and take a look at some assembly-level features later. -> e Pull down the Execution menu. Press F1 to display the help screen for the execution menu. The 'S' or Step command is your main tool, used to perform high-level steps, one statement at a time, through your code. 'S IN' or Step INto, will step into statements instead of through them. Later we will use the equivalent instruction-level commands 'IS', Instruction Step and 'IS IN', Instruction Step INto. -> s Single-step through one statement. -> s Again. -> s Again, executing the entire procedure insert(). The highlight in the Source window should now be on line #38, at the procedure printall. The highlight indicates the statement about to be executed. -> s in Step INto printall. Note the source window automatically updates to show the source for printall, part of the file sub_func. The file name appears on the barline separating Source and Dialog windows. -> s 3 Make 3 steps. Line #67 in printall should be highlighted. -> go til #72 Execute from the current PC to line #72 in the current module. The 'til' is optional. -> go til ret Execute from the current PC until a Return from subroutine occurs, i.e., a stack pop returns us to the previous scope, main(). -> b #43 We'll do more with breakpoints in a later section, but for now we need to use one to show the function of 'Go Forever'. -> go This causes the program to execute, stopping at the breakpoint on line 43. -> g for Go Forever starts the emulator without installing any defined breakpoints. -> running Check status. -> mem 0 While the emulator is running, some operations are not permitted. -> b 0 #44 Ditto. -> pri However, you can dump the trace buffer. -> htrc The trace buffer stops acquisition when you display it. The HTRC command restarts the acquisition. -> macro snap You may skip this step, but this macro definition is MD>pri 8188t presented here to give you an idea of one useful way MD>htrc to use the 'pri' and 'htrc' commands. MD>emac ->:snap Next we'll take a look at the IS, 'Instruction Step' command. This can be used in conjunction with 'View Mix' to step through code at the instruction level, but is more useful when debugging assembly level code. We'll reset the emulator and step through the assembly-level startup code. [If using 486, skip next two steps. Type instead: ->reset486 -> reset You should see the code at the reset vector. -> is The emulator executes one instruction, the JMP to start_. -> is 12t The emulator executes 12 instructions. -> u Disassemble, starting at current CS:IP. Note the REP instruction about to be executed. -> is The IS command recognizes this as a "high-level" statement and stops on the other side, rather than stepping into it. This completes the tutorial section on LOADING AND EXECUTING CODE. ============================================================================== WINDOW MANAGEMENT This portion of the tutorial demonstrates the various hyperSOURCE data windows and pull-down menus, as well as their operation. -> inc setupr.inc list Use this include file to reset the emulator to a known state and load the real-mode demo program. -> The F1 key is used to summon help. If a menu is being displayed, F1 will display help text describing that menu. -> s Open the Symbols menu, e and select Evaluate. The help window describes the type of expressions which can be entered for evaluation. To close the help windows. -> help Open the main help menu. Scroll down and select a help item by pressing Enter. You may also go directly to the help item by typing the command as an argument to help, i.e., 'help tm'. The on-line help screens are virtually identical to the command summary section of the user manual. Escape to return to the command line. -> r Open the Register menu. hyperSOURCE offers two types of windows: Data Windows are provided to monitor and/or modify data or debug variables. Examples are the Register window, the Memory window, the Breakpoints window, etc. These Data windows are 'sticky'; that is, they remain on screen when the key is pressed. They can be identified by the number assigned to them (i.e., 3:Register) and their contents can be edited. The Register window stays on screen. s 4 The open Register window is automatically updated. 3 This shortcut can be used to select any open window, i.e., # will take you to the numbered window you select, in this case the Register window, #3. Close the Register window. -> s Transient Windows are provided as temporary g viewports to debug information. They pop up when selected, but close immediately with the key. They are not assigned numbers and cannot be edited. ============================================================================== VIEWING SOURCE FILES This section demonstrates the various ways you can use hyperSOURCE to view source files. Choose the appropriate include file/command to set up your emulator for next portion of the tutorial. -> inc setupr.inc list Use this include file to reset the emulator to a known state and load the real-mode demo program. [If using 486, skip next 2 steps. Type instead: -> reset486 ] -> reset Reset the emulator, setting CS:IP to the startup vector. -> s Single step the processor, jumping to the start of the assembly level initialization code. Even though the current module, $startup, is known by HS, the source file is not displayed because the source file extension is .ASM, not .C. To see the assembly source file, we will manually associate the current module with it. -> c Using the HS pull-down menus, we SET the current m module $startup to point to the source file startup startup.asm. As long as startup.asm is located in a subdirectory identified in SPATH, it will now be startup.asm displayed in the Source window. -> s If necessary, a Step command causes the Source window to be updated. -> go main Execute through the startup assembly code, to main(). -> 1 Move the hyperSOURCE cursor into the Source window. The Source window is always #1, the Dialog window is always #2. The HOME environment variable determines whether the cursor will return to the Source window or to the command line by default. -> Use , , , and keys to scroll in the source window. Notice the current module name dm_main displayed on the barline at midscreen. g Alt-g is a shortcut key to Goto a new location. Pressing Enter accepts the offered default of current CS:IP, which is currently line #31 of main(). g Use delete to erase the default, then enter #43 #43 and Enter to go to line number 43. >>>>>>>> Now, using the cursor keys, position the cursor up one line, on line #42, under the p in printall. Press F2 to Follow, which switches the source window into the procedure printall(). The CS:IP of the emulator has not changed, only the source window view. Notice the module name on the barline is now $sub_func. This procedure works when: 1. The procedure to be followed is part of a module with a corresponding filename with .c extension. (Assuming EXT is set to .c in the .env file.) 2. The source file is in a subdirectory which is named in the SPATH variable. You can use the cursor keys to view sub_func.c. g Go (back) to CS:IP. Alt-g, "main", would also work. The cursor should still be in the Source window; if not, use 1 to switch it there. Mixed mode shows both high-level statements and the (select Mixed) corresponding assembly-level instructions. This display is disassembled machine code. (select Assembly) Code On/Off controls the display of machine code in (select Code display) the source window when in assembly-level display. (select OFF) Turn off the code display in the source window. Resume high-level display. (select High Level) When the cursor is in the Source window, F8 is equivalent to the S command. F7 is equivalent to the S IN command. (But there is no subroutine to step into at this point, so it acts like the S command.) F6, 'go here' causes the emulator to begin execution at its current CS:IP, stopping on the line where the cursor is located. The Search key, F9, can be useful for finding a iteration specific location, symbol, etc. in the Source window. Return the cursor to the command line. -> sou printall The source command can be used from the command line to view any source file in SPATH. -> sou insert -> sou startup -> g Return source window to CS:IP Return the cursor to the command line. ============================================================================== EXAMINING & MODIFYING DATA This portion of the tutorial will demonstrate several ways in which you can view and modify data, in low to high level constructs. Choose the appropriate include file/command to set up your emulator for next portion of the tutorial. -> inc sample.inc list For 286, 386 or 486. -> inc samplex.inc list For 386SX. Use this include file to reset the emulator to a known state, load the protected-mode demo program and execute into main(). -> pause on Turn on the pause feature in the Dialog window. -> symb The Symbol command shows you all the symbols currently understood by HS. These were loaded from the OMF file. -> global To see only the Global symbols. -> local To see Local symbols in the current module. -> s Displays the modules currently loaded. m Displays symbols in a module. -> s Displays structure definitions. s -> b #43 Set a breakpoint, -> g then execute through the program one time to initialize variables. -> ?i Query the value of a variable. -> i=8 Assign i the value 8. -> i++ Auto-increment i. -> ?i Verify the new value. (Should be 9!) -> eva i Evaluate the current value of the variable i. -> eva i+4 Various C expressions can be evaluated. -> eva i*i -> char outbuf len Evaluate a C expression. sizeof (outbuf) -> local i is the only local variable in this module. -> exa top Open an examine window for the variable 'top'. Follow the linked list. Select "struct links far *next". Walk the linked list by continuing to press :Follow and as desired. Close all open variable windows. -> *top->next->next-> Display the value in the third element of the linked string list. -> mem 100 View a specific address in memory. Close the window. -> mem outbuf View the output buffer used by the procedure printall(). 2038 Enter the bytes shown into the memory assigned to outbuf. 2038 Change the memory display Size to byte. Return to the command line, leaving the memory window open. -> g Execute through the program loop one time. Notice that the memory window now contains different data (outbuf has been written to) and that is automatically updated at the breakpoint. -> exa i Open a variable examine window to monitor the variable i, the program loop counter. d Select Decimal format, then press Esc to keep it on-screen. -> g Notice i is incremented on each program loop. -> 4 Switch to window #4 and close it. 3 Switch to window #3 and close it. -> go til #36 The procedure insert() is about to be executed. -> s in Step into insert(). -> s Step again to validate current stack. -> d Open the Callstack window. Note that the c (current) scope of insert() is highlighted. View local symbols in the scope of insert(). Note the value of i. To close the Callstack:Locals window, a transient window. Select the scope of main(). To view local symbols in main(). Notice the variable i in this scope has a different value (this i is the main program loop counter). Close both windows. -> g hyperSOURCE is aware we've changed the program's scope. The go starts from the current CS:IP, after restoring the proper scope. Program breaks at the breakpoint set above on line #43 of main(). -> r Selects the Register window, and leave it open. -> cx=5555 Change a register value from the command line. You can also do this directly in the Register window. Notice cx in the Register window is updated. -> 3 Place cursor in the Register window, select the CX register field, 1234 and enter a new value for CX. Close the Register window. ============================================================================== BREAKPOINTS This section will demonstrate how to access the various types of breakpoints in hyperSOURCE. Choose the appropriate include file/command to set up your emulator for next portion of the tutorial. -> inc sample.inc list For 286, 386 or 486. -> inc samplex.inc list For 386SX. Use this include file to reset the emulator to a known state, load the protected-mode demo program and execute into main(). -> b #33 Set a breakpoint on the statement on line #33. Notice the line number is highlighted, indicating the presence of a breakpoint. -> b By default, hyperSOURCE uses a software breakpoint. -> help b The help page on breakpoints will explain when and how hardware execution breakpoints are used. -> b exe #36 Force a hardware execution breakpoint on line #36. -> b Debug registers are used to implement hardware breakpoints. If HS cannot set a software breakpoint because the address is in ROM, it will automatically set a hardware breakpoint. -> go Load software breakpoints into emulator memory, and start emulation, breaking on the software breakpoint on line #33. -> view mix Software breakpoints are implemented by inserting INT3 instructions in the code. They are inserted only when you type go, and are removed after a breakpoint before the prompt is displayed. Thus, you will never see INT3's unless they are in your user code. If that happens, hyperSOURCE will report a spurious breakpoint, i.e., one it did not place. -> view hl Resume high-level display. -> d Open the breakpoint window. HyperSOURCE supports b 32 software breakpoints, each of which can have a conditional statement and/or count. To insert a new breakpoint, #38 at line #38. To accept the definition. Highlight breakpoint 1: on line #36. Disable it. Highlight breakpoint 2: on line #38. Edit it. Move cursor to the CONDITION field. i>5 Type in the condition i>5. Accept it. Close the breakpoint window. -> i=2 Set i to 2 before running the test. -> g Start emulator. The program will run, stopping at line #38 each time it is encountered long enough to evaluate the condition. If not true, emulation resumes. When the condition evaluates true, emulation halts. -> ?i Query the value of i (should be 6). -> i=2 Reset the value of i to 2. These conditional breakpoints are powerful, but they require stopping the emulator long enough to evaluate the condition. Simple breaks can be defined and executed in realtime by using the MICE TRIGx:WHEN command in transparent mode. ============================================================================= TRACE ANALYSIS In this section you will use the MICE RTA board to capture and analyze data which was captured in the realtime trace buffer. -> inc setupr.inc list Use this include file to reset the emulator to a known state and load the real-mode demo program. -> go main Execute to main(). -> go #43 Execute through the program one time, to initialize the loop counter variable, i. -> exa i Open a variable window to monitor i. Leave it open. -> xlt &i Note the physical address in memory where the variable i is stored. -> tm Enter transparent mode. > trig0: when addr Replace the "nnn" in this command with the actual 0nnnP then brk physical address of i obtained above. This command sets a MICE-V complex breakpoint to break emulation whenever the address of the variable i is accessed. > htrc trig0 Make trig0 an active trigger. ^A Press control-A to end transparent mode and return to hyperSOURCE. -> go Run the program. The program will break. Even though hyperSOURCE is not aware of any breakpoints, it will sync to the program location of the current instruction pointer. Note that i has been incremented. -> pri Display the last 10t cycles of the trace buffer in the dialog window. The bus event which caused the break (access to address nnn) is seen several cycles before the end of the buffer. The additional cycles are due to emulator "skid" and the process of coming-out-of-emulation. ^G^G^G As needed to expand the Dialog window. -> go Go one time around the program loop. -> d Load the trace buffer into a hyperSOURCE Runtrace r window. By default, only the last 100 frames are uploaded. You can use the F3:SetMax key to change this value, up to the maximum of 8192 frames. l 'L'ocate the Runtrace window down two lines to uncover the variable window, #3. Leave the Runtrace window open. -> go Run program, causing it to make one loop and break again. The open Runtrace window will be automatically updated. -> tm Enter transparent mode. > trig0:when addr Substitute the actual physical address of i for the 0nnnP then trc or "nnn" as above. This command sets up the trace to when addr 0nnnnP capture only bus cycles with this address, and then data xxxxxxxxx causes a break when the data value 1234 is read or then brk written at that address. NOTE: Instead of xxxxxxxxx, enter: 0xxxx1234 for 286 & 386 1234 for 386SX 01234xxxx for 486 > htrc trig0 Make trig0 active. ^A Exit transparent mode. -> go Run the program. When the value 1234 appears at the address of i, the program will break and the Runtrace window will be automatically updated with the last 100t frames of the buffer. This time, the buffer contains only actions involving the address of the variable i. -> quit This completes the hyperSOURCE tutorial. You may refer to the MICE-V manual for additional information about setting up complex triggers.