HI-CROSS V2.6

+----------------------------+
| Guide to the HI-CROSS Demo |                (ANSI-C, M68xxx)
+----------------------------+


This file contains a short guide for this demo installation of
HI-CROSS. Please print it on paper and carefully follow its in-
structions.
  Note: throughout this guide we'll assume you installed HI-CROSS
in directory C:\HICROSS. If you did install it in some other di-
rectory, please substitute that path for "C:\HICROSS" wherever the
latter appears in this guide.


I.  The Edit - Compile - Link Cycle
    ===============================

    Start WinEdit by clicking on the WinEdit Icon. It starts up
    with the file "fibo.c" already opened.
      First make sure that WinEdit is correctly configured. (This
    should already have been done by the installation program, but
    check it all the same!)
    
    Note: If WinEdit did not open file "fibo.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 "fibo.c" in directory "C:\HICROSS\DEMO".
          Now all pull-down menus should be visible.


I.1 WinEdit Configuration
    ---------------------

    Choose <Configure> from pull-down menu "Project". The "Project
    Management" dialog box opens with its entries initialized as
    follows:

       Working Directory:       C:\HICROSS\DEMO

       Compile command:         C:\HICROSS\PROG\CM68K %f

       Make command:            C:\HICROSS\PROG\HIMAKE 

       Rebuild command:         C:\HICROSS\PROG\HILINK

       Debug command:           C:\HICROSS\PROG\SIMUM68K 

       Execute command:         C:\HICROSS\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.
    

I.2 Editing a File
    --------------
    
    Now we are going to insert two errors in the source file "fibo.c"
    in order to see how the editor handles compilation errors.

    Insert an additional parameter "ep" in line 37! To do this, you
    first have to get to line 37 of course. The fastest way is typing
    Alt - G (i.e. typing "G" while holding down the "Alt" key) or 
    choosing entry "Go to line..." from pull-down menu "Search" and
    entering the line number in the small box that appears in the lower
    left corner. 
    
       =>   fiboCount = Fibonacci(counter, ep);
                                        ======
       
    Select entry "Save" from pull-down menu "File" to save the changes 
    in file "fibo.c" (or type F2, i.e. function key number 2).
    

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 ("fibo.c"). To give you an idea of what's going on, all
    HI-CROSS programs change the shape of the mouse cursor to the
    icon used in WinEdit when started from WinEdit.
      Now the compiler beeps, indicating there was at least one
    error 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.)
      Now we have to correct the errors we just had inserted.
    
    Remove the previously inserted parameter from line 37, which is
    the highlighted one!
     
       =>   fiboCount = Fibonacci(counter);
       
    Choose "Compile" from menu "Project" to recompile the file.
    Since we didn't save the changes we've just made, WinEdit asks
    if it should save it prior to calling the compiler. Click "Ok"
    to save the file. Now the compiler can recompile the file,
    there should be no error anymore.
    
    Note: The compiler also can be invoked by clicking on the "funnel"
          icon in WinEdit's tool bar.
    
    
I.4 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 "fibo.prm". Choose "Open"
    from the "File" menu and select this file.
      The parameters in this file have the following meaning:
    
       LINK   Fibo.ABS    The executable file produced by 
                          the linker will be called "fibo.abs".
                          
       NAMES  ... END     "fibo.abs" uses procedures or global
                          variables from modules "fibo.o", "startmc.o"
                          and from the library "ansi32.lib".
                          
       SECTIONS           A section named "MY_RAM" is defined from
                          0x4000 to 0x43FF for read/write access.
                          The Section "MY_ROM" is defined from 0x1000
                          to 0x3FFF for read access only.
                          
       PLACEMENT .. END   The code of "fibo.abs", the strings and ROM
                          variables will be placed in section "MY_ROM".
                          The global data of "fibo.abs" will be placed 
                          in section "MY_RAM".
                          
       STACKSIZE 0x200    The size of the stack is 512 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 HI-CROSS Linker's window is opened
    and you are prompted for a parameter file name.

    Enter "fibo.prm".

    The message "linking succeeded" appears after correct linkage
    of the program.

    Hit the "ESC"-key to exit the HI-CROSS linker!
        
    Note: The linker can also be started by clicking on the
          "brick wall" icon in WinEdit's tool bar.

          
II. Using the Simulator/Debugger (or Downloader/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 "HI-CROSS Simulator/Debugger" is opened now. There are
    six subwindows within it's main window.
    
    The message "--  Simulator ready Vx.x" 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 "fibo.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:
    
       Fibonacci   in fibo
       main        in fibo
       
    The procedure on the second line is the procedure currently
    being executed, and it is implemented in module "fibo".
    The procedure on the third line is implemented in module 
    "fibo", too, and is the procedure which had called procedure
    "Fibonacci".

    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.
    HI-CROSS 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 "fibo = n;" 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.

    In our demo program, the local variable "n" is incremented
    each time the program enters procedure "Fibonacci". Please
    note the current value of this variable.
     
    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.
 
    If you compare the current value of local variable "n" with the
    previous one, you will see that this variable was incremented
    by 1. The procedure "Fibonacci" was executed once more again.
    
    
II.3.3 Counting Breakpoints
       --------------------
       
    Point to the statement "fibo = n;" in the "Source" window
    and click both the right and the left mouse button!
    The "Break Point Setting" dialog box is opened now.
    Change the value stored in the field "Interval" to 10.
    The value stored in "current count" will automatically be
    changed to suit the new value of "interval".
    Click on "Set" to set the breakpoint and close the dialog
    box.
   
    Please note the current value of variable "n". 
    Select "Continue" from the pull-down menu "Procedure"!
    The program continues execution and stops when reaching
    the counting breakpoint for the 10th time.

    If you compare the current value of the local variable "n"
    with the previous one, you will see that this variable was
    incremented by 10. The procedure "Fibonacci" was executed
    10 more times.
    
    Select "Continue" from the pull-down menu "Procedure"! Again,
    the program is stopped when it reaches the breakpoint for the
    10th time.
      Counting break points act like permanent break points, i.e.
    they remain valid until they are deleted.
    
    Select "Delete Breaks" from pull-down menu "Target"!
    All break points in the application are deleted now.
    
    
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 eventually updated.
      Run the demo program to the statement "fib1 = fib2;" within the 
    procedure "Fibonacci" (just click with the left mouse button on
    that statement in the "Source" window). 
      Point to procedure "Fibonacci" in the "Procedure" window and
    click the left mouse button! Now, the local variables of procedure
    "Fibonacci" are displayed in the "Data 1" window. 
      Point on the variable "fib2" in the "Data 1" window and click
    the right mouse button. The value of the variable "fib2" is re-
    placed by "______", indicating that the value of this variable
    may be updated. Enter 10 and press "return"!
      Now the value displayed next to the variable "fib2" is "10". This
    value has been directly updated in the target system's RAM (in
    the simulated Random Access Memory of the Simulator).
    
    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.

    Point to module "Startmc" in the "Module List" window and click
    the left mouse button! Now, the global variables of module
    "Startmc" are displayed in the "Data 2" window.
    
    Point to variable "_startupData" in the "Data 2" window and click
    the left mouse button! Now you can see into the startup data structre.
    Click right button on the variable "dataPage", no you may change the 
    value of this variabl. It might be a good idea not to change this value,
    so press "ESC" , which leaves the value of "dataPage" unchanged.

    Enter "ESC"! The value in the variable "dataPage" remains unchanged.
    
    
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 4000 and press the "Enter" key! This is the start address
    for the global data as defined in the linker parameter file
    "fibo.prm". Now the content of the memory starting at address
    0x4000 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 "Fibo" 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 the statement "fib2 = fibo;" in "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.
    
    Enter 1000! This is the start address for the code defined in the
    linker parameter file "fibo.prm".
    
    
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.
    
    Point to the variable "counter" in the "Data 2" window and
    type "t" while holding down the left mouse button! The variable
    "counter" is displayed in the "Target" window.
    
    Point to the variable "fiboCount" in the "Data 2" window and
    type "t" while holding down the left mouse button! The variable
    "fiboCount" is displayed in the "Target" window, too.

    Select "Continue" from the pull-down menu "Procedure"!
    While the application continues its execution, the value of the
    variables in the "Target" window are updated continuously.
    

III The Decoder/Inline Generator
    ============================    

III.1 Generating Inline Assembler
      ---------------------------
      
    With HI-CROSS you can generate from a standard HLL file another
    HLL file that contains the inline assembler statements 
    corresponding to the HLL statements in the source file. This
    may be very useful for optimization purposes.
    
    Invoke the Decoder/Inline-Gererator by selecting the entry 
    "Execute" from pull-down menu "Project" or by clicking on 
    "traffic light" icon in WinEdit's tool bar!

    The HI-CROSS decoder window is opened now. You are asked for
    an object file name.
    
    Enter -I "fibo.o"!

    -I specifies the format in which the file will be decoded.

    The decoder now decodes the object file "fibo.o" into the file
    "fibo.lst".
    
    Type "ESC" in order to quit the decoder. Now open the generated
    file "fibo.lst"! This file is equivalent to the original file
    "fibo.c", except that it is written with inline assembler state-
    ments. The assembly code may be optimized by hand and compiled
    again.
    
    
III.2 Generating Embedded Source and Assembler
      ----------------------------------------
      
    From a standard HLL file you can generate a file in which
    source code and associated assembler statements are embedded.
     
    Start the decoder and enter the object file as above! This time,    
    enter "-C" as the format and quit the decoder by hitting the "ESC"
    key. Open file "fibo.lst" again.
    
    In this file the assembler statements generated by a HLL 
    statement are displayed under the HLL statement.
    
    
III.3 Generating Assembler
      --------------------

    You also may generate a listing file containing only the assem-
    bler statements generated by the compiler. Simply enter "-X" as
    the format code in the decoder.
    

IV. Using the Make Utility
    ======================
    
    The make utility delivered with HI-CROSS is similar to the make 
    utility found in UNIX system.


IV.1 Writing a Make File
     -------------------
     
    Open the file "calc.mak"!  This is an example of a make file.
    For each source module of the application, there must be an
    entry of the following format:
    
       InOut.o : InOut.c hidef.h InOut.h Terminal.h
          $(HICOMP) InOut.c
       
    The first line indicates that the file "InOut.o" depends on the
    files "InOut.c stddef.h InOut.h Terminal.h". The make utility
    must rebuild "InOut.o" if one on the previously listed files
    is newer than the existing "InOut.o" or if "InOut.o" doesn't
    exist at all.
      The second line indicates that file "InOut.o" is produced
    by the compilation of file "InOut.c". HICOMP is a macro which
    is defined in the environment file "DEFAULT.ENV" or by a DOS
    environment variable "HICOMP".
      For the main module of the application, there must be an entry
    of the following format:    
    
       Calc.abs : Calc.prm Calc.o InOut.o Terminal.o TermPort.o ...
          $(HILINK)  Calc.prm
          
    The first line indicates that the file "Calc.abs" depends on
    the files "Calc.prm Calc.o InOut.o Terminal.o TermPort.o
    startmc.o ansi32.lib", i.e. all these files must be built prior
    to "Calc.abs".
      The second line indicates that the file "Calc.abs" is produced
    by the linkage of the "Calc.prm" file. "HILINK" is a macro
    which is defined in the environment file "DEFAULT.ENV" or by
    a DOS environment variable "HILINK".
    
    Note: The first line of each rule must NOT have any leading
          space characters!! The second however, must have at
          least one leading space character.
    
    
IV.2 Invoking the Make Utility
     -------------------------
     
    Now let's try the make utility. Open the file "Terminal.h" and
    select "Save" from the pull-down menu "File". (This file gets
    the newest date)!
    
    Select entry "Make" from the pull-down menu "Project"! The make
    utility starts and asks you for a make file.
    
    Note: The make utility can also be started by clicking on the
          "hammer" icon in WinEdit's tool bar.
    
IV.2.1 Building a Specific Entry from the Make File
       --------------------------------------------
       
    First we are going to rebuild a specific entry from the make
    file: the file "InOut.o".
    
    Enter "Calc.mak InOut.o"!

    The cursor changes to the compiler icon, indicating that
    the file "InOut.c" is beeing recompiled (because it depends
    on the newly saved file "Terminal.h").
    
IV.2.2 Building the Default Entry from the Make File
       ---------------------------------------------
       
    Enter "Calc.mak"!
    
    The first entry in the make file is considered the default
    entry. So the make utility is now building file "Calc.abs".
    The compiler cursor is displayed while the "Calc.c" file is
    being compiled. After compilation the HI-CROSS Linker is
    called and the file "Calc.prm" is linked.
    

RS, 23-jun-93

