









                               Kernel Load Images

                                    for the

                              Dunfield MicroScope

                                    Debugger



                                  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



                             DMS Kernel Load Images

                               TABLE OF CONTENTS


                                                                         Page

     1. Introduction                                                        1


     2. Load Image format                                                   1

        2.1 00 - End of File                                                1
        2.2 01-F9 - Data record                                             1
        2.3 FA bb - Set serial baudrate                                     1
        2.4 FB tt - Flush/Delay                                             1
        2.5 FC cc - Wait for character                                      2
        2.6 FD - Expect echo OFF                                            2
        2.7 FE - Expect echo ON                                             2
        2.8 FF tt - Set receive timeout                                     2

     3. Load File Builder utility                                           2

        3.1 OUTPUT <filename>[.DML]                                         3
        3.2 TIMEOUT <value>                                                 3
        3.3 ECHO ON|OFF                                                     3
        3.4 WAITFOR <value>                                                 3
        3.5 FLUSH <value>                                                   4
        3.6 FILE <filename> BINARY|HEX|TEXT                                 4
        3.7 SEND <value> [value ...]                                        4
        3.8 PREFIX/SUFFIX                                                   4
        3.9 BAUD [speed]                                                    4
        3.10 END                                                            4
        3.11 File Image Values                                              5
    DMS Kernel Load Images                                           Page: 1


    1. Introduction

       To accomodate those systems which use a serial bootstrap loader,  and
       do not have the DMS debug kernel resident on  powerup.  DMS  provides
       the ability to automatically load the kernel into the target system.

       To accomplish this,  DMS looks for a file by the name of <target>.DML
       in the DMS home directory,  and if found,  sends the content of  this
       file to the system. If no <target.DML> file exists, then no action is
       taken.

       NOTE that this file does not have to actually contain a kernel image.
       You can also use this facility to provide any startup sequence needed
       by the target system firmware to activate a resident debug kernel.

    2. Load Image format

       To provide minimal handshaking between  DMS  and  the  target  serial
       bootloader,  the .DML file is encoded with a  simple  binary  command
       structure:

       2.1 00 - End of File

          When DMS encounters a command code of 00  (hex)  in the  file,  it
          terminates processing.  This function is not required,  however it
          is recommended that all .DML files be ended  with  this  code,  to
          prevent any data which may be appended  to  the  file  from  being
          transmitted to the target system.

       2.2 01-F9 - Data record

          This command code causes DMS to read the indicated number of bytes
          (1-249)  immediately following this code and to send them  to  the
          target system.

          You may use multiple data records to send  as  much  data  as  you
          like. Also note that you are responsible for providing the data in
          the format expected by the target.  For  example,  if  the  target
          expects binary data,  then you must send binary data  records.  If
          the target expects ASCII-HEX download records,  then you must send
          ASCII-HEX download records.

       2.3 FA bb - Set serial baudrate

          Causes DMS to reset it's serial baud-rate to the  indicated  value
          'bb', which is calculated as 115200/desired-rate.

          A  'bb'  value of 0 causes DMS to revert to it's  original  serial
          baudrate.

       2.4 FB tt - Flush/Delay

          This command causes DMS to wait until there has been no data  from
          the target for the indicated 'tt' number of 55ms clock ticks. This
          is useful to:
             - Clear transient/superflous data emitted by target
             - Perform a programmed delay function
    DMS Kernel Load Images                                           Page: 2


       2.5 FC cc - Wait for character

          Causes DMS to wait until the specified character 'cc'  is received
          from the target.  If no data is received within a  timeout  period
          (see FF command code),  DMS will abort the  download  with  a  "No
          Response" error message.

       2.6 FD - Expect echo OFF

          This code causes DMS to stop expecting an  echo  from  the  target
          system  (see FE command code).  The default setting  for  echo  is
          "OFF".

       2.7 FE - Expect echo ON

          This code causes DMS to expect an echo  of  each  character  sent.
          After each character is transmitted,  DMS will wait to receive the
          same character back from the target. If no data is received within
          a timeout period  (see  FF  command  code),  DMS  will  abort  the
          download with a "No Response"  error message.  The default setting
          for echo is "OFF".

       2.8 FF tt - Set receive timeout

          Sets the timeout used by the FC and FD commands to  the  indicated
          'tt' number of 55ms clock ticks. This allows timeouts ranging from
          55ms to approximately 14 seconds.

    3. Load File Builder utility

       The DMSLFB utility can  be  used  to  assist  in  the  generation  of
       properly formatted .DML image  files  for  the  loader.  The  command
       syntax is:

                 DMSLFB <input_file[.LFB]> [output_file>[.DML]]

       The input file is a text file containing commands  which  define  how
       the output file will be generated:

       Any <value> item shown may be entered as:

            0-255       <= Decimal value in the range of 0-255
            $xx         <= Any 2-digit hexidecimal value
            'c'         <= Single ascii character *1
            "c"         <= Single ascii character *1
            '...'       <= Multiple ASCII characters *1 *2
            "..."       <= Multiple ASCII characters *1 *2
            @SL         <= Size of loaded file      (low byte)
            @SH         <= Size of loaded file      (high byte)
            @CL         <= Checksum of loaded file  (low byte)
            @CH         <= Checksum of loaded file  (high byte)
            @FI         <= File content as binary image *4
            @FB(bsize)  <= File content as fixed length blocks *4
            @FR(rterm)  <= File content as variable records *4
            -<value>    <= Negative of any value
            ~<value>    <= Compliment of any value
            (expr)      <= Multiple values in an expression *3
    DMS Kernel Load Images                                           Page: 3


        *1 - Either type of quote may be used, which allows the other
             type to occur within the string.

        *2 = When '-' or '~' is applied to a multi-character value, only
             the first character is modified. Multi-character values
             should not be used within expressions.

        *3 = Expressions must be contained within brackets, and consist of
             the form: (<value> <operator> <value> [operator value ...])
             All operations are performed left to right with no precedence.
             <operator>s are:
                    +       <= Addition
                    -       <= Subtraction
                    *       <= Multiplication
                    /       <= Division
                    %       <= Modulus
                    &       <= Logical AND
                    |       <= Logical OR
                    ^       <= Exclusive OR

        *4 = See "File Image Values"
             Valid for "SEND" only, and not within prefix/suffix.

       3.1 OUTPUT <filename>[.DML]

          Establishes a default output filename which will  be  used  if  no
          output file is given on the command line.  If this command is  NOT
          used, and no output file is specified on the command line,  DMSLFB
          will perform the motions of creating the  image  without  actually
          creating an output file.

          This command must occur BEFORE any commands which result  in  data
          being written to the output file.

       3.2 TIMEOUT <value>

          Defines the timeout value used by the WAITFOR and  ECHO  commands.
          Value is in 55ms PC BIOS clock ticks.
                         ie: 1=55ms, 10=550ms, 100=5.5s

       3.3 ECHO ON|OFF

          When  "ECHO ON"  is in effect,  any data sent  to  the  target  is
          expected to be echoed back within the TIMEOUT specified period.

          If no data is received within a TIMEOUT period, DMS will abort the
          download with a "No Response"  error message.  The default setting
          for echo is "OFF".

       3.4 WAITFOR <value>

          Causes DMS to  wait  until  the  specified  character  <value>  is
          received from the target.  If no data is received within a TIMEOUT
          period,  DMS will abort the download with a  "No  Response"  error
          message.
    DMS Kernel Load Images                                           Page: 4


       3.5 FLUSH <value>

          This command causes DMS to wait until there has been no data  from
          the target for the indicated  <value>  number of 55ms clock ticks.
          This is useful to:
             - Clear transient/superflous data emitted by target
             - Perform a programmed delay function

       3.6 FILE <filename> BINARY|HEX|TEXT

          Loads the indicated file for later transmission  by  a  BINARY  or
          RECORD command. At this time the size and checksum of the file are
          computed for later use by the @Sx and @C. value elements.

          BINARY|HEX|TEXT indicates how the file should be loaded:

            BINARY  = File contains a raw binary image
            HEX     = File contains Motorola/Intel HEX format data
            TEXT    = File will be read as TEXT (newline translation)

          NOTE: this mode does not affect how the file is transmitted to the
          target.  The actual file transmission is controlled by the type of
          file value specified in the SEND command.

       3.7 SEND <value> [value ...]

          Transmit the specified values to the target.  If  ECHO  ON  is  in
          effect, a echo response will be expected for each character sent.

       3.8 PREFIX/SUFFIX

          Begins the definition of a PREFIX or SUFFIX block. All commands up
          to END are recorded in the block.  The PREFIX block  is  processed
          before each  file  RECORD  or  BLOCK,  and  the  SUFFIX  block  is
          processed AFTER each file RECORD or BLOCK.

          The PREFIX/SUFFIX blocks may contain  the  TIMEOUT,  ECHO,  FLUSH,
          WAITFOR and SEND commands.

       3.9 BAUD [speed]

          Sets the serial baudrate to the indicated value.  If a value of  0
          (zero)  is given,  the serial baudrate is reset to  it's  original
          value.

       3.10 END

          Terminates the definition of a PREFIX or  SUFFIX  block.  If  used
          outside of a block definition,  writes the 00 (END)  marker to the
          file.
    DMS Kernel Load Images                                           Page: 5


       3.11 File Image Values

          The content of the previously loaded FILE can  be  transmitted  to
          the target by using one of the  following  "file"  value  elements
          within the parameters to a SEND command.

          3.11.1 @FI

             Causes the previously loaded FILE  to  be  transmitted  to  the
             target as a single binary image. No handshaking is performed.

          3.11.2 @FB(bsize)

             Causes the previously loaded file  to  be  transmitted  to  the
             target as a series of fixed length blocks.  The  <bsize>  value
             identifies how many bytes are to be transmitted in each block.

             To allow for host interaction,  a PREFIX block of commands  can
             be processed before each block,  and the SUFFIX  block  can  be
             processed after each block.

          3.11.3 @BR(rterm)

             Causes the prevously loaded  file  to  be  transmitted  to  the
             target as a series of records. The <rterm> value identifies the
             binary character which terminates each record.  For text files,
             this is normally set to 10 ($0A = Newline).

             To allow for host interaction,  a PREFIX block of commands  can
             be processed before each record,  and the SUFFIX block  can  be
             processed after each record.
