









                              Dunfield MicroScope



                                       A

                               Target Independant

                                   PC Hosted

                             Source Level Debugger

                                   for small
                                Embedded Systems



                                  Release 1.0

                               Revised 27-May-01










                          Dunfield Development Systems
                          ----------------------------
                             High quality tools for
                              Embedded Development
                                 at low prices.

                            http://www.dunfield.com


                       Copyright 1988-2005 Dave Dunfield
                              All rights reserved



                              Dunfield MicroScope

                               TABLE OF CONTENTS


                                                                         Page

     1. INTRODUCTION                                                        1

        1.1 Target Independence                                             1
        1.2 Hex Load File                                                   2
        1.3 Map File                                                        2

     2. COMMAND LINE FORMAT                                                 4

        2.1 Video Attributes Option                                         4

     3. MicroScope COMMANDS                                                 5

        3.1 Command Parameters                                              5
        3.2 Command Summary                                                 6
        3.3 'B' - set Breakpoint                                            6
        3.4 'C' - Calculator                                                7
        3.5 'D' - Display address                                           7
        3.6 'E' - Erase watch                                               7
        3.7 'F' - display File                                              7
        3.8 'G' - Go (execute)                                              7
        3.9 'K' - Kill breakpoint                                           7
        3.10 'L' - Load HEX file into memory                                7
        3.11 'M' - edit Memory                                              8
        3.12 'N' - go to line Number                                        8
        3.13 'O' - Open source file                                         8
        3.14 'R' - edit Registers                                           8
        3.15 'S' - Single Step                                              8
        3.16 'T' - Tty session                                             10
        3.17 'W' - set Watch                                               11
        3.18 '?' - Search File                                             11
        3.19 '/' - Search Again                                            11
        3.20 SPACE - Step Again                                            11
        3.21 TAB - Set Display Tab Width                                   11
        3.22 F1 - Help                                                     12
        3.23 F2 - Reset Target                                             12
        3.24 F3 - Toggle Status Display                                    12
        3.25 F4 - Toggle source display ON/OFF                             12
        3.26 F5 - update watch display                                     12
        3.27 F6 - Set Default number radix                                 12
        3.28 F9 - DOS Shell                                                12
        3.29 F10 - Terminate MicroScope                                    12

     4. Target Definition File Patch Utility                               13

    Dunfield MicroScope                                              Page: 1


    1. INTRODUCTION

       MicroScope is a target independent debugging tool for  small  control
       systems,  which provides powerful features by utilizing a  PC  hosted
       user interface,  along with a minimal kernel residing in  the  target
       system.

       MicroScope provides all of the usual Debug/Monitor functions, as well
       as source level and symbolic debugging capabilities.

       1.1 Target Independence

          MicroScope is capable of supporting virtually any CPU  and  target
          system by utilizing a Target/CPU definition  file  which  contains
          all of the information that MicroScope requires about a particular
          target system.  Target/CPU definition files are available from DDS
          for a number of popular processors.

          1.1.1 Target/CPU Definition file

             MicroScope  loads  a  complete  description   of   the   target
             system/CPU from  a  file  with  the  name  <target>.DMS,  where
             <target> is the target name specified on the command line. This
             file must be located in the MicroScope home directory.

          1.1.2 Target/CPU Definition Compiler

             The MicroScope Target/CPU compiler is available from  DDS,  and
             enables you  (the  user)  to  generate  your  own  .DMS  files,
             providing support for virtually  any  processor  and/or  target
             system.

             These customized Target/CPU definition files may be distributed
             to other MicroScope users,  allowing them to use MicroScope  to
             debug on your custom hardware.  See the DMSC documentation  for
             more information.

          1.1.3 Target System Kernel

             MicroScope uses a small  "kernel"  program/monitor installed in
             the target system to accomplish certain functions, including:

                - Read memory
                - Write memory
                - Set breakpoint
                - Execute
                - Single-Step

             This kernel work in unison with the Target/CPU definition  file
             to provide MicroScope  will  all  the  resources  it  needs  to
             accomplish  high  level  debugging  capabilities  with  minimal
             system intrusion.

             MicroScope includes a capability to automatically download  the
             kernel image to  systems  which  utilize  a  serial  port  boot
             loader.
    Dunfield MicroScope                                              Page: 2


       1.2 Hex Load File

          The HEX file contains the binary image of the program to be loaded
          into the target system for debugging.

          This file may be in either Motorola or  Intel  ASCII/HEX  download
          format.

       1.3 Map File

          The MAP file contains the  information  needed  by  MicroScope  to
          perform source level and symbolic debugging.  If this file is  not
          specified,  MicroScope will work as a binary/disassembly  debugger
          only.

          The MAP file contains the following records:

             File specification
             Symbol Definition
             Address->File Mappings

          Lines in the MAP file beginning with  ';'  are  considered  to  be
          comments, and are ignored.

          1.3.1 File Specification Record

                F<filename>

             This record is used to identify source files which are used  in
             the mapping of addresses to source file lines.

             Files are numbered from 1 in the order that they occur  in  the
             MAP file.

             MicroScope supports a maximum  of  255  files  in  a  debugging
             session.

                eg: Fmyfile.c
                    Fc:\mc\stdio.h

          1.3.2 Symbol Definition Record

                <type><symbol> <file> <value> [scope range]

            type:   0 or C  = Constant symbol
                    1-6     = Memory type where symbol is located
                    7 or S  = Symbol is a stack relative offset
            file:   The file index (1-255) where symbol is defined
                    0 = Symbol is not associated with a file
            value:  Value/Address assigned to symbol.
            scope:  A range of addresses in the form: LLLL HHHH
            range   which identifies the program counter memory range
                    where this symbol is "in scope".

            eg:     1main 1 3BFE
                    Slvar 1 0023 3BFE 3D48
    Dunfield MicroScope                                              Page: 3


          1.3.3 Address->File Mapping Record

                A<addr> <file> <line>

            addr:   Address to associate with this file.
            file:   File index (1-255) where this address is defined.
            line:   Line number in file where address occurs.

            eg:     A0899 1 112
                    A089B 1 113
                    A089D 2 10
                    A089E 2 15
                    A08A0 1 128
    Dunfield MicroScope                                              Page: 4


    2. COMMAND LINE FORMAT

       The syntax of the MicroScope command line is:

                  DMS -target [hex-file [map-file]] [options]
                                      -or-
                          DMS parameter_file [options]

        Options:
            -target     = Target/CPU definition file to use
            -CS         = Symbols are case Sensitive
            -CI         = Symbols are case Insensitive
            -RH         = Radix is Hexadecimal
            -RD         = Radix is Decimal
            -RO         = Radix is Octal
            -RB         = Radix is Binary
            CP=1-4      = Communications port
            CS=value    = Communications Speed
            TW=n        = Tab Width
            Va=xx       = Video attributes

       Commonly  used  command  line  parameters,  (including  the   -target
       specification,  and hex/map files),  can be placed into an ASCII text
       file (one per line).

       When this filename is passed  as  the  FIRST  parameter  on  the  DMS
       command line,  MicroScope will read the file and process the  options
       just as if they had been entered on the command line.

       Further command line options occurring after the parameter file  will
       then  be  processed.  Multiple  parameter  files  may  be  specified.
       Processing of HEX and MAP files will occur only  after  a  target/CPU
       has been defined.

       2.1 Video Attributes Option

          Video attributes are set to two HEX  digits  which  represent  the
          Background and Foreground colors (Va=bf).

                VS= Status Line             VA= Attention Displays
                VR= Register names          VC= Current address line
                VD= Display window          VB= Breakpoint lines
                VW= Watch window            VH= Help window
                VM= Message window          VL= Help Links
                VE= Edit windows            VX= Help cursor
                VP= Prompt windows
    Dunfield MicroScope                                              Page: 5


    3. MicroScope COMMANDS

       3.1 Command Parameters

          When  MicroScope  needs  additional  information  to  complete   a
          command, you will be prompted with the following input requests:

          3.1.1 Entering Values/Addresses

             When prompted by MicroScope, you may enter any value or address
             as a series of values or symbols and arithmetic operations:

            0-9,A-F - Number in current radix (must begin with 0-9)
            $n      - Number in Hexadecimal (Base 16)
            .n      - Number in Decimal     (Base 10)
            @n      - Number in Octal       (Base  8)
            %n      - Number in Binary      (Base  2)
            'cc'    - ASCII character value (1 or 2 chars)
            SYMBOL  - Value of SYMBOL
            =REG    - Current content of any CPU register

             When entering any value,  you may use an expression  consisting
             of the value elements described above, and any of the following
             arithmetic operators:

            +   = Addition              &   = Logical AND
            -   = Subtraction           |   = Logical OR
            *   = Multiplication        ^   = Logical XOR
            /   = Division              <   = Shift LEFT
            %   = Modulus               >   = Shift RIGHT

             When  a  symbol  is  entered  in  a  Value/Address  expression,
             MicroScope will search for occurances  of  that  name  in  it's
             symbol  table,  and  will  prompt  for  confirmation  with  the
             symbol's type and value.  If you respond  'N'o to  the  prompt,
             MicroScope will continue to search for additional symbols  with
             the same name.

             Symbols can have one of 8 possible symbol types, which are:

            Constant= Symbol is not associated with a memory type
            <name>  = Up to 6 memory types defined for the target processor
            Stack   = Symbol is an offset from the stack **

             Note:  MicroScope does not try  to  automatically  resolve  the
             address of stack symbols,  however you can easily retrieve  the
             address offset from the  stack  with  an  expression  such  as:
             =SP+symbol [+/-n]

             When entering a value, you may use the following edit keys:

            Home/End    = Clear field and re-enter
            Left/Bs     = Backspace and delete
              ENTER     = Accept value as displayed
                ESC     = Abort data entry (and command)
    Dunfield MicroScope                                              Page: 6


          3.1.2 Entering Strings

                When prompted for string input,  you may use  the  following
             editing keys:

            Left/Right  = Move cursor Fwd/Back
              Home/End  = Move to Start/End of line
             Backspace  = Backspace and delete
                   Del  = Delete character under cursor
                   Ins  = Toggle Insert ON/OFF
                  PgUp  = Clear entire field
                  PgDn  = Clear from cursor to end
                 ENTER  = Accept value
                   ESC  = Abort entry (and command)

          3.1.3 Memory Type Selection

             When the target  processor  supports  more  than  one  type  of
             memory,  you will be prompted for the memory type  to  use  for
             certain operations.

             When this prompt appears,  simply select the memory type  which
             you wish to use for the current operation and press  ENTER,  or
             hit ESCAPE to cancel the operation.

             This prompt will NOT appear for targets with  only  one  memory
             type.

       3.2 Command Summary

            B - Set breakpoint  F1  - Help              ?   - Search File
            C - Calculator      F2  - Reset Target      /   - Search again
            D - Display Address F3  - Toggle Status
            E - Erase watch     F4  - Toggle Source
            F - Select file     F5  - Update watch
            G - Go (execute)    F6  - Set radix
            K - Kill breakpoint F9  - DOS shell
            L - Load file       F10 - Exit MicroScope
            M - Edit Memory
            N - goto line Num.  tab         - set Tab width
            O - Open file       space       - Step again
            R - Edit Registers  arrows/Home - Move display
            S - Single-Step     PgUp/PgDn   - Scroll 1 screen
            T - Tty session     ^PgUp/^PgDn - Move to top/bottom
            W - Set watch

       3.3 'B' - set Breakpoint

          Prompts  you  to  enter  an  address  ...  When  this  address  is
          encountered following a  'G'o  command,  control  will  return  to
          MicroScope.

          Breakpoints can be removed with the 'K'ill command.
    Dunfield MicroScope                                              Page: 7


       3.4 'C' - Calculator

          This command allows you to evaluate Value/Address expressions, and
          will display the results in Hex/Decimal/Octal/Binary.

          This command is very handy for evaluating  small  expressions,  as
          well as providing an easy way to do symbol lookups.

       3.5 'D' - Display address

          Prompts or an address, and the repositions the main display window
          to view this address.

          If Source Display is enabled,  and the  address  is  mapped  to  a
          source file, the corresponding line from that file will be shown.

          If no source lines are available,  the display window will show an
          instruction disassembly of the memory address.

       3.6 'E' - Erase watch

          Places a large blinking cursor in the watch area near the  top  of
          the screen.  Use the Up/Down keys to position the  cursor  on  the
          line of the watch you wish to erase,  then press ENTER.  The watch
          will be removed. Press ESC to cancel without erasing a watch.

       3.7 'F' - display File

          Prompts with a list of all files mapped in  the  current  session.
          Scroll through the list and select the file you wish to view.

          Press ENTER,  and the selected file will be  opened  in  the  main
          display window.

       3.8 'G' - Go (execute)

          Any breakpoints which have been defined will be implanted into the
          target  code  memory  before  execution  commences,  and   removed
          immediately after control  returns  to  MicroScope  ...  In  other
          words,  although breakpoints are inserted into the  target  system
          memory,  you should never see them,  as they are restored whenever
          MicroScope is active.

       3.9 'K' - Kill breakpoint

          Prompts you to enter an address ...  Removes this address from the
          breakpoint table,  so that MicroScope will not stop there when the
          address is encountered during the execution of a 'G'o command.

       3.10 'L' - Load HEX file into memory

          You will be prompted for the filename to load.

          If the target supports multiple memory types,  you  will  also  be
          prompted for the memory type in which to load the file.

          The file will be loaded into memory.
    Dunfield MicroScope                                              Page: 8


       3.11 'M' - edit Memory

          The memory editor shows the content of memory in a  standard  Hex-
          ASCII dump format.  You may edit the memory by typing  HEX  digits
          into the HEX display, or ASCII characters into the ASCII display.

            F1  - Help              Left/Right  = Move 1 character
            F2  - Go to address          Up/Dn  = Move 1 line    (16 bytes)
            F3  - Toggle Hex/ASCII   PgUp/PgDn  = Move 1 screen (256 bytes)
            F4  - Block Fill          Home/End  = Move to start/end of line
            F5  - Refresh          ^PgUp/^PgDn  = Move to Top/Bottom
           ESC  - Exit

       3.12 'N' - go to line Number

          Prompts or an value,  and the repositions the  file  in  the  main
          display window to place this line number at the top.

       3.13 'O' - Open source file

          Prompts for a file name.  The file is added  to  the  source  file
          list, and made the current display file.

       3.14 'R' - edit Registers

          The register editor allows you to select and replace  the  content
          of any of the processor registers. Available keys

                 Up/Dn  - Select register (1 by 1)
             PgUp/PgDn  - Select register (page)
              Home/End  - Move to Top/End of register display
               0-9,A-F  - Enter HEX data directly into register
                 space  - Enter value to replace register content
                   +/-  - Increase/Decrease indirect memory display
             ESC/Enter  - Exit          F1 - Help

       3.15 'S' - Single Step

          Prompts for the single-step type to perform:
                1-Into instruction          5-Over instruction
                2-Into this file            6-Over this file
                3-Into any  file            7-Over any file
                4-Into HL   file            8-Over HL  file

          You will also be prompted for the  number  of  steps  to  perform.
          While stepping,  the display  shows:  <execution  address>  <steps
          remaining> Press ESC to stop multiple instruction stepping.

          You can repeat  a  single  step  operation  with  the  Step  again
          command.
    Dunfield MicroScope                                              Page: 9


          3.15.1 Step Into Instruction

             The target processor  steps  one  instruction  per  count,  and
             returns to MicroScope.

             If the  instruction  to  be  executed  is  a  subroutine  call,
             MicroScope steps "into" the subroutine,  and will return at the
             first address in the subroutine.

          3.15.2 Step Into this file

             For each count,  the target processor steps  until  it  reaches
             another address which mapped to  a  source  line  in  the  file
             currently being displayed.

             If the  instruction  to  be  executed  is  a  subroutine  call,
             MicroScope steps "into" the subroutine.

          3.15.3 Step Into any file

             For each count,  the target processor steps  until  it  reaches
             another address which mapped to a source  line  in  ANY  source
             file.

             If the  instruction  to  be  executed  is  a  subroutine  call,
             MicroScope steps "into" the subroutine.

          3.15.4 Step Into HL file

             For each count,  the target processor steps  until  it  reaches
             another address which maps to a source line in any  file  which
             is NOT the 1st file in the  mapping  tables.  This  accomodates
             development systems which map addresses from a  "listing file",
             and hence associate all instruction addresses with a file, even
             when they do not reside on a source line boundary in any of the
             actual program source files.

             You can use this step  type  to  proceed  to  any  source  file
             without stopping on the addresses occurring only in the listing
             file.

             If the  instruction  to  be  executed  is  a  subroutine  call,
             MicroScope steps "into" the subroutine.

          3.15.5 Step Over Instruction

             The target processor  steps  one  instruction  per  count,  and
             returns to MicroScope.

             If the  instruction  to  be  executed  is  a  subroutine  call,
             MicroScope steps  "over"  the subroutine,  executing the entire
             subroutine as  a  single  instruction,  and  returning  at  the
             address which follows the subroutine call.
    Dunfield MicroScope                                              Page: 10


          3.15.6 Step Over this file

             For each count,  the target processor steps  until  it  reaches
             another address which mapped to  a  source  line  in  the  file
             currently being displayed.

             If  an  instruction  to  be  executed  is  a  subroutine  call,
             MicroScope steps "over" the subroutine,  and does not check any
             address within the subroutine.

          3.15.7 Step Over any file

             For each count,  the target processor steps  until  it  reaches
             another address which mapped to a source line in ANY file.

             If  an  instruction  to  be  executed  is  a  subroutine  call,
             MicroScope steps "over" the subroutine,  and does not check any
             address within the subroutine.

          3.15.8 Step Over HL file

             For each count,  the target processor steps  until  it  reaches
             another address which maps to a source line in any  file  which
             is NOT the 1st file in the  mapping  tables.  This  accomodates
             development systems which map addresses from a  "listing file",
             and hence associate all instruction addresses with a file, even
             when they do not reside on a source line boundary in any of the
             actual program source files.

             You can use this step  type  to  proceed  to  any  source  file
             without stopping on the addresses occurring only in the listing
             file.

             If an instruction to be executed  is  a  subroutine  call,  the
             debugger steps "over" the subroutine.

       3.16 'T' - Tty session

          Enters into a TTY session with the target.

          Characters typed on the keyboard are sent to  the  target  system.
          Characters received from the target are displayed.

          Available function keys:
             F1 - Help
             F8 - "Zoom" to/from large message window
             F9 - Toggle local echo ON/OFF
             F10 - Return to MicroScope main screen
    Dunfield MicroScope                                              Page: 11


       3.17 'W' - set Watch

          Prompts for an address and a memory type (if necessary) and sets a
          watch on this address.

          Watches are always displayed near the top of the screen,  and will
          be updated whenever an operation occurs on the target system.  You
          can also manually update the display at any time.

       3.18 '?' - Search File

          Prompts for a  string,  and  searches  the  file  currently  being
          displayed for the  string.  If  the  string  is  found,  the  line
          containing the string will be moved to the top of the display.

          The search begins with the line on the  top  of  the  screen,  and
          commences to the end of the file.

          To continue the search, use the search again command.

       3.19 '/' - Search Again

          Searches for the string last searched for  using  the  '?'  search
          command,  and moves any line where the string is found to the  top
          of the screen.

          To allow for repeated searches to find successive strings  in  the
          file, the search begins ONE LINE AFTER the top of the screen.

       3.20 SPACE - Step Again

          Press <space> to repeat the last single-step operation.

          The target will be single-stepped with the same step type  as  was
          previously performed, and a count of 1.

       3.21 TAB - Set Display Tab Width

          Press TAB to set the display tab width.

          You will be prompted for a new value to define the  width  of  TAB
          stops in the displayed source files.

          If a file is currently being displayed,  the  new  tab  will  take
          effect for this file only.

          If no file is currently being displayed,  the new  tab  will  take
          effect for any files which have not had  their  tabs  individually
          set.
    Dunfield MicroScope                                              Page: 12


       3.22 F1 - Help

          Press F1 to activate context sensitive help screens.

       3.23 F2 - Reset Target

          Performs a hard RESET of the target system.

       3.24 F3 - Toggle Status Display

          Switches the status line  displayed  at  the  top  of  the  screen
          between a view of the processor registers,  and information  about
          the source file and line number or disassembly address displayed.

       3.25 F4 - Toggle source display ON/OFF

          When ON,  addresses which are mapped to files will be displayed in
          the display window as the source file line  corresponding  to  the
          address.  When  OFF,  addresses  are  always   displayed   in   an
          instruction disassembly format.

       3.26 F5 - update watch display

          Normally,  watch points are automatically updated  on  the  screen
          whenever MicroScope regains control from the  target  system,  and
          you do not need to manually refresh them.

          If however you are watching any quantity which might change  while
          MicroScope is active, you can use this function to refresh the on-
          screen watch display.

       3.27 F6 - Set Default number radix

          Press F6 to set the default number radix.

          You will be prompted with a menu of:

             Hexadecimal / Decimal / Octal / Binary

          Select the radix that you wish to use as  the  default  for  value
          input (You can always override the radix with '$ . @ or %'.

       3.28 F9 - DOS Shell

          Press F9 to launch a DOS command shell.

          Unlike  F10-Terminate  MicroScope  remains  in  memory,  and  will
          re-activate when you issue the EXIT command to the shell.

       3.29 F10 - Terminate MicroScope

          Press F10 to terminate MicroScope  and  return  to  the  operating
          system.

          You will be prompted for confirmation.  Press 'Y' to terminate, or
          'N' to cancel and continue with your debug session.
    Dunfield MicroScope                                              Page: 13


    4. Target Definition File Patch Utility

       DMSPATCH is a utility for patching the content  of  the  .DMS  target
       definition files. This utility allows you to change:

          Processor ID
          Kernel memory block assignments
          System memory address ranges
          Target control flags
          Kernel command definitions
          Initial register contents
          Predefined symbols

       DMSPATCH is very straightforward to use. Simply type:

                                 DMSPATCH <cpu>

       And the corresponding <cpu>.DMS file will be edited.

       DMSPATCH provides on-screen prompts of it's command keys,  as well as
       a help screen which is shown any  time  an  unrecognized  command  is
       input.

       Some resources cannot be edited, added or removed with DMSPATCH.  For
       complete control of the target definition file,  please refer to  the
       DDSC Target Definition File Compiler.
