ARCHIMEDES V1.0 +------------------------------+ | Guide to the ARCHIMEDES Demo | (ANSI-C, M68HC11) +------------------------------+ This file contains a short guide for ARCHIMEDES. Note: throughout this guide we'll assume you installed ARCHIMEDES in directory C:\ARCHIMED. If you did install it in some other di- rectory, please substitute that path for "C:\ARCHIMED" wherever the latter appears in this guide. I. The Edit - Compile - Link Cycle =============================== Start WinEdit by clicking on the WinEdit Icon. Note: If WinEdit did not open file "Lab0.c" upon startup, not all pull-down menus are available, and the buttons in the tool bar are disabled. Choose "open" from the file menu and select the file "Lab0.C" in directory "C:\ARCHIMED\DEMO". Now all pull-down menus should be visible. I.3 Invoking the Compiler from WinEdit, Error Handling -------------------------------------------------- Select entry "Compile" from pull-down menu "Project". The com- piler is started now and compiles the file in the selected window ("Lab0.C"). To give you an idea of what's going on, all ARCHIMEDES programs change the shape of the mouse cursor to the icon used in WinEdit when started from WinEdit. The compiler beeps if there are any errors detected in the compilation of the file. To see the errors discovered by the compiler in the source window, you have to select entry "Next Error" from pull-down menu "Search". The line containing the error is highlighted, while the error message appears in the box in the bottom right corner of the WinEdit window. (A shortcut for the "Next Error" command is a double mouse click in that box.) Note: The compiler also can be invoked by clicking on the "funnel" icon in WinEdit's tool bar. II. Using the Simulator/Debugger ============================ Start the Simulator/Debugger by selecting the entry "Debug" from pull-down menu "Project" or by clicking the "bug" icon in WinEdit's icon bar. The "ARCHIMEDES Simulator/Debugger" is opened now. There are six subwindows within it's main window. The message "-- Simulator ready" in the Procedure Chain Window shows that the simulator is initialized and ready to run a program. II.1 Loading and Starting an Application ----------------------------------- Select entry "Load" from pull-down menu "Target" and choose file "Lab0.ABS" in the standard Windows file selector box. Click on "Open"! The dialog box is closed and the "Downloading" dialog box is opened. This window remains open until the program is loaded completely. Now select entry "Start-Restart" from pull-down menu "Target". The application starts execution now. The message "-- running" in the Procedure Chain Window indicates that the application is running. II.2 Stopping an Application ----------------------- Select entry "Halt" from pull-down menu "Procedure"! The message "-- halted" in the Procedure Chain Window indicates that the application is halted. The statement where the program was halted is highlighted in the Source Window. (i.e. the next statement that will be executed.) The second and third line in the Procedure Chain Window show the actual procedure call chain and look like this: Lab0 in Lab0 main in Lab0 The procedure on the second line is the procedure currently being executed, and it is implemented in module "Lab0". The procedure on the third line is implemented in module "Lab0", too, and is the procedure which had called procedure "Lab0". The Data 1 Window shows the name and the local variables of the procedure currently being executed. The Data 2 Window shows the name and the global variables of the module of the procedure currently being executed. II.3 Working with Break Points ------------------------- Once the application is stopped, break points may be set. ARCHIMEDES provides four kinds of break points: 1. Temporary break points The application will be stopped the next time it tries to execute the statement. 2. Permanent break points The application will be stopped each time it tries to execute the statement. 3. Counting break points The application will be stopped once it has executed the statement a given number of times. 4. Single steps The application will be stopped at the next statement. Now we are going to set some break points: Select entry "Marks" from pull-down menu "Source". All points (statements) in the program where a breakpoint may be set are identified by a special mark. Select entry "Marks" from pull-down menu "Source" again to remove the marks. II.3.1 Temporary Break Points ---------------------- Point to the beginning of statement "fib1 = fib2;" in the "Source" window and click the left mouse button! The program continues execution and stops before executing this statement. After stopping the message "-- Break Point" is displayed in the Procedure Chain Window to indicate that the program was stopped due to a break point. Select entry "Continue" from the pull-down menu "Procedure". The program continues execution and will not stop anymore because the temporary break point was removed automatically. II.3.2 Permanent Breakpoints --------------------- Select "Halt" from the pull-down menu "Procedure"! The program is stopped again. Point to the statement in the "Source" window and click the right mouse button! Now a break point mark indicates the existence and position of the break point set. Select "Continue" from the pull-down menu "Procedure"! The application continues execution and stops when reaching the break point, i.e. just before the highlighted statement is about to be executed. Select "Continue" from the pull-down menu "Procedure" once more! The program continues execution and is stopped again the next time it comes to the breakpoint. II.3.4 Single Stepping --------------- Select "Single Step" from the menu "Procedure". The application stops on the next HLL (High Level Language) statement. II.4 Working with Data Windows ------------------------- The "Data 1" and "Data 2" windows have the same functionality each. Initially, the "Data 1" window shows the local variables of the procedures activated at the moment the programm was halted. The "Data 2" Window shows the global data of a selected module. II.4.1 Display and Update of Local Variables ------------------------------------- The local variables of any procedure that is listed in the "Procedure Chain" window can be displayed and updated. Note: Local variables can only be displayed and modified when the application program is halted. II.4.2 Display and Update of Global Variables -------------------------------------- The global variables of the modules that are listed in the "Module List" window can be displayed and updated, too. II.4.3 Displaying the Register Contents -------------------------------- Select "Register" from pull-down menu "Data 2"! The current contents of all the registers are displayed. You may change the content of most of the registers in the same way as the variables (see above). II.4.4 Inspecting the Memory --------------------- Select "Memory" from the pull-down menu "Data 2"! The current content of the target system's RAM starting at address 0x0000 is displayed. Select entry "Address" from pull-down menu "Data 2"! The "Enter Address" dialog box is opened. Here you can enter the starting address for the display of memory (The address is always read as an hexadecimal number!). Enter 80 and press the "Enter" key! This is the start address for the global data as defined in the linker parameter file "Lab0.PRM". Now the content of the memory starting at address 0x0080 is displayed in the "Data 2" window in hexadecimal format. Select first entry "Format" from the pull-down menu "Data 2" and then entry "Unsigned". Now the content of the memory is shown in unsigned decimal format. Try some of the other formats! Reset the format to "Hex" and select "Symbolic" from the pull- down menu "Data 2"! The global variables of module "Lab0" are shown again. II.5 Working with the Assembler Window --------------------------------- II.5.1 Online Disassembling -------------------- While the application is stopped you can display the assembler statements associated with a HLL statement. Point to a statement in the "Source" window and type "A" while still holding down the left mouse button! The "Assembly" window is now opened and shows some assembly statements. The highlighted lines are the assembler statements generated by the compiler to implement the selected HLL state- ment. The assembler statements are disassembled directly from the target system's memory (or the simulator's RAM). Therefore, when the code has been destroyed, e.g. because the stack grew into the code in a heavily recursive program, this becomes visible in the "Assembly" window immediately. II.5.2 Displaying the Code ------------------- Select "Display Code" from the pull-down menu "Assembly"! The hexadecimal code associated with each assembly statement is displayed left of it. Select "Display Adr" from the pull-down menu "Assembly"! The memory location in the target system's ROM (or RAM) of each assembler statement is displayed. Select "Display Code" from the pull-down menu "Assembly"! The hexadecimal codes are removed again. Select "Address" from the pull-down menu "Assembly"! The "Enter Address" dialog box is opened. In this box you can define an address from which you want to have the code displayed. II.5.3 Working with Break Points in the Assembler Window ------------------------------------------------- Breakpoints can be set in the "Assembly" Window in the same way as they are in the "Source" window. (See II.3). II.6 Tracing Variables ----------------- You have the possibility to trace the actual value of variables while the application is running. III. Configuring a Linker Parameter File ----------------------------------- Now we are going to link our test program. First we have a look at the linker parameter file, named "Lab0.PRM". Choose "Open" from the "File" menu and select this file. The parameters in this file have the following meaning: LINK Lab0.ABS The executable file produced by the linker will be called "Lab0.ABS". NAMES ... END "Lab0.ABS" uses procedures or global variables from modules "Lab0.o", "start11.o" and from the library "ansi.lib". SECTIONS A section named "MY_RAM" is defined from 0x0080 to 0x00FF for read/write access. The Section "MY_ROM" is defined from 0xF000 to 0xFEFF for read access only. PLACEMENT .. END The code of "Lab0.ABS", the strings and ROM variables will be placed in section "MY_ROM". The global data of "Lab0.abs" will be placed in section "MY_RAM". STACKSIZE 96 The size of the stack is 96 bytes. The stack is located next to the global data. Select entry "Rebuild" from pull-down menu "Compile" (or click on the "brick wall" icon)! The ARCHIMEDES Linker's window is opened and you are prompted for a parameter file name. Enter "Lab0.PRM". The message "linking succeeded" appears after correct linkage of the program. Hit the "ESC"-key to exit the ARCHIMEDES linker! Note: The linker can also be started by clicking on the "brick wall" icon in WinEdit's tool bar. III.1 WinEdit Configuration --------------------- Choose from pull-down menu "Project". The "Project Management" dialog box opens with its entries initialized as follows: Working Directory: C:\ARCHIMED\DEMO Compile command: C:\ARCHIMED\PROG\CHC11 %f Make command: C:\ARCHIMED\PROG\HIMAKE Rebuild command: C:\ARCHIMED\PROG\LINKER Debug command: C:\ARCHIMED\PROG\SIMUHC11 Execute command: C:\ARCHIMED\PROG\HIDECODE If some entries do not match above specifications, correct them and click on "Save". When you're asked for a file name, enter "DEFAULT.WPJ" and click on "OK" to close the dialog box.